refactor: migrate to Tencent Cloud backend

docs/design/01-BLE通信协议明细.md

@@ -0,0 +1,196 @@
+# BLE 通信协议明细
+
+基于 `软件系统说明.docx` 整理。本文档用于把 BLE 通信协议推进到"可联调设计"层，把帧结构、服务、命令表和时序骨架补到足够继续细化的程度。
+
+本文档仍然遵循一个原则：不虚构未被产品说明证实的命令字、UUID 或 payload 值。以下内容中，凡是来源仅为"推导"而非"文档原文确认"的，会标明"待确认"。
+
+## 已确认事实
+
+- 通信方式：`BLE 5.0 GATT`
+- 协议帧格式：帧头 `0xAA 0x55`，随后是长度、类型、数据、XOR 校验
+- 已知服务 UUID：
+  - `FFE0`：设备信息服务
+  - `FFE1`：数据通信服务
+  - `FFE2`：OTA 升级服务
+- 业务流程中至少存在以下设备交互阶段：连接设备、确认佩戴、自动扫描、开始治疗
+
+## 帧结构草案
+
+### 帧总体格式
+
+| 字段 | 偏移 | 长度 | 值域 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `header` | 0 | 2 字节 | `0xAA 0x55` | 文档确认 | 帧头标识 |
+| `length` | 2 | 1 字节 | 待确认 | 文档确认存在，定义待补 | 数据长度 |
+| `type` | 3 | 1 字节 | 待确认 | 文档确认存在，枚举待补 | 命令/数据/事件类型 |
+| `payload` | 4 | N 字节 | 待确认 | 文档确认存在 | 业务载荷 |
+| `checksum` | 4+N | 1 字节 | 待确认 | 文档确认为 XOR | 校验 |
+
+### 必须补齐的帧定义
+
+| 项目 | 当前状态 | 阻塞影响 |
+| --- | --- | --- |
+| `length` 是否包含 `type`、`checksum` | 未定义 | 无法正确解析帧 |
+| `checksum` XOR 计算范围 | 未定义 | 无法正确校验帧 |
+| 多字节字段字节序 | 未定义 | 数值解析错误 |
+| 字符串编码方式 | 未定义 | 文本解析错误 |
+| 最大 payload 长度 | 未定义 | 分包策略无法设计 |
+| MTU 约束 | 未定义 | 传输效率与可靠性 |
+
+### 建议帧计算规则（待确认）
+
+以下为建议方案，非最终定义：
+
+- `length`：建议仅表示 `payload` 的字节长度
+- `checksum`：建议对 `length`、`type`、`payload` 所有字节做 XOR 运算
+- 字节序：建议统一大端序（`Big-Endian`）
+- 字符串：建议统一 `UTF-8`
+
+## 服务与 characteristic 草案
+
+### `FFE0` 设备信息服务
+
+职责：提供设备基础信息。
+
+建议 characteristic 划分（待确认）：
+
+| 建议名称 | 建议属性 | 说明 |
+| --- | --- | --- |
+| `device_info` | `read` | 读取设备型号、固件版本、硬件版本、序列号 |
+| `battery_level` | `read` / `notify` | 电量信息 |
+
+UUID 值：待确认
+
+### `FFE1` 数据通信服务
+
+职责：承担主要业务通信。
+
+建议 characteristic 划分（待确认）：
+
+| 建议名称 | 建议属性 | 说明 |
+| --- | --- | --- |
+| `write_cmd` | `write` / `writeWithoutResponse` | 小程序向设备发送命令 |
+| `notify_data` | `notify` | 设备向小程序上报数据和事件 |
+
+UUID 值：待确认
+
+### `FFE2` OTA 升级服务
+
+职责：固件升级传输。
+
+建议 characteristic 划分（待确认）：
+
+| 建议名称 | 建议属性 | 说明 |
+| --- | --- | --- |
+| `ota_control` | `write` / `notify` | OTA 控制命令和状态通知 |
+| `ota_data` | `writeWithoutResponse` | 升级包分片传输 |
+
+UUID 值：待确认
+
+## 命令表草案
+
+以下命令基于业务流程推导，所有 `type` 值和 `payload` 结构都是待确认的占位。
+
+### 设备信息类
+
+| 建议命令名 | 建议方向 | 建议功能 | type 占位 | payload 请求 | payload 响应 | 待确认 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `GET_DEVICE_INFO` | 小程序 -> 设备 | 读取设备型号、固件版本、序列号 | `0x??` | 空 | 设备信息结构体 | 是 |
+| `GET_BATTERY` | 小程序 -> 设备 | 读取设备电量 | `0x??` | 空 | 电量值 | 是 |
+| `GET_DEVICE_STATUS` | 小程序 -> 设备 | 读取设备当前状态 | `0x??` | 空 | 状态码 | 是 |
+
+### 治疗流程类
+
+| 建议命令名 | 建议方向 | 建议功能 | type 占位 | payload 请求 | payload 响应 | 待确认 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `START_WEARING_CHECK` | 小程序 -> 设备 | 启动佩戴确认 | `0x??` | 空 | 佩戴检测结果 | 是 |
+| `WEARING_CHECK_RESULT` | 设备 -> 小程序 | 上报佩戴确认结果 | `0x??` | 无（通知） | 佩戴状态 | 是 |
+| `START_AUTO_SCAN` | 小程序 -> 设备 | 启动自动扫描 | `0x??` | 空 | 扫描结果 | 是 |
+| `AUTO_SCAN_RESULT` | 设备 -> 小程序 | 上报自动扫描结果 | `0x??` | 无（通知） | 扫描数据 | 是 |
+| `START_TREATMENT` | 小程序 -> 设备 | 开始治疗 | `0x??` | 治疗参数（待确认） | 确认/拒绝 | 是 |
+| `PAUSE_TREATMENT` | 小程序 -> 设备 | 暂停治疗 | `0x??` | 空 | 确认 | 是 |
+| `RESUME_TREATMENT` | 小程序 -> 设备 | 恢复治疗 | `0x??` | 空 | 确认 | 是 |
+| `STOP_TREATMENT` | 小程序 -> 设备 | 结束治疗 | `0x??` | 空 | 治疗摘要 | 是 |
+| `TREATMENT_PROGRESS` | 设备 -> 小程序 | 上报治疗进度 | `0x??` | 无（通知） | 进度数据 | 是 |
+| `TREATMENT_ERROR` | 设备 -> 小程序 | 上报治疗异常 | `0x??` | 无（通知） | 错误码 | 是 |
+
+### OTA 类
+
+| 建议命令名 | 建议方向 | 建议功能 | type 占位 | payload 请求 | payload 响应 | 待确认 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `OTA_START` | 小程序 -> 设备 | 启动 OTA | `0x??` | 固件版本、总大小 | 确认/拒绝 | 是 |
+| `OTA_CHUNK` | 小程序 -> 设备 | 传输分片 | `0x??` | 分片序号、分片数据 | 确认 | 是 |
+| `OTA_VERIFY` | 小程序 -> 设备 | 校验完整固件 | `0x??` | 校验值 | 校验结果 | 是 |
+| `OTA_APPLY` | 小程序 -> 设备 | 应用新固件 | `0x??` | 空 | 结果 | 是 |
+| `OTA_PROGRESS` | 设备 -> 小程序 | 上报 OTA 进度 | `0x??` | 无（通知） | 进度百分比 | 是 |
+
+## 会话时序草案
+
+### 连接后初始化时序（建议）
+
+以下为建议流程，非最终定义：
+
+1. 小程序扫描并连接设备 GATT
+2. 发现 `FFE0`、`FFE1`、`FFE2` 服务
+3. 订阅 `FFE1` 的 `notify_data` 通知
+4. 读取 `FFE0` 的 `device_info` 获取设备基本信息
+5. 根据业务需要发送后续命令
+
+### 治疗主流程时序（建议）
+
+1. 发送 `START_WEARING_CHECK`
+2. 等待 `WEARING_CHECK_RESULT` 通知
+3. 佩戴确认通过后发送 `START_AUTO_SCAN`
+4. 等待 `AUTO_SCAN_RESULT` 通知
+5. 扫描完成后发送 `START_TREATMENT`
+6. 接收 `TREATMENT_PROGRESS` 周期通知
+7. 治疗完成或用户主动停止后发送 `STOP_TREATMENT`
+
+### 异常处理时序（建议）
+
+- 命令超时：建议 3-5 秒未收到响应则重试，最多重试 3 次
+- 断连重连：建议重连后重新订阅 notify 并查询设备当前状态
+- 治疗中断：建议重连后查询是否需要恢复上次治疗会话
+
+## ACK/NACK 机制建议
+
+建议每个命令都存在对应的 ACK 或 NACK 响应（待确认）：
+
+| 响应类型 | 含义 |
+| --- | --- |
+| ACK | 命令已接收并执行成功 |
+| NACK | 命令接收失败或执行失败，附带错误码 |
+
+建议错误码表（待确认）：
+
+| 建议范围 | 含义 |
+| --- | --- |
+| `0x00` | 成功 |
+| `0x01` - `0x0F` | 通用错误 |
+| `0x10` - `0x1F` | 参数错误 |
+| `0x20` - `0x2F` | 设备状态错误 |
+| `0x30` - `0x3F` | 治疗相关错误 |
+| `0x40` - `0x4F` | OTA 相关错误 |
+
+## 分包与粘包建议
+
+当前文档未定义，以下为建议方案（待确认）：
+
+- 建议每个 BLE 写入操作对应一个完整帧
+- 若 payload 超过 MTU 限制，建议在应用层定义分包协议
+- 每个分包建议携带：帧序号、是否最后一包的标记
+- 接收端建议按序号拼装，收到最后一包后校验完整性
+
+## 待确认问题
+
+- 设备绑定是否依赖 BLE 返回的设备唯一标识，还是依赖扫码
+- "确认佩戴"由什么传感器或状态判断，是自动还是手动
+- "自动扫描"具体扫描什么数据
+- 治疗模式、档位、时长是否由小程序下发
+- 治疗记录是否由小程序组装后上传，还是由设备通过 MQTT 直接上报云端
+- OTA 是否通过小程序中转升级包
+- 是否需要设备端主动发起的连接认证或握手
+
+## 当前结论
+
+当前说明已经足够把 BLE 协议推进到"命令表草案"层。所有标为"待确认"的命令字、payload 和 UUID 都需要在下一步被确认或修正。最优先要补齐的是 `FFE1` 下的 characteristic UUID、命令字分配、ACK/NACK 机制和帧计算规则。

