Explorar el Código

docs: 华为运动健康接入配置清单与前端接入契约(H1-H4,认证通过后配置开发)

Agnes Agent hace 6 horas
padre
commit
1492c221d5

+ 143 - 0
docs/2026-11-18-华为运动健康小程序端接入契约-H1-H4.md

@@ -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)与小米侧独立,互不依赖。

+ 129 - 0
docs/2026-11-18-华为运动健康接入配置清单与联调指引.md

@@ -0,0 +1,129 @@
+# 华为运动健康接入 · 配置清单与联调指引(H-Config)
+
+> 生成日期:2026-11-18 | 关联方案:`docs/2026-11-06-华为运动健康开放平台接入方案.md`(v1.2)
+> 前置状态:✅ 华为开发者认证通过(用户 2026-11-18 确认);✅ 后端 D1-D5 已合入主线 `978d1bc95`(mock 默认)
+> 用途:华为后台操作 + 后端 env 注入 + real/ mock 双通道切换的**唯一步骤文档**
+
+---
+
+## 0. 一句话结论
+
+后端接入代码(OAuth 授权码流程 + 5 类数据映射 + token 加密落库 + 定时同步)已全部就绪且默认 mock。**认证已通过后要做的只有一件事:在华为开发者后台开通/申请「健康数据」权限,把真实 `client_id/client_secret` 与 URL 形式 scope 注入环境变量,切 `mock-enabled=false` 联调。**
+
+---
+
+## 1. 华为官方权威 OAuth Scope(2026-11-18 从开发者官网核实)
+
+华为 Health Service Kit 的 OAuth scope 是 **URL 形式**(空格分隔多值),**不是** `step,heart_rate` 这类简写。后端当前默认值 `step,distance,heart_rate,sleep,body_weight` 只能用于 mock 通道,**real 模式必须整体替换为下列 URL 形式**:
+
+| 数据 | 读权限 scope(官方权威值) | 本期 | 维度映射 |
+|---|---|---|---|
+| 步数 | `https://www.huawei.com/healthkit/step.read` | ✅ | body.exercise |
+| 距离 | `https://www.huawei.com/healthkit/distance.read` | ✅ | body.exercise |
+| 心率 | `https://www.huawei.com/healthkit/heartrate.read` | ✅ | body.immunity |
+| 睡眠 | `https://www.huawei.com/healthkit/sleep.read` | ✅ | body.sleep |
+| 体重/身高 | `https://www.huawei.com/healthkit/heightweight.read` | ✅ | body.nutrition, body.growth |
+| 血氧 | `https://www.huawei.com/healthkit/oxygensaturation.read` | 备选 | - |
+| 热量 | `https://www.huawei.com/healthkit/calories.read` | 备选 | - |
+| 账号基础信息 | `https://www.huawei.com/auth/account/base.profile`(授权登录必需,随 OAuth 一并带) | 必需 | - |
+
+**real 模式完整 scope 字符串**(空格分隔,本期 5+1 个):
+
+```
+https://www.huawei.com/auth/account/base.profile https://www.huawei.com/healthkit/step.read https://www.huawei.com/healthkit/distance.read https://www.huawei.com/healthkit/heartrate.read https://www.huawei.com/healthkit/sleep.read https://www.huawei.com/healthkit/heightweight.read
+```
+
+---
+
+## 2. 华为开发者后台操作清单(认证通过后)
+
+### 2.1 开通 Health Service Kit 服务
+1. 登录 [华为开发者联盟控制台](https://developer.huawei.com/consumer/cn/)(认证主体:北京安盈创卓科技有限公司 或 认证时选择的账号主体)。
+2. 控制台 → **我的项目** → 选择/创建 AppGallery Connect 项目。
+3. 项目内 → **开发服务 → 运动健康(Health Service Kit)** → 按向导**开通服务**。
+4. 在服务详情页获取 **Client ID / Client Secret**(OAuth 2.0 客户端凭据)。
+
+### 2.2 申请健康数据权限(联盟卡片)
+权限申请入口在各数据类型文档中标注为「联盟卡片申请的权限名称」:
+
+| 权限(联盟卡片名称) | 勾选 |
+|---|---|
+| 健康数据 > 运动数据 > 步数 | ✅ read |
+| 健康数据 > 运动数据 > 距离 | ✅ read |
+| 健康数据 > 心率数据 | ✅ read |
+| 健康数据 > 睡眠数据 | ✅ read |
+| 健康数据 > 身高体重数据(heightweight) | ✅ read |
+| 健康数据 > 血氧数据 | ⏳ 备选(暂不申请) |
+| 健康数据 > 热量数据 | ⏳ 备选(暂不申请) |
+
+> ⚠️ 华为权限区分「基础数据」(个人/企业开发者均可)与「高阶数据」(仅企业账号)。本期 6 项均为基础可申请。`base.profile` 为账号授权自动携带,无需单独申请卡片。
+
+### 2.3 配置 OAuth 回调地址
+- Health Service Kit OAuth 回调使用 **H5 中转页**(与小米同款架构,见接入契约文档 5.1):`https://cfc.etotem.com.cn/huawei-cb.html`(**注意:不是 `/api/huawei-health/callback`**——那是 POST 接口,不能直接收 OAuth 浏览器重定向)。
+- 在后台「OAuth 2.0 回调地址」白名单中登记该 URL。认证环境登记**开发环境地址**,生产发布前追加生产地址。
+
+### 2.4 其他
+- App 包名/签名:纯「云服务接入」模式(无 Android App)时,授权走 **H5 OAuth**(Account Kit 网页授权),不强制要求 Android 签名证书;但后台若要求登记应用签名,用 debug keystore 临时值占位并备注(验收专家以 OAuth 回调实测为准)。
+
+---
+
+## 3. 后端 env 注入清单(生产 / 预发 / 本地联调三环境通用)
+
+| 环境变量 | 当前默认值(mock) | real 模式必填值 |
+|---|---|---|
+| `HUAWEI_HEALTH_MOCK_ENABLED` | `true` | `false` |
+| `HUAWEI_CLIENT_ID` | `mock-client-id` | 后台 2.1 获取的真实 Client ID |
+| `HUAWEI_CLIENT_SECRET` | `mock-client-secret` | 后台 2.1 获取的真实 Client Secret |
+| `HUAWEI_REDIRECT_URI` | `https://cfc.etotem.com.cn/api/huawei-health/callback` | `https://cfc.etotem.com.cn/huawei-cb.html`(**⚠ 必须改为中转页**) |
+| `HUAWEI_SCOPE` | `step,distance,heart_rate,sleep,body_weight` | **第 1 节整段 URL 形式 scope**(值含空格,注入时注意引号) |
+| `HUAWEI_TOKEN_URL` | `https://oauth-login.cloud.huawei.com/oauth2/v3/token` | 保持默认(官方 OAuth v3 token 端点) |
+| `HUAWEI_AUTHORIZE_URL` | `https://oauth-login.cloud.huawei.com/oauth2/v3/authorize` | 保持默认(官方 OAuth v3 authorize 端点) |
+| `HUAWEI_REVOKE_URL` | `https://health-api.cloud.huawei.com/oauth/v1/token/revoke` | 保持默认 |
+| `HUAWEI_API_BASE_URL` | `https://health-api.cloud.huawei.com` | 保持默认 |
+| `HUAWEI_TOKEN_ENCRYPT_KEY` | `huaweiDevKey1234` | 生产改用强随机密钥(32 字符以上),**严禁用默认值上线** |
+| `HUAWEI_SYNC_DAYS` | `1` | 按需(建议 7,与同步频率配平) |
+| `HUAWEI_SYNC_CRON` | `0 15 3 * * ?` | 按需(03:15 每日全量补偿) |
+
+---
+
+## 4. real 模式三个代码必改点(2026-11-18 代码核验结论)
+
+> ⚠️ 以下为后端 `HuaweiAuthService` real 分支当前与官方要求不符处,**联调前必须由开发侧修正**(随 H-B2 后端小修一并派发,见接入契约文档 §7.1)。
+
+| # | 现状(代码) | 官方要求 | 影响 |
+|---|---|---|---|
+| B1 | `generateAuthUrl` 未带 `access_type=offline` | Account Kit OAuth 需 `access_type=offline` 才下发 `refresh_token` | 缺 refresh_token → 令牌 2h 过期后无法续期 |
+| B2 | token 交换 `Content-Type: application/json` | 华为 token 端点要求 `application/x-www-form-urlencoded` body | JSON body 会被华为拒绝(400),授权码流程中断 |
+| B3 | 默认 scope 简写(见 3 表) | 必须 URL 形式空格分隔 | 简写 scope 华为不识别 → 授权回调失败 |
+
+B3 可纯配置解决;B1/B2 需代码小改 + 契约单测补强。
+
+---
+
+## 5. 联调路线(按顺序推进)
+
+```
+阶段 A(mock 全链路,当前状态)────────────
+小程序 → auth-url(mock) → 直接调 callback(mock 占位 code)
+  → token 加密落库 → sync(mock 数据) → 卡片展示
+  ✅ 前端 H1-H4 开发验收可完全在此阶段完成
+
+阶段 B(real 半链路,凭证到位后)─────────
+后端加 env(真实 client/secret + URL scope)→ mock-enabled=false
+  → 授权 URL 打开华为账号授权 → 华为回调 huawei-cb.html
+  → 中转页 POST /callback 换真 token → sync 拉真数据
+  ⚠ 步骤:先本地联调 → 再预发 → 最后生产;B1/B2 必须先修
+```
+
+---
+
+## 6. 关键链接(官方文档,2026-11-18 复核有效)
+
+| 文档 | URL |
+|---|---|
+| 数据开放总览(开放等级表) | https://developer.huawei.com/consumer/cn/doc/HarmonyOS-Guides/health-data-overview |
+| OAuth scope 列表(Xamarin 插件版,全量) | https://developer.huawei.com/consumer/en/doc/HMS-Plugin-Guides-V1/scope-list-0000001073459663-V1 |
+| Scope 常量参考(Android SDK) | https://developer.huawei.com/consumer/cn/doc/development/HMSCore-References-V5/scopes-0000001050092713-V5 |
+| 血氧文档(scope 实例) | https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/blood-oxygen-0000001131264010 |
+| 获取用户授权 | https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/extended-requesting-user-authorization-0000001071733944 |
+| 智慧手表数据获取(read 范围说明) | https://developer.huawei.com/consumer/en/doc/HMSCore-Guides/obtain-smart-watch-data-0000001365189921/ |