# 言迹智能工牌API对接文档

## ✅ 实施状态：已完成并测试通过

- **实施日期**：2025-10-15
- **API环境**：正式环境 `https://open.yanjiai.com`
- **OAuth认证**：✅ 成功
- **接口测试**：✅ 全部通过（4/4）
- **代码状态**：✅ 无linter错误

## 概述

言迹智能工牌是一个智能语音记录和分析系统，通过工牌设备录制销售人员与客户的对话，并提供AI分析能力。

**已实现功能：**
- ✅ OAuth2.0认证（含Token缓存机制）
- ✅ 获取来访录音信息
- ✅ 获取录音ASR分析结果（对话文本）
- ✅ 组合接口获取完整对话记录

## ✅ 账户信息（已验证通过）

- **租户名称**：贵阳曼尼斐绮
- **tenantId**：516799409476866048
- **estateId**（项目ID）：516799468310364162
- **clientId**：1Fld4LCWt2vpJNG5
- **clientSecret**：XE8w413qNtJBOdWc2aCezV0yMIHpUuTZ
- **认证状态**：✅ 正式环境认证成功

## 环境地址

- **测试环境**：https://open-test.yanjiai.com/
- **正式环境**：https://open.yanjiai.com/ ✅（当前使用，已验证）

## 接口概述

### 1. 授权认证
- **说明**：OAuth2.0客户端模式，获取access_token
- **文档**：[授权认证.md](./授权认证.md)

### 2. 获取来访录音信息
- **路径**：POST /api/beauty/v1/visit/audios
- **说明**：根据来访单ID批量获取录音信息
- **文档**：[获取来访录音信息.md](./获取来访录音信息.md)

### 3. 获取录音ASR分析结果
- **路径**：GET /api/beauty/v1/audio/asr-analysed
- **说明**：获取录音的语音识别和对话文本
- **文档**：[获取录音ASR分析结果.md](./获取录音ASR分析结果.md)

### 4. 获取客户来访列表
- **路径**：GET /api/beauty/v1/visit/by-customer
- **说明**：根据客户ID获取来访记录列表
- **文档**：[获取客户来访列表.md](./获取客户来访列表.md)

## 业务流程

### 获取员工最近N条对话记录

1. 通过OAuth2.0获取access_token
2. 调用"获取来访录音信息"接口，获取录音列表
3. 对每个录音调用"获取录音ASR分析结果"接口，获取对话文本
4. 组合返回完整的对话记录

## 响应格式规范

所有接口返回格式：

```json
{
  "code": 0,          // 业务码，0表示成功，其他表示失败
  "msg": "success",   // 业务消息
  "data": {}          // 业务数据
}
```

## 认证方式

```
Authorization: Bearer {access_token}
```

## 字符编码

- 使用UTF-8编码
- JSON数据格式
- HTTPS协议（测试环境可使用HTTP）

## 集成目标

1. 获取员工与客户的对话记录
2. 将对话数据传递给Dify工作流进行AI评分
3. 生成员工能力雷达图
4. 推荐学习课程