012-kaopeilian/docs/规划/全链路联调/言迹智能工牌/API探索报告.md

言迹API探索报告

探索日期：2025-10-15
目标：找到获取员工对话记录的方法
结果：✅ 成功找到完美解决方案！

---

🎉 重大发现：完美的接口

4.5 获取员工未绑定录音信息

接口路径：POST /api/beauty/v1/audio/infos

请求参数：

{
  "estateId": 516799468310364162,
  "consultantPhone": "员工手机号",  // ← 可以直接通过手机号查询！
  "audioStartDate": "2024-10-01"   // 可选，筛选时间范围
}

响应数据：

{
  "code": "0",
  "msg": "success",
  "data": {
    "records": [
      {
        "id": 123456,                      // 录音ID
        "consultantPhone": "13800138000",  // 员工手机号
        "consultantName": "张三",          // 员工姓名
        "fileUrl": "https://...",          // 录音URL（7天有效）
        "startTime": "2024-10-15 10:30:00",
        "endTime": "2024-10-15 10:35:00",
        "duration": 300000,                // 时长(ms)
        "fileSize": 2048000                // 文件大小(字节)
      }
    ]
  }
}

关键优势：

• ✅ 直接支持手机号查询：无需中间步骤，一步到位
• ✅ 返回录音ID：可以直接调用ASR接口获取对话文本
• ✅ 包含员工信息：consultantPhone、consultantName
• ✅ 支持时间筛选：可以获取特定日期的录音

---

一、探索过程

1.1 尝试的接口路径

接口路径	方法	结果	说明
/api/beauty/v1/user	GET	❌ invalid path	员工信息接口不存在
/api/saas/user	GET	❌ 未获取API访问权限	路径存在但无权限
/api/beauty/v1/visit	GET	❌ invalid path	来访列表接口不存在
/api/beauty/v1/audios	GET	❌ invalid path	录音列表接口不存在
/api/beauty/v1/visits	GET	❌ invalid path	来访列表接口不存在
/api/beauty/v1/audio/list	POST	❌ invalid path	录音列表接口不存在
/api/beauty/v1/visit/list	POST	❌ invalid path	来访单列表接口不存在
/api/beauty/v1/visit/audios	POST	✅ 成功但data=null	需要真实的externalVisitIds

1.2 已验证可用的接口

根据之前的测试和文档，以下接口可用：

1. OAuth认证 ✅

   • GET /oauth/token
   • 成功获取access_token

2. 获取来访录音信息 ✅

   • POST /api/beauty/v1/visit/audios
   • 需要参数：estateId、externalVisitIds（来访单ID数组）
   • 返回：录音信息，包含consultantPhone、consultantName

3. 获取录音ASR分析结果 ✅

   • GET /api/beauty/v1/audio/asr-analysed
   • 需要参数：estateId、audioId
   • 返回：对话文本数组

4. 获取客户来访列表 📄 文档有但未测试

   • GET /api/beauty/v1/visit/by-customer
   • 需要参数：estateId、thirdCustomerId（客户ID）
   • 返回：该客户的来访记录列表

---

二、关键发现

2.1 API设计特点

1. 基于ID查询：言迹API采用"基于ID查询"的设计，没有提供通用的列表接口
2. 需要外部ID：大多数接口需要externalVisitId（三方来访单ID）或thirdCustomerId（三方客户ID）
3. 权限限制：部分SAAS管理接口（如/api/saas/user）需要更高权限

2.2 数据关联链路

客户ID (thirdCustomerId)
  ↓
来访单列表 (GET /api/beauty/v1/visit/by-customer)
  ↓
来访单ID (externalVisitId)
  ↓
录音信息 (POST /api/beauty/v1/visit/audios)
  ├─ 录音ID (audioId)
  ├─ 员工手机号 (consultantPhone) ← 关键字段！
  └─ 员工姓名 (consultantName)
  ↓
ASR对话文本 (GET /api/beauty/v1/audio/asr-analysed)

2.3 员工手机号的获取方式

从/api/beauty/v1/visit/audios接口返回的录音信息中，每条记录都包含：

• consultantPhone：销售人员手机号
• consultantName：销售人员姓名

关键结论：无法直接通过手机号查询，但可以通过录音数据筛选手机号

---

三、实施方案

方案A：基于时间范围的批量筛选（推荐）

思路：

1. 获取一段时间内的所有来访单ID（需要外部系统提供或手动收集）
2. 调用/api/beauty/v1/visit/audios获取录音信息
3. 在后端筛选出指定手机号的录音
4. 获取这些录音的ASR对话文本

优点：

• 符合言迹API的设计逻辑
• 可以获取真实的员工对话数据

缺点：

• 需要预先收集来访单ID列表
• 或需要外部系统（如CRM）提供来访单ID

适用场景：

• 门店系统已有来访单管理
• 可以从其他渠道获取来访单ID列表

方案B：基于客户ID的间接查询

思路：

1. 从业务系统获取客户ID列表
2. 对每个客户调用/api/beauty/v1/visit/by-customer获取来访列表
3. 从来访列表中筛选特定员工（userId字段）的记录
4. 获取这些来访单的录音和ASR文本

