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

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