Files

- 从服务器拉取完整代码
- 按框架规范整理项目结构
- 配置 Drone CI 测试环境部署
- 包含后端(FastAPI)、前端(Vue3)、管理端

技术栈: Vue3 + TypeScript + FastAPI + MySQL

2026-01-24 19:33:28 +08:00

10 KiB

Raw Blame History

言迹智能工牌API完整测试报告

📅 测试日期：2025-10-15

🏢 测试租户：贵阳曼尼斐绮

一、OAuth认证接口

✅ 授权认证

接口: GET /oauth/token
状态: ✅ 成功
说明: OAuth2.0认证正常，Token获取成功

二、通讯录接口

1.3 获取租户员工

接口: GET /api/wangke/v1/device/list
状态: ✅ 成功
数据量: 27个员工
关键数据:

✅ 员工手机号（phone）
✅ 员工姓名（userName）
✅ 员工openId

价值: ⭐⭐⭐⭐⭐ 核心接口，提供手机号匹配基础

三、录音相关接口

4.5 获取员工未绑定录音信息 ⭐核心接口⭐

接口: POST /api/beauty/v1/audio/infos
状态: ✅ 成功
数据量: 19+条录音
参数:

{
  "estateId": 516799468310364162,
  "consultantPhone": "13708515779"
}

返回数据:

{
  "records": [{
    "id": 1977936576392384514,
    "consultantPhone": "13708515779",
    "consultantName": "熊媱媱",
    "startTime": "2025-10-14 11:16:19",
    "endTime": "2025-10-14 11:16:24",
    "duration": 5000,
    "fileSize": 20529,
    "fileUrl": "https://oss.wangxiaobao.com/...mp3?X-Amz-..."
  }]
}

关键发现:

✅ fileUrl: 录音文件可直接下载（7天有效）
✅ 音频格式：MP3, 40kbps, 16kHz, 单声道
✅ 音质良好，适合ASR转写

价值: ⭐⭐⭐⭐⭐ 最核心接口，提供真实录音文件

4.8 获取录音ASR分析结果

接口: GET /api/beauty/v1/audio/asr-analysed
状态: ❌ 无数据
测试范围: 27个员工，19+条录音
返回结果: 全部返回 data: null

原因分析:

录音时长较短（4-15秒）
租户可能未开启ASR分析功能
ASR分析需要特定触发条件

价值: ❌ 当前不可用

4.4 获取来访录音信息

接口: POST /api/beauty/v1/visit/audios
状态: ⚠️ 需要externalVisitId
说明: 需要先有来访单ID才能调用

价值: ⚠️ 依赖来访单系统

4.6 获取录音详情页地址

接口: GET /api/beauty/v1/audio/detail-url
状态: ❌ Invalid path
说明: 该路径在正式环境中不存在

四、来访单相关接口

4.1 新增同步来访单

接口: POST /api/beauty/v1/visit/create
状态: ⚠️ 未测试（写入接口）
说明: 外部系统向言迹同步来访单

用途: 需要先同步来访单，才能使用后续分析接口

4.2 批量获取来访单分析结果

接口: GET /api/beauty/v1/visit/analyze-tags
状态: ⚠️ 需要externalVisitIds
说明: 获取话术匹配结果（销讲、挖需、风控、标签）

返回数据示例:

{
  "externalVisitId": "xxx",
  "result": [{
    "modelName": "销讲模型",
    "modelCategory": 1,
    "dimensionName": "开场白",
    "speechName": "礼貌问候"
  }],
  "missedResult": []
}

价值: ⭐⭐⭐⭐ 如果有来访单ID，可获得AI分析结果

4.3 游标获取来访单分析结果

接口: POST /api/beauty/v1/visit/analyze-tags/cursor
状态: ❌ Invalid path
说明: 该路径在正式环境中不存在

4.7 获取客户来访列表

接口: GET /api/beauty/v1/visit/by-customer
状态: ⚠️ 需要thirdCustomerId
说明: 根据顾客ID获取来访记录

参数:

estateId: 项目ID（必填）
thirdCustomerId: 三方顾客ID（必填）
visitTimeStart: 来访开始时间（可选）
visitTimeEnd: 来访结束时间（可选）

价值: ⚠️ 需要先有顾客系统对接

4.11 批量获取来访单咨询总结

接口: GET /api/beauty/v1/visit/white-desc
状态: ⚠️ 需要externalVisitIds
说明: 获取AI生成的咨询总结文本

返回数据示例:

[{
  "externalVisitId": "xxx",
  "whiteDesc": "客户对面部护理项目感兴趣，主要关注价格和效果..."
}]

价值: ⭐⭐⭐⭐⭐ 如果有来访单ID，可直接获取AI总结

五、事件推送接口（Webhook）

5.1 来访分析完成（事件）

说明: 当来访单分析完成时，言迹主动推送
eventType: aivoice.visit.analyzed

5.2 来访分析完成-推送咨询总结（事件）

说明: 推送咨询总结内容

5.3 录音ASR分析完成（事件）

说明: 当录音ASR分析完成时推送
eventType: aivoice.audio.asr.analyzed

5.4 来访记录加解绑（事件）

说明: 录音与来访单绑定/解绑时推送

5.5 来访分析完成汇总（事件）

说明: 汇总分析结果推送

价值: ⭐⭐⭐⭐ 适合实时数据同步场景

六、API测试总结

✅ 可用接口（5个）

