# 言迹智能工牌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"
```