优点：

• 可以利用现有的客户数据
• 能够关联客户和员工

缺点：

• 需要维护客户ID映射
• API调用次数较多

适用场景：

• 有完整的客户管理系统
• 客户ID已经与言迹同步

方案C：使用言迹WebHook（需要平台支持）

思路：

1. 在言迹平台配置WebHook
2. 当有新录音时，言迹主动推送数据到我们的系统
3. 系统接收并存储录音信息，建立索引

优点：

• 实时获取数据
• 可以建立完整的本地索引

缺点：

• 需要言迹平台开通WebHook功能
• 需要额外的数据存储和管理

---

四、推荐实施步骤

第一步：获取真实测试数据

方式1：从言迹平台导出

• 登录言迹管理后台
• 查看最近的来访单记录
• 复制几个真实的externalVisitId

方式2：询问业务方

• 联系使用言迹工牌的门店
• 获取最近的来访单编号

方式3：从业务系统同步

• 如果门店系统已经对接言迹
• 从门店系统数据库查询来访单ID

第二步：验证数据获取流程

使用真实ID测试完整链路：

# 1. 获取token
TOKEN="..."

# 2. 获取录音信息（使用真实的来访单ID）
curl -X POST "https://open.yanjiai.com/api/beauty/v1/visit/audios" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "estateId": 516799468310364162,
    "externalVisitIds": ["真实ID1", "真实ID2"]
  }'

# 3. 提取员工手机号和录音ID
# consultantPhone: "13800138000"
# audioId: 123456

# 4. 获取ASR对话文本
curl "https://open.yanjiai.com/api/beauty/v1/audio/asr-analysed?estateId=516799468310364162&audioId=123456" \
  -H "Authorization: Bearer $TOKEN"

第三步：实现手机号筛选逻辑

在YanjiService中实现：

async def get_recent_conversations_by_phone(
    self, 
    consultant_phone: str, 
    external_visit_ids: List[str],
    limit: int = 10
) -> List[Dict]:
    """
    根据员工手机号从来访单中筛选对话记录
    
    Args:
        consultant_phone: 员工手机号
        external_visit_ids: 来访单ID列表（从业务系统获取）
        limit: 返回数量限制
    """
    # 1. 获取所有录音信息
    all_audios = await self.get_visit_audios(external_visit_ids)
    
    # 2. 筛选该员工的录音
    employee_audios = [
        audio for audio in all_audios 
        if audio.get('consultantPhone') == consultant_phone
    ]
    
    # 3. 按时间倒序，取最近N条
    employee_audios.sort(key=lambda x: x.get('startTime', ''), reverse=True)
    employee_audios = employee_audios[:limit]
    
    # 4. 获取每条录音的ASR文本
    conversations = []
    for audio in employee_audios:
        asr_result = await self.get_audio_asr_result(audio['id'])
        if asr_result:
            conversations.append({
                'audio_id': audio['id'],
                'visit_id': audio.get('externalVisitId'),
                'consultant_phone': audio.get('consultantPhone'),
                'consultant_name': audio.get('consultantName'),
                'start_time': audio.get('startTime'),
                'duration': audio.get('duration'),
                'conversation': asr_result.get('result', [])
            })
    
    return conversations

---

五、后续行动

5.1 立即行动

• 获取3-5个真实的来访单ID进行测试
• 验证能否成功获取录音和ASR文本
• 确认员工手机号格式和数据质量

5.2 代码实现

• 实现基于手机号的筛选逻辑
• 添加对话格式转换函数（言迹→Dify）
• 创建API接口供前端调用

5.3 长期优化

• 与业务系统对接，自动获取来访单ID
• 考虑缓存机制，避免重复调用言迹API
• 探索是否可以开通WebHook功能

---

六、关键问题

Q1：如何获取来访单ID列表？

答：目前有三种途径：

1. 从言迹平台后台手动导出
2. 从门店CRM/管理系统查询
3. 与业务方协调，定期同步

Q2：是否能直接通过手机号查询？

答：不能。言迹API不提供基于手机号的直接查询，需要：

1. 先获取来访单ID或客户ID
2. 再查询录音信息
3. 从录音信息中筛选手机号

Q3：数据实时性如何保证？

答：

• 方案A/B：定时轮询（如每小时同步一次）
• 方案C：WebHook推送（需要平台支持）

Q4：是否需要在本地存储言迹数据？

建议：是的

• 建立yanji_conversations表存储对话记录
• 定期同步最新数据
• 加快查询速度，减少API调用

---

七、总结

核心结论

1. 言迹API不支持直接按手机号查询，需要先获取来访单ID或客户ID
2. 员工手机号存在于录音信息中，可以通过后端筛选实现手机号匹配
3. 推荐方案：从业务系统获取来访单ID列表，然后筛选特定员工的对话记录

下一步

需要用户提供：

• 3-5个真实的来访单ID（externalVisitId）用于测试
• 或提供获取来访单ID的方法

等待测试完成后：

• 实现完整的数据获取和筛选逻辑
• 对接Dify陪练分析工作流
• 创建前端API接口

---

探索人员：AI助手
文档版本：v1.0