设备文档更新

diff --git a/code/sdk/zhihui/leiniao/设备API接口文档.md b/code/sdk/zhihui/leiniao/设备API接口文档.md
index 9f3f74e..9e7768f 100644 (file)
--- a/code/sdk/zhihui/leiniao/设备API接口文档.md
+++ b/code/sdk/zhihui/leiniao/设备API接口文档.md
@@ -49,8 +49,8 @@ sequenceDiagram
 | timestamp | String | 是 | 毫秒时间戳 | "1640995200000" |\r
 | nonce | String | 是 | 随机数，用于防重放攻击 | "abc123" |\r
 | signature | String | 是 | 签名，用于验证请求合法性 | "a1b2c3d4..." |\r
-| deviceModel | String | 否 | 设备型号，默认值: "abmybox_1" | "abmybox_1" |\r
-| deviceVersion | String | 否 | 设备固件版本，默认值: "1.0.0" | "1.0.0" |\r
+| deviceModel | String | 是 | 设备型号，默认值: "AB101" | "AB101" |\r
+| deviceVersion | String | 是 | 设备固件版本，默认值: "1.0.0" | "1.0.0" |\r
 \r
 ### 签名算法\r
 签名使用 HMAC-SHA256 算法生成，具体步骤如下：\r
@@ -860,7 +860,7 @@ sequenceDiagram
     Device->>Server: GET /v1/device/getCharacter<br/>Headers: deviceId, deviceToken\r
     \r
     alt 首次开机\r
-        Server->>Device: 返回默认角色信息<br/>{"characterId", "characterName", "characterAvatar", "emotionEmojis"}\r
+        Server->>Device: 返回默认角色信息<br/>{"characterId", "characterName", "characterAvatar"}\r
         Device->>Device: 应用默认角色配置\r
     else 已有角色配置\r
         Server->>Device: 返回用户选择的角色信息\r
@@ -872,7 +872,26 @@ sequenceDiagram
     \r
     alt 设备已绑定用户\r
         Server->>Device: 返回用户ID<br/>{"data": "user_001"}\r
-        Device->>Device: 正常运行模式\r
+        Device->>Device: 进入正常运行模式\r
+        \r
+        %% 获取对话体力和流量信息\r
+        Device->>Server: GET /v1/device/getChatStamina<br/>获取体力和流量状态\r
+        Server->>Server: 查询用户体力和物联网卡流量\r
+        \r
+        alt 体力和流量充足\r
+            Server->>Device: 返回正常状态<br/>{"chatStaminaLeft": 100, "cardFlowLeft": 500}\r
+            Device->>Device: 显示正常状态，允许对话\r
+        else 体力不足\r
+            Server->>Device: 返回体力不足<br/>{"chatStaminaLeft": 5, "chatStaminaDesc": "对话额度不足20轮"}\r
+            Device->>Device: 显示体力不足提示\r
+        else 流量不足\r
+            Server->>Device: 返回流量不足<br/>{"cardFlowLeft": 50, "cardFlowDesc": "流量不足100M了哦"}\r
+            Device->>Device: 显示流量不足提示\r
+        else 会员用户\r
+            Server->>Device: 返回会员状态<br/>{"chatStaminaLeft": -1}\r
+            Device->>Device: 显示会员无限体力状态\r
+        end\r
+        \r
     else 设备未绑定\r
         Server->>Device: 返回空值<br/>{"data": null}\r
         Device->>Device: 显示绑定二维码\r
@@ -1014,6 +1033,150 @@ sequenceDiagram
 |--------|------|\r
 | AUTH_FAILURE | 认证失败（设备ID为空或Token无效） |\r
 \r