docs/design/02-小程序业务流程与状态机.md

@@ -0,0 +1,209 @@
+# 小程序业务流程与状态机
+
+基于 `软件系统说明.docx` 整理。本文档用于把现有流程描述收敛成可继续细化的页面与状态框架，不补充未经确认的产品规则。
+
+## 已确认范围
+
+### 技术边界
+
+- 小程序技术栈：微信原生 `WXML / WXSS / JS`
+- 与设备通过 `BLE 5.0 GATT` 通信
+- 与云端通过 `HTTPS/MQTT` 通信
+
+### 页面范围
+
+- 首页：设备连接、治疗开始
+- 护理历史：记录和统计
+- 发现：美容百科、公告
+- 我的：用户中心、订阅管理
+
+### 已确认流程
+
+首次使用：
+
+1. 扫码
+2. 蓝牙授权
+3. 设备绑定
+4. 获得 7 天试用
+5. 确认佩戴
+6. 自动扫描
+7. 开始治疗
+
+日常使用：
+
+1. 打开小程序
+2. 连接设备
+3. 确认佩戴
+4. 自动扫描
+5. 开始治疗
+
+## 建议页面职责
+
+### 首页
+
+承载主链路：
+
+- 设备连接状态展示
+- 设备连接入口
+- 佩戴确认结果
+- 自动扫描结果或状态
+- 开始治疗入口
+- 治疗中状态展示
+
+### 护理历史
+
+承载治疗结果查询：
+
+- 历史记录列表
+- 单次治疗摘要
+- 与云端同步状态
+
+### 发现
+
+承载弱业务内容：
+
+- 美容百科
+- 公告
+
+### 我的
+
+承载账号与订阅信息：
+
+- 用户信息
+- 设备绑定信息
+- 订阅状态
+- 试用状态
+
+## 建议最小状态机
+
+以下状态用于支撑第一阶段开发，不代表最终产品态。
+
+| 状态 | 含义 | 是否由文档直接确认 |
+| --- | --- | --- |
+| `UNAUTHORIZED_BLE` | 未完成蓝牙授权 | 是 |
+| `DISCONNECTED` | 未连接设备 | 是 |
+| `CONNECTED_UNBOUND` | 已连接但未绑定 | 间接确认 |
+| `BOUND_IDLE` | 已绑定，待治疗 | 间接确认 |
+| `WEARING_CHECK` | 佩戴确认中 | 是 |
+| `AUTO_SCAN` | 自动扫描中 | 是 |
+| `READY_TO_TREAT` | 可开始治疗 | 间接确认 |
+| `TREATING` | 治疗中 | 是 |
+| `SYNC_PENDING` | 治疗完成待同步 | 间接确认 |
+| `SYNC_FAILED` | 记录同步失败 | 间接确认 |
+
+## 首次使用流程拆解
+
+### 1. 扫码
+
+已知：首次使用从扫码开始。
+
+待确认：
+
+- 扫码内容是设备 SN、激活码、绑定码还是 URL
+- 扫码失败后的兜底方式
+
+### 2. 蓝牙授权
+
+已知：首次使用要求蓝牙授权。
+
+待确认：
+
+- 是否还需要定位权限
+- 拒绝授权后的引导方式
+
+### 3. 设备绑定
+
+已知：首次使用需要绑定设备。
+
+待确认：
+
+- 绑定前是否必须先 BLE 连接成功
+- 绑定成功由本地判断还是服务端返回
+- 一人多设备/一设备多用户规则
+
+### 4. 获得 7 天试用
+
+已知：首次使用绑定后获得 7 天试用。
+
+待确认：
+
+- 试用按用户发还是按设备发
+- 是否有领取次数限制
+- 试用到期后的处理
+
+### 5. 确认佩戴
+
+已知：治疗前要确认佩戴。
+
+待确认：
+
+- 由设备自动判断还是用户手动确认
+- 失败时的提示和重试机制
+
+### 6. 自动扫描
+
+已知：佩戴确认后进入自动扫描。
+
+待确认：
+
+- 自动扫描的业务含义
+- 扫描结果是否决定治疗参数
+
+### 7. 开始治疗
+
+已知：自动扫描后可以开始治疗。
+
+待确认：
+
+- 是否允许用户手动调节模式、时长、档位
+- 是否需要先校验订阅状态
+
+## 日常使用流程拆解
+
+日常使用与首次流程的区别在于不再强调扫码、绑定和试用发放，因此可视为：
+
+1. 恢复登录态
+2. 连接已绑定设备
+3. 佩戴确认
+4. 自动扫描
+5. 开始治疗
+6. 记录同步
+
+## 异常流清单
+
+以下异常流文档尚未定义，但开发前必须明确：
+
+- 蓝牙授权被拒绝
+- 扫描不到设备
+- 设备连接中断
+- 设备已被他人绑定
+- 试用已到期
+- 订阅无效
+- 佩戴确认失败
+- 自动扫描失败
+- 治疗中断
+- 记录同步失败
+
+## 页面与状态的最低接口需求
+
+为了让小程序能继续设计，云端和 BLE 至少需要提供这些能力：
+
+- 查询当前用户信息
+- 查询当前绑定设备
+- 绑定/解绑设备
+- 查询订阅状态
+- 同步治疗记录
+- BLE 读取设备状态
+- BLE 执行佩戴确认、自动扫描、开始治疗
+
+## 待确认问题
+
+- 小程序是否直接使用 MQTT
+- 首页是否需要展示实时传感器数据
+- 护理历史中的“统计”是本地统计还是云端聚合统计
+- 发现页内容是否来自 CMS 或静态配置
+- 我的页面是否包含售后、反馈、设置等附加入口
+
+## 当前结论
+
+当前说明已经给出主流程，但还没有给出完整状态机、异常流和页面交互规则。后续应优先把首页主链路和绑定/订阅规则细化清楚。

