docs(huawei-health): 华为运动健康开放平台接入方案 v1.0（方案二 Health Service Kit REST API + 双轨产品策略）

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

@@ -0,0 +1,204 @@
+# 华为运动健康开放平台接入方案（Health Service Kit REST API）
+
+> 版本：v1.0 · 日期：2026-11-06 · 决策：方案二（官方云侧 REST API）
+> 关联模块：cfclub 小程序 / cfc-backend / 五维能量体系 / 家庭健康档案
+
+---
+
+## 一、决策记录
+
+| 项 | 内容 |
+|----|------|
+| 选型 | 方案二：华为运动健康开放平台（Health Service Kit）云侧 REST API |
+| 否决 | 方案一：小程序蓝牙 BLE 直连（华为手环协议私有+加密+签名认证，不可行） |
+| 配套 | 方案三变通：儿童/全家档案走「手动导入」补充（双轨产品策略，见第七节） |
+| 决策日期 | 2026-11-06 |
+| 依据 | 华为开发者联盟官方文档：Health Service Kit 应用接入流程、面向应用开放服务、数据开放总览 |
+
+**关键事实（官方明文）**：
+1. 跨平台 / 微信小程序等 WEB 场景，**优先建议走 REST API**（云侧），保证多端体验一致性。
+2. Health Service Kit **不支持开放儿童相关数据**——家庭健康场景中孩子端数据必须绕开本通道。
+3. 开放基础原子数据：步数、心率、睡眠、体重等（华为穿戴设备采集，质量有保障）。
+4. 实时数据（实时心率/实时运动）属扩展能力，门槛更高，**本期不接入**。
+
+---
+
+## 二、申请主体与资质
+
+| 项 | 要求 | 备注 |
+|----|------|------|
+| 开发者类型 | **企业开发者**（个人开发者不满足） | 需企业营业执照 + 对公账户打款验证等 |
+| 主体一致性 | 华为开发者账号主体 == 小程序主体 | **第一前置动作**：确认用哪家企业主体 |
+| 候选主体 | 北京安盈创卓科技 / 亿图腾（北京）科技 | 需与 cfclub 小程序注册主体一致 |
+| 前置服务 | 账号服务（Account Kit）必须先开通 | Health Service Kit 依赖账号服务能力 |
+
+**第一动作**：确认 cfclub 小程序当前注册主体，华为开发者账号用同一主体注册企业实名认证。
+
+---
+
+## 三、审批链路与排期（约 33+ 个工作日）
+
+| 阶段 | 内容 | 周期 | 关键交付 |
+|------|------|------|----------|
+| ① 企业实名 + 账号服务 | 注册开发者、实名认证、开通 Account Kit | 3-5 工作日 | 企业认证通过 |
+| ② 权限审批 | 申请 Health Service Kit：选产品类型、勾选数据权限、交企业介绍+材料 | 15 工作日 | 数据权限批复 |
+| ③ 验证申请 | 开发测试完成后提交验证：佐证视频 + 自检 Checklist | 15 工作日 | 验证通过 |
+| ④ 正式商用 | 解除 100 用户测试限制 | — | 开放商用 |
+
+> 排期起点：审批链总计约 **33 个工作日（6-7 周）**，建议即刻启动申请；开发链并行推进（见第六节），互不阻塞。
+> 测试期限制：验证通过前仅 **100 用户**可用，灰度期用小范围种子用户。
+
+---
+
+## 四、技术架构
+
+```
+┌─────────────┐   ①用户授权(华为账号)   ┌──────────────┐   ②OAuth code→token   ┌──────────────────┐
+│ cfclub 小程序 │ ───────────────────────→ │  cfc-backend   │ ────────────────────→ │ 华为 Health Service │
+│  (uni-app)   │                          │  (Java/Spring) │                        │  Kit 云侧 REST API  │
+└─────────────┘                          └──────┬───────┘                        └──────────────────┘
+        ↑  ⑤前端展示(五维/健康档案)               │ ③ 定期拉取数据(调度)                        ↑
+        └────────────────────────────────────────┼──────────────────────────────────────┘
+                                                 ↓ ④ 映射入库
+                                      health_data_sources(sourceType='huawei_health')
+                                      + 五维 body.* 子维得分 + energy_source_config
+```
+
+**分层职责**：
+- **小程序**：引导用户授权华为账号（OAuth）→ 拿授权码 → 交后端；展示同步后的步数/心率/睡眠/体重 → 五维/健康档案。
+- **cfc-backend**：`HuaweiAuthService`（OAuth 换 token、刷新、撤销授权）+ `HealthSyncService`（定时拉取 + 数据类型映射 + 入库）。
+- **华为云侧**：REST API，用户授权后按数据类型返回原子数据。
+
+**关键点**：
+- 所有华为 API 调用**仅经后端**，小程序不直接持 token（安全 + 统一认证）。
+- 数据同步为**云端非实时**（基础原子数据），频率建议按日/小时级调度，不做秒级。
+- 用户授权、撤销授权、按数据类型细分控制——隐私合规必须实现。
+
+---
+
+## 五、数据模型映射（核心）
+
+华为数据类型 → 五维能量体系（`DimensionCodeConstants`，统一量纲 0-100）→ 入库落点。
+
+| 华为数据类型 | 五维根/子维 | 说明 | 入库落点 |
+|--------------|------------|------|----------|
+| HUAWEI_HEALTH_TYPE_STEP（步数） | body.exercise | 活动量 → 运动子维 | health_data_sources |
+| HUAWEI_HEALTH_TYPE_DISTANCE（距离） | body.exercise | 有氧活动 | health_data_sources |
+| HUAWEI_HEALTH_TYPE_HEART_RATE（心率） | body.immunity | 心肺/循环状态 | health_data_sources |
+| HUAWEI_HEALTH_TYPE_SLEEP（睡眠） | body.sleep | 睡眠时长/质量 | health_data_sources |
+| HUAWEI_HEALTH_TYPE_BODY_WEIGHT（体重） | body.nutrition / body.growth | 体重/体脂 | health_data_sources |
+| HUAWEI_HEALTH_TYPE_SPO2（血氧） | body.immunity | 血氧饱和度 | health_data_sources |
+
+**入库结构复用**（`HealthDataSourceRecord` / `health_data_sources` 表，无需建新表）：
+- `sourceType = 'huawei_health'`
+- `dimensionCodes = 'body.exercise,body.sleep,body.immunity'`（按实际数据类型组合）
+- `parsedResult = JSON`（华为原始数据 + 归一化得分，保留审计）
+- `confidence`：归一化置信度（依据同步完整性计算）
+- `memberId`：绑定家庭成员（**仅能登录用户/成人**；不能登录用户走手动导入）
+
+**五维能量联动**：
+- `energy_source_config` 新增 `source_type='huawei_health'`（可选，若需按来源归一化到能量沙盘）。
+- 归一化口径复用 `NormCompareEngine` 百分位带（P5/P25/P75/P95 → 偏低/正常/偏高），与既有维度评分共享同一量纲。
+
+> ⚠ 华为数据只映射**身体（body）维度**；智/心/行/富四根不适用（手环无对应采集）。
+
+---
+
+## 六、后端接口设计（新增，供开发派发）
+
+| 组件 | 职责 | 备注 |
+|------|------|------|
+| `HuaweiHealthController` | 授权入口、授权回调、数据同步触发、同步状态查询 | `@PostMapping`，走统一 JWT |
+| `HuaweiAuthService` | OAuth 授权 URL 生成、code 换 token、token 刷新、撤销授权 | token 加密存库 |
+| `HealthSyncService` | 定时拉取各数据类型、归一化、映射入库 | 复用 `NormCompareEngine` |
+| `HuaweiTokenStore`（表或缓存） | token 持久化 | 建议新增 `huawei_health_tokens` 表 |
+
+**新增表**（DatabaseInitializer 迁移，幂等）：
+- `huawei_health_tokens`：member_id / access_token / refresh_token / expires_at / scope / created_at / updated_at
+
+**接口清单（草案，实现时以 API_REFERENCE.md 无重复为前置）**：
+- `POST /api/huawei-health/auth-url`（获取授权 URL）
+- `POST /api/huawei-health/callback`（授权回调，code 换 token）
+- `POST /api/huawei-health/sync`（触发同步）
+- `POST /api/huawei-health/revoke`（撤销授权，合规必需）
+- `GET  /api/huawei-health/status`（绑定/同步状态）
+
+---
+
+## 七、双轨产品策略（成人 API + 儿童/全家手动导入）
+
+> Health Service Kit 不支持儿童数据，家庭场景必须双轨组合。
+
+| 用户类别 | 数据通道 | 说明 |
+|----------|----------|------|
+| 能登录用户（成人） | 华为云端 API（本方案） | 授权后自动同步步数/心率/睡眠/体重 |
+| 不能登录用户（儿童/家属代管） | **手动导入**（方案三，复用报告解析链路） | 华为运动健康 App 导出/截图 → 上传 → LangGraph 解析 → 健康档案 |
+
+- 手动导入链路完全复用现有「健康报告 PDF 上传与解析」（ReportParser / 报告解析），零新增主体依赖。
+- 五维能量沙盘对两类来源统一归一化，口径一致，避免同一成员出现两套分数。
+
+---
+
+## 八、风险与合规清单
+
+| 风险 | 影响 | 等级 | 处置 |
+|------|------|------|------|
+| 儿童数据不支持 | 家庭场景缺口 | 高 | 双轨组合（成人 API + 手动导入） |
+| 审批周期 33+ 工作日 | 上线节奏延后 | 中 | 即刻启动申请，开发链并行 |
+| 主体不一致 | 申请被驳回 | 高 | 第一动作确认主体一致性 |
+| 100 用户测试限 | 灰度受限 | 低 | 验证期小范围种子用户 |
+| 企业资质材料不全 | 审批卡点 | 中 | 提前备企业介绍、应用场景说明 |
+| 授权/撤销/数据细分 | 隐私合规 | 高 | 实现授权管理 + 撤销 + 按类型控制 |
+| token 泄漏 | 数据安全 | 高 | 仅后端持有，加密存库，不落小程序 |
+
+---
+
+## 九、开发任务拆解（派发契约）
+
+> 目标：后端对接框架 + OAuth 流程 + 数据模型 + mock 凭证可测试；**华为 API 凭证未批前用 mock/模拟数据跑通全链路**。
+
+| 任务 | 内容 | 依赖 |
+|------|------|------|
+| D1 数据模型 | `huawei_health_tokens` 表迁移 + `HealthDataSourceRecord` 复用核对 | 无 |
+| D2 OAuth 模块 | `HuaweiAuthService`：授权 URL / code 换 token / 刷新 / 撤销 | D1 |
+| D3 同步引擎 | `HealthSyncService`：定时拉取 + 归一化 + 映射入库 | D2 |
+| D4 接口层 | `HuaweiHealthController`：5 个接口 + API_REFERENCE 无重复校验 | D3 |
+| D5 Mock 通道 | 凭证未批前的 mock 数据源，端到端可测 | D4 |
+
+**开发约束**：
+- 接口统一 `@PostMapping`，响应 `Result<T>`，JWT 拦截 `/api/**`（8 公开路径除外）。
+- 新表迁移走 `DatabaseInitializer.runMigrations()`（`ensureColumn`/幂等），同步 schema.sql。
+- 新增 Controller 前查 `docs/superpowers/api/API_REFERENCE.md` 防重复；`mvn clean compile` 验证。
+- 实现仅在 feature 分支，**不得假定包路径/不得直接改主线**（按 CFC 派发纪律）。
+
+---
+
+## 十、验证与上线标准
+
+1. `mvn clean compile` 通过，无路由/Bean 冲突（`grep -rn '@Mapping'` 查重复）。
+2. Mock 通道端到端：授权 → token → 拉取 → 映射 → 入库 → 前端展示（步数/心率/睡眠/体重）。
+3. 五维归一化：`body.exercise/body.sleep/body.immunity` 得分进入能量沙盘，量纲 0-100 一致。
+4. 双轨验证：成人（API）+ 儿童（手动导入）同一家庭五维口径一致，无两套分数。
+5. 合规：授权/撤销/按类型控制接口可用，token 不落小程序。
+6. 凭证到位后：真实 Health Service Kit 联调，替换 mock，验证通过后按「验证申请」提交华为。
+
+---
+
+## 附录 A：华为开放数据类型（本期用 + 备选）
+
+| 类型 | 数据 | 本期 |
+|------|------|------|
+| STEP | 步数 | ✅ |
+| DISTANCE | 距离 | ✅ |
+| HEART_RATE | 心率 | ✅ |
+| SLEEP | 睡眠 | ✅ |
+| BODY_WEIGHT | 体重 | ✅ |
+| SPO2 | 血氧 | 备选 |
+| CALORIES | 热量 | 备选 |
+| HEART_RATE_REALTIME | 实时心率 | ❌（扩展能力，门槛高） |
+
+## 附录 B：参考文档
+
+- 华为开发者联盟《面向应用开放服务》Health Service Kit：developer.huawei.com/consumer/cn/doc/HMsCore-Guides/application_description-0000001418052318
+- 华为《运动健康服务接入流程》：developer.huawei.com/consumer/cn/doc/hmscore-guides/application-access-process-0000001611092953
+- 本项目 `DimensionCodeConstants` / `HealthDataSourceRecord` / `energy_source_config` / `NormCompareEngine`