|
|
@@ -0,0 +1,55 @@
|
|
|
+# D/X 域批次 · 开工包（华为/小米运动健康接入契约核对）
|
|
|
+
|
|
|
+> 归属：契约补建计划独立批次（O-14）· 生成 2026-11-07 20:1x（研发负责人 闭环巡检）
|
|
|
+> 数据源：`docs/2026-11-06-华为运动健康开放平台接入方案.md`（v1.2）· `docs/superpowers/api/API_REFERENCE.md` §4.43/§4.44 · 源码端点比对
|
|
|
+> 前置：O-14 主理人拍板（2026-11-07 17:5x，commit 78277897e）——**D/X 域作 O-7 独立契约核对批次**（契约核对 = 文档核对 + 端点比对，防假 RED）**不纳入 241 SC 基线**（当前 DEV_GOAL=241 无 D/X 域条目，基线与台账不膨胀）；实现已合入无需研发重做，仅需设计契约登记 + 测试证据补建。
|
|
|
+
|
|
|
+## 批次定位
|
|
|
+
|
|
|
+D/X 域 = **运动健康多生态接入**（华为 Health Service Kit + 小米 HealthKit / Zepp）：
|
|
|
+- 实现已合入 origin/cfclub：`4344688d2`（feat xiaomi-health X1-X5）、`978d1bc95`（feat huawei-health D1-D5）、`4815aae95`（fix isBound intValue）；B-50 华为 5 端点补鉴权 `cc7b3e00b`（19:40，IN CHAIN ✓）与 xiaomi 对齐。
|
|
|
+- 开工包端点初核全部 ✅ 存在（见下表），本批 = **契约核对（文档 ⇄ 端点比对）+ 契约登记**，产出契约文档后转测试侧补契约 JUnit + 三类流证据，不建伪实现任务。
|
|
|
+
|
|
|
+## 端点核验（初核候选，会话须逐条核实并回填）
|
|
|
+
|
|
|
+### D 域 · 华为运动健康（Huawei Health Service Kit）
|
|
|
+
|
|
|
+| 编号 | 端点 | 载体（origin/cfclub 工作树） | 初核 |
|
|
|
+|------|------|------------------------------|------|
|
|
|
+| D-1 | `POST /api/huawei-health/auth-url` | `controller/huawei/HuaweiHealthController` L54 | ✅ |
|
|
|
+| D-2 | `POST /api/huawei-health/callback` | 同上 L79（code 换 token） | ✅ |
|
|
|
+| D-3 | `POST /api/huawei-health/sync` | 同上 L111（触发数据同步） | ✅ |
|
|
|
+| D-4 | `POST /api/huawei-health/revoke` | 同上 L152（撤销授权，合规必需） | ✅ |
|
|
|
+| D-5 | `POST /api/huawei-health/status` | 同上 L177（绑定/同步状态） | ✅ |
|
|
|
+
|
|
|
+> 支撑件：`entity/HuaweiHealthToken.java` / `mapper/HuaweiHealthTokenMapper` / `service/huawei/HuaweiAuthService`（OAuth 换 token/刷新/撤销）/ `service/huawei/HuaweiHealthApiClient`（real + mock 双实现，`HuaweiMockHealthApiClient` / `HuaweiRealHealthApiClient`）/ `job/HuaweiHealthSyncJob`（定时拉取）；数据表 `huawei_health_tokens`（迁移 452）+ 同步入 `health_data_sources`（sourceType='huawei_health'，未新建表）。
|
|
|
+> 鉴权：`config/JwtInterceptor` LOGIN_REQUIRED_PATHS L116 含 `/api/huawei-health/`（B-50 修复 cc7b3e00b 已合入）——未登录访问 5 端点须 401。
|
|
|
+> 通道开关：`application.yml` `huawei.health.mock-enabled`（默认 true=mock；凭证批复后 false=真实 Health Service Kit 云侧 REST）。
|
|
|
+
|
|
|
+### X 域 · 小米运动健康（Xiaomi HealthKit / Zepp）
|
|
|
+
|
|
|
+| 编号 | 端点 | 载体（origin/cfclub 工作树） | 初核 |
|
|
|
+|------|------|------------------------------|------|
|
|
|
+| X-1 | `POST /api/xiaomi-health/auth-url` | `controller/xiaomi/XiaomiHealthController` L62 | ✅ |
|
|
|
+| X-2 | `POST /api/xiaomi-health/callback` | 同上 L95（code 换 token） | ✅ |
|
|
|
+| X-3 | `POST /api/xiaomi-health/sync` | 同上 L129（触发数据同步） | ✅ |
|
|
|
+| X-4 | `POST /api/xiaomi-health/revoke` | 同上 L170（撤销授权，合规必需） | ✅ |
|
|
|
+| X-5 | `POST /api/xiaomi-health/status` | 同上 L195（绑定/同步状态） | ✅ |
|
|
|
+
|
|
|
+> 支撑件：`entity/XiaomiHealthToken.java` / `mapper/XiaomiHealthTokenMapper` / `service/XiaomiAuthService` / `service/XiaomiHealthTokenService` / `service/xiaomi/XiaomiHealthService` + `XiaomiHealthApiClientImpl`（云服务接口 hlthopen.io.mi.com，mock 通道）；数据表 `xiaomi_health_tokens`（迁移 453）+ 同步入 `health_data_sources`（sourceType='xiaomi_health'）。
|
|
|
+> 鉴权：`config/JwtInterceptor` LOGIN_REQUIRED_PATHS L115 含 `/api/xiaomi-health/`（已有，非新增）。
|
|
|
+> 通道开关：`application.yml` `xiaomi.health.mock-enabled`（默认 true=mock；凭证批复后 false=真实云服务接口）。
|
|
|
+
|
|
|
+> ⚠ 待核实（会话须回填实测结论）：① 同步数据落库后的前端消费链路（五维 body.* 子维得分 / 健康档案展示）契约段；② 儿童/全家档案「手动导入」双轨（设计 v1.2 第七节）当前是否有端点载体；③ `health_data_sources` 复用写入的校验/去重/覆盖语义。
|
|
|
+
|
|
|
+## 会话要求
|
|
|
+
|
|
|
+1. **端点核对 = 文档核对 + 端点比对**（防假 RED）：逐条用 grep 在 `cfc-backend/src/main/java` 实测定位端点载体，回填上表候选是否成立（✅/⚠/❌）；⚠ 项须回填实测结论。确无载体的登记为契约缺口（仅登记不实现），不建伪实现任务。
|
|
|
+2. **先拉取**：开工前 `git fetch origin cfclub` 并基于 `origin/cfclub` 新建分支 `feature/evd17-dx-health-contract`（独立 worktree，不与主工作树 WIP 冲突；远程 Linux 实例需加 `MSYS_NO_PATHCONV=1`）。
|
|
|
+3. **只动承诺文件**：新增 `docs/superpowers/specs/2026-11-07-dx-health-contract.md`（新建契约文档：D1-D5 + X1-X5 端点表 + 数据表 + 鉴权 + mock/真实通道语义 + 三类流建议用例点），如发现 API_REFERENCE §4.43/§4.44 与实现不符则修正该段（章节号 4.45 起追加，避开已用 4.64）。**不改任何业务代码、不改测试文件、不动 `.tdd/`、不动其他文档**。
|
|
|
+4. **完成后必须 push**：`git push -u origin feature/evd17-dx-health-contract`，汇报 commit sha 与文件清单。
|
|
|
+5. 收尾自查：`git status --porcelain` 干净 + `git log --oneline -3`，若 GAP 会话同机并行注意不要 `reset --hard`/`checkout -- .`/`stash` 他人改动。
|
|
|
+
|
|
|
+## 交付
|
|
|
+
|
|
|
+契约文档 `docs/superpowers/specs/2026-11-07-dx-health-contract.md` + API_REFERENCE 增补/修正 + commit sha + 逐端点核对结论（满足/缺口）。产出后转测试侧（TR-17）按 O-7 口径补契约 JUnit + 三类流执行证据（D-4 撤销授权合规流、X-3/X-D-3 同步幂等与去重为重点）。
|
Agnes Agent