docs/design/03-云函数API接口清单.md

@@ -0,0 +1,394 @@
+# 云函数 API 接口清单
+
+基于 `软件系统说明.docx` 整理。本文档用于把已知云函数职责推进到“接口草案”层，便于后续继续拆成真实路由和字段定义。
+
+本文档仍然遵循一个原则：不把文档未确认的 URL、字段值、错误码和业务规则写成既定事实。以下内容中的“建议”是为了便于继续设计，不代表已定方案。
+
+## 已确认云端职责
+
+文档已确认云函数负责：
+
+- 用户认证（微信登录）
+- 设备绑定/解绑
+- 订阅管理
+- 护理记录同步
+- 设备注册（动态获取 `DeviceSecret`）
+- 试用订阅管理
+- 数据统计
+
+## 设计目标
+
+当前阶段，这份接口文档的目标不是给出最终 API，而是统一以下边界：
+
+- 哪些接口是一定需要的
+- 每类接口由谁调用
+- 每类接口最少要交换哪些信息
+- 每类接口执行时会影响哪些业务对象
+
+## 调用方划分
+
+当前系统至少存在四类调用方：
+
+- 小程序
+- 管理后台
+- 设备或设备接入链路
+- 云内部任务或异步处理链路
+
+## 建议接口分组
+
+### 1. 认证接口
+
+至少需要：
+
+- 微信登录
+- Token 校验或续期
+- 当前用户信息查询
+
+### 2. 设备接口
+
+至少需要：
+
+- 设备绑定
+- 设备解绑
+- 当前绑定设备查询
+- 设备详情查询
+
+### 3. 订阅接口
+
+至少需要：
+
+- 当前订阅状态查询
+- 试用订阅发放
+- 订阅列表查询
+- 订阅创建或续期
+
+### 4. 护理记录接口
+
+至少需要：
+
+- 护理记录上传
+- 护理记录列表查询
+- 单条护理记录详情查询
+
+### 5. 设备注册与 IoT 接口
+
+至少需要：
+
+- 设备注册
+- `DeviceSecret` 下发
+- 设备状态同步或查询
+
+### 6. 统计接口
+
+至少需要：
+
+- 用户统计
+- 设备统计
+- 治疗统计
+- 订阅统计
+
+## 接口命名草案
+
+下表中的“接口标识”仅用于当前设计阶段统一讨论，不代表最终路由。
+
+| 分组 | 接口标识 | 主要调用方 | 文档是否确认需要 | 说明 |
+| --- | --- | --- | --- | --- |
+| 认证 | `auth.wx_login` | 小程序 | 是 | 微信登录换取系统身份 |
+| 认证 | `auth.refresh_token` | 小程序 | 间接确认 | Token 续期 |
+| 认证 | `auth.get_profile` | 小程序 | 间接确认 | 获取当前用户基础信息 |
+| 设备 | `device.bind` | 小程序 | 是 | 绑定设备 |
+| 设备 | `device.unbind` | 小程序 / 后台 | 是 | 解绑设备 |
+| 设备 | `device.get_current_binding` | 小程序 | 间接确认 | 查询当前绑定设备 |
+| 设备 | `device.get_detail` | 小程序 / 后台 | 间接确认 | 查询设备详情 |
+| 订阅 | `subscription.get_current` | 小程序 | 间接确认 | 查询当前订阅状态 |
+| 订阅 | `subscription.grant_trial` | 云内部任务 / 小程序链路 | 是 | 发放 7 天试用 |
+| 订阅 | `subscription.list` | 后台 | 间接确认 | 查询订阅列表 |
+| 订阅 | `subscription.create_or_renew` | 后台 | 是 | 创建或续期订阅 |
+| 护理记录 | `record.sync` | 小程序 / 设备链路 | 是 | 同步护理记录 |
+| 护理记录 | `record.list` | 小程序 / 后台 | 间接确认 | 查询护理记录列表 |
+| 护理记录 | `record.detail` | 小程序 / 后台 | 间接确认 | 查询护理记录详情 |
+| IoT | `iot.register_device` | 设备链路 / 云内部任务 | 是 | 注册设备 |
+| IoT | `iot.issue_device_secret` | 设备链路 / 云内部任务 | 是 | 下发 `DeviceSecret` |
+| IoT | `iot.get_device_status` | 后台 / 云内部任务 | 间接确认 | 查询设备状态 |
+| 统计 | `stats.user_overview` | 后台 | 是 | 用户统计 |
+| 统计 | `stats.device_overview` | 后台 | 是 | 设备统计 |
+| 统计 | `stats.treatment_overview` | 后台 | 是 | 治疗统计 |
+| 统计 | `stats.subscription_overview` | 后台 | 是 | 订阅统计 |
+
+## 统一接口契约建议
+
+后续细化每个接口时，建议统一补齐以下字段：
+
+- 接口标识
+- 调用方
+- 请求方式
+- 路由
+- 鉴权要求
+- 幂等要求
+- 请求参数
+- 返回结构
+- 错误码
+- 侧效应
+- 依赖数据表
+
+## 建议统一响应包络
+
+当前文档没有确认具体返回格式，但为了后续接口设计一致，建议统一采用一个最小响应包络。
+
+| 字段 | 是否建议保留 | 说明 |
+| --- | --- | --- |
+| `code` | 是 | 业务结果码 |
+| `message` | 是 | 成功或失败说明 |
+| `data` | 是 | 业务数据 |
+| `request_id` | 建议 | 便于日志追踪 |
+
+## 各接口组的最小信息集合
+
+### 认证接口
+
+#### `auth.wx_login`
+
+最小目标：
+
+- 接收小程序登录凭证
+- 识别或创建用户身份
+- 返回系统可识别的登录态
+
+至少需要定义：
+
+- 输入凭证类型
+- 返回 token 结构
+- 是否同时返回用户资料和订阅状态
+
+可能影响的对象：
+
+- `users`
+- 登录态或会话存储
+
+#### `auth.refresh_token`
+
+最小目标：
+
+- 延长有效登录态或重新签发 token
+
+至少需要定义：
+
+- 续期条件
+- 旧 token 处理方式
+- 是否支持滑动过期
+
+### 设备接口
+
+#### `device.bind`
+
+最小目标：
+
+- 建立用户与设备的绑定关系
+
+至少需要定义：
+
+- 设备标识来源
+- 是否依赖扫码
+- 是否要求设备在线
+- 绑定成功后的试用发放关系
+
+可能影响的对象：
+
+- `devices`
+- `bindings`
+- `subscriptions`
+- `operation_logs`
+
+#### `device.unbind`
+
+最小目标：
+
+- 解除当前用户与设备的有效绑定关系
+
+至少需要定义：
+
+- 谁可发起解绑
+- 解绑是否影响订阅归属
+- 历史绑定如何保留
+
+#### `device.get_current_binding`
+
+最小目标：
+
+- 返回当前用户的绑定设备摘要
+
+至少需要定义：
+
+- 是否允许无绑定返回空对象
+- 返回摘要字段范围
+
+### 订阅接口
+
+#### `subscription.get_current`
+
+最小目标：
+
+- 返回当前用户或当前设备的有效订阅状态
+
+至少需要定义：
+
+- 查询口径是按用户还是按设备
+- 返回是否包含试用信息
+
+#### `subscription.grant_trial`
+
+最小目标：
+
+- 在满足条件时发放 7 天试用
+
+至少需要定义：
+
+- 触发时机
+- 幂等规则
+- 发放对象
+
+#### `subscription.create_or_renew`
+
+最小目标：
+
+- 后台创建或续期订阅
+
+至少需要定义：
+
+- 是否存在订单概念
+- 生效时间规则
+- 是否允许覆盖现有有效期
+
+### 护理记录接口
+
+#### `record.sync`
+
+最小目标：
+
+- 接收一次护理记录并落入后续处理链路
+
+至少需要定义：
+
+- 上传主体
+- 请求是完整记录还是过程数据
+- 幂等键
+- 同步成功与异步入库成功的关系
+
+可能影响的对象：
+
+- `sessions`
+- `treatment_records`
+- `pd_data`
+- `operation_logs`
+- `CMQ` 或其他异步链路
+
+#### `record.list`
+
+最小目标：
+
+- 查询治疗记录列表
+
+至少需要定义：
+
+- 小程序和后台是否共用同一查询能力
+- 过滤条件
+- 排序字段
+
+### IoT 接口
+
+#### `iot.register_device`
+
+最小目标：
+
+- 为设备建立平台侧可识别身份
+
+至少需要定义：
+
+- 调用方
+- 调用时机
+- 注册成功后的返回值
+
+#### `iot.issue_device_secret`
+
+最小目标：
+
+- 为设备签发或返回 `DeviceSecret`
+
+至少需要定义：
+
+- 签发条件
+- 是否只可获取一次
+- 返回方式与安全控制
+
+### 统计接口
+
+统计接口当前只确认“后台需要”，最先要补的是统计口径：
+
+- 时间范围
+- 去重规则
+- 试用与正式订阅是否分开统计
+- 设备在线数是否为实时值
+
+## 建议接口字段模板
+
+后续继续细化某个接口时，可直接套用以下模板：
+
+| 项目 | 内容 |
+| --- | --- |
+| 接口标识 | 待定义 |
+| 调用方 | 待定义 |
+| 请求方式 | 待定义 |
+| 路由 | 待定义 |
+| 鉴权要求 | 待定义 |
+| 幂等要求 | 待定义 |
+| 请求参数 | 待定义 |
+| 返回结构 | 待定义 |
+| 错误码 | 待定义 |
+| 侧效应 | 待定义 |
+| 依赖数据表 | 待定义 |
+
+## 最先需要定下来的横切规则
+
+在继续细化具体接口前，建议先统一这几项横切规则：
+
+- 统一响应包络
+- 统一错误码风格
+- 统一分页结构
+- 统一时间字段格式
+- 统一幂等键规则
+- 统一日志追踪字段，如 `request_id`
+
+## 关键接口待确认问题
+
+### 微信登录
+
+- 小程序提交给云端的是 `code` 还是其他凭证
+- 云端返回自有 token 还是复用微信态
+- Token 7 天有效期是否支持续期
+
+### 设备绑定
+
+- 绑定是否必须基于扫码
+- 绑定时是否校验设备在线状态
+- 重复绑定、换绑、解绑是否有限制
+
+### 试用订阅
+
+- 发放时机是否严格绑定在首次绑定成功后
+- 试用对象是用户还是设备
+- 到期后是否自动降级为不可治疗
+
+### 护理记录同步
+
+- 上传主体是小程序还是设备侧
+- 同步是实时提交还是治疗结束后提交
+- 异步写入与接口返回成功的关系
+
+### 设备注册
+
+- 调用方是生产工具、设备首次上线，还是小程序触发
+- `DeviceSecret` 是否只签发一次
+
+## 当前结论
+
+当前说明已经足够把云函数职责推进到“接口草案”层，但还不能直接生成真实 API。最优先要继续细化的是 `auth.wx_login`、`device.bind`、`subscription.get_current`、`subscription.grant_trial`、`record.sync` 这五个核心接口。