接口	功能	数据量	价值
OAuth认证	获取访问令牌	-	⭐⭐⭐⭐⭐
获取租户员工	员工列表+手机号	27人	⭐⭐⭐⭐⭐
获取录音信息	录音列表+下载URL	19+条	⭐⭐⭐⭐⭐
录音文件下载	真实MP3文件	可用	⭐⭐⭐⭐⭐
批量获取分析结果	AI话术分析	需来访单ID	⭐⭐⭐⭐

❌ 不可用/无数据接口（3个）

接口	原因
ASR分析结果	全部返回null
录音详情页地址	Invalid path
游标获取分析结果	Invalid path

⚠️ 需要前置条件接口（4个）

接口	所需条件
获取来访录音	externalVisitId
客户来访列表	thirdCustomerId
咨询总结	externalVisitId
批量分析结果	externalVisitIds

七、核心发现

🎯 最有价值的数据流

1. 获取租户员工列表（含手机号）
   ↓
2. 根据手机号获取录音列表
   ↓
3. 下载录音文件（MP3）
   ↓
4. 本地Whisper转写 ←[当前可行方案]
   ↓
5. 发送到Dify工作流分析

💡 关键技术洞察

言迹的数据模型:
- 核心是"来访单"（Visit），不是录音
- 录音需要绑定到来访单才能分析
- 未绑定的录音只能获取音频文件
ASR分析触发条件:
- 可能需要录音绑定到来访单
- 可能需要手动触发或满足时长要求
- 当前租户所有录音都未做ASR
录音文件特性:
- 格式：MP3, 40kbps, 16kHz
- 单声道，适合语音识别
- URL有效期：7天
- 音质：良好

八、推荐实施方案

方案A：本地ASR转写（强烈推荐⭐⭐⭐⭐⭐）

技术栈:

OpenAI Whisper（免费，开源，准确率高）
或腾讯云/阿里云语音识别

优势:

✅ 不依赖言迹ASR功能
✅ 完全可控，质量稳定
✅ 支持多种语言和方言
✅ 可定制化（说话人分离、标点等）

实施步骤:

1. 调用 /api/beauty/v1/audio/infos 获取录音列表
2. 下载 fileUrl 对应的MP3文件
3. 调用 Whisper API 转写
4. 格式化为对话文本（销售+客户）
5. 发送到 Dify 陪练分析工作流

方案B：等待言迹ASR + Webhook（长期方案）

前置条件:

联系言迹开启ASR分析服务
配置Webhook接收ASR完成事件
或定期轮询ASR结果

优势:

✅ 使用言迹原生ASR
✅ 可能包含说话人识别
✅ 实时推送，及时性好

劣势:

❌ 依赖言迹服务状态
❌ 需要额外配置
❌ 当前不可用

方案C：混合方案（最佳⭐⭐⭐⭐⭐）

策略: 优先级降级

IF 言迹ASR有数据 THEN
    使用言迹ASR结果
ELSE
    调用本地Whisper转写
END IF

优势:

✅ 充分利用言迹ASR（如果可用）
✅ 保证100%可用性
✅ 灵活适应不同场景

九、已获取的真实数据

样本录音文件

文件	时长	大小	员工	日期
样本录音-熊媱媱-5秒.mp3	5秒	20KB	熊媱媱	2025-10-14
样本录音-熊媱媱-15秒.mp3	15秒	54KB	熊媱媱	2025-06-17

文件位置:

考培练系统规划/全链路联调/言迹智能工牌/
├── 样本录音-熊媱媱-5秒.mp3
└── 样本录音-熊媱媱-15秒.mp3

员工数据

共27个员工，包含：

手机号（可用于系统用户匹配）
姓名
openId（言迹唯一标识）

录音元数据

19+条录音记录，包含：

录音ID
员工信息（手机号、姓名）
时间信息（开始、结束、时长）
文件信息（大小、下载URL）

十、下一步行动建议

立即可做（优先级：高）

✅ 集成Whisper进行本地ASR转写
✅ 实现完整的数据获取和分析链路
✅ 测试Dify工作流分析效果
✅ 实现员工手机号自动匹配

并行进行（优先级：中）

联系言迹技术支持，咨询ASR服务开通
探索来访单同步方案（如果需要AI分析结果）
配置Webhook接收实时事件推送

未来优化（优先级：低）

对接言迹来访单系统
使用言迹原生AI分析结果
实现说话人自动分离

✅ 结论

言迹智能工牌集成完全可行！

虽然ASR分析功能当前不可用，但我们成功获取了：

✅ 完整的员工信息（支持手机号匹配）
✅ 真实的录音文件（音质良好，可下载）
✅ 完整的录音元数据

推荐立即采用"本地Whisper转写方案"，实现端到端功能，后续可根据需要优化为混合方案。

附录：测试命令记录

获取Token

curl -X GET "https://open.yanjiai.com/oauth/token?grant_type=client_credentials&client_id=1Fld4LCWt2vpJNG5&client_secret=XE8w413qNtJBOdWc2aCezV0yMIHpUuTZ"

获取员工列表

curl -X GET "https://open.yanjiai.com/api/wangke/v1/device/list?estateId=516799468310364162" \
  -H "Authorization: Bearer $TOKEN"

获取录音列表

curl -X POST "https://open.yanjiai.com/api/beauty/v1/audio/infos" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"estateId": 516799468310364162, "consultantPhone": "13708515779"}'

下载录音文件

curl -L "$AUDIO_URL" -o yanji_audio.mp3

获取ASR结果

curl -X GET "https://open.yanjiai.com/api/beauty/v1/audio/asr-analysed?estateId=516799468310364162&audioId=$AUDIO_ID" \
  -H "Authorization: Bearer $TOKEN"

10 KiB Raw Blame History Unescape Escape