+### 4.3 获取对话体力和流量信息\r
+\r
+#### 接口描述\r
+获取对话体力和流量信息接口。返回设备当前的对话体力剩余数量、流量使用情况以及相关说明信息，用于设备端显示用户的使用额度和充值提醒。该接口需要设备Token认证。\r
+\r
+#### 请求信息\r
+- **URL**: `/v1/device/getChatStamina`\r
+- **方法**: `GET`\r
+- **Content-Type**: `application/json`\r
+\r
+#### 认证要求\r
+该接口需要设备Token认证，Token通过请求头传递。\r
+\r
+#### 请求头参数\r
+\r
+| 参数名 | 类型 | 必填 | 描述 | 示例 |\r
+|--------|------|------|------|------|\r
+| deviceId | String | 是 | 设备唯一标识符 | "DEVICE_001" |\r
+| deviceToken | String | 是 | 设备访问令牌 | "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." |\r
+\r
+\r
+#### 响应数据\r
+\r
+**成功响应（普通用户）**：\r
+\r
+```json\r
+{\r
+  "errorCode": null,\r
+  "message": null,\r
+  "data": {\r
+    "chatStaminaLeft": 10,\r
+    "chatStaminaDesc": "对话额度不足20轮，可扫码续充",\r
+    "cardFlowLeft": 80,\r
+    "cardFlowDesc": "流量不足100M了哦，扫码可充值流量",\r
+    "qrcodeUrl": "https://example.com/qrcode/recharge"\r
+  }\r
+}\r
+```\r
+\r
+**成功响应（会员用户）**：\r
+\r
+```json\r
+{\r
+  "errorCode": null,\r
+  "message": null,\r
+  "data": {\r
+    "chatStaminaLeft": -1,\r
+    "chatStaminaDesc": null,\r
+    "cardFlowLeft": 500,\r
+    "cardFlowDesc": null,\r
+    "qrcodeUrl": "https://example.com/qrcode/recharge"\r
+  }\r
+}\r
+```\r
+\r
+**成功响应（体力用完）**：\r
+\r
+```json\r
+{\r
+  "errorCode": null,\r
+  "message": null,\r
+  "data": {\r
+    "chatStaminaLeft": 0,\r
+    "chatStaminaDesc": "啊哦，对话轮数已用完，扫码续上吧",\r
+    "cardFlowLeft": 0,\r
+    "cardFlowDesc": "流量用完了哦",\r
+    "qrcodeUrl": "https://example.com/qrcode/recharge"\r
+  }\r
+}\r
+```\r
+\r
+**失败响应（设备未绑定用户）**：\r
+\r
+```json\r
+{\r
+  "errorCode": "DEVICE_NOT_FOUND",\r
+  "message": "设备信息异常",\r
+  "data": null\r
+}\r
+```\r
+\r
+**失败响应（认证失败）**：\r
+\r
+```json\r
+{\r
+  "errorCode": "AUTH_FAILURE",\r
+  "message": "设备Token无效",\r
+  "data": null\r
+}\r
+```\r
+\r
+#### 响应字段说明\r
+\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| chatStaminaLeft | Integer | 剩余对话体力，-1表示会员无限体力，>=0表示剩余体力值 |\r
+| chatStaminaDesc | String | 对话体力说明文字，当体力充足时为null |\r
+| cardFlowLeft | Integer | 剩余流量（MB） |\r
+| cardFlowDesc | String | 流量说明文字，当流量充足时为null |\r
+| qrcodeUrl | String | 充值二维码链接 |\r
+\r
+#### 体力状态说明\r
+\r
+对话体力的不同状态及对应的提示信息：\r
+\r
+| 体力值 | 状态描述 | 提示信息 |\r
+|--------|----------|----------|\r
+| -1 | 会员无限体力 | 无提示信息 |\r
+| > 20 | 体力充足 | 无提示信息 |\r
+| 1-20 | 体力不足 | "对话额度不足20轮，可扫码续充" |\r
+| 0 | 体力用完 | "啊哦，对话轮数已用完，扫码续上吧" |\r
+\r
+#### 流量状态说明\r
+\r
+物联网卡流量的不同状态及对应的提示信息：\r
+\r
+| 流量值(MB) | 状态描述 | 提示信息 |\r
+|------------|----------|----------|\r
+| > 100 | 流量充足 | 无提示信息 |\r
+| 1-100 | 流量不足 | "流量不足100M了哦，扫码可充值流量" |\r
+| 0 | 流量用完 | "流量用完了哦" |\r
+\r
+#### 错误码\r
+| 错误码 | 描述 |\r
+|--------|------|\r
+| AUTH_FAILURE | 认证失败（设备ID为空或Token无效） |\r
+| DEVICE_NOT_FOUND | 设备未绑定用户 |\r
+| SERVER_ERROR | 服务器内部错误 |\r
+\r
+#### 使用说明\r
+- 该接口用于获取设备当前的对话体力和流量使用情况\r
+- 设备端应根据返回的体力和流量状态进行相应的用户提示\r
+- 当体力或流量不足时，可引导用户扫描充值二维码进行充值\r
+- 会员用户的对话体力为-1，表示无限制使用\r
+- 建议在用户发起对话前检查体力状态，避免对话中途中断\r
+- 流量信息来自物联网卡，用于监控设备的网络使用情况\r
+\r
+#### 业务流程说明\r
+1. **状态查询**：设备端在需要时调用此接口获取当前体力和流量状态\r
+2. **状态判断**：根据返回的体力值判断是否允许进行对话\r
+3. **用户提示**：当体力或流量不足时，显示相应的提示信息\r
+4. **充值引导**：提供充值二维码供用户扫描充值\r
+5. **定期检查**：建议定期调用此接口更新状态显示\r
+\r
 ---\r
 \r
 ## 5. OTA升级任务接口\r