docs/design/04-数据库表结构设计.md

@@ -0,0 +1,288 @@
+# 数据库表结构设计
+
+基于 `软件系统说明.docx` 整理。本文档用于把已知数据实体推进到表级字段草案，便于后续直接转成 DDL。
+
+本文档仍然遵循一个原则：不把文档未确认的业务规则写成既定事实。以下字段草案中，凡是来源仅为"推导"而非"文档原文确认"的，会标明"待确认"。所有表名、字段名均为设计阶段讨论名，不代表最终数据库列名。
+
+## 全局设计约定
+
+以下约定建议在所有表统一采用：
+
+- 主键：统一使用自增 `id`，类型 `BIGINT UNSIGNED`，具体方案待确认
+- 时间字段：`created_at`、`updated_at`，类型 `DATETIME`，时区统一为待确认
+- 软删：建议统一使用 `deleted_at`，值为 `NULL` 表示未删除，具体策略待确认
+- 字符集：建议统一 `utf8mb4`
+- 审计：建议所有表至少保留 `created_at` 和 `updated_at`
+
+## 已确认逻辑表
+
+- `users`
+- `devices`
+- `bindings`
+- `subscriptions`
+- `sessions`
+- `treatment_records`
+- `pd_data`
+- `operation_logs`
+
+## 表级字段草案
+
+### `users`
+
+承载用户身份与账号信息。
+
+| 字段名 | 建议类型 | 是否必填 | 默认值 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `id` | `BIGINT UNSIGNED` | 是 | 自增 | 约定 | 主键 |
+| `openid` | `VARCHAR(128)` | 是 | 无 | 推导 | 微信用户唯一标识，待确认字段名 |
+| `union_id` | `VARCHAR(128)` | 否 | `NULL` | 推导 | 微信开放平台跨应用标识，待确认是否需要 |
+| `nickname` | `VARCHAR(64)` | 否 | `NULL` | 推导 | 用户昵称，待确认是否存储 |
+| `avatar_url` | `VARCHAR(512)` | 否 | `NULL` | 推导 | 用户头像地址，待确认是否存储 |
+| `phone` | `VARCHAR(32)` | 否 | `NULL` | 推导 | 手机号，待确认是否需要 |
+| `status` | `TINYINT UNSIGNED` | 是 | `1` | 推导 | 用户状态枚举，待确认 |
+| `created_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 约定 | 创建时间 |
+| `updated_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP ON UPDATE` | 约定 | 更新时间 |
+| `deleted_at` | `DATETIME` | 否 | `NULL` | 约定 | 软删时间 |
+
+建议唯一索引：`openid`
+
+建议状态枚举（待确认）：
+
+| 值 | 含义 |
+| --- | --- |
+| `1` | 正常 |
+| `2` | 禁用 |
+| `3` | 注销 |
+
+### `devices`
+
+承载设备主数据。
+
+| 字段名 | 建议类型 | 是否必填 | 默认值 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `id` | `BIGINT UNSIGNED` | 是 | 自增 | 约定 | 主键 |
+| `device_sn` | `VARCHAR(64)` | 是 | 无 | 推导 | 设备序列号，作为设备唯一业务标识，待确认字段名和格式 |
+| `product_id` | `VARCHAR(64)` | 是 | 无 | 文档确认 | IoT 平台产品 ID |
+| `device_name` | `VARCHAR(128)` | 是 | 无 | 文档确认 | IoT 平台设备名称 |
+| `firmware_version` | `VARCHAR(32)` | 否 | `NULL` | 推导 | 当前固件版本 |
+| `hardware_version` | `VARCHAR(32)` | 否 | `NULL` | 推导 | 硬件版本 |
+| `status` | `TINYINT UNSIGNED` | 是 | `1` | 推导 | 设备状态枚举，待确认 |
+| `activated_at` | `DATETIME` | 否 | `NULL` | 推导 | 首次激活时间 |
+| `created_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 约定 | 创建时间 |
+| `updated_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP ON UPDATE` | 约定 | 更新时间 |
+| `deleted_at` | `DATETIME` | 否 | `NULL` | 约定 | 软删时间 |
+
+建议唯一索引：`device_sn`
+
+建议状态枚举（待确认）：
+
+| 值 | 含义 |
+| --- | --- |
+| `1` | 未激活 |
+| `2` | 已激活 |
+| `3` | 禁用 |
+| `4` | 故障 |
+
+### `bindings`
+
+承载用户与设备的绑定关系。
+
+| 字段名 | 建议类型 | 是否必填 | 默认值 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `id` | `BIGINT UNSIGNED` | 是 | 自增 | 约定 | 主键 |
+| `user_id` | `BIGINT UNSIGNED` | 是 | 无 | 推导 | 关联 `users.id` |
+| `device_id` | `BIGINT UNSIGNED` | 是 | 无 | 推导 | 关联 `devices.id` |
+| `status` | `TINYINT UNSIGNED` | 是 | `1` | 推导 | 绑定状态枚举，待确认 |
+| `bound_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 推导 | 绑定时间 |
+| `unbound_at` | `DATETIME` | 否 | `NULL` | 推导 | 解绑时间 |
+| `created_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 约定 | 创建时间 |
+| `updated_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP ON UPDATE` | 约定 | 更新时间 |
+
+建议索引：`user_id` + `status`，`device_id` + `status`
+
+建议状态枚举（待确认）：
+
+| 值 | 含义 |
+| --- | --- |
+| `1` | 有效 |
+| `2` | 已解绑 |
+
+待确认关系约束：
+
+- 同一时刻一个用户是否只能绑定一台设备
+- 同一时刻一台设备是否只能绑定一个用户
+- 解绑后是否保留历史记录
+
+### `subscriptions`
+
+承载试用与正式订阅信息。
+
+| 字段名 | 建议类型 | 是否必填 | 默认值 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `id` | `BIGINT UNSIGNED` | 是 | 自增 | 约定 | 主键 |
+| `user_id` | `BIGINT UNSIGNED` | 是 | 无 | 推导 | 关联 `users.id`，待确认是否同时关联设备 |
+| `device_id` | `BIGINT UNSIGNED` | 否 | `NULL` | 推导 | 关联 `devices.id`，待确认是否需要 |
+| `type` | `TINYINT UNSIGNED` | 是 | 无 | 推导 | 订阅类型枚举 |
+| `status` | `TINYINT UNSIGNED` | 是 | `1` | 推导 | 订阅状态枚举 |
+| `started_at` | `DATETIME` | 是 | 无 | 推导 | 生效时间 |
+| `expired_at` | `DATETIME` | 是 | 无 | 推导 | 到期时间 |
+| `source` | `VARCHAR(32)` | 否 | `NULL` | 推导 | 来源说明，如 `trial_grant`、`manual_create`、`purchase`，待确认 |
+| `source_id` | `VARCHAR(64)` | 否 | `NULL` | 推导 | 来源关联 ID，如订单号，待确认是否有订单概念 |
+| `created_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 约定 | 创建时间 |
+| `updated_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP ON UPDATE` | 约定 | 更新时间 |
+
+建议索引：`user_id` + `status`，`user_id` + `type`
+
+建议类型枚举（待确认）：
+
+| 值 | 含义 |
+| --- | --- |
+| `1` | 试用 |
+| `2` | 正式 |
+| `3` | 赠送 |
+
+建议状态枚举（待确认）：
+
+| 值 | 含义 |
+| --- | --- |
+| `1` | 有效 |
+| `2` | 已过期 |
+| `3` | 已停用 |
+
+### `sessions`
+
+承载一次治疗会话的过程态。
+
+| 字段名 | 建议类型 | 是否必填 | 默认值 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `id` | `BIGINT UNSIGNED` | 是 | 自增 | 约定 | 主键 |
+| `user_id` | `BIGINT UNSIGNED` | 是 | 无 | 推导 | 关联 `users.id` |
+| `device_id` | `BIGINT UNSIGNED` | 是 | 无 | 推导 | 关联 `devices.id` |
+| `status` | `TINYINT UNSIGNED` | 是 | `1` | 推导 | 会话状态枚举 |
+| `started_at` | `DATETIME` | 否 | `NULL` | 推导 | 会话开始时间 |
+| `ended_at` | `DATETIME` | 否 | `NULL` | 推导 | 会话结束时间 |
+| `created_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 约定 | 创建时间 |
+| `updated_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP ON UPDATE` | 约定 | 更新时间 |
+
+建议索引：`user_id` + `status`，`device_id`
+
+建议状态枚举（待确认）：
+
+| 值 | 含义 |
+| --- | --- |
+| `1` | 进行中 |
+| `2` | 已完成 |
+| `3` | 已中断 |
+| `4` | 失败 |
+
+待确认边界：`sessions` 与 `treatment_records` 是否一对一。
+
+### `treatment_records`
+
+承载治疗结果记录。
+
+| 字段名 | 建议类型 | 是否必填 | 默认值 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `id` | `BIGINT UNSIGNED` | 是 | 自增 | 约定 | 主键 |
+| `session_id` | `BIGINT UNSIGNED` | 是 | 无 | 推导 | 关联 `sessions.id`，待确认一对一还是一对多 |
+| `user_id` | `BIGINT UNSIGNED` | 是 | 无 | 推导 | 关联 `users.id`，冗余查询用 |
+| `device_id` | `BIGINT UNSIGNED` | 是 | 无 | 推导 | 关联 `devices.id`，冗余查询用 |
+| `duration_seconds` | `INT UNSIGNED` | 否 | `NULL` | 推导 | 治疗时长秒数，待确认字段名和单位 |
+| `mode` | `TINYINT UNSIGNED` | 否 | `NULL` | 推导 | 治疗模式，待确认枚举 |
+| `result_summary` | `VARCHAR(512)` | 否 | `NULL` | 推导 | 结果摘要，待确认格式 |
+| `sync_status` | `TINYINT UNSIGNED` | 是 | `1` | 推导 | 同步状态，用于追踪异步写入 |
+| `synced_at` | `DATETIME` | 否 | `NULL` | 推导 | 同步完成时间 |
+| `started_at` | `DATETIME` | 否 | `NULL` | 推导 | 治疗开始时间 |
+| `ended_at` | `DATETIME` | 否 | `NULL` | 推导 | 治疗结束时间 |
+| `created_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 约定 | 创建时间 |
+| `updated_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP ON UPDATE` | 约定 | 更新时间 |
+
+建议索引：`user_id` + `started_at`，`session_id`，`sync_status`
+
+建议同步状态枚举（待确认）：
+
+| 值 | 含义 |
+| --- | --- |
+| `1` | 待同步 |
+| `2` | 已同步 |
+| `3` | 同步失败 |
+
+### `pd_data`
+
+承载与 `PD` 相关的数据。
+
+当前只知道该表存在，字段无法推导。
+
+| 字段名 | 建议类型 | 是否必填 | 默认值 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `id` | `BIGINT UNSIGNED` | 是 | 自增 | 约定 | 主键 |
+| `session_id` | `BIGINT UNSIGNED` | 否 | `NULL` | 推导 | 关联 `sessions.id`，待确认 |
+| `device_id` | `BIGINT UNSIGNED` | 否 | `NULL` | 推导 | 关联 `devices.id`，待确认 |
+| `data_payload` | 待定义 | 待定义 | 待定义 | 待定义 | 数据内容，格式和结构完全未确认 |
+| `recorded_at` | `DATETIME` | 否 | `NULL` | 推导 | 采集时间 |
+| `created_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 约定 | 创建时间 |
+
+待确认：
+
+- `PD` 的含义和数据来源
+- 是否为高频时序数据
+- 是否需要单独存储引擎
+- 是否按会话切片
+
+### `operation_logs`
+
+承载操作日志。
+
+| 字段名 | 建议类型 | 是否必填 | 默认值 | 来源 | 说明 |
+| --- | --- | --- | --- | --- | --- |
+| `id` | `BIGINT UNSIGNED` | 是 | 自增 | 约定 | 主键 |
+| `operator_type` | `TINYINT UNSIGNED` | 是 | 无 | 推导 | 操作者类型，区分管理员和系统 |
+| `operator_id` | `BIGINT UNSIGNED` | 否 | `NULL` | 推导 | 操作者 ID，关联 `users` 或后台管理员表 |
+| `target_type` | `VARCHAR(32)` | 是 | 无 | 推导 | 操作对象类型，如 `user`、`device`、`subscription`、`binding` |
+| `target_id` | `BIGINT UNSIGNED` | 否 | `NULL` | 推导 | 操作对象 ID |
+| `action` | `VARCHAR(32)` | 是 | 无 | 推导 | 操作类型，如 `create`、`update`、`delete`、`bind`、`unbind` |
+| `before_snapshot` | `TEXT` | 否 | `NULL` | 推导 | 操作前数据快照，待确认格式 |
+| `after_snapshot` | `TEXT` | 否 | `NULL` | 推导 | 操作后数据快照，待确认格式 |
+| `ip_address` | `VARCHAR(64)` | 否 | `NULL` | 推导 | 操作来源 IP |
+| `user_agent` | `VARCHAR(256)` | 否 | `NULL` | 推导 | 操作来源客户端标识 |
+| `remark` | `VARCHAR(256)` | 否 | `NULL` | 推导 | 备注说明 |
+| `created_at` | `DATETIME` | 是 | `CURRENT_TIMESTAMP` | 约定 | 创建时间 |
+
+建议索引：`target_type` + `target_id`，`operator_type` + `operator_id`，`created_at`
+
+建议操作者类型枚举（待确认）：
+
+| 值 | 含义 |
+| --- | --- |
+| `1` | 管理员 |
+| `2` | 系统自动 |
+
+## 实体关系总结
+
+| 关系 | 左侧 | 右侧 | 类型 | 待确认 |
+| --- | --- | --- | --- | --- |
+| 用户绑定设备 | `users` | `devices` | 通过 `bindings` 多对多 | 是，实际可能接近一对一 |
+| 用户拥有订阅 | `users` | `subscriptions` | 一对多 | 否 |
+| 设备关联订阅 | `devices` | `subscriptions` | 待确认 | 是，是否需要关联 |
+| 用户发起会话 | `users` | `sessions` | 一对多 | 否 |
+| 设备执行会话 | `devices` | `sessions` | 一对多 | 否 |
+| 会话产生记录 | `sessions` | `treatment_records` | 待确认 | 是，一对一还是一对多 |
+| 会话产生 PD 数据 | `sessions` | `pd_data` | 待确认 | 是 |
+| 操作日志记录对象 | `operation_logs` | 各业务表 | 多态关联 | 否 |
+
+## 每张表仍需补齐的设计项
+
+后续推进到 DDL 时，每张表至少还需要：
+
+- 确认主键方案
+- 确认字段类型和长度
+- 确认枚举值
+- 确认时区约定
+- 确认软删策略
+- 补充 DDL
+- 补充索引设计
+- 补充迁移脚本
+
+## 当前结论
+
+当前说明已经足够把数据库推进到"字段草案"层。所有标为"推导"的字段都需要在下一步被确认或修正。最优先要确认的是 `users` 与 `devices` 的绑定约束、`subscriptions` 的归属模型、`sessions` 与 `treatment_records` 的关系。

