012-kaopeilian/docs/规划/全链路联调/言迹智能工牌/真实数据获取报告.md

# 言迹真实数据获取报告

## 📅 日期：2025-10-15

## ✅ 成功获取的数据

### 1. 员工信息数据（27人）

**接口**：`GET /api/wangke/v1/device/list`

**数据样本**：
```json
{
  "estateId": 516799468310364162,
  "tenantId": 516799409476866048,
  "deviceId": "XX:XX:XX:XX:XX:XX",
  "phone": "13708515779",
  "userName": "熊媱媱",
  "openId": "1900506936382013442",
  "createTime": "2024-12-11 16:25:34"
}
```

**关键字段**：
- `phone`：员工手机号（可用于匹配系统用户）
- `userName`：员工姓名
- `openId`：员工唯一标识

**员工列表**（部分）：
1. 陈谊 - 15329451271
2. 熊媱媱 - 13708515779（录音最多）
3. 黄雪 - 19192552551
4. 夏雨沫 - 13698554507
5. 张永梅 - 13608562128
... 共27人

---

### 2. 录音文件数据

**接口**：`POST /api/beauty/v1/audio/infos`

**请求参数**：
```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/zadig-prod-1308228548/516799409476866048/2025/10/14/fcf3bd06-2c2c-46e9-a60e-e2755c8dd3ca.mp3?X-Amz-..."
    }
  ]
}
```

**关键发现**：
- ✅ `fileUrl`：录音文件下载地址（7天有效期）
- ✅ `duration`：录音时长（毫秒）
- ✅ `fileSize`：文件大小（字节）
- ✅ `startTime/endTime`：录音时间范围

---

### 3. 真实录音文件

**已下载样本**：
1. **样本1**：`样本录音-熊媱媱-5秒.mp3`
   - 时长：5秒
   - 大小：20KB
   - 格式：MP3, 40kbps, 16kHz, 单声道
   - 录音时间：2025-10-14 11:16:19

2. **样本2**：`样本录音-熊媱媱-15秒.mp3`
   - 时长：15秒
   - 大小：54KB
   - 格式：MP3, 40kbps, 16kHz, 单声道
   - 录音时间：2025-06-17 13:23:58

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

**音频规格**：
- 编码：MPEG ADTS, layer III, v2
- 比特率：40 kbps
- 采样率：16 kHz
- 声道：单声道（Monaural）
- 元数据：ID3 v2.4.0

---

## ❌ 无法获取的数据

### ASR分析结果（对话文本）

**接口**：`GET /api/beauty/v1/audio/asr-analysed`

**测试结果**：所有录音返回 `data: null`

**原因分析**：
1. 录音时长较短（4-15秒），可能未达到ASR分析阈值
2. 租户可能未开启ASR分析功能
3. ASR分析需要手动触发或满足特定条件

**测试范围**：
- 测试了27个员工的录音
- 包括最新录音和最早录音（2025-04-24）
- 总计测试超过19条录音
- **结果**：全部返回 `data: null`

---

## 🎯 解决方案

### 方案1：使用本地ASR转写（推荐⭐⭐⭐）

**工具选择**：
- **OpenAI Whisper**（免费，准确率高，支持中文）
- 阿里云语音识别
- 腾讯云语音识别

**实施步骤**：
1. 从言迹API获取录音文件URL
2. 下载录音文件到临时目录
3. 调用Whisper API转写
4. 格式化为对话文本
5. 发送到Dify工作流分析

**Whisper集成示例**：
```python
import whisper
import httpx

async def transcribe_yanji_audio(audio_url: str) -> str:
    """使用Whisper转写言迹录音"""
    # 1. 下载录音
    async with httpx.AsyncClient() as client:
        response = await client.get(audio_url)
        audio_file = "/tmp/temp_audio.mp3"
        with open(audio_file, "wb") as f:
            f.write(response.content)
    
    # 2. Whisper转写
    model = whisper.load_model("base")
    result = model.transcribe(audio_file, language="zh")
    
    return result["text"]
```

**优势**：
- ✅ 完全独立，不依赖言迹ASR
- ✅ 可控制转写质量
- ✅ 支持更多语言和场景

---

### 方案2：联系言迹开启ASR服务

**行动计划**：
1. 联系言迹技术支持
2. 询问ASR服务开通条件
3. 请求手动触发历史录音的ASR分析
4. 了解ASR分析的触发条件

**联系方式**：
- 查看飞书文档中的技术支持联系方式
- 通过开放平台工单系统

---

### 方案3：混合方案（最佳⭐⭐⭐⭐⭐）

**策略**：
1. 优先使用言迹ASR结果（如果有）
2. 如果ASR为null，自动调用本地Whisper转写
3. 缓存转写结果，避免重复转写

**流程图**：
```
获取录音列表
    ↓
尝试获取ASR结果
    ↓
ASR有数据？ ──是→ 使用言迹ASR
    ↓否
下载录音文件
    ↓
Whisper转写
    ↓
格式化对话文本
    ↓
发送到Dify分析
```

---

## 📊 数据统计

| 数据类型 | 获取状态 | 数量 | 可用性 |
|---------|---------|------|--------|
| 员工信息 | ✅ 成功 | 27人 | 100% |
| 录音列表 | ✅ 成功 | 19+条 | 100% |
| 录音文件 | ✅ 成功 | 可下载 | 100% |
| ASR文本 | ❌ 无数据 | 0条 | 0% |

---

## 🚀 下一步行动

### 立即可做（推荐）：
1. ✅ 已获取真实录音文件
2. 🔄 集成Whisper进行本地转写
3. 🔄 实现完整的数据获取链路
4. 🔄 测试Dify工作流分析

### 并行进行：
1. 联系言迹询问ASR服务
2. 探索是否有其他接口可获取对话文本
3. 了解咨询总结接口的使用场景

---

## 💡 关键发现

1. **录音获取完全可行**：
   - 可按员工手机号获取录音列表
   - 录音文件URL 7天有效，可直接下载
   - 音频质量良好（16kHz单声道）

2. **ASR分析未启用**：
   - 所有录音都没有ASR分析结果
   - 可能是租户配置问题
   - 不影响核心功能实现

3. **本地转写完全可行**：
   - Whisper模型成熟稳定
   - 16kHz采样率适合语音识别
   - 可实现端到端闭环

---

## ✅ 结论

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

虽然ASR分析结果为空，但我们成功获取了：
- ✅ 完整的员工信息（支持手机号匹配）
- ✅ 真实的录音文件（可下载，音质良好）
- ✅ 完整的录音元数据（时间、时长、员工信息）

**建议采用混合方案**：优先使用言迹ASR，降级到本地Whisper，确保系统稳定可用。