|
|
@@ -0,0 +1,143 @@
|
|
|
+# 华为运动健康 · 小程序端接入契约(H1–H4 派发契约)
|
|
|
+
|
|
|
+> 生成日期:2026-11-18 | 关联:`docs/2026-11-06-华为运动健康开放平台接入方案.md` §13(小米版,体例对齐)
|
|
|
+> 关联:`docs/2026-11-18-华为运动健康接入配置清单与联调指引.md`(配置与官方 scope 权威值)
|
|
|
+> 后端状态:✅ D1-D5 已合入主线 `978d1bc95`,5 接口齐备,默认 mock 通道
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 1. 背景与已确认决策
|
|
|
+
|
|
|
+| 项 | 状态 |
|
|
|
+|---|---|
|
|
|
+| 华为开发者账号 + 企业实名认证 | ✅ 2026-11-18 用户确认通过 |
|
|
|
+| 后端 D1-D5(5 接口 + token 加密 + 归一化 + 定时同步) | ✅ `978d1bc95` |
|
|
|
+| 后端 `HuaweiHealthController` 5 接口契约 | ✅ 本文 §3 随文登记,无需再查代码 |
|
|
|
+| 用户拍板(2026-11-18) | 「华为认证好了,继续配置开发」→ 认证后进入前端开发阶段 |
|
|
|
+| 沿用小米版架构决策 | ✅ web-view + 自有 H5 中转页;不建 Android 原生 App |
|
|
|
+
|
|
|
+**核心命题**:与小米完全同构——小程序内 web-view 打开 H5 中转页 → 跳华为 OAuth 授权 → 回调中转页换 token → 返回小程序。mock 凭证/未切 real 时全链路走 mock 分支(**不得触发 web-view**)。
|
|
|
+
|
|
|
+**与小米的两处差异(务必按华为实现)**:
|
|
|
+
|
|
|
+1. **scope 是 URL 形式**(`https://www.huawei.com/healthkit/step.read` 等),不是 `step,heart_rate` 简写;且授权 URL 需带 `access_type=offline`。
|
|
|
+2. **华为回调页与小米回调页物理隔离**:华为用 `huawei-auth.html` / `huawei-cb.html`,**不复用** `xiaomi-*.html`(不同 scope 体系、不同授权域名)。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 数据类型映射(本期范围)
|
|
|
+
|
|
|
+| 后端 dataType | 华为数据 | 单位 | 维度 | 小程序展示 |
|
|
|
+|---|---|---|---|---|
|
|
|
+| `step` | 步数 | 步 | body.exercise | 卡片今日步数 |
|
|
|
+| `distance` | 距离 | km | body.exercise | 折叠在步数下 |
|
|
|
+| `heart_rate` | 心率 | bpm | body.immunity | 卡片心率摘要 |
|
|
|
+| `sleep` | 睡眠 | h | body.sleep | 卡片睡眠时长 |
|
|
|
+| `body_weight` | 体重 | kg | body.nutrition, body.growth | 卡片体重 |
|
|
|
+| 血氧 / 热量 | 备选 | - | - | 本期不申请权限、不展示 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 接口契约(后端已就绪,前端直接调用;JWT 拦截 `/api/**`,全部 `@PostMapping`)
|
|
|
+
|
|
|
+基址 `https://cfc.etotem.com.cn`,路径前缀 `/api/huawei-health`。
|
|
|
+
|
|
|
+| # | 接口 | 入参 | 出参关键字段 | 用途 |
|
|
|
+|---|---|---|---|---|
|
|
|
+| 1 | `POST /api/huawei-health/auth-url` | `{memberId?, scope?}`(memberId 空取当前登录成员;scope 空取后端默认) | `authUrl` / `memberId` / `scope` / `generateAt` | 取授权 URL |
|
|
|
+| 2 | `POST /api/huawei-health/callback` | `{code, memberId?}` | `bound` / `status` / `expiresAt` | code 换 token(加密落库,token 不落小程序) |
|
|
|
+| 3 | `POST /api/huawei-health/sync` | `{memberId?, dataType?}`(空=全量 5 类) | `syncAt` + `result`(单类型) 或 `results`(全量) | 触发同步 |
|
|
|
+| 4 | `POST /api/huawei-health/revoke` | `{memberId?}` | `revoked` | 撤销授权(合规必需) |
|
|
|
+| 5 | `POST /api/huawei-health/status` | `{memberId?}` | `bound` / `channel` / `mock` / `configured` / `expiresAt` / `scope` | 状态查询 |
|
|
|
+
|
|
|
+> ⚠️ **契约差异点(与小米不同,前端必须适配)**:接口 1 返回的 `authUrl` 中 **`scope` 已是后端拼好的 URL 形式字符串**(已 encode);前端**不得**自行拼接或改写 scope 参数,直接原样使用 `authUrl`。
|
|
|
+> ⚠️ 接口 1 返回**无** `mode` / `state` 字段(华为以 `state=memberId` 形式内嵌于 URL);前端判 mock 分支的判据是 **`authUrl` 是否指向华为授权域名**(`oauth-login.cloud.huawei.com`)——**不是** `mode` 字段。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 前端任务拆解(H1–H4)
|
|
|
+
|
|
|
+### H1 `cfc-frontend/utils/api.js`
|
|
|
+按既有封装风格新增 5 个方法(`huaweiAuthUrl` / `huaweiCallback` / `huaweiSync` / `huaweiRevoke` / `huaweiStatus`),字段与 §3 契约逐一致,全部 POST JSON。
|
|
|
+
|
|
|
+### H2 入口与状态卡片
|
|
|
+- `cfc-frontend/pages/health-main.vue` 挂「运动手环 · 华为健康」卡片:
|
|
|
+ - **未绑定态**:绑定按钮 + 用途说明;
|
|
|
+ - **已绑定态**:最近同步时间 + 步数/心率/睡眠/体重摘要 + mock 角标 + 「数据来自华为运动健康」标注 + 手动同步按钮。
|
|
|
+- `profile-main.vue` 增「设备管理」二级入口,复用同卡片。
|
|
|
+- 卡片文案不得出现「诊断/治疗/康复疗效」表述;血氧/热量本期不展示。
|
|
|
+
|
|
|
+### H3 授权链路(mock/real 双分支)
|
|
|
+```
|
|
|
+点「绑定」
|
|
|
+ → 接口1 取 authUrl
|
|
|
+ → 判据:authUrl 含 oauth-login.cloud.huawei.com ?
|
|
|
+ ├─ 否(mock)→ 直接调接口2(code 用 mock 占位值,如 "mock-code")
|
|
|
+ │ → 成功后调接口5 刷新卡片为已绑定(全程不触发 web-view)
|
|
|
+ └─ 是(real)→ 小程序内 web-view 打开 /huawei-auth.html?memberId=<id>
|
|
|
+ → 该页 location.replace(authUrl) 跳华为授权
|
|
|
+ → 华为回调 /huawei-cb.html?code=<code>&state=<memberId>
|
|
|
+ → 中转页 POST 接口2 → 渲染三态(成功/失败/参数缺失)
|
|
|
+ → 用户返回小程序 → 调接口5 刷新为已绑定
|
|
|
+```
|
|
|
+- **mock 分支硬约束**:不得打开任何 web-view(华为 mock authUrl 非授权域名,web-view 会白屏)。
|
|
|
+- **real 分支约束**:`huawei-auth.html` 与 `huawei-cb.html` 部署在小程序 web-view 业务域名下(与 cfclub 现有 web-view 域名一致)。
|
|
|
+
|
|
|
+### H4 同步、撤销、错误与合规
|
|
|
+- 手动同步 → 接口3;单类型失败按 `dataType` 给具体错误文案(如「睡眠数据同步失败,请重新授权」)。
|
|
|
+- 撤销 → 二次确认弹窗 → 接口4 → 卡片回未绑定态。
|
|
|
+- 合规常驻文案:「撤销授权即停止同步;数据仅用于家庭健康档案展示」。
|
|
|
+- 授权前数据用途说明必须可见:读取步数/距离/心率/睡眠/体重/身高,仅用于家庭健康档案与趋势分析。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 静态中转页(B1)
|
|
|
+
|
|
|
+### 5.1 `web/huawei-auth.html`
|
|
|
+- 入口:`/huawei-auth.html?memberId=<id>`;
|
|
|
+- 行为:读 query → `location.replace(decodeURIComponent(authUrl))`(authUrl 由前端调接口1后拼在本页 query 或通过后端中转获取,**优先用后端中转以免 URL 过长**);
|
|
|
+- 视觉:与 cfclub 现有 web-view 页一致(顶部标题「连接华为运动健康」,加载态 + 「若未自动跳转请点此」兜底按钮);
|
|
|
+- 禁止在页面内出现任何华为账号密码输入框(防钓鱼观感与合规风险)。
|
|
|
+
|
|
|
+### 5.2 `web/huawei-cb.html`
|
|
|
+- 入口:`/huawei-cb.html?code=<code>&state=<memberId>`;
|
|
|
+- 行为:解析 query → POST 接口2(`{code, memberId:Number(state)}`)→ 三态渲染:
|
|
|
+ - 成功:「已授权,请返回小程序」(≥3s 自动尝试关闭引导);
|
|
|
+ - 失败:错误文案 + 重试按钮(重试走重新授权);
|
|
|
+ - 参数缺失(无 code):兜底文案「授权未完成,请返回重试」;
|
|
|
+- `state` 校验:华为 OAuth 原样带回 `memberId`,中转页只做**类型与长度**基本校验;**服务端 memberId 与 JWT 归属的最终校验在后端接口2完成**(前端不得仅凭 query 决定绑定对象)。
|
|
|
+
|
|
|
+### 5.3 部署与约束
|
|
|
+- 两页部署到 `https://cfc.etotem.com.cn/`(与小程序 web-view 业务域名一致),随 `web/` 仓库同步上线;
|
|
|
+- `HUAWEI_REDIRECT_URI` 指向 `https://cfc.etotem.com.cn/huawei-cb.html`(**不是** `/api/huawei-health/callback`);
|
|
|
+- 华为后台 OAuth 回调白名单需登记同一 URL(配置清单 §2.3)。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 6. 验收标准(派发交付判据)
|
|
|
+
|
|
|
+1. **mock 全链路**:绑定 → status 已绑定 + mock 角标 → 手动同步成功 → 卡片展示步数/心率/睡眠/体重摘要 → 撤销回未绑定态;**全程无 web-view 打开**。
|
|
|
+2. **契约一致**:`api.js` 5 方法与 §3 逐一致(路径/POSTJSON/字段名/错误码透传);**前端不自行拼 scope**。
|
|
|
+3. **安全合规**:token 不落小程序任何存储;JWT 鉴权路径与后端一致;撤销二次确认;用途说明在绑定前可见。
|
|
|
+4. **红线**:不做社区逆向接口;不做境外聚合中转(数据出境);正式文案无治疗/诊断宣称;不承诺「儿童手环数据」(华为儿童数据不开放)。
|
|
|
+5. **real 留白**:mock 开关切 false + env 注入路径在交付文档显式标注(引用配置清单 §3),联调方案随交付。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 7. 随契约派发的后端小修(H-B1~B3,属 real 联调前置,不阻塞 mock 验收)
|
|
|
+
|
|
|
+| # | 位置 | 改法 | 单测 |
|
|
|
+|---|---|---|---|
|
|
|
+| H-B1 | `HuaweiAuthService.generateAuthUrl` | 授权 URL 追加 `access_type=offline`(获取 refresh_token 必需) | 断言 URL 含 `access_type=offline` |
|
|
|
+| H-B2 | `HuaweiAuthService.exchangeCode` real 分支 | token 交换改 `application/x-www-form-urlencoded` form body(华为官方要求) | mock 分支不受影响;real 分支用 mock RestTemplate 断言 Content-Type 与 body 形态 |
|
|
|
+| H-B3 | `application.yml` + 配置清单 | 默认 scope 改为 URL 形式(或至少在 real 启动时校验 scope 含 `https://www.huawei.com/healthkit/` 前缀,缺失则 fail-fast 并给出明确报错) | 断言 real 模式下非法 scope 被拒绝 |
|
|
|
+
|
|
|
+> 注:H-B1/B2 涉及 OAuth 协议细节,属**后端小修**范围,须由开发侧按 RED→YELLOW→GREEN 推进,不在本前端契约的交付判据内,但需在交付说明中列出完成状态。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 8. 与小米端的并存说明
|
|
|
+
|
|
|
+- 两条通道**并存**,同一家庭成员可分别绑定小米与华为;卡片分开呈现,不合并数据源显示。
|
|
|
+- 同步时分别触发各自 `/sync`,落库时**各自来源标记**,不得互相覆盖;跨源合并展示留待后续版本(本期不做)。
|
|
|
+- 后台同步任务 `HuaweiHealthSyncJob`(03:15)与小米侧独立,互不依赖。
|