docs/design/05-IoT设备注册与MQTT消息规范.md

@@ -0,0 +1,156 @@
+# IoT 设备注册与 MQTT 消息规范
+
+基于 `软件系统说明.docx` 整理。本文档用于固定当前已知的 IoT 与 MQTT 事实，并列出设备接入、消息定义和云端处理前必须补齐的规格项。
+
+本文档不虚构未被文档确认的 topic、payload 或接入流程。
+
+## 已确认事实
+
+- 设备接入平台：`Tencent Cloud IoT Hub`
+- 设备通过 `MQTT over TLS` 连接 IoT Hub
+- 已知上报主题：`$iot/{product_id}/{device_name}/telemetry`
+- 已知事件主题：`$iot/{product_id}/{device_name}/event`
+- 云端业务组件包含：`SCF`、`MySQL`、`Redis`、`CLS`、`CMQ`
+- 护理记录存在异步写入路径
+- 云函数职责中包含：设备注册、动态获取 `DeviceSecret`
+
+## 已知接入边界
+
+从当前文档可确认以下边界：
+
+- 设备端不是直接写业务数据库，而是先接入 IoT Hub
+- 云端至少存在一条设备消息 -> 云端处理 -> 数据落库的链路
+- 设备身份认证依赖 `DeviceSecret`
+- 系统同时存在实时设备通信和异步消息处理
+
+## 设备接入流程的最小骨架
+
+当前文档没有给出完整时序，但从已知信息可整理出一条最小流程骨架：
+
+1. 设备具备 `product_id` 和 `device_name`
+2. 设备获取或持有 `DeviceSecret`
+3. 设备通过 `MQTT over TLS` 连接 IoT Hub
+4. 设备向指定 topic 上报 telemetry 和 event
+5. 云端处理消息并执行日志、异步、入库等后续动作
+
+## 待补齐的设备注册流程
+
+当前最大缺口是 `DeviceSecret` 和设备注册流程，至少需要明确：
+
+- 设备是在生产阶段预注册，还是首次使用时动态注册
+- `DeviceSecret` 是一次性签发还是可轮换
+- `DeviceSecret` 由谁调用云函数获取：生产工具、设备端、小程序端，还是后台系统
+- 设备首次上线是否需要激活
+- 设备注册与用户绑定是否是两个独立阶段
+- 设备换绑、禁用、报废时如何处理 IoT 身份
+
+## MQTT topic 已知信息
+
+### 遥测主题
+
+- Topic：`$iot/{product_id}/{device_name}/telemetry`
+- 作用：设备业务数据上报
+
+当前缺失：
+
+- payload 结构
+- 上报频率
+- 是否包含治疗过程数据
+- 是否包含传感器原始数据
+
+### 事件主题
+
+- Topic：`$iot/{product_id}/{device_name}/event`
+- 作用：设备事件上报
+
+当前缺失：
+
+- 事件类型枚举
+- 事件触发条件
+- 事件 payload
+- 错误事件与普通事件的区分
+
+## 必须补齐的消息规范
+
+### 1. Telemetry 消息
+
+至少需要确认：
+
+- 消息体格式：JSON、二进制或其他格式
+- 核心字段
+- 时间戳字段
+- 设备状态字段
+- 治疗相关字段
+- 是否包含批量数据
+- 是否需要签名或序列号
+
+### 2. Event 消息
+
+至少需要确认：
+
+- 事件类型枚举
+- 事件等级
+- 事件时间
+- 事件附加上下文
+- 是否需要重试
+
+### 3. 下行控制消息
+
+当前文档没有明确写出下行 topic，但若系统需要远程控制或同步状态，必须明确：
+
+- 是否存在云端 -> 设备的下发 topic
+- 是否存在应答 topic
+- 远程指令的触发方：小程序、后台、云端任务
+- 指令时效和超时规则
+
+## 消息处理链路待确认
+
+当前只知道使用 `CMQ` 异步处理，至少需要明确：
+
+- IoT Hub 消息如何进入云函数或消息队列
+- 哪些消息同步处理，哪些消息异步处理
+- 护理记录异步写入的触发条件
+- 失败重试策略
+- 死信消息处理策略
+- 日志打点字段
+
+## 建议补充的消息模板
+
+后续可以按以下模板补齐实际 payload。
+
+### Telemetry 模板
+
+| 字段 | 类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| 待定义 | 待定义 | 待定义 | 待定义 |
+
+### Event 模板
+
+| 字段 | 类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| 待定义 | 待定义 | 待定义 | 待定义 |
+
+## 设备状态建议先澄清的枚举
+
+后续设计时建议先统一这些状态的定义：
+
+- 未注册
+- 已注册未激活
+- 已激活未绑定
+- 已绑定
+- 在线
+- 离线
+- 禁用
+- 故障
+
+## 待确认问题
+
+- `DeviceSecret` 是否通过云函数动态返回给设备
+- 小程序在设备注册链路中扮演什么角色
+- 设备是否需要主动上报固件版本、硬件版本、电量、错误状态
+- `telemetry` 和 `event` 的边界如何划分
+- 后台是否需要通过云端下发控制指令
+
+## 当前结论
+
+当前说明已足够确定 IoT 接入方式和两个基础 MQTT topic，但远不足以支持设备接入开发。最先要补的是设备注册流程、`DeviceSecret` 生命周期、payload 结构和消息处理链路。

