012-kaopeilian/docs/规划/全链路联调/言迹智能工牌/获取员工录音信息.md

获取员工未绑定录音信息

接口信息

• 路径：POST /api/beauty/v1/audio/infos
• 说明：根据员工手机号获取录音信息（最关键的接口）

请求参数

Body参数（JSON）

参数	必选	类型	默认值	描述
estateId	是	integer	-	项目ID
consultantPhone	否	string	-	员工手机号（三方员工id 必传其一）
externalUserId	否	string	-	三方员工id（员工手机号 必传其一）
audioStartDate	否	string	-	录音时间（例：2025-05-06）

请求示例

{
  "estateId": 516799468310364162,
  "consultantPhone": "13800138000",
  "audioStartDate": "2024-10-01"
}

响应结果

Body结构

参数	类型	说明
records	list	录音文件列表
└─ id	bigint	录音ID
└─ externalUserId	string	三方员工ID
└─ consultantPhone	string	员工手机号
└─ consultantName	varchar	销售人员姓名
└─ fileUrl	varchar	录音地址，7天有效
└─ startTime	datetime	录音开始时间(yyyy-MM-dd HH:mm:ss)
└─ endTime	datetime	录音结束时间(yyyy-MM-dd HH:mm:ss)
└─ duration	bigint	文件时长(ms)
└─ fileSize	bigint	文件大小(bt)

响应示例

{
  "code": "0",
  "msg": "success",
  "data": {
    "records": [
      {
        "id": 123456,
        "externalUserId": "EMP001",
        "consultantPhone": "13800138000",
        "consultantName": "张三",
        "fileUrl": "https://example.com/audio/123456.mp3",
        "startTime": "2025-01-15 10:30:00",
        "endTime": "2025-01-15 10:35:00",
        "duration": 300000,
        "fileSize": 2048000
      },
      {
        "id": 123457,
        "externalUserId": "EMP001",
        "consultantPhone": "13800138000",
        "consultantName": "张三",
        "fileUrl": "https://example.com/audio/123457.mp3",
        "startTime": "2025-01-15 14:00:00",
        "endTime": "2025-01-15 14:10:00",
        "duration": 600000,
        "fileSize": 4096000
      }
    ]
  }
}

业务逻辑

1. 通过员工手机号直接查询该员工的录音
2. 可选：通过时间范围筛选特定日期的录音
3. 返回录音列表，包含录音ID用于后续获取ASR文本
4. 录音URL有效期为7天，过期需重新获取

使用场景

这是获取员工对话记录的核心接口

1. 按手机号查询员工录音 - 最常用的场景
2. 时间范围筛选 - 获取指定日期的录音
3. 获取最近N条对话 - 配合时间排序实现
4. 员工能力评估 - 获取录音后调用ASR分析，传递给Dify工作流

完整业务流程

获取员工最近N条对话记录

# 1. 调用此接口获取员工录音列表
audios = get_employee_audios(
    consultant_phone="13800138000",
    audio_start_date="2024-10-01"
)

# 2. 按时间倒序排序
audios.sort(key=lambda x: x['startTime'], reverse=True)

# 3. 取前N条
recent_audios = audios[:10]

# 4. 对每条录音获取ASR文本
for audio in recent_audios:
    asr_result = get_audio_asr_result(audio['id'])
    # 组合成完整对话记录
    conversation = {
        'audio_id': audio['id'],
        'consultant_phone': audio['consultantPhone'],
        'consultant_name': audio['consultantName'],
        'start_time': audio['startTime'],
        'duration': audio['duration'],
        'conversation': asr_result.get('result', [])
    }

传递给Dify工作流

# 5. 转换为Dify陪练工作流格式
dialogue_history = []
for msg in conversation['conversation']:
    dialogue_history.append({
        'speaker': 'user' if msg['role'] == 'consultant' else 'ai',
        'content': msg['text'],
        'timestamp': calculate_timestamp(
            conversation['start_time'], 
            msg['begin_time']
        )
    })

# 6. 调用Dify陪练分析工作流
analysis_result = await dify_service.analyze_practice_session(
    dialogue_history=dialogue_history
)

错误码

code	msg	说明
0	success	成功
400	顾问手机号和三方员工ID不能同时为空	必须传入手机号或员工ID
1002	未授权	access_token无效或过期

关键优势

vs 其他方案

方案	步骤	效率
此接口	1步：手机号→录音列表	✅ 最优
通过来访单ID	3步：业务系统→来访单ID→录音	❌ 需要外部数据
通过客户ID	3步：客户ID→来访单→录音	❌ 需要额外维护

为什么是最佳方案

1. ✅ 直接查询：一个接口直接获取员工录音，无需中间步骤
2. ✅ 手机号匹配：天然支持手机号匹配，符合业务需求
3. ✅ 时间筛选：支持按日期筛选，获取最近对话
4. ✅ 完整信息：返回录音ID、员工信息、时间信息

注意事项

1. 手机号和员工ID必传其一：不能两者都为空
2. 录音URL有效期7天：过期需重新调用获取新URL
3. 时间范围建议：不建议查询超过30天的数据
4. 未绑定录音：此接口获取"未绑定来访单的录音"，即员工的所有录音记录

实施建议

立即行动

1. 获取真实员工手机号：从贵阳曼尼斐绮门店获取1-2个真实员工手机号
2. 验证接口调用：使用真实手机号测试接口，确认能获取录音列表
3. 检查ASR数据：确认录音是否有对应的ASR分析结果

代码实现

在YanjiService中实现：

async def get_employee_audios_by_phone(
    self,
    consultant_phone: str,
    start_date: str = None,
    limit: int = 10
) -> List[Dict]:
    """
    根据员工手机号获取录音信息
    
    Args:
        consultant_phone: 员工手机号
        start_date: 起始日期（可选，格式：2024-10-01）
        limit: 返回数量限制
    
    Returns:
        录音信息列表，按时间倒序
    """
    payload = {
        "estateId": self.estate_id,
        "consultantPhone": consultant_phone
    }
    
    if start_date:
        payload["audioStartDate"] = start_date
    
    data = await self._request(
        method="POST",
        path="/api/beauty/v1/audio/infos",
        json_data=payload
    )
    
    if data is None:
        return []
    
    records = data.get("records", [])
    
    # 按时间倒序排序
    records.sort(key=lambda x: x.get('startTime', ''), reverse=True)
    
    # 限制返回数量
    return records[:limit]

---

文档版本：v1.0
最后更新：2025-10-15