998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
428 lines
10 KiB
Markdown
428 lines
10 KiB
Markdown
# 言迹智能工牌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+条录音
|
||
**参数**:
|
||
```json
|
||
{
|
||
"estateId": 516799468310364162,
|
||
"consultantPhone": "13708515779"
|
||
}
|
||
```
|
||
|
||
**返回数据**:
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**原因分析**:
|
||
1. 录音时长较短（4-15秒）
|
||
2. 租户可能未开启ASR分析功能
|
||
3. 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
|
||
**说明**: 获取话术匹配结果（销讲、挖需、风控、标签）
|
||
|
||
**返回数据示例**:
|
||
```json
|
||
{
|
||
"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生成的咨询总结文本
|
||
|
||
**返回数据示例**:
|
||
```json
|
||
[{
|
||
"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工作流分析
|
||
```
|
||
|
||
### 💡 关键技术洞察
|
||
|
||
1. **言迹的数据模型**:
|
||
- 核心是"来访单"（Visit），不是录音
|
||
- 录音需要绑定到来访单才能分析
|
||
- 未绑定的录音只能获取音频文件
|
||
|
||
2. **ASR分析触发条件**:
|
||
- 可能需要录音绑定到来访单
|
||
- 可能需要手动触发或满足时长要求
|
||
- 当前租户所有录音都未做ASR
|
||
|
||
3. **录音文件特性**:
|
||
- 格式：MP3, 40kbps, 16kHz
|
||
- 单声道，适合语音识别
|
||
- URL有效期：7天
|
||
- 音质：良好
|
||
|
||
---
|
||
|
||
## 八、推荐实施方案
|
||
|
||
### 方案A：本地ASR转写（强烈推荐⭐⭐⭐⭐⭐）
|
||
|
||
**技术栈**:
|
||
- OpenAI Whisper（免费，开源，准确率高）
|
||
- 或腾讯云/阿里云语音识别
|
||
|
||
**优势**:
|
||
- ✅ 不依赖言迹ASR功能
|
||
- ✅ 完全可控，质量稳定
|
||
- ✅ 支持多种语言和方言
|
||
- ✅ 可定制化（说话人分离、标点等）
|
||
|
||
**实施步骤**:
|
||
```python
|
||
1. 调用 /api/beauty/v1/audio/infos 获取录音列表
|
||
2. 下载 fileUrl 对应的MP3文件
|
||
3. 调用 Whisper API 转写
|
||
4. 格式化为对话文本（销售+客户）
|
||
5. 发送到 Dify 陪练分析工作流
|
||
```
|
||
|
||
---
|
||
|
||
### 方案B：等待言迹ASR + Webhook（长期方案）
|
||
|
||
**前置条件**:
|
||
1. 联系言迹开启ASR分析服务
|
||
2. 配置Webhook接收ASR完成事件
|
||
3. 或定期轮询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）
|
||
|
||
---
|
||
|
||
## 十、下一步行动建议
|
||
|
||
### 立即可做（优先级：高）
|
||
|
||
1. ✅ 集成Whisper进行本地ASR转写
|
||
2. ✅ 实现完整的数据获取和分析链路
|
||
3. ✅ 测试Dify工作流分析效果
|
||
4. ✅ 实现员工手机号自动匹配
|
||
|
||
### 并行进行（优先级：中）
|
||
|
||
1. 联系言迹技术支持，咨询ASR服务开通
|
||
2. 探索来访单同步方案（如果需要AI分析结果）
|
||
3. 配置Webhook接收实时事件推送
|
||
|
||
### 未来优化（优先级：低）
|
||
|
||
1. 对接言迹来访单系统
|
||
2. 使用言迹原生AI分析结果
|
||
3. 实现说话人自动分离
|
||
|
||
---
|
||
|
||
## ✅ 结论
|
||
|
||
**言迹智能工牌集成完全可行！**
|
||
|
||
虽然ASR分析功能当前不可用，但我们成功获取了：
|
||
- ✅ 完整的员工信息（支持手机号匹配）
|
||
- ✅ 真实的录音文件（音质良好，可下载）
|
||
- ✅ 完整的录音元数据
|
||
|
||
**推荐立即采用"本地Whisper转写方案"**，实现端到端功能，后续可根据需要优化为混合方案。
|
||
|
||
---
|
||
|
||
## 附录：测试命令记录
|
||
|
||
### 获取Token
|
||
```bash
|
||
curl -X GET "https://open.yanjiai.com/oauth/token?grant_type=client_credentials&client_id=1Fld4LCWt2vpJNG5&client_secret=XE8w413qNtJBOdWc2aCezV0yMIHpUuTZ"
|
||
```
|
||
|
||
### 获取员工列表
|
||
```bash
|
||
curl -X GET "https://open.yanjiai.com/api/wangke/v1/device/list?estateId=516799468310364162" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
### 获取录音列表
|
||
```bash
|
||
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"}'
|
||
```
|
||
|
||
### 下载录音文件
|
||
```bash
|
||
curl -L "$AUDIO_URL" -o yanji_audio.mp3
|
||
```
|
||
|
||
### 获取ASR结果
|
||
```bash
|
||
curl -X GET "https://open.yanjiai.com/api/beauty/v1/audio/asr-analysed?estateId=516799468310364162&audioId=$AUDIO_ID" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|