Sfoglia il codice sorgente

docs(huawei-health): 方案 v1.4 补第十三节 小程序端小米集成设计(2026-11-16 派发契约)

Agnes Agent 10 ore fa
parent
commit
87e9d7dfa1

+ 65 - 1
docs/2026-11-06-华为运动健康开放平台接入方案.md

@@ -1,7 +1,8 @@
 # 运动健康多生态接入方案(华为 Health Service Kit + 小米 HealthKit / Zepp)
 
-> 版本:v1.2 · 日期:2026-11-07 · 决策:华为方案二(云侧 REST API)+ 小米官方云服务接口(多生态并行)
+> 版本:v1.4 · 日期:2026-11-16 · 决策:华为方案二(云侧 REST API)+ 小米官方云服务接口(多生态并行)
 > 关联模块:cfclub 小程序 / cfc-backend / 五维能量体系 / 家庭健康档案
+> v1.4 新增:第十三节「小程序端小米集成设计」(2026-11-16 用户拍板:应用名 cfc · 不建手机应用 · 集成落在现有小程序)
 
 ---
 
@@ -264,6 +265,69 @@
 
 ---
 
+## 十三、小程序端小米集成设计(2026-11-16 派发契约)
+
+### 13.0 背景与已确认决策
+
+| 项 | 状态 |
+|---|---|
+| 后端 X1-X5(5 接口 + token 加密库 + 归一化 + GAP-A 桥接) | ✅ 已合入主线 `4344688d2`(见 12.1) |
+| 小米开发者账号 + 企业实名认证 | ✅ **2026-11-16 13:50 审核通过**(dev.mi.com,企业主体「北京浠艾福科技有限公司」,小米 ID `778190837`,登录邮箱 liaoxiaoguang@sina.com) |
+| 小米运动健康数据服务凭证/权限申请 | ⏳ 未开始(需绑定应用 + 服务审批;用户拍板「不建手机应用」,服务申请策略另行决策) |
+| 后端 5 接口契约(字段/路径/方法) | ✅ `XiaomiHealthController`(随文登记,无需再查) |
+| 用户拍板(2026-11-16) | ① 应用名用 **cfc**;② **不建 Android 手机应用**;③ 小米手环集成落在**现有 cfclub 小程序内** |
+
+**核心设计命题**:小程序内完成 OAuth 授权走「web-view + 我们自己的 H5 中转页」,不依赖任何原生 App。mock 凭证未批复前全链路可用 mock 通道联调(`xiaomi.health.mock-enabled=true`),凭证到位改配置切 real。
+
+### 13.1 接口契约(后端已就绪,前端直接调用;JWT 拦截 `/api/**`,全部 `@PostMapping`)
+
+| # | 接口 | 入参 | 出参关键字段 | 用途 |
+|---|---|---|---|---|
+| 1 | `POST /api/xiaomi-health/auth-url` | `{memberId?}`(空取当前登录成员) | `authUrl` / `mode`(mock\|real) / `redirectUri` / `state` / `scope` | 取授权 URL + state |
+| 2 | `POST /api/xiaomi-health/callback` | `{code, memberId?}` | `bound` / `status` / `expiresAt` | code 换 token(加密落库,token 不触小程序) |
+| 3 | `POST /api/xiaomi-health/sync` | `{memberId?, dataType?}`(空=全量) | `syncAt` + `result`(单类型) 或 `results`(全量) | 触发同步 |
+| 4 | `POST /api/xiaomi-health/revoke` | `{memberId?}` | `revoked` | 撤销授权(合规必需) |
+| 5 | `POST /api/xiaomi-health/status` | `{memberId?}` | `bound` / `channel` / `mock` / `configured` / `expiresAt` / `scope` | 状态查询 |
+
+### 13.2 前端任务拆解(F1–F4)
+
+- **F1 `cfc-frontend/utils/api.js`**:按既有封装风格新增 5 个方法(authUrl / callback / sync / revoke / status),字段与 13.1 契约逐一致。
+- **F2 入口与状态卡片**:`cfc-frontend/pages/health-main.vue` 挂「运动手环 · 小米健康」卡片——未绑定态(绑定按钮+用途说明)/已绑定态(最近同步时间 + 步数/睡眠摘要 + mock 角标 + 数据来自小米的标注)+ 手动同步按钮;`profile-main.vue` 增「设备管理」二级入口可复用同卡片。
+- **F3 授权链路(mock/real 双分支)**:
+  - 点绑定 → 接口 1 拿 `authUrl`/`mode`;
+  - **real 分支**:`web-view` 打开 H5 中转页(13.3),用户授权成功后中转页 POST 接口 2,渲染「授权成功,请返回小程序」;用户返回小程序后调接口 5 刷新为已绑定;
+  - **mock 分支**(`mode=mock`):authUrl 为 mock 占位域(web-view 打不开)——前端直接调接口 2(code 用 mock 占位值)完成联调绑定,**不得再走 web-view**。
+- **F4 同步、撤销、错误与合规**:
+  - 手动同步调接口 3,结果 toast 分类型展示(单类型失败给 error 文案);
+  - 撤销需二次确认弹窗,调接口 4,成功后卡片回未绑定态;
+  - 合规:卡片常驻「撤销即停止同步」入口;绑定页需一份数据用途说明(步数/心率/睡眠/体重 + 仅家庭健康档案内展示);
+  - ⚠️ 不做「儿童手环」承诺性文案(华为侧儿童数据不开放;小米侧以官方回复为准)。
+
+### 13.3 OAuth web 回调中转(B1,后端/静态层小改)
+
+**问题**:real 模式 `xiaomi.health.redirect-uri` 默认值 `https://cfc.etotem.com.cn/api/xiaomi-health/callback` 是 POST 接口,而 OAuth 浏览器重定向为 GET 带 code,直接回打不可用。
+
+**方案(两个静态中转页,放小程序 web-view 业务域名下)**:
+
+1. `xiaomi-auth.html?memberId=<id>` —— 由后端接口 1 返回的 `authUrl` 驱动 `location.replace(authUrl)` 跳转小米授权;仅作 web-view 落地壳。header/文案与 cfclub 视觉一致。
+2. `xiaomi-cb.html?code=<code>&state=<state>` —— 解析 query,POST 接口 2 换 token,渲染三态:成功(「已授权,请返回小程序」)/失败(error 文案 + 重试按钮)/参数缺失兜底;成功后 ≥3s 自动关闭引导(web-view 由小程序侧关闭)。
+
+**约束**:部署位置为**与小程序 web-view 业务域名一致**的静态域(由开发在交付说明中确认实际部署路径);`redirect-uri` 默认值同步改为中转页地址(H5 URL),真实凭证批复前该地址可先用;`state` 校验(防 CSRF)在 callback 链路补齐(后端小修)。
+
+### 13.4 验收标准(派发给开发的交付判据)
+
+1. **mock 全链路**:小程序内完成 绑定(F3 mock 分支)→ status 显示已绑定+mock 角标 → 手动同步成功 → 卡片展示步数/睡眠摘要 → 撤销回未绑定态;全程无 web-view 报错(mock 分支不得触发 web-view)。
+2. **契约一致**:`api.js` 5 方法与 13.1 契约字段逐一致;路径/方法/POSTJSON/错误码透传正确。
+3. **安全合规**:token 不落小程序任何存储;JWT 鉴权路径与后端一致;二次确认撤销;用途说明可见。
+4. **后端小修(如涉及 B1)**:`state` 校验 + callback 对缺失 code 的 400 行为保持;补/改相应单测(契约级),RED→YELLOW→GREEN 按编排通道推进。
+5. **real 模式留白**:mock 开关切 false + 环境变量注入路径在文档/代码注释中显式标注,联调方案随交付文档。
+
+### 13.5 红线(与 11 节一致)
+
+禁社区逆向接口;禁境外聚合中转(数据出境);token 仅后端持有;授权/撤销/按类型细分必须实现;正式材料不作治疗/诊断宣称。
+
+---
+
 ## 附录 A:华为开放数据类型(本期用 + 备选)
 
 | 类型 | 数据 | 本期 |