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