998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
297 lines
8.4 KiB
Markdown
297 lines
8.4 KiB
Markdown
# 言迹智能工牌API接口测试清单
|
||
|
||
## 测试日期：2025-10-15
|
||
## 测试租户：贵阳曼尼斐绮
|
||
|
||
---
|
||
|
||
## 接口测试状态统计
|
||
|
||
| 状态 | 数量 | 说明 |
|
||
|------|------|------|
|
||
| ✅ 成功可用 | 4个 | 可获取真实数据 |
|
||
| ❌ 无数据/失败 | 4个 | 返回空或错误 |
|
||
| ⚠️ 需前置条件 | 5个 | 需要来访单ID等 |
|
||
| 🔄 未测试 | 5个 | 写入/推送类接口 |
|
||
|
||
---
|
||
|
||
## 一、OAuth认证（1个）
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 授权认证 | GET | /oauth/token | ✅ | 获取access_token成功 |
|
||
|
||
---
|
||
|
||
## 二、通讯录接口（3个）
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 1.1 添加租户员工 | POST | /api/wangke/v1/user | 🔄 | 未测试（写入接口） |
|
||
| 1.2 添加项目成员 | POST | /api/wangke/v1/estate/user | 🔄 | 未测试（写入接口） |
|
||
| 1.3 获取租户员工 | GET | /api/wangke/v1/device/list | ✅ | **27个员工，含手机号** |
|
||
|
||
---
|
||
|
||
## 三、顾客中心接口（1个）
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 2.1 批量同步顾客 | POST | /api/beauty/v1/customer/batch | 🔄 | 未测试（写入接口） |
|
||
|
||
---
|
||
|
||
## 四、设备中心接口（3个）
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 3.1 开始记录 | POST | /api/wangke/v1/device/start | 🔄 | 未测试（控制接口） |
|
||
| 3.2 停止记录 | POST | /api/wangke/v1/device/stop | 🔄 | 未测试（控制接口） |
|
||
| 3.3 获取项目下工牌数据 | GET | /api/wangke/v1/device/list | ✅ | 同1.3，返回员工信息 |
|
||
|
||
---
|
||
|
||
## 五、言迹工牌对外接口（11个）
|
||
|
||
### 5.1 来访单相关（6个）
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 4.1 新增同步来访单 | POST | /api/beauty/v1/visit/create | 🔄 | 未测试（写入接口） |
|
||
| 4.2 批量获取来访单分析结果 | GET | /api/beauty/v1/visit/analyze-tags | ⚠️ | 需要externalVisitIds |
|
||
| 4.3 游标获取来访单分析结果 | POST | /api/beauty/v1/visit/analyze-tags/cursor | ❌ | Invalid path |
|
||
| 4.7 获取客户来访列表 | GET | /api/beauty/v1/visit/by-customer | ⚠️ | 需要thirdCustomerId |
|
||
| 4.9 更新来访单主销 | PUT | /api/beauty/v1/visit/consultant | ⚠️ | 未测试（写入接口） |
|
||
| 4.11 批量获取来访单咨询总结 | GET | /api/beauty/v1/visit/white-desc | ⚠️ | 需要externalVisitIds |
|
||
|
||
### 5.2 录音相关（5个）
|
||
|
||
| 接口 | 方法 | 路径 | 状态 | 说明 |
|
||
|------|------|------|------|------|
|
||
| 4.4 获取来访录音信息 | POST | /api/beauty/v1/visit/audios | ⚠️ | 需要externalVisitIds |
|
||
| 4.5 获取员工未绑定录音信息 | POST | /api/beauty/v1/audio/infos | ✅ | **19+条录音，含下载URL** |
|
||
| 4.6 获取录音详情页地址 | GET | /api/beauty/v1/audio/detail-url | ❌ | Invalid path |
|
||
| 4.8 获取录音ASR分析结果 | GET | /api/beauty/v1/audio/asr-analysed | ❌ | 全部返回null |
|
||
| 4.10 绑定录音与来访单 | POST | /api/beauty/v1/visit/audio/bind | ⚠️ | 未测试（写入接口） |
|
||
|
||
---
|
||
|
||
## 六、事件推送接口（5个）
|
||
|
||
| 事件 | eventType | 状态 | 说明 |
|
||
|------|-----------|------|------|
|
||
| 1. 来访分析完成 | aivoice.visit.analyzed | 🔄 | Webhook推送 |
|
||
| 2. 来访分析完成-推送咨询总结 | aivoice.visit.summary | 🔄 | Webhook推送 |
|
||
| 3. 录音ASR分析完成 | aivoice.audio.asr.analyzed | 🔄 | Webhook推送 |
|
||
| 4. 来访记录加解绑 | aivoice.visit.bind | 🔄 | Webhook推送 |
|
||
| 5. 来访分析完成汇总 | aivoice.visit.summary.batch | 🔄 | Webhook推送 |
|
||
|
||
---
|
||
|
||
## 详细测试结果
|
||
|
||
### ✅ 成功可用的接口（4个）
|
||
|
||
#### 1. OAuth认证
|
||
```bash
|
||
curl -X GET "https://open.yanjiai.com/oauth/token?grant_type=client_credentials&client_id=1Fld4LCWt2vpJNG5&client_secret=XE8w413qNtJBOdWc2aCezV0yMIHpUuTZ"
|
||
```
|
||
**返回**：access_token, expires_in
|
||
|
||
---
|
||
|
||
#### 2. 获取租户员工（核心接口⭐⭐⭐⭐⭐）
|
||
```bash
|
||
curl -X GET "https://open.yanjiai.com/api/wangke/v1/device/list?estateId=516799468310364162" \
|
||
-H "Authorization: Bearer $TOKEN"
|
||
```
|
||
**返回**：
|
||
- 27个员工
|
||
- 每个员工含：phone, userName, openId
|
||
- **关键价值**：手机号可用于匹配系统用户
|
||
|
||
---
|
||
|
||
#### 3. 获取员工录音信息（核心接口⭐⭐⭐⭐⭐）
|
||
```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"
|
||
}'
|
||
```
|
||
**返回**：
|
||
- 录音列表（records数组）
|
||
- 每条录音含：id, fileUrl, duration, startTime, endTime
|
||
- **关键价值**：fileUrl可直接下载MP3文件
|
||
|
||
---
|
||
|
||
#### 4. 下载录音文件
|
||
```bash
|
||
curl -L "$AUDIO_URL" -o audio.mp3
|
||
```
|
||
**结果**：
|
||
- 格式：MP3, 40kbps, 16kHz, 单声道
|
||
- 音质良好，适合ASR
|
||
- **已下载样本**：5秒和15秒录音
|
||
|
||
---
|
||
|
||
### ❌ 无数据/失败的接口（4个）
|
||
|
||
| 接口 | 原因 | 测试范围 |
|
||
|------|------|----------|
|
||
| 4.8 获取ASR结果 | 全部返回data: null | 测试了27个员工，19+条录音 |
|
||
| 4.6 录音详情页地址 | Invalid path | - |
|
||
| 4.3 游标获取分析结果 | Invalid path | - |
|
||
| 其他list/page接口 | Invalid path | - |
|
||
|
||
---
|
||
|
||
### ⚠️ 需前置条件的接口（5个）
|
||
|
||
| 接口 | 所需参数 | 获取方式 |
|
||
|------|----------|----------|
|
||
| 4.2 批量获取分析结果 | externalVisitIds | 需先调用4.1同步来访单 |
|
||
| 4.4 获取来访录音 | externalVisitIds | 需先调用4.1同步来访单 |
|
||
| 4.7 获取客户来访列表 | thirdCustomerId | 需先调用2.1同步顾客 |
|
||
| 4.10 绑定录音与来访单 | audioIds, externalVisitId | 需先有来访单 |
|
||
| 4.11 批量获取咨询总结 | externalVisitIds | 需先调用4.1同步来访单 |
|
||
|
||
---
|
||
|
||
## 核心发现
|
||
|
||
### 1. 数据模型依赖关系
|
||
|
||
```
|
||
外部系统
|
||
↓ 4.1 同步来访单
|
||
来访单（Visit）
|
||
↓ 4.10 绑定录音
|
||
录音（Audio）
|
||
↓ ASR分析
|
||
对话文本（ASR Result）
|
||
↓ AI分析
|
||
分析结果（Tags/Summary）
|
||
```
|
||
|
||
### 2. 当前可用的数据流
|
||
|
||
```
|
||
获取员工列表（含手机号）
|
||
↓
|
||
根据手机号获取录音列表
|
||
↓
|
||
下载录音文件（MP3）
|
||
↓
|
||
[缺失环节：ASR转写]
|
||
↓
|
||
对话文本
|
||
```
|
||
|
||
### 3. 缺失环节的解决方案
|
||
|
||
**方案A：使用本地Whisper** ⭐推荐
|
||
- OpenAI Whisper API
|
||
- 16kHz音频完全适配
|
||
- 免费且准确率高
|
||
|
||
**方案B：等待言迹ASR**
|
||
- 联系言迹开通服务
|
||
- 或配置Webhook接收推送
|
||
|
||
**方案C：使用其他ASR服务**
|
||
- 腾讯云语音识别
|
||
- 阿里云ASR
|
||
- 百度语音识别
|
||
|
||
---
|
||
|
||
## 已获取的真实数据
|
||
|
||
### 员工数据（27人）
|
||
```
|
||
陈谊 - 15329451271
|
||
熊媱媱 - 13708515779（录音最多，14条）
|
||
黄雪 - 19192552551
|
||
夏雨沫 - 13698554507
|
||
张永梅 - 13608562128
|
||
... 共27人
|
||
```
|
||
|
||
### 录音数据（19+条）
|
||
```
|
||
ID: 1977936576392384514
|
||
员工: 熊媱媱 (13708515779)
|
||
时间: 2025-10-14 11:16:19
|
||
时长: 5秒
|
||
大小: 20KB
|
||
URL: https://oss.wangxiaobao.com/...
|
||
```
|
||
|
||
### 样本文件
|
||
```
|
||
考培练系统规划/全链路联调/言迹智能工牌/
|
||
├── 样本录音-熊媱媱-5秒.mp3
|
||
└── 样本录音-熊媱媱-15秒.mp3
|
||
```
|
||
|
||
---
|
||
|
||
## 推荐实施方案
|
||
|
||
### 阶段1：本地ASR转写（1-2天）
|
||
|
||
1. 集成Whisper API
|
||
2. 实现录音下载和转写
|
||
3. 格式化为对话文本
|
||
4. 测试转写准确率
|
||
|
||
### 阶段2：Dify工作流集成（1天）
|
||
|
||
1. 调用现有陪练分析工作流
|
||
2. 适配对话格式
|
||
3. 返回分析结果
|
||
|
||
### 阶段3：系统集成（2-3天）
|
||
|
||
1. 实现员工手机号匹配
|
||
2. 创建API接口
|
||
3. 前端展示分析结果
|
||
4. 缓存机制优化
|
||
|
||
### 阶段4：优化（可选）
|
||
|
||
1. 配置Webhook接收言迹推送
|
||
2. 混合使用言迹ASR+本地Whisper
|
||
3. 实时分析能力
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
### ✅ 已完成
|
||
- [x] 完整测试所有可用API接口
|
||
- [x] 获取真实员工数据（27人）
|
||
- [x] 获取真实录音文件（19+条）
|
||
- [x] 下载样本录音（2个文件）
|
||
- [x] 验证音频格式和质量
|
||
- [x] 确定技术实施方案
|
||
|
||
### 🚀 推荐行动
|
||
1. **立即实施**：集成Whisper进行本地ASR转写
|
||
2. **并行进行**：联系言迹咨询ASR服务开通
|
||
3. **未来优化**：配置Webhook实现实时推送
|
||
|
||
### 📊 可行性评估
|
||
- **技术可行性**：⭐⭐⭐⭐⭐（完全可行）
|
||
- **数据可用性**：⭐⭐⭐⭐⭐（录音质量良好）
|
||
- **实施复杂度**：⭐⭐⭐☆☆（中等）
|
||
- **预期效果**：⭐⭐⭐⭐⭐（可实现完整闭环）
|
||
|