@@ -1772,13 +1935,16 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 **枚举说明**：\r
 \r
 眼型\r
+\r
 | 值 | 描述 |\r
 |--------|------|\r
 | calm-eyes | 平缓眼 |\r
 | round-eyes | 圆眼 |\r
 | upturned-eyes | 上挑眼 |\r
 \r
+\r
 瞳色\r
+\r
 | 值 | 描述 |\r
 |--------|------|\r
 | red | 红 |\r
@@ -1792,6 +1958,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 | yellow-green-gradient | 黄绿渐变 |\r
 \r
 发色\r
+\r
 | 值 | 描述 |\r
 |--------|------|\r
 | light-brown | 浅棕色 |\r
@@ -1804,6 +1971,7 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 | gold | 金色 |\r
 \r
 发型\r
+\r
 | 值 | 描述 |\r
 |--------|------|\r
 | side-parted-comma | 偏分逗号 |\r
@@ -1812,6 +1980,8 @@ WebSocket连接需要设备Token认证，有以下两种方式传递Token：
 | center-parted-bangs | 中分刘海 |\r
 | straight-bangs | 齐刘海 |\r
 | side-parted-texture | 偏分纹理 |\r
+| curly-hair | 卷发 |\r
+\r
 \r
 \r
 #### 6. 角色配置更改 (CharacterConfigChange)\r
@@ -2361,7 +2531,162 @@ sequenceDiagram
 \r
 ---\r
 \r