docs/design/06-管理后台功能与权限设计.md

@@ -0,0 +1,172 @@
+# 管理后台功能与权限设计
+
+基于 `软件系统说明.docx` 整理。本文档用于把管理后台的已知模块拆成可继续细化的功能和权限骨架。
+
+本文档不虚构页面字段、角色名或权限编码，只保留已知边界和待确认项。
+
+## 已确认事实
+
+- 后台技术栈：`uniapp + Vue 3 + uView Plus`
+- 部署方式：腾讯云静态网站托管
+- 已确认功能模块：
+- 仪表盘
+- 设备管理
+- 用户管理
+- 订阅管理
+- 护理记录
+- 操作日志
+- 系统设置
+- 文档明确存在角色权限和 API 级别鉴权
+
+## 模块职责拆解
+
+### 仪表盘
+
+文档已确认包含：
+
+- 用户统计
+- 设备统计
+- 治疗统计
+- 订阅统计
+
+待确认：
+
+- 统计口径
+- 统计时间范围
+- 是否支持趋势图、排行榜、分布图
+- 是否区分实时统计和离线统计
+
+### 设备管理
+
+文档已确认包含：
+
+- 设备列表
+- 设备详情
+- 设备绑定管理
+
+待确认：
+
+- 列表字段
+- 筛选条件
+- 是否支持设备禁用、解绑、查看在线状态
+- 是否支持远程指令或仅查询
+
+### 用户管理
+
+文档已确认包含：
+
+- 用户列表
+- 用户详情
+- 订阅管理
+- 绑定管理
+
+待确认：
+
+- 用户详情页字段
+- 是否支持用户禁用
+- 是否支持人工调整订阅状态
+
+### 订阅管理
+
+文档已确认包含：
+
+- 订阅列表
+- 创建订阅
+- 续期管理
+
+待确认：
+
+- 是否需要退款、停用、赠送功能
+- 是否有订单概念
+- 是否记录发放来源
+
+### 护理记录
+
+文档已确认包含：
+
+- 治疗记录查询
+- 数据导出
+
+待确认：
+
+- 查询维度
+- 导出格式
+- 是否支持查看原始传感器数据
+
+### 操作日志
+
+文档已确认包含：
+
+- 日志查询
+
+待确认：
+
+- 记录哪些操作
+- 是否区分管理员操作和系统操作
+- 查询维度和保留时间
+
+### 系统设置
+
+文档已确认包含：
+
+- 管理员管理
+- 权限配置
+
+待确认：
+
+- 是否还包含公告管理、字典配置、设备参数配置等系统能力
+
+## 建议最小后台版本
+
+为了支持第一阶段上线，后台最小版本建议先覆盖：
+
+- 用户列表与详情
+- 设备列表与详情
+- 绑定关系查询
+- 订阅列表与续期
+- 治疗记录查询
+- 操作日志查询
+
+## 权限模型待确认
+
+文档只确认存在“角色权限”和“API 级别鉴权”，至少需要明确：
+
+- 角色有哪些
+- 每个角色可访问哪些菜单
+- 每个角色可调用哪些接口
+- 是否区分只读和可操作权限
+- 高风险操作是否需要二次确认
+
+## 建议权限拆分维度
+
+后续可按以下维度细化：
+
+- 菜单权限
+- 页面按钮权限
+- API 调用权限
+- 数据范围权限
+
+## 建议页面规格模板
+
+后续细化每个页面时，至少需要明确：
+
+- 页面名称
+- 页面入口
+- 访问角色
+- 列表字段
+- 查询条件
+- 可执行操作
+- 详情字段
+- 导出字段
+
+## 待确认问题
+
+- 后台管理员如何登录
+- 是否存在超级管理员
+- 是否需要多组织或多租户隔离
+- 仪表盘统计口径是否来自实时聚合还是离线任务
+- 数据导出是否受角色限制
+
+## 当前结论
+
+当前说明已经能定义后台模块边界，但还不能直接进入页面和接口实现。最先要补的是角色定义、菜单结构、列表字段、操作权限和统计口径。

