docs(huawei-health): 方案 v1.2 补充小米多生态接入（小米HealthKit 云服务接口 + Zepp 老款通道 + X1-X5 任务拆解 + 合规红线）

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

@@ -1,6 +1,6 @@
-# 华为运动健康开放平台接入方案（Health Service Kit REST API）
+# 运动健康多生态接入方案（华为 Health Service Kit + 小米 HealthKit / Zepp）
 
-> 版本：v1.0 · 日期：2026-11-06 · 决策：方案二（官方云侧 REST API）
+> 版本：v1.2 · 日期：2026-11-07 · 决策：华为方案二（云侧 REST API）+ 小米官方云服务接口（多生态并行）
 > 关联模块：cfclub 小程序 / cfc-backend / 五维能量体系 / 家庭健康档案
 
 ---
@@ -14,6 +14,7 @@
 | 配套 | 方案三变通：儿童/全家档案走「手动导入」补充（双轨产品策略，见第七节） |
 | 决策日期 | 2026-11-06 |
 | 依据 | 华为开发者联盟官方文档：Health Service Kit 应用接入流程、面向应用开放服务、数据开放总览 |
+| 小米补充 | 2026-11-07 补充：小米运动健康数据服务（云服务接口）+ Zepp 开放平台（老款）双通道；详见「十一、多生态接入」 |
 
 **关键事实（官方明文）**：
 1. 跨平台 / 微信小程序等 WEB 场景，**优先建议走 REST API**（云侧），保证多端体验一致性。
@@ -74,6 +75,7 @@
 - **小程序**：引导用户授权华为账号（OAuth）→ 拿授权码 → 交后端；展示同步后的步数/心率/睡眠/体重 → 五维/健康档案。
 - **cfc-backend**：`HuaweiAuthService`（OAuth 换 token、刷新、撤销授权）+ `HealthSyncService`（定时拉取 + 数据类型映射 + 入库）。
 - **华为云侧**：REST API，用户授权后按数据类型返回原子数据。
+- **多生态适配器（见第十一节）**：`XiaomiHealthService` / `ZeppHealthService` 与 `HuaweiHealthService` 共用同一归一化管线，数据统一入 `health_data_sources`（sourceType 区分 `huawei_health` / `xiaomi_health` / `zepp_health`）。
 
 **关键点**：
 - 所有华为 API 调用**仅经后端**，小程序不直接持 token（安全 + 统一认证）。
@@ -177,6 +179,18 @@
 - 新增 Controller 前查 `docs/superpowers/api/API_REFERENCE.md` 防重复；`mvn clean compile` 验证。
 - 实现仅在 feature 分支，**不得假定包路径/不得直接改主线**（按 CFC 派发纪律）。
 
+**小米通道任务（X1-X5，与 D 系并行，共用管线）**：
+
+| 任务 | 内容 | 依赖 |
+|------|------|------|
+| X1 数据模型 | `xiaomi_health_tokens` 表迁移 + 复用 `HealthDataSourceRecord`（sourceType='xiaomi_health'） | 无 |
+| X2 OAuth 模块 | `XiaomiAuthService`：授权 URL / code 换 token / 刷新 / 撤销（小米云服务认证鉴权） | X1 |
+| X3 同步引擎 | `XiaomiHealthService`：云服务接口拉取（采样/订阅事件）+ 复用 `NormCompareEngine` 归一化 | X2 |
+| X4 接口层 | `XiaomiHealthController`：auth-url / callback / sync / revoke / status（与华为 5 接口同构） | X3 |
+| X5 Mock 通道 | 凭证未批前 mock 数据源，端到端可测 | X4 |
+
+> 老款 Zepp 通道（`zepp_health`）暂以「数据源适配器」预留接口，待 Zepp 凭证落地后接 Webhook 推送（OAuth2 + push/ping-pull 模型），不与 X 系串行。
+
 ---
 
 ## 十、验证与上线标准
@@ -190,6 +204,33 @@
 
 ---
 
+## 十一、多生态接入（小米 HealthKit / Zepp）
+
+### 11.1 小米手环分代际路径
+
+| 手环代际 | 数据承载 | 官方通道 | 小程序可行性 |
+|----------|----------|----------|--------------|
+| 新款（小米运动健康：手环 7/8/9、小米手表等） | 小米云 | 小米运动健康数据服务：云服务接口（hlthopen.io.mi.com，HTTPS 标准 API + 分页 cursor + 订阅事件 SAMPLESET_EVENT） | ✅ 后端直接 HTTPS 调用，无需端上 SDK |
+| 老款（华米代工：Mi Band 1-5 / Redmi Smart Band / Amazfit） | Zepp 云 | Zepp 开放平台（OAuth2 + REST + Webhook；老版 Huami API 审核 3-7 天） | ✅ 纯云侧接入，小程序完全可走 |
+
+### 11.2 关键利好（相对华为）
+
+- 小米 / Zepp **无「不支持儿童数据」明文禁令**（以申请时官方回复为准）——儿童佩戴小米手环自动同步全家健康档案成为可能，补足华为方案的短板。
+- 审批周期短（小米服务开通审核 + Zepp 老款 3-7 天），可与华为审批并行，不互相挤占。
+- 端侧 SDK（Android AIDL）不可用于小程序，但**云服务接口为服务端标准 HTTPS**，无需 Android 壳，接入门槛低于华为。
+
+### 11.3 架构与数据落点
+
+- 新增 `XiaomiHealthService` / `ZeppHealthService`，与 `HuaweiHealthService` **共用同一归一化管线**（NormCompareEngine → body.* 子维 → health_data_sources）。
+- sourceType：`xiaomi_health` / `zepp_health`（区分来源；维度映射同华为：body.exercise / sleep / immunity / nutrition）。
+
+### 11.4 合规红线
+
+- **禁用社区逆向接口**（如 Mi Fitness MCP 类：userId/passToken 仿冒 App 内部接口）——伪造凭证 + 仿冒接口，正式产品禁用。
+- **不引入境外聚合中转**（如 Terra：健康数据出境触发个保法监管红线），不作为主力通道。
+
+---
+
 ## 附录 A：华为开放数据类型（本期用 + 备选）
 
 | 类型 | 数据 | 本期 |
@@ -208,3 +249,5 @@
 - 华为开发者联盟《面向应用开放服务》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`
+- 小米运动健康数据服务（云服务接口）：dev.mi.com/xiaomihyperos/documentation/detail?pId=2328（接口）、pId=2333（服务端接入指南）
+- Zepp 开放平台：devopen.zepp.com（OAuth2 + REST + Webhook）