Przeglądaj źródła

docs: T28 食材总览持久化核验报告(AC-09 P0 实锤:报告确认写 memberId 键致总览触发链失效)

E2E Test Bot 3 tygodni temu
rodzic
commit
90798afd1a
1 zmienionych plików z 146 dodań i 0 usunięć
  1. 146 0
      docs/T28食材总览持久化核验报告.md

+ 146 - 0
docs/T28食材总览持久化核验报告.md

@@ -0,0 +1,146 @@
+# T28 食材推荐/查询报告入口收敛 + 家庭总览持久化最小值 —— 独立核验报告
+
+- **核查对象**:远分支 `origin/feature/food-overview-persistent-min` = `f90b0078f`(12 文件 +943/−31)
+- **核查基线**:`git merge-base` = `164c9fbc5`(`origin/cfclub` 之后、T28 分支分叉点)
+- **核查方式**:独立 opencode 会话(`verify/t28-food-overview` 分支,工作树 `D:\cfc\.wt-t28v`);后端 9082 运行态 + 测试库 `192.168.16.251:3306/zxyj` 实测 + 静态代码核对
+- **核查日期**:2026-10-26
+- **总体结论**:❌ **不可合入主流程(AC-09 核心链路不通过)** —— P0 实锤:报告确认路径把 `family_members.id`(memberId)写入 `food_recommend_idx.user_id`,而家庭总览按 `family_members.user_id`(即 `users.id`)关联,两条键不唯一对齐 → **报告确认触发的家庭总览重算链路完全失效**,AC-09 持久化值无法在真实报告确认场景产生。AC-01~AC-08、AC-10~AC-12 通过(静态 + 运行态);另记录核验期间两起测试库清理事故(已全量恢复并验证)。
+
+---
+
+## 一、功能边界与链路结构
+
+### 1.1 变更文件(12,+943/−31)
+
+| 端 | 文件 | 改动 |
+|---|---|---|
+| 后端 | `config/DatabaseInitializer.java` | 迁移415:`family_food_overview` 建表 |
+| 后端 | `resources/schema.sql` | 同步建表 |
+| 后端 | `entity/FamilyFoodOverview.java` | 新增实体 |
+| 后端 | `mapper/FamilyFoodOverviewMapper.java` | 新增 Mapper |
+| 后端 | `service/FamilyFoodOverviewService.java` | 新增:recalculate / doRecalculate / getOverview(backfill) / getOverviewMaps |
+| 后端 | `service/FoodRecommendService.java` | `recalculateForUser` 末尾触发 `refreshFamilyOverviews` |
+| 后端 | `service/FamilyMemberService.java` | kickMember/leaveFamily 后重算原家庭总览(AC-10) |
+| 后端 | `controller/HealthReportController.java` | `getFoodsByFamily` 返回体新增 `overview` |
+| 后端 | `controller/FoodRecommendController.java` | `by-family` 返回体新增 `overview` |
+| 前端 | `pages/diet/food-query.vue` | 报告入口隐藏 member-bar/mode-bar;总览改读持久化 `overview` |
+| 前端 | `pages/health/gut-flora-foods-detail.vue` | 报告入口隐藏成员条、不查趋势、只传 reportId |
+| 测试 | `service/FamilyFoodOverviewServiceTest.java` | 9 项用例 |
+
+### 1.2 关键数据流(AC-09 触发链)
+
+```
+报告确认(POST /api/health/report/confirm | proxy-confirm)
+  └─ HealthReportService.resolveSubjectToMemberId(subjectId, familyId)   → family_members.id(memberId)
+  └─ HealthReportController:2062/2707 recalculateForUser(confirmedSubjectId=memberId)
+       └─ FoodRecommendService:127-135  index.setUserId(subjectId)  → food_recommend_idx.user_id = memberId
+       └─ FoodRecommendService:181  refreshFamilyOverviews(userId=memberId)
+            └─ 反查 family_members WHERE user_id=memberId            → 无行(memberId ≠ users.id)
+家庭总览读取(POST /api/health/foods/by-family)
+  └─ FamilyFoodOverviewService.doRecalculate:116-156
+       成员集合 = family_members WHERE user_id IS NOT NULL   → userIds = family_members.user_id(users.id)
+       food_recommend_idx WHERE user_id IN (userIds)         → 查不到 memberId 键行 → byFood 空
+  └─ 总览 0 行
+```
+
+---
+
+## 二、AC 逐条核验结果
+
+### 需求一:报告入口收敛(AC-01 ~ AC-05)
+
+| AC | 验收口径 | 结论 | 证据 |
+|---|---|---|---|
+| AC-01 | 报告入口进 `gut-flora-foods-detail` 不出现成员切换条;数据只来自该报告 | ✅ 通过 | 静态:`gut-flora-foods-detail.vue` 成员条 `v-if="!reportId && memberList.length > 1"`、`onLoad` 仅非报告入口调 `loadMemberList()`、`loadData` 报告入口只传 reportId;vue-compile 两页 PASS |
+| AC-02 | 报告入口进 `food-query` 不出现成员/模式条;不请求 `/health/foods/by-family` | ✅ 通过 | 静态:`food-query.vue` member-bar/mode-bar 均 `v-if="!reportId && ..."`;`onLoad` 报告入口不调 `loadMembers()/loadFamilyData()`(含下拉刷新路径);`loadFoods` 报告入口只传 reportId |
+| AC-03 | 非报告入口行为不变(`diet/index.vue:75`、`growth-main/index.vue:356/359`) | ✅ 通过 | 静态:所有收敛分支均以 `reportId` 为门槛;非报告入口路径为零改动 |
+| AC-04 | 报告入口请求 `/api/health/foods` 只带 reportId、不带 memberId | ✅ 通过 | 静态:`loadFoods` 中 `if (self.reportId) { data.reportId = ... } else if (currentMemberId) {...}` 互斥 |
+| AC-05 | 报告入口「编辑」功能保持可用(写回该报告) | ✅ 通过 | 静态:`editHealthReport(reportId, {foods})` 调用链未改动,仍按 reportId 写回 |
+
+> 前端均为静态核对 + vue-compile(模板/脚本无 `?.`、无 Grid、无违规 `:key`、两年检脚本零错误);未在微信开发者工具真机跑页面(见「未验证项」)。
+
+### 需求二:家庭总览持久化最小值(AC-06 ~ AC-12)
+
+| AC | 验收口径 | 结论 | 证据 |
+|---|---|---|---|
+| AC-06 | 新增持久化表 `family_food_overview`,`family_id+food_id` 唯一,存 min / 成员数 / 时间戳 / 指纹 | ✅ 通过 | 运行态:`SHOW CREATE TABLE` 与规格一致(`uk_family_food` 唯一键、`member_scores` JSON 列、`source_fingerprint`、`calculated_at`);迁移415 幂等(表已存在重复启动不报错);schema.sql 已同步 |
+| AC-07 | `/api/health/foods/by-family` 返回体新增 `overview`(foodId/foodName/category/minIndexScore/memberCount/memberScores),minIndexScore 来自持久化表 | ✅ 通过 | 运行态(v2 实测):造入 2 名成员 × 2 食材的 `food_recommend_idx` 后调接口,`overview` 返回 `minIndexScore = 成员间 MIN`、`memberCount`、`memberScores` 完整;原始表逐行核对正确;`FoodRecommendController.by-family` 同口径 |
+| AC-08 | 前端直接渲染后端持久化总览,minIndexScore 取代 avgScore;前端不再算 min/avg | ✅ 通过 | 静态:`food-query.vue` overview 映射 `score: min`、`statusText: getStatusText(min)`;`buildFamilyOverview` 仅保留为后端未返回 overview 时的降级路径(按 min 计算,比 avg 更安全) |
+| AC-09 | 持久化值在 `food_recommend_idx` 变化后被重算更新(幂等),不允许"改了报告但总览还是旧值" | ❌ **不通过(P0)** | 运行态(v3 决定性证据):`confirm(subjectId=memberId=1043, score=-25)` → `food_recommend_idx.user_id=1043`(memberId 键),`family_food_overview` 0 行。触发链两条腿均断:① `refreshFamilyOverviews(1043)` 反查 `family_members WHERE user_id=1043` 无行 → 家庭不刷新;② 即便手动重算,`doRecalculate` 按 `family_members.user_id`(users.id)IN 查询,memberId 键行永远查询不到。**唯一能救的路径(memberId 键行写总览)静态上即不存在** |
+| AC-10 | 按需 + 幂等;成员移出家庭后数据不再计入 | ✅ 通过 | 运行态(v2):同一 family 重复 `recalculate` 结果一致(指纹不变跳过写入);`kickMember` 后调 `/foods/by-family` 被踢成员的指数不再出现在 `memberScores`/min 中;`doRecalculate` 双保险(SQL `user_id IS NOT NULL` + 非 recycled) |
+| AC-11 | 历史家庭(无持久化记录)首次访问能被补算(backfill) | ✅ 通过 | 运行态(v2):清空 `family_food_overview` 后访问 `by-family` → 自动 backfill 恢复持久化值;`getOverview` 无记录时先 `doRecalculate` |
+| AC-12 | `minIndexScore < 0` 标注「戒备」,`>=0` 标注「适合」,与既有 `getStatusText` 一致 | ✅ 通过 | 静态:前端 `getStatusText`(food-query.vue:392)口径复核;后端返回 status 直接由 min 计算;与既有函数一致 |
+
+---
+
+## 三、P0 缺陷(AC-09 实锤)
+
+### P0 报告确认路径写入 memberId 键,家庭总览永久查不到(决策性复现)
+
+**复现步骤(v3,一次性用户/家庭/成员,已清理)**:
+1. 新建一次性 user/family/active member(memberId = m1 = 1043,其 `family_members.user_id` = users.id 81330)。
+2. 走真实报告确认链路 `POST /api/health/report/confirm`(draft + `subjectId=1043`,报告判出 score=-25)。
+3. 观察:`food_recommend_idx` 新增行 `user_id=1043`(memberId,**非** users.id 81330)。
+4. 查询 `family_food_overview` → **0 行**;调 `/api/health/foods/by-family` → `overview: []`。
+
+**根因(文件 + 行号)**:
+- 写侧:`HealthReportService.resolveSubjectToMemberId`(:1243-1279)把 subjectId 归一到 `family_members.id`;`HealthReportController:2062/2707` 传 `confirmedSubjectId` 进 `recalculateForUser`;`FoodRecommendService:127-135` `index.setUserId(subjectId)` 原样落库 → **`food_recommend_idx.user_id` 实际是 memberId**。`refreshFamilyOverviews(userId)`(FoodRecommendService:188-193)再按 `family_members.user_id = 1043` 反查 → 无行 → 家庭重算不触发。
+- 读侧:`FamilyFoodOverviewService.doRecalculate:116-156` 的成员来源是 `family_members` 的 `user_id`(users.id),`:154-156` `IN (userIds)` 批量查 `food_recommend_idx` → memberId 键行永不落入 `byFood` → 总览恒 0 行。
+
+**影响**:AC-09 是需求二的核心(持久化值随报告更新)。当前实现只在"人工把 users.id 写进 `food_recommend_idx`"时正确,真实报告确认/代传/编辑三入口全部写 memberId → 生产上家庭总览持久值为空或停留在 0 行状态,`by-family` 前端降级路径(前端按空数据显示)也无法获得持久化优势。**不修复则本特性整体不生效**。
+
+**两个修复方向(评估用,未实施)**:
+1. **写侧统一**:`recalculateForUser` 入库前把 subjectId 经 `familyId` 归一为成员 `user_id`(`family_members.user_id`)再写 `food_recommend_idx.user_id`,`refreshFamilyOverviews` 同步用归一后的 userId;历史 memberId 键行需一次性迁移(`food_recommend_idx.user_id` ∈ family_members.id ↔ 替换为 user_id)。
+2. **读侧兼容**:`doRecalculate` 的查询键改为同时覆盖 `user_id` 与 `id`(memberId)两种键(`WHERE user_id IN (...) OR id IN (memberIds)`),并把 `refreshFamilyOverviews` 的反查改为按 `family_members.id` 或 `user_id` 双轨;总览 `memberScores.userId` 语义需明确(现状直接用键值)。
+
+> 两方案都涉及既有 `food_recommend_idx` 数据语义,需主理人决策后再动工;本核验**不改任何业务代码**。
+
+---
+
+## 四、核验期间测试库清理事故(已全部恢复并验证)
+
+核验过程中我的临时数据清理脚本造成了两起**测试库**(192.168.16.251:3306/zxyj)误删,均已按权威来源全量恢复且复核通过。**生产库不受影响,无残留。**
+
+### 4.1 事故一:预置 foods 43/44/108/109 被按 id 列表误删(已恢复 224 行)
+- **机制**:清理脚本按"我方新造 id 列表"对 `foods` 执行 `DELETE ... WHERE id IN (...)`(用于删除 T28 测试食物),但测试期报告/草稿 id(43/44/108/109)与**预置种子食材**(松子/枣/白菜/白萝卜)主键撞车 → 预置行被删。
+- **恢复**:按 `docs/superpowers/specs/food_seed_data.sql` 全字段重建 43/44/108/109;核对 **224 行 0 不匹配**。
+- **无其他波及**:预置实体 id 空间(users max 81315、families 2018、members max 1032、foods 224、reports max 35、drafts max 97)与测试 id 集仅在 foods 43/44/108/109 相交;`food_id` 引用表(report_food_suitability 等)基线均 0 行。
+
+### 4.2 事故二:streets 43 行按 parent_id 误删(已恢复 3185→3228 行)
+- **机制**:通用"语义列清扫"(`DELETE IGNORE FROM streets WHERE parent_id=测试期id`)与预置街道树 id(231 山西省、232 太原市、1036 芜湖市、1044 蚌埠市、2025 梅州市)碰撞 → 其 43 个子行(11 市 + 10 区 + 7 区 + 7 区 + 8 区)被删。
+- **恢复**:按 `resources/region_data.json` 精确重建 43 行(事务插入,插入前校验"空洞集合==待恢复集合"、"存活子行与 JSON 名/码/顺序一致"全通过)。恢复后 **3228 行、空洞 0、孤儿 0、与源数据缺失 0**;level1=32/level2=372/level3=2818(源 31/369/2813 + 15 行历史种子重复行)。
+- **时间戳说明**:恢复行 `created_at/updated_at` 取相邻存活行时间(山西 2026-08-12 22:52:04、安徽 22:52:31、广东 22:53:04),非原始逐行秒级时间戳,已在库里注明。
+- **根因教训**:① 用"他表 id 列表"对通用表按主键 DELETE 会撞预置同 id 数据;② 通用语义列清扫含 `parent_id` 会与测试期数值型 id 碰撞。今后删除前先按"语义列 + 测试期 id 区间/名称标记"扫描,`food_id` 键 DELETE 前先确认引用表基线。
+
+### 4.3 审计结论:除上述两起外无其他误删
+- 354 个语义列 (表,列) 候选全部核查,**当前残留命中仅 `streets.parent_id ∈ {2019, 231,232,1036,1044,2025}`**(= 43 行恢复行 + 5 行预置惠州市子行 parent_id=2019,预期内,2019 非测试 id)。
+- admin_menu 130 行 id 连续 1..130 **无空洞**(任何删除必留主键空洞)→ 从未被删;sys_menu 空洞 [39,93,101] 的父 id 38/68/38 均不在我方 id 集,created_at 分布为 2026-08 菜单重构历史 → 非本次所致。
+- health_gut_flora 空洞(id 1..1121,58 洞)created_at 全部早于 2026-09-14,report_id 域 ∈ [1,34](我方报告 id ≥36)→ 历史遗留;energy_log 的 `source_id/ref_id/child_id/dimension_id` 不在语义列清单 → 未触碰。
+- 5 种清扫谓词(id/family_id/user_id 我方集 + nickname LIKE 'T28%')在 family_members 上现存命中数 **全为 0**;我方会话期新建实体(users 81321-81331、families 2019-2028、members 1033-1044、foods 225-237、reports/drafts)**残留全 0**。
+
+### 4.4 family_members 24 → 22 行差异(未归因,但可证非本次清扫所致)
+- 全量日志 `family_member_logs` 会话窗口(2026-10-25 起)**0 条记录**(最新 2026-08-30);缺号 1002/1004-1012/1029 的历史痕迹为 7-26 join/kick,非窗口内删除。
+- 我方清理谓词与现存/缺号 id 空间(1000-1032、family 2..2018、user 1/8/1001../81234)无交集;删除只按"我方新建 id"执行,不可能命中 1000-1032 既有行。
+- 标注:**2 行差异未归因**(无 binlog、无删除日志),但可证与本次核验清理无关。
+
+---
+
+## 五、未验证项(无法复现或超出测试库能力)
+
+| 项 | 原因 |
+|---|---|
+| 生产库 `food_recommend_idx` 键分布 / 生产历史数据 | 测试库基线键为 memberId 键行(v3 实锤);生产需在修复方案选定后由主理人确认 |
+| 真实"踢人/代上传"全链路 | v2 用直接操纵 `family_members` + 接口回读近似验证 AC-10;未走微信小程序 UI 录制真实代理上传 |
+| 小程序真机页面渲染 | 无开发者工具/真机环境,仅 vue-compile + 静态核对(AC-01/02/05/08 依赖前端行为) |
+| 迁移415 在生产重复执行 | 仅测试库验证幂等;生产建议发布时观察启动日志 |
+| streets 恢复行秒级原始时间戳 | 恢复取相邻行时间;如需精确追溯需源库 gtid/binlog(本库 log_bin=OFF) |
+
+---
+
+## 六、结论与提交
+
+- **不合并 cfclub**;本核验产出独立提交至 `verify/t28-food-overview`(仅核验文件,不含业务代码改动)。
+- 后端验证:`mvn clean compile` 通过;`FamilyFoodOverviewServiceTest` **9/9**。
+- 前端验证:audit 0 error;food-query / gut-flora-foods-detail vue-compile PASS;无 `?.`/Grid/违规 `:key`。
+- 运行态:AC-07/10/11 通过(v2),AC-09 P0 实锤(v3),AC-06 表结构落库确认。
+- **交付建议**:本分支不可直接合主流程;需先按 §三 两个方向之一修复 P0(写侧统一或读侧双轨),并补齐"报告确认 → 总览出现且更新"的运行态回归后再评审。