# 云函数 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` 这五个核心接口。