Просмотр исходного кода

docs(T05): 统一维度历史数据迁移执行报告(59行裸维度名改写为body.*,含备份/校验/越界扫描)

Xiaogang Liao 1 неделя назад
Родитель
Сommit
32a624e409
1 измененных файлов с 90 добавлено и 0 удалено
  1. 90 0
      docs/2026-11-05-T5-dimension-unified-migration-report.md

+ 90 - 0
docs/2026-11-05-T5-dimension-unified-migration-report.md

@@ -0,0 +1,90 @@
+# T5 统一维度历史数据迁移 — 生产库执行报告
+
+- 执行时间:2026-11-05 21:29~21:32 (Asia/Shanghai)
+- 执行人:opencode agent(T5 任务)
+- 迁移脚本:`cfc-backend/src/main/resources/db/migrate_dimension_unified.sql`(源 commit `aa6ccb2dd` 合入 cfclub)
+
+## 1. 工作树状态
+
+| 项目 | 值 |
+|---|---|
+| 分支 | `feature/t05-dimension-unified-migration`(基于 `origin/cfclub` `1eaa76c85` 新建) |
+| 基线 commit | `1eaa76c85`(origin/cfclub,含 P0/P1/P2 合入 `aa6ccb2dd`) |
+| 脚本存在 | ✅ `cfc-backend/src/main/resources/db/migrate_dimension_unified.sql`(3348 B) |
+
+> 注:任务脚本在基线 `origin/cfclub` 之前未合入当前 `cfclub` 分支,经核验为 `aa6ccb2dd merge(dimension): 统一维度体系 P0+P1+P2 合入 cfclub` 的产物,已在 origin/cfclub 中存在,故基于 origin/cfclub 建分支即可获得。
+
+## 2. 数据库连接
+
+| 项目 | 值 |
+|---|---|
+| Host | `mysql-internet-cn-north-1-23feae22680e4dfa.rds.jdcloud.com:3306` |
+| Database | `zxyj` |
+| MySQL 版本 | 8.0.34 |
+| 连接时服务器时间 | 2026-11-05 21:29:17 |
+
+> 连接信息取自运行中后端实际加载的配置 `/app/pro/cfc/backend/config/application-prod.yml`(systemd `ExecStart` 确认 `--spring.config.additional-location=/app/pro/cfc/backend/config/`)。未修改任何应用配置。
+
+## 3. 预检(Step A)
+
+- 表总行数 `health_dimension_scores`:**59**
+- 裸名分布(7 个裸维度名):
+
+| dimension | cnt |
+|---|---|
+| growth | 12 |
+| sleep | 11 |
+| vision | 0 |
+| immunity | 12 |
+| nutrition | 12 |
+| gut | 12 |
+| exercise | 0 |
+| **合计** | **59** |
+
+- 全量维度分布确认:表内 59 行全部为裸名,**无任何已带 `body.` 前缀的行**(改写前)。
+- 备份表 `health_dimension_scores_bak_20261105` 预先不存在(将全新创建)。
+
+## 4. 备份写入行数(Step1)
+
+- `INSERT ... WHERE NOT EXISTS` 实际写入:**59 行**(与预检总行数一致,备份完整)。
+- 备份表行数核对:59。
+
+## 5. UPDATE 实际影响行数(Step2)
+
+- `UPDATE ... SET dimension = CONCAT('body.', dimension) WHERE dimension IN (7裸名)` 影响行数:**59 行**。
+- 与预检裸名合计 59 完全一致,无意外影响行。
+
+## 6. 校验(Step C)
+
+- 裸名残留 `COUNT(*)`:**0** ✅
+- 带 `body.` 前缀行数:**59** ✅
+- 改写后分布:body.growth 12 / body.sleep 11 / body.immunity 12 / body.nutrition 12 / body.gut 12(合计 59)。
+- 备份表行数 59 ≥ 改写行数 59 ✅
+- 幂等性复核(重跑脚本):备份 INSERT 追加 **0** 行,UPDATE 影响 **0** 行 —— 二次执行无副作用 ✅
+- 备份表维度分布与改写前完全一致(growth 12 / sleep 11 / immunity 12 / nutrition 12 / gut 12),回滚源完整。
+
+## 7. 越界扫描清单(Step3,仅报告)
+
+`indicator_definitions` 中 `dimension_code` 不在白名单(5 根 + 33 子维)的记录:
+
+| id | code | name | dimension_code |
+|---|---|---|---|
+| 3700 | dim.body | 身体 | higher_is_better |
+| 3701 | dim.mind | 心理 | higher_is_better |
+| 3702 | dim.wisdom | 智慧 | higher_is_better |
+| 3703 | dim.action | 行动 | higher_is_better |
+| 3704 | dim.wealth | 财富 | higher_is_better |
+
+- 5 条越界均为**根维度展示标签**(code=`dim.body` 等),其 `dimension_code` 被误填为 `higher_is_better`(评分方向标签,非维度编码)。
+- 这是**既有数据缺陷**,非本迁移引入;应作为 P1-T3 收敛项人工确认后修正,建议改为对应根编码(`body`/`mind`/`wisdom`/`action`/`wealth`)或置空。
+
+## 8. 风险 / 后续建议
+
+1. **⚠️ 切换时序(最重要)**:后端 P1-T1 健康页雷达图已改为注册中心配置驱动(`body.*` 读取),但**前端/后端对 7-dim 旧 key 的读取改造须在本 T5 完成后再切换**。若在 T5 前用旧 `growth` key 读取,会命中改写后的 `body.growth` 行而读到 0 分。本迁移已完成,下一步应推进 P1 消费方(雷达/沙盒/指标)的 key 收敛改造并验证。
+2. **回滚**:如需回退,可 `UPDATE health_dimension_scores SET dimension = SUBSTRING(dimension, 6) WHERE dimension LIKE 'body.%'`,数据源为备份表 `health_dimension_scores_bak_20261105`(59 行,与原分布一致)。
+3. **越界 5 条**(`dim.body` 等 `dimension_code='higher_is_better'`)为历史遗留,建议在 P1-T3 指标收敛时一并修正。
+4. 本脚本为 DBA 手工执行脚本,未进入 `DatabaseInitializer` 调用链,应用重启不受影响(未重启应用)。
+
+## 结论
+
+T5 历史数据迁移已成功完成:`health_dimension_scores` 中 59 行裸维度名全部改写为统一 `body.*` 编码,与 `product_dimension_config` 注册中心对齐;备份完整、幂等可重复、无意外影响行。