docs/design/07-安全与鉴权方案.md

@@ -0,0 +1,112 @@
+# 安全与鉴权方案
+
+基于 `软件系统说明.docx` 整理。本文档用于把当前已知安全要求整理成可继续细化的设计骨架。
+
+本文档不虚构签名算法、密钥管理方案或合规要求，只固定已知要求和必须补齐的实现细节。
+
+## 已确认事实
+
+- 全链路传输使用 `TLS 1.2+`
+- 设备认证依赖 `DeviceSecret`
+- 用户认证为微信登录 + Token
+- Token 有效期为 7 天
+- 敏感数据需要加密存储
+- 需要 API 鉴权
+- 需要角色权限控制
+- 需要 API 级别鉴权
+
+## 安全边界拆分
+
+当前系统至少存在四类安全边界：
+
+- 小程序用户身份安全
+- 设备身份安全
+- 云端 API 访问安全
+- 后台管理权限安全
+
+## 用户鉴权待补项
+
+至少需要明确：
+
+- 微信登录到自有 token 的完整链路
+- Token 格式
+- Token 签名算法
+- Token 7 天有效期是否支持续期
+- Token 失效、登出、吊销机制
+- 多端并发登录规则
+
+## 设备鉴权待补项
+
+至少需要明确：
+
+- `DeviceSecret` 的签发时机
+- `DeviceSecret` 的保存位置
+- `DeviceSecret` 是否可轮换
+- 设备被盗用或泄露后的失效机制
+- 设备认证失败后的告警与禁用策略
+
+## API 安全待补项
+
+至少需要明确：
+
+- API 鉴权中间件规则
+- 接口级权限定义
+- 限流策略
+- 防重放策略
+- 防刷策略
+- 请求日志中需要记录的审计字段
+
+## 数据安全待补项
+
+至少需要明确：
+
+- 哪些字段属于敏感数据
+- 加密字段范围
+- 加密方式
+- 脱敏展示规则
+- 数据保留周期
+- 备份与恢复的安全要求
+
+## 后台权限安全待补项
+
+至少需要明确：
+
+- 管理员认证方式
+- 角色权限模型
+- 高风险操作的二次确认规则
+- 操作日志保留策略
+- 是否需要登录告警和异常操作审计
+
+## 建议最先统一的安全对象
+
+为了后续设计不混乱，建议先统一这些对象的定义：
+
+- 用户身份
+- 设备身份
+- 管理员身份
+- 访问 token
+- 设备密钥
+- 角色
+- 权限
+
+## 建议补充的安全设计模板
+
+后续可按以下模板逐项补齐：
+
+| 主题 | 已知要求 | 待确认实现 | 风险 |
+| --- | --- | --- | --- |
+| 用户登录 | 微信登录 + Token | 待定义 | 待评估 |
+| 设备认证 | `DeviceSecret` | 待定义 | 待评估 |
+| API 鉴权 | API 级别鉴权 | 待定义 | 待评估 |
+| 数据加密 | 敏感数据加密存储 | 待定义 | 待评估 |
+
+## 待确认问题
+
+- 小程序 token 是否只用于云端 API，还是也影响设备绑定授权
+- 后台是否与小程序共用用户体系
+- 是否需要设备侧应用层签名或加密，而不仅是 TLS
+- 是否有合规或审计的特殊要求
+
+## 当前结论
+
+当前说明已经明确安全目标，但没有给出实现方案。最先要补的是 token 生命周期、`DeviceSecret` 生命周期、权限模型和敏感数据定义。

