主题
第 8 章 小程序接入方案
小程序是 JoyInside 接入的「可选增强场景」，不是独立的接入方式。设备端语音接入（第二部分）是前置条件，小程序用于扩展用户交互面：配网、设备绑定、角色管理、聊天记录、在线设备管理。
本章讲小程序接入方案与适配策略；接口协议明细见 附录 A。
8.1 小程序定位
⚠️ JoyInside不提供小程序，需客户自行对接C端开放接口
- JoyInside 提供的是小程序对接所需的 HTTP 接口（设备注册、音色、角色、绑定、聊天、在线设备管理），见 附录 A
8.2 接入前置：设备注册
小程序对接 JoyInside 的第一步是设备注册，拿到 botId 后才能调用后续接口。
设备注册接口：详见 4.2 设备注册与绑定 的注册接口（/device/register）。
设备注册与语音侧共用同一套注册流程（见 4.2）。注册拿到 botId 后，小程序即可用它调用角色管理、绑定、聊天等接口。此处不重复，详见第4章。
第二步需要完成用户绑定，绑定用户uid和设备的关联关系。
8.3 接口总览与鉴权
7 类接口总览
| 类别 | 接口 | 详见 |
|---|---|---|
| 音色列表 | /soulmate/timbre/findAllByVendorId | §9.1 |
| AI 角色管理 | 10 个接口（系统角色/自定义角色 CRUD + 设备绑定 + 昵称） | 附录 A.4 |
| 用户绑定 | /device/bindUser、/device/queryBotBind、/device/unbindUser | §9.3 |
| 聊天记录与报告 | /soulmate/chatReport/recentDays、/soulmate/chatReport/chatMessage/page | §9.4 |
| 在线设备管理 | /online/bot/query、/online/bot/broadcast/instant | §9.5 |
公共参数
| 参数 | 说明 | 出现在 |
|---|---|---|
vendorId | 企业 id（与 JoyInside 获取），测试环境固定 200196 | 多数接口 |
botId | JoyInside 设备 id | 多数接口 |
requestId | 请求追踪，建议 UUID | 多数接口 |
uid | 用户 id，关联长期记忆与聊天报告 | 绑定/聊天接口 |
uid 详细规则（≤128 字节、必须真实）见 4.3 重要参数介绍。
统一返回结构
所有接口返回统一格式：
| 字段 | 数据类型 | 备注 |
|---|---|---|
state | String | SUCCESS（成功）/ FAILURE（失败）/ ERROR（系统错误） |
code | Number | 200（成功）/ 50x（系统错误） |
result | String | 错误消息，code 不等于 200 时有值 |
data | 各接口不同 | 业务数据 |
部分接口（如聊天记录、在线设备管理）返回
code为0000成功，详见各接口说明。
下一步
- 小程序接口明细：读 附录 A HTTP API 参考 —— 7 类接口完整字段
- 设备注册：读 4.2 设备注册与绑定 —— botId 注册流程
- uid 规则：读 4.3 重要参数介绍 —— uid ≤128 字节约束
- 小程序决策：回 2.6 小程序接入决策 —— 是否需要小程序