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