-## 9. 系统整体时序图\r
+## 9. 时间线状态接口\r
+\r
+### 时序图\r
+\r
+```mermaid\r
+sequenceDiagram\r
+    participant Device as 设备端\r
+    participant Server as 服务端\r
+    \r
+    Note over Device, Server: 时间线状态查询流程\r
+    \r
+    Device->>Device: 需要获取当前时间线状态\r
+    Device->>Server: GET /v1/timeline/getStatus<br/>Headers: deviceId, deviceToken\r
+    \r
+    alt Token验证成功\r
+        Server->>Server: 验证设备Token\r
+        Server->>Server: 获取设备信息\r
+        Server->>Server: 获取角色信息\r
+        Server->>Server: 查询当前时间线事件\r
+        Server->>Server: 构建状态描述和心情\r
+        Server->>Device: 返回时间线状态<br/>{"description", "emotion"}\r
+        Device->>Device: 显示时间线状态信息\r
+        Device->>Device: 根据心情状态选择表情\r
+        \r
+    else Token验证失败\r
+        Server->>Device: 返回认证错误<br/>{"errorCode": "AUTH_FAILURE"}\r
+        Device->>Device: 重新获取Token\r
+    end\r
+```\r
+\r
+### 接口描述\r
+获取时间线状态接口。返回当前设备角色的时间线状态，包含文案描述和心情状态，用于设备端显示角色当前状态和选择对应表情。该接口需要设备Token认证。\r
+\r
+### 请求信息\r
+- **URL**: `/v1/timeline/getStatus`\r
+- **方法**: `GET`\r
+- **Content-Type**: `application/json`\r
+\r
+### 认证要求\r
+该接口需要设备Token认证，Token通过请求头传递。\r
+\r
+### 请求头参数\r
+| 参数名 | 类型 | 必填 | 描述 | 示例 |\r
+|--------|------|------|------|------|\r
+| deviceId | String | 是 | 设备唯一标识符 | "DEVICE_001" |\r
+| deviceToken | String | 是 | 设备访问令牌 | "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." |\r
+\r
+### 响应数据\r
+**成功响应**：\r
+```json\r
+{\r
+  "errorCode": null,\r
+  "message": null,\r
+  "data": {\r
+    "description": "【学习中】今天要好好学习新知识，充实自己的大脑",\r
+    "emotion": "happy"\r
+  }\r
+}\r
+```\r
+\r
+**失败响应（认证失败）**：\r
+```json\r
+{\r
+  "errorCode": "AUTH_FAILURE",\r
+  "message": "设备Token无效",\r
+  "data": null\r
+}\r
+```\r
+\r
+**失败响应（设备不存在）**：\r
+```json\r
+{\r
+  "errorCode": "INVALID_PARAMETER",\r
+  "message": "设备不存在",\r
+  "data": null\r
+}\r
+```\r
+\r
+**失败响应（角色不存在）**：\r
+```json\r
+{\r
+  "errorCode": "INVALID_PARAMETER",\r
+  "message": "角色不存在",\r
+  "data": null\r
+}\r
+```\r
+\r
+**失败响应（事件状态不存在）**：\r
+```json\r
+{\r
+  "errorCode": "DATA_NOT_EXIST",\r
+  "message": "事件状态不存在",\r
+  "data": null\r
+}\r
+```\r
+\r
+### 响应字段说明\r
+| 字段名 | 类型 | 描述 |\r
+|--------|------|------|\r
+| description | String | 文案描述，格式：【${NPC状态}中】${NPC内心自白} |\r
+| emotion | String | 心情状态枚举值，用于选择表情展示 |\r
+\r
+### 心情状态枚举\r
+时间线状态接口返回的心情状态包括以下枚举值：\r
+\r
+| 枚举值 | JSON值 | 中文描述 |\r
+|--------|--------|----------|\r
+| HAPPY | happy | 开心/微笑 |\r
+| LAUGHING | laughing | 大笑 |\r
+| ANGRY | angry | 生气 |\r
+| WRONGE | wronged | 委屈 |\r
+| HEARTBEAT | heartbeat | 心动 |\r
+| AWKWARD | awkward | 尴尬 |\r
+| CONFUSED | confused | 疑惑 |\r
+| SHOCKED | shocked | 震惊 |\r
+| WINKING | winking | 眨眼/闭眼 |\r
+| CRYING | crying | 流泪 |\r
+| BLOWING_KISS | blowing-kiss | 亲吻 |\r
+| SLEEPY | sleepy | 困倦 |\r
+| MISCHIEVOUS | mischievous | 调皮 |\r
+| SPEECHLESS | speechless | 无语 |\r
+| Dizzy | dizzy | 晕 |\r
+| THINKING | thinking | 思考 |\r
+| SLEEPING | sleeping | 睡觉 |\r
+| WORKING | working | 工作 |\r
+| EXERCISING | exercising | 锻炼 |\r
+| PLAYING | playing | 玩耍 |\r
+| DAYDREAMING | daydreaming | 发呆 |\r
+\r
+### 错误码\r
+| 错误码 | 描述 |\r
+|--------|------|\r
+| AUTH_FAILURE | 认证失败（设备ID为空或Token无效） |\r
+| INVALID_PARAMETER | 参数无效（设备不存在或角色不存在） |\r
+| DATA_NOT_EXIST | 数据不存在（事件状态不存在） |\r
+| SERVER_ERROR | 服务器内部错误 |\r
+\r
+### 使用说明\r
+- 该接口用于获取设备当前的时间线状态信息\r
+- 返回的description字段包含格式化的状态描述，可直接显示给用户\r
+- 返回的emotion字段用于设备端选择对应的表情动画进行展示\r
+- 设备解锁时调用此接口更新显示状态\r
+- 如果返回错误，设备端应根据错误类型进行相应处理：\r
+  - **AUTH_FAILURE**: 重新获取设备Token\r
+  - **INVALID_PARAMETER**: 检查设备配置或联系技术支持\r
+  - **DATA_NOT_EXIST**: 可能是系统初始化中，稍后重试\r
+  - **SERVER_ERROR**: 服务器异常，建议稍后重试\r
+\r
+### 业务流程说明\r
+1. **状态查询**：设备端根据需要调用此接口获取当前时间线状态\r
+2. **状态解析**：解析返回的description和emotion字段\r
+3. **界面更新**：根据description更新文案显示\r
+4. **表情选择**：根据emotion选择对应的表情动画\r
+---\r
+\r
+## 10. 系统整体时序图\r
 \r
 ### 设备完整生命周期流程\r
 \r
@@ -2484,6 +2809,7 @@ sequenceDiagram
 5. **WebSocket通信**：展示实时通信和命令推送流程\r
 6. **OTA升级流程**：展示固件升级的完整过程\r
 7. **表情管理流程**：展示表情下载、删除和状态同步的完整过程\r
-8. **系统整体流程**：展示设备完整生命周期的综合时序图\r
+8. **时间线状态流程**：展示设备获取和显示时间线状态的完整过程\r
+9. **系统整体流程**：展示设备完整生命周期的综合时序图\r
 \r
 每个时序图都详细描述了参与方之间的交互序列，有助于开发者理解系统架构和实现细节。\r