admin/012-kaopeilian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 初始化考培练系统项目

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

技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
2026-01-24 19:33:28 +08:00
commit 998211c483
1197 changed files with 228429 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

296
docs/规划/全链路联调/言迹智能工牌/API接口测试清单.md Normal file
View File

@@ -0,0 +1,296 @@
# 言迹智能工牌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实现实时推送
### 📊 可行性评估
- **技术可行性**：⭐⭐⭐⭐⭐（完全可行）
- **数据可用性**：⭐⭐⭐⭐⭐（录音质量良好）
- **实施复杂度**：⭐⭐⭐☆☆（中等）
- **预期效果**：⭐⭐⭐⭐⭐（可实现完整闭环）