docs/design/08-测试与验收标准.md

@@ -0,0 +1,156 @@
+# 测试与验收标准
+
+基于 `软件系统说明.docx` 整理。本文档用于给后续研发和联调提供测试与验收的最小框架。
+
+当前仓库没有源码、测试配置或 CI，因此本文档只定义应覆盖的测试范围和待确认项，不编造执行命令。
+
+## 当前测试目标
+
+基于说明文档，第一阶段测试至少需要覆盖四条主链路：
+
+- 小程序登录与设备绑定
+- BLE 连接、佩戴确认、自动扫描、开始治疗
+- 云端护理记录同步与查询
+- 后台用户、设备、订阅、治疗记录查询
+
+## 建议测试分层
+
+### 1. 设备与 BLE 联调测试
+
+至少应覆盖：
+
+- 扫描设备
+- 连接设备
+- 读取设备信息
+- 佩戴确认
+- 自动扫描
+- 开始治疗
+- 治疗中断与断连重连
+- OTA 基础链路
+
+当前缺失：
+
+- 设备模拟方案
+- BLE 协议明细
+- 测试数据与预期结果
+
+### 2. 云端接口测试
+
+至少应覆盖：
+
+- 微信登录
+- 设备绑定/解绑
+- 订阅状态查询
+- 试用订阅发放
+- 护理记录同步
+- 治疗记录查询
+
+当前缺失：
+
+- API 契约
+- 错误码规范
+- 鉴权策略
+
+### 3. IoT 与 MQTT 联调测试
+
+至少应覆盖：
+
+- 设备接入 IoT Hub
+- telemetry 上报
+- event 上报
+- 云端消息处理
+- 护理记录异步写入
+- 异常重试
+
+当前缺失：
+
+- payload 结构
+- 设备注册流程
+- 重试与死信规则
+
+### 4. 小程序端到端测试
+
+至少应覆盖：
+
+- 首次使用流程
+- 日常使用流程
+- 治疗记录同步
+- 试用到期后的表现
+- 网络异常、蓝牙异常、同步失败等异常流
+
+当前缺失：
+
+- 页面行为定义
+- 状态机细节
+- 异常流规则
+
+### 5. 后台功能测试
+
+至少应覆盖：
+
+- 用户查询
+- 设备查询
+- 绑定关系查询
+- 订阅管理
+- 治疗记录查询
+- 操作日志查询
+
+当前缺失：
+
+- 页面字段
+- 权限矩阵
+- 统计口径
+
+## 建议验收主链路
+
+第一阶段验收建议围绕以下主链路：
+
+1. 新用户扫码并完成设备绑定
+2. 绑定后自动获得 7 天试用
+3. 小程序成功连接设备并完成佩戴确认
+4. 自动扫描成功并开始治疗
+5. 治疗完成后记录可在云端查询
+6. 管理后台可查询用户、设备、订阅、治疗记录
+
+## 建议异常流验收项
+
+至少需要定义以下异常流是否通过验收：
+
+- 蓝牙授权被拒绝
+- 找不到设备
+- 设备断连
+- 设备已绑定他人
+- 订阅失效
+- 治疗中断
+- 云端同步失败
+- IoT 上报失败
+
+## 建议验收模板
+
+后续可按如下模板逐项编写测试用例：
+
+| 用例名称 | 前置条件 | 操作步骤 | 预期结果 | 备注 |
+| --- | --- | --- | --- | --- |
+| 待定义 | 待定义 | 待定义 | 待定义 | 待定义 |
+
+## 建议先补齐的测试前提
+
+后续执行测试前，至少需要先明确：
+
+- 是否存在设备测试机和模拟器
+- 开发、测试、生产环境的联调边界
+- 测试账号准备方式
+- 测试数据初始化方式
+- 日志排查入口
+- 故障复现与回归流程
+
+## 待确认问题
+
+- 小程序是否有最低微信版本要求
+- 设备联调是否依赖特定手机机型
+- 护理记录异步写入的最终一致性验收口径是什么
+- 后台导出是否属于第一阶段验收范围
+
+## 当前结论
+
+当前说明已经足够定义测试范围，但还不足以编写可执行测试用例。最先要补的是 BLE 协议、API 契约、状态机和验收口径。