浠艾福平台 · 确定性差距修复实施计划

版本： v1.0 日期： 2026-07-10 前置审计： docs/superpowers/plans/2026-07-10-determinism-gap-audit.md（基于 5 路并行 explore 代码审计） 总体工作量估算： 38-52 人天（P0: 5-7d / P1: 15-20d / P2: 12-16d / P3: 6-9d）

实施总览

本计划以"确定性"为主线，把审计报告中的 18 个修复任务按优先级分层，强调安全先于叙事、闭环先于优化、闭环先于优化、闭环先于优化。

阶段	主题	任务数	估算人天	价值锚点
P0	隐私 + 营销根基	3	5-7	堵最大隐私漏洞；打开"成长可视化"叙事
P1	信任 + 数据闭环	6	15-20	邀请/视角/订单/Dify 闭环；地址全国可用
P2	数据质量 + 可维护性	5	12-16	迁移可追溯；schema 自洽；报告机读；推荐可解释
P3	长期治理	4	6-9	死字段清理；PDF 多供应商；sfms 只读；前端去 mock

关键里程碑：

M1（第 1 周）：P0 完成。familyId 越权测试零案例；五维分数可图表化回放
M2（第 3-4 周）：P1 完成。地址全国可用；家长可看到"测评结果可看"通知；Dify 宕机对话不丢
M3（第 6-7 周）：P2 完成。每次重启跳过所有已跑迁移；schema.sql 重建数据库成功
M4（第 9-10 周）：P3 完成。死字段全部接入或删除；前端图表不出现假数据

P0 关键安全与根基（立即修）

共用约定：所有新建表通过 DatabaseInitializer.runMigrations() 新增 CREATE TABLE IF NOT EXISTS；schema.sql 同步追加；新增 controller 用 @PostMapping；DI 用 @Resource 字段名匹配 Bean Name。

G7. familyId 入参校验（最大隐私漏洞）

优先级： P0 🔴 估算： 1.5 人天 前置依赖： 无 影响文件： JwtInterceptor.java、WebConfig.java、7 个控制器

问题定位

7 个控制器从 JSON body/参数中拿 familyId 后直接使用，不校验该家庭是否属于当前 JWT 用户：

DanAssessmentController 第 65/79/89/208 行
InteractionLogController 第 62 行
FoodRecommendController 第 50 行
WishController 第 229 行
TeacherMessageController 第 43 行
GrowthRecordController 第 90 行
TraditionalMirrorController 第 88 行

修复步骤

[ ] 新增 FamilyAccessInterceptor（config/FamilyAccessInterceptor.java）
- 拦截 /api/**（除 JwtInterceptor 已放行的 8 个公开路径）
- 在 preHandle 阶段：解析 body 中的 familyId 字段（用 ContentCachingRequestWrapper 缓存 body 以便可重复读）
- 从 @RequestAttribute("userId") 查 User.familyId 与 User.teacherFamilyIds
- 校验：body 中 familyId 必须等于 user.familyId 或在 teacherFamilyIds 列表中
- 不通过：response.setStatus(403)；返回 JSON {"code":403,"message":"无权访问该家庭数据"}
- 通过：放行
[ ] WebConfig.addInterceptors 注册 FamilyAccessInterceptor，order 在 JwtInterceptor 之后
[ ] User 实体新增 helper getEffectiveFamilyIds()：返回包含 familyId + 解析后的 teacherFamilyIds 的 Set<Long>
[ ] 识别例外路径：admin 调用路径（如 /api/admin/*）跳过此拦截器；teacher 绑定家庭的 guideBindFamily 由 G10 任务单独加审批，暂放行
[ ] 测试：新增 FamilyAccessInterceptorTest
- parent A 携 familyId=B → 403
- parent A 携 familyId=A → 200
- teacher T 携 familyId=已绑定家庭 → 200
- 缺 familyId 字段 → 放行（有些端点不强制）
- admin 路径 → 跳过
[ ] 不要修改原有 7 个控制器内部逻辑——拦截器统一处理

验证

mvn clean compile 通过
mvn test -Dtest=FamilyAccessInterceptorTest 通过
临时启动后端，用 parent A 的 token + body {familyId: B的家庭ID} 调 /api/dan-assessment/materials 返回 403
用 parent A + 自家 familyId 返回 200

完成条件

所有 /api/** 路径（除 admin 子树）自动校验 familyId 归属
越权测试用例全 PASS
无控制器内部 familyId 重复校验代码

G1. 五维能量分数持久化（解锁全部可视化叙事）

优先级： P0 🔴 估算： 2.5 人天 前置依赖： 无 影响文件： 新增 entity/mapper/service、EnergyService.java、DatabaseInitializer.java、schema.sql

问题定位

EnergyService.calculateFamilyEnergy() 每次请求重算身/心/智/行/富 0-100 分；无任何表保存"X 孩子在 Y 日期的分数"，导致：

无法做趋势图、"上次 vs 本次"对比
算法改一处，所有"历史成绩"瞬时漂移
AGENTS.md 宣传文案"自驱力 4.07→5.30"在系统中根本查不到

修复步骤

[ ] 新建 five_dimension_scores 表

CREATE TABLE IF NOT EXISTS five_dimension_scores (
 id BIGINT AUTO_INCREMENT PRIMARY KEY,
 member_id BIGINT NOT NULL COMMENT '家庭成员ID(family_members.id)',
 family_id BIGINT NOT NULL,
 dimension_code VARCHAR(32) NOT NULL COMMENT 'body/mind/wisdom/action/wealth',
 score INT NOT NULL COMMENT '0-100 分',
 assessed_at DATETIME NOT NULL COMMENT '评估时间',
 source_type VARCHAR(32) NOT NULL COMMENT 'assessment/task_complete/manual/periodic',
 source_id BIGINT COMMENT '源对象ID(如dan_assessment_results.id)',
 detail_json TEXT COMMENT '细分项快照(cognitive_scores/emi_scores/...)',
 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 INDEX idx_member_dim_time (member_id, dimension_code, assessed_at),
 INDEX idx_family_dim_time (family_id, dimension_code, assessed_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='五维能量历史快照';

通过 DatabaseInitializer.runMigrations() 添加
同步追加到 schema.sql

[ ] 新建 FiveDimensionScore entity（标准 MyBatis-Plus）
- @TableName("five_dimension_scores"), @TableId(type=IdType.AUTO)
- 所有字段对应表结构
[ ] 新建 FiveDimensionScoreMapper
[ ] 新建 FiveDimensionScoreService
- recordSnapshot(memberId, familyId, dimension, score, sourceType, sourceId, detailJson)：插入
- getHistoryByMember(memberId, dimension, limit=20)：返回时间序列
- getLatestByFamilyMap(familyId)：返回 Map
- compareFirstVsLatest(memberId)：返回 delta（先实现接口，G18 用）
[ ] EnergyService.calculateFamilyEnergy() 末尾插入持久化钩子
- 在每次计算完每个孩子每个维度分数后，调用 fiveDimensionScoreService.recordSnapshot(...)
- 去重策略：若同一 memberId+dimension+assessed_at(精度=天)+source_type+source_id 已存在，跳过插入
- 不要改 EnergyService 的计算逻辑——只在尾部加 record
[ ] EnergyController.getOverview 优先读 fiveDimensionScores 最新记录；fallback 到现有重算逻辑（保证向下兼容）
[ ] 新增端点：
- POST /api/energy/score-history：入参 memberId, dimension, limit，返回时间序列
- POST /api/energy/family-score-history：入参 familyId, dimension, fromDate, toDate

验证

mvn clean compile 通过
调 /api/energy/overview 两次，DB 中应出现两条快照（去重生效时只有 1 条）
调 /api/energy/score-history?memberId=X&dimension=wisdom&limit=5 返回时间序列
修改 EnergyService.calcChildWisdom() 系数（如临时改为 0.5），重启，历史分数不变，新分数按新系数

完成条件

五维分数写入 DB
历史可查询、趋势可绘制（前端可用）
EnergyService 算法改动不再影响历史数据

G18. 首次 vs 最新测评对比端点

优先级： P0 🔴 估算： 1.5 人天 前置依赖： G1（推荐先完成，否则对比来源是重算数据） 影响文件： GrowthRecordController/AssessmentService，或新建 AssessmentComparisonController

问题定位

AGENTS.md 宣传文案"自驱力 4.07→5.30"在系统中无法查到——无 compareAssessments 端点，没有方法取首个和最近一次测评计算 delta。cognitive-report.vue 只显示单次报告。

修复步骤

[ ] 新建 AssessmentComparisonService
- compareByChild(childId)：取该孩子 dan_assessment_results 中最早 + 最近两条，计算维度 delta
- compareByChildAndDimension(childId, dimensionCode)：聚焦单维度
- getProgressNarrative(childId)：返回结构化 delta + 文本叙事（"智维度提升 +12 分，主要由 logicScore 拉动 +18，专注力下降 -5，建议..."）
[ ] 数据源策略：
- 优先从 five_dimension_scores（G1 新增）取历史值
- fallback 到 dan_assessment_results 直接 diff

[ ] 新建端点：

POST /api/assessment/compare/by-child 入参 childId 返回：

{
"firstAssessment": { "id":42, "date":"2025-08-10", "scores":{...} },
"latestAssessment": { "id":88, "date":"2026-07-01", "scores":{...} },
"dimensionDeltas": [
 {"dimension":"wisdom","delta":12.3,"direction":"up","drivers":["logicScore +18","memoryScore +6"]},
 ...
],
"overallDelta": 7.4,
"narrative": "智维度提升 12.3 分，主要由 logicScore..."
}

POST /api/assessment/compare/by-family 入参 familyId，返回家庭所有孩子对比数组

[ ] 前端 pages/wisdom-detail/ 新增 assessment-comparison.vue：渲染对比卡片（先文案样式即可，不强求图表）

验证

后端单元测试 AssessmentComparisonServiceTest：mock 两次测评，断言 delta 计算
/api/assessment/compare/by-child?childId=X 返回结构化 delta
前端能看到"首次→最新"对比卡

完成条件

平台本身能产出 AGENTS.md 营销文案所需数据
不依赖运营人工抠数字

P1 信任与数据闭环（本季度修）

G8. 视角切换统一为一套机制 + 密码校验

优先级： P1 估算： 2.5 人天 前置依赖： 无 影响文件： FamilyUserController、UserService、FamilyMembersController、前端 store/index.js、pages/profile/*

修复步骤

保留机制 3：/api/family/member/switch（返回 SwitchMemberVO，不动 DB）——这是正确模型
废弃机制 1、2：
- FamilyUserController.switchMode → 改为 404 或重定向到 /member/switch
- FamilyUserController.switchToChild → 同上
- UserService.switchToChild、switchMode 加 @Deprecated，保留代码以兼容老 JWT 但记 log warning
UserService.switchBackToParent() 加入密码校验：
- 接收 password 参数，调用 passwordEncoder.matches(password, user.password)
- 校验失败返回 Result.error("密码错误")
- 不允许 null/空密码通过
新增端点 POST /api/family/user/switch-back-verify：前端切回家长视角前调用，强制输入密码
前端 store/index.js 改造：
- 移除 isSwitchedChild、isSwitchedMember 双 bool，合并为 currentView: 'self'|'member'
- switchBackFromMember 调用 /switch-back-verify，失败显示密码弹窗
- localStorage 中 role 单点真源，仍写但加签名（HMAC with server-issued nonce）防止篡改（可选，先做密码校验）
前端文案：家长切回视角时弹"请输入密码以确认身份"

验证

切到孩子视角后，清空 localStorage，强制刷新，调用 /switch-back-verify 必须密码通过才能切回
mvn test -Dtest=UserServiceTest#switchBackWithWrongPassword 失败
三个端点 /switch-mode、/switch-to-child 返回 410 Gone 或 308

完成条件

全平台只有一套视角切换机制
切回家长必须密码
AGENTS.md 中"切换过来的孩子端退出需要密码"承诺兑现

G9. 邀请码加过期+使用次数+吊销

优先级： P1 估算： 1.5 人天 前置依赖： 无 影响文件： FamilyController、FamilyInviteController、FamilyInvitationService、UserAddress 等

修复步骤

统一两个邀请流为一套：废弃 FamilyController /invite-code 的简易码，全部走 FamilyInviteController /generate 生成 token-based invitation
FamilyInvitation 增强：
- 添加 maxUseCount INT DEFAULT 1
- 添加 usedCount INT DEFAULT 0
- 添加 inviterUserId BIGINT NOT NULL
- 已有字段 expiresAt（7 天）保持
validateInvitation() 强化：
- 检查 usedCount < maxUseCount
- 检查 status='active' 且未过期
- 校验失败返回明确原因
acceptInvitation() 在事务中 UPDATE ... SET usedCount = usedCount + 1，并带 WHERE usedCount < maxUseCount 防并发
新增端点 POST /api/family/invite/revoke：入参 invitationId，仅 inviter 或 family admin 可调用，将 status 设为 revoked
FamilyController.guideBindFamily 加 familyId 视角下AMILY.getId() ≠ 邀请绑定的(endpoint 自然受 G7 拦截器保护，可保留)
rate-limit：每家庭每天最多生成 10 个邀请码（用 Bucket4j 或简单 Redis 计数）

验证

同一邀请码使用次数超 maxUseCount 后 accept 返回 410
revoke 后立即失效
老简易 invite-code 端点返回 410

完成条件

邀请码泄露可吊销
暴力枚举有 rate limit 防护

G10. 规划师绑定家庭加审批

优先级： P1 估算： 2 人天 前置依赖： G9（共用邀请码机制） 影响文件： FamilyController.guideBindFamily、TeacherFamilyBindingRequest（新 entity）、FamilyController

修复步骤

[ ] 新建 teacher_family_binding_requests 表

CREATE TABLE IF NOT EXISTS teacher_family_binding_requests (
 id BIGINT AUTO_INCREMENT PRIMARY KEY,
 teacher_id BIGINT NOT NULL,
 family_id BIGINT NOT NULL,
 invitation_id BIGINT NOT NULL,
 status VARCHAR(20) NOT NULL DEFAULT 'pending' COMMENT 'pending/approved/rejected/cancelled',
 requested_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 decided_by BIGINT COMMENT '审批家长 user_id',
 decided_at DATETIME,
 reject_reason VARCHAR(200),
 UNIQUE KEY uk_teacher_family (teacher_id, family_id) COMMENT '防重复申请',
 INDEX idx_family_status (family_id, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

[ ] FamilyController.guideBindFamily() 改造：从直接 ADD teacherFamilyIds → 插入 binding_request，status=pending
[ ] 新增端点：
- POST /api/family/teacher-bindings/pending：家长查看自家待审批列表
- POST /api/family/teacher-bindings/approve：入参 requestId，调家长权限校验，status=approved，写入 User.teacherFamilyIds
- POST /api/family/teacher-bindings/reject：入参 requestId, reason
[ ] 消息通知：审批状态变化通过现有 MessageService 推送小程序模板消息给规划师
[ ] MessageController 增加类型：teacher_binding_approved / teacher_binding_rejected

验证

规划师调用 guideBindFamily 后，家长收到待审批消息
家长 reject 前规划师不能在 teacherFamilyIds 看到 familyId
同一 (teacher, family) 重复申请被 UK 拦截

完成条件

陌生规划师凭邀请码无法直接看到家庭数据

G2. 测评订单 → 结果 linkage + "results_ready" 状态

优先级： P1 估算： 2 人天 前置依赖： 无 影响文件： AssessmentOrder、AssessmentOrderService、GuideRecordController、AssessmentService

修复步骤

assessment_orders 加字段 result_id BIGINT + results_ready_at DATETIME（通过迁移）
AssessmentOrder.status 枚举扩展：pending|paid|results_ready|completed|cancelled|refunded
GuideRecordController.record() 写结果后联动更新订单：
- 用 appointmentId 反查 order，写入 orders.result_id = danAssessmentResult.id、status='results_ready'、results_ready_at=now()
- 若找不到对应 order（直接录入场景），跳过
AssessmentOrderController 新增端点 POST /api/assessment/order/{id}/ack-results：家长确认收到结果，订单 status → completed
家长端 polling 或消息推送：订单变 results_ready 触发小程序模板消息
- 复用 MessageService.sendTemplateMessage 已有路径
- 消息类型 assessment_results_ready
AssessmentOrderController.detail 返回 resultId、resultsReadyAt、resultSnapshot（精简版 DanAssessmentResult）

验证

规划师录入结果 → 订单 status=results_ready、result_id 非空
家长端收到模板消息
POST /order/{id}/ack-results 后变 completed

完成条件

付费→结果链闭合
无"我付费了为啥看不到结果"客服投诉

G13. 地址数据库全量导入 + 废弃静态列表

优先级： P1 估算： 3-4 人天 前置依赖： 无 影响文件： DatabaseInitializer.java（seed）、RegionController.java、Street.java、新建 china_regions.csv/SQL

修复步骤

获取权威数据源：民政部《中华人民共和国县以上行政区划代码》最新版，或开源 modood/Administrative-divisions-of-China GitHub 仓库（CSV/JSON 格式，已包含省/市/区/街道 4 级）
生成 SQL 种子文件 db/seed/china_regions.sql：
- 用脚本把 CSV 转成 INSERT INTO streets (...) VALUES ..., (...); 批量语句
- 预计 ~3000 省/市/区/街道行（不动 countries）
DatabaseInitializer 添加迁移：检测 streets 表行数 < 1000 时执行种子导入
- 跑导入前先 DELETE FROM streets WHERE province_code != '44' 清掉旧的广东测试数据（或保留并 IDUPSERT）
- 用 INSERT IGNORE 或 ON DUPLICATE KEY UPDATE 保证幂等
RegionController 改造：
- 删除 ALL_REGIONS 静态硬编码列表
- 所有端点改为查询 StreetService
- /api/region/streets 真正返回街道数据
UserAddress 表加 street_id BIGINT 外键（保留旧 street 字符串字段以兼容历史数据），新建地址时填 street_id
user_address 和 danshop_addresses 写入逻辑：地址选择器只允许从 streets 表选，强制 street_id 非空
前端 AddressPicker 组件：四联动从 /api/region/provinces → cities → districts → streets 拉 DB 数据
区域回退匹配保留：StreetService.matchByStreetWithFallback() 仍然有效，但现在数据齐了，回退少触发

验证

SELECT COUNT(*) FROM streets ≈ 3000+
选北京/上海/西藏任意地址都能选到街道级
RegionController 全部端点单测 PASS
AddressPicker 组件在家长地址页能选北京→朝阳→XX街道

完成条件

95% 中国地区可填到街道
RegionController 中无任何硬编码

G14. Dify 会话本地镜像表

优先级： P1 估算： 2.5 人天 前置依赖： 无 影响文件： 新建 chat_conversations、chat_messages 表 + entity + service；AIService.sendMessage 加镜像写入；端点 fallback 读本地

修复步骤

[ ] 新建 chat_conversations 表

CREATE TABLE IF NOT EXISTS chat_conversations (
 id BIGINT AUTO_INCREMENT PRIMARY KEY,
 user_id BIGINT NOT NULL,
 dify_conversation_id VARCHAR(64) NOT NULL,
 assistant_type VARCHAR(32) NOT NULL COMMENT 'family/nutrition/tongue',
 title VARCHAR(200),
 last_message_at DATETIME,
 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 UNIQUE KEY uk_dify_conv (dify_conversation_id),
 INDEX idx_user (user_id)
) ENGINE=InnoDB;

[ ] 新建 chat_messages 表

CREATE TABLE IF NOT EXISTS chat_messages (
 id BIGINT AUTO_INCREMENT PRIMARY KEY,
 conversation_id BIGINT NOT NULL,
 dify_message_id VARCHAR(64),
 role VARCHAR(20) NOT NULL COMMENT 'user/assistant',
 content TEXT NOT NULL,
 inputs_json TEXT,
 metadata TEXT COMMENT '推荐标签解析结果等',
 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 INDEX idx_conv (conversation_id)
) ENGINE=InnoDB;

[ ] 新建 ChatConversation / ChatMessage entity、Mapper、Service
[ ] AIService.sendMessage 改造：
- 收到 Dify 响应后异步落库（@Async 或直接同步，量大时再优化）
- 给响应中 conversationId 自动 upsert chat_conversations（找不到插一条）
- 给 user message + assistant message 各插一条 chat_messages
[ ] AIChatController.getConversations / getMessages 加 fallback：
- 优先调 Dify，状态码 != 200 时读本地 chat_messages
- 完全不调 Dify 时返回本地数据（ потенц future 应用：纯本地查询模式）
[ ] 新增端点 POST /api/ai/chat/search-history：用户全文搜索自己历史对话（搜 content LIKE）

验证

调 sendMessage 后 chat_messages 表 2 条新记录
关闭 Dify 访问（DNS 指向 127.0.0.1），调 getMessages 仍能返回历史（来自本地）
search-history 能从消息中搜到关键词

完成条件

Dify 短时不可用不影响用户查历史
Dify 永久切换 API key 时本地仍有完整对话（至少 LLM 返回过的）

P2 数据质量与可维护性（下季度修）

G23. 迁移版本表 schema_versions

优先级： P2 估算： 3 人天 前置依赖： 无 影响文件： DatabaseInitializer.java、新建 SchemaVersion entity

修复步骤

[ ] 新建 schema_versions 表

CREATE TABLE IF NOT EXISTS schema_versions (
 id BIGINT AUTO_INCREMENT PRIMARY KEY,
 version_code VARCHAR(64) NOT NULL UNIQUE COMMENT '如 migration_2026_07_10_001',
 description VARCHAR(500),
 checksum VARCHAR(64) COMMENT 'SHA256 of SQL content',
 applied_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 applied_by VARCHAR(100)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

[ ] 重构 DatabaseInitializer.runMigrations()：
- 把现有 200+ ad-hoc migration 归类到 batch（可保留 try-catch 包装每个，但每个 batch 完成后插一行 schema_versions）
- 提供 helper migrationApplied(versionCode) 查表，已跑则跳过
- 启动时第一阶段：创建 schema_versions 表
- 第二阶段：遍历 batch list，对每个未应用的 batch 执行 SQL then 插入记录
[ ] 不立即重构所有现存迁移（206 个分散的 try-catch），先冻结现状并按"重要 batch"切割为 5-10 个 version_code（如 base_schema_v1, growth_record_rebuild_v1, address_seed_v1）
[ ] 新加迁移强制使用新机制：未来所有 DDL 必须用 runMigration("version_X", "描述", () -> { ... }) helper
[ ] /api/admin/schema-versions 端点：admin 查看已跑迁移（只读）

完成条件

启动跳过所有已跑 batch
失败有日志可追溯（不只是吞掉）
历史迁移保留兼容，新迁移走新机制

G25. schema.sql 对账补齐

优先级： P2 估算： 2 人天 前置依赖： G23（共享版本机制后对账更准） 影响文件： schema.sql、新建脚本 tools/validate-schema-sync.ps1

修复步骤

[ ] 跑脚本枚举 DatabaseInitializer + entity @TableName：

# 列出所有 DatabaseInitializer 中 CREATE TABLE 的表名
# 列出所有 @TableName 注解的 entity 表名
# 比对 schema.sql 中 CREATE TABLE 表名

[ ] 补齐 schema.sql 缺失的 ~40 张表：
- danshop_* 10 张
- emotion_checkin、bazi_reading_template、numsoul_config、nutrition_indicator_mapping、nutrition_deficiency_record
- food_recommend_idx、family_invitations、member_discount_configs、article_reading_records、article_quiz_records
- health_dimension_scores、health_data_sources、health_norm_reference
- user_nutrition_profile、user_food_preference
- G1 新增的 five_dimension_scores、G14 新增的 chat_conversations/chat_messages、G9/G10 增强表
[ ] 补齐已有表缺失的列：扫描 entity 字段 vs schema.sql 列名，diff 出缺失字段补到 schema.sql
[ ] 新增 CI 脚本 tools/validate-schema-sync.ps1：每次提交时跑对账，diff 非空时 fail build

完成条件

从 schema.sql 重建数据库，应用启动时无"列不存在/表不存在"错误
CI 对账脚本 PASS

G3. 测评报告核心结论结构化

优先级： P2 估算： 3 人天 前置依赖： 无 影响文件： DanAssessmentResult、GuideRecordController、AssessmentService、web 端规划师录入表单

修复步骤

DanAssessmentResult 新增字段 structured_analysis JSON（保留 analysis_report TEXT 兼容历史）

[ ] 结构化 schema：

{
 "summary": "一句话总评",
 "dimensions": [
   {"code":"wisdom","score":82,"level":"good","indicator":"logicScore","comment":"逻辑推理突出"},
   ...5个维度...
 ],
 "highlight_strengths": ["专注力","记忆容量"],
 "concern_areas": ["情绪管理"],
 "suggestions": [
   {"dimension":"mind","action":"每日 15 分钟正念练习","target":"3 周后 EMI 自我觉察 ≥75"},
   ...
 ]
}

[ ] GuideRecordController.create() 接收 structured_analysis JSON，验证字段必填
[ ] 新增端点 POST /api/dan-assessment/results/{id}/structured：返回结构化数据（家长端用）
[ ] ReportParseService 改造：从 AI prompt 解析时产出 structured_analysis 一起入库
[ ] 家长端 cognitive-report.vue 渲染结构化维度块、建议列表
[ ] web 端规划师录入表单：从单 big textarea 改为分维度表单（强制总结 + 5 维度评分 + 至少 2 个 strength + 1 个 concern）

完成条件

测评报告机读可解析
家长端统一卡片式展示，不再看规划师散文

G26. test-mode 启动断言

优先级： P2 估算： 0.5 人天 前置依赖： 无 影响文件： WechatService、application.yml

修复步骤

WechatService 加 @PostConstruct 启动检查
- 注入 @Value("${spring.profiles.active:dev}") 与 @Value("${wechat.test-mode:false}")
- 若 prod 且 test-mode=true：throw new IllegalStateException("wechat.test-mode=true in production profile!")
CI 检查：新增 tools/check-test-mode.ps1 扫描 application-prod*.yml 有 test-mode: true 时 fail
日志告警：dev 环境下 test-mode=true 时 startup 日志输出 WARN（不是错误，但提醒）

完成条件

prod 下 test-mode=true 启动必失败
CI 拦截配置错误

G15. 饮食推荐规则层 + 解释链 + 推荐日志

优先级： P2 估算： 3-4 人天 前置依赖： 无（G14 同期，可并行） 影响文件： MealRecommendService、新建 RecommendationRuleService、recommendation_log 表

修复步骤

[ ] 新建 recommendation_log 表

CREATE TABLE IF NOT EXISTS recommendation_log (
 id BIGINT AUTO_INCREMENT PRIMARY KEY,
 user_id BIGINT NOT NULL,
 family_member_id BIGINT,
 recommendation_type VARCHAR(32) NOT NULL COMMENT 'meal/supplement/exercise',
 recommended_item VARCHAR(200),
 explanation_json TEXT COMMENT '规则命中的解释',
 dify_response_snippet VARCHAR(500),
 accepted BOOLEAN,
 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 INDEX idx_user_time (user_id, created_at)
) ENGINE=InnoDB;

[ ] 新建 RecommendationRuleService：在 Dify 之前执行确定性规则层
- 输入：用户健康指标、营养偏好、缺失项
- 规则示例：
  - 若缺铁 → 推荐含铁食材（来自 Food 表 nutritionTags contains 'iron'）+ reason="你的健康报告显示铁含量低，建议补充含铁食物"
  - 若过敏原 user_food_preference.allergens 非空 → 排除 candidate foods 中含过敏原的
- 输出结构化 result：{recommendations:[...], reason: "规则命中文本"}
[ ] MealRecommendService.buildDifyInputs() 改造：
- 先跑规则层得到候选食物列表
- 把规则层候选作为 Dify 的"must include"约束
- 规则层结果与 Dify 结果合并，规则层 reason 优先展示
[ ] DietaryRestrictions 不再硬编码：从 user_food_preference 表读 allergens、restrictions
[ ] MealRecommendController.recommend 落库：每次返回前插 recommendation_log
[ ] 新增端点 POST /api/meal/recommend/{logId}/accept：用户标记采纳/拒绝，回填 accepted 字段
[ ] 新增端点 POST /api/meal/recommendations/history：用户查历史推荐

完成条件

用户问"为什么推荐菠菜" → 平台有确定性答案（"你铁含量低，建议补铁"）
过敏原强制过滤生效
推荐有审计日志

P3 长期治理

G4. 清理死字段 / 接入消费者

优先级： P3 估算： 2 人天 前置依赖： G3（测评结构化后死字段已部分被替代） 影响文件： DanAssessmentResult、ReportParseService

修复步骤

审计 4 个字段：
- resultDesc + processDesc：规划师原来填的，G3 改为结构化后已经无意义 → 删除（迁移 DROP COLUMN，实体删字段）
- gameRecords JSON：有价值（原始测试数据），但无消费者 → 接入：新增端点 POST /api/dan-assessment/results/{id}/game-records 返回解析后数据；EnergyService.calcChildWisdom 可读 gameRecords 替代部分 INT 字段
- Big Five（openness..neuroticism 6 列）：有学术价值但无解读 → 接入：新增 BigFiveNormService 做百分位换算；cognitive-report.vue 增"人格倾向"模块

[ ] 删字段迁移：

try {
   jdbcTemplate.execute("ALTER TABLE dan_assessment_results DROP COLUMN result_desc");
   jdbcTemplate.execute("ALTER TABLE dan_assessment_results DROP COLUMN process_desc");
} catch (Exception e) {}

[ ] 同步删 entity 字段、DanAssessmentResult.java

完成条件

DB 表无死字段
保留字段全部有端点读

G21. PDF 解析多供应商抽象 + OCR 后备 + 置信度

优先级： P3 估算： 3-4 人天 前置依赖： 无 影响文件： PdfParseService 重构为 ReportParserRegistry、ReportParser接口、各供应商 parser impl

修复步骤

[ ] 定义接口 ReportParser

interface ReportParser {
 String supplierCode();
 boolean canHandle(String pdfTextOrFilename);
 ParsedReport parse(byte[] pdfBytes) throws ReportParseException;
}

[ ] 抽象 ReportParserRegistry：注入所有 ReportParser bean，按 canHandle 自动路由
[ ] 现有募极逻辑移到 MujiGutReportParser implements ReportParser（保留 868 行现有代码）
[ ] 新增通用 fallback SimpleScoreReportParser：现有 ReportParseService 抽出
[ ] 解析结果加 ParseConfidence：枚举 HIGH/MEDIUM/LOW；分数全找到=HIGH，<50% 字段找到=LOW
[ ] HealthReportDraft 加 confidence_level 字段，preview 端点返回
[ ] OCR 后备：若 PDF 文本提取为空（扫描版），调用腾讯云 OCR 或阿里 OCR 把图像转文本后走相同 parser
[ ] HealthReportController.parse-preview 入参加 supplierHint：可显式指定供应商

完成条件

至少 2 个供应商 parser 并行工作
扫描版 PDF 能 OCR 后解析
解析失败有 confidence 信号

G27. sfms DataSource 唯读强制

优先级： P3 估算： 0.5 人天 前置依赖： 无 影响文件： SfmsDataSourceConfig

修复步骤

HikariConfig 加 setReadOnly(true)
连接初始化 SQL：connection-test-query: SET SESSION TRANSACTION READ ONLY（MySQL 8 支持会话级 read only）
sfmsJdbcTemplate.execute() 包装层：新增 SfmsReadOnlyJdbcTemplate extends JdbcTemplate，覆写所有 write 方法抛 UnsupportedOperationException

完成条件

任何 write 操作 fail-fast
DataMigration 仍能 read 正常

G22. 前端 mock 数据 fallback 处理

优先级： P3 估算： 1.5 人天 前置依赖： G1（G1 完成后真正有数据可用） 影响文件： growth-curve.vue、health-trend.vue、stats/index.vue、dimension-detail.vue

修复步骤

growth-curve.vue 第 135 行 mock 移除
- API 调用失败时显示 Element 风格 EmptyState "暂无记录" 按钮"添加首次测量"
- 不允许显示假数据
health-trend.vue 第 109-132 行 mock 移除，改为 EmptyState
统一 EmptyState 组件 components/EmptyState.vue：图标 + 提示 + CTA
dev 模式 mock 数据通过环境变量开关：process.env.NODE_ENV === 'development' && uni.getStorageSync('useMock') 才显示 mock，且页面顶部加 "演示数据" 红色 banner

完成条件

生产环境不出现假数据
dev 调试仍可用 mock，但显式可见

待办依赖与并行机会图

P0：
  G7 ──┐
  G1 ──┬──── G18 (建议 G1 先)
       │
P1：    │
  G8 ───┤                  (G8 不依赖 G1)
  G9 ───┬─ G10
  G13 ──┤                  (G13 与 G1 并行)
  G14 ──┤                  (G14 与 G1 并行)
  G2 ───┘                  (G2 与其他独立)
       │
P2：    │
  G23 ──┬─ G25 (G23 先,对账机制)
  G26 ──┤              (G26 独立)
  G3 ───┤              (G3 与 G23 并行)
  G15 ──┤              (G15 与 G23 并行)
       │
P3：    │
  G27 ──┐        (G27 独立)
  G22 ──┤        (G22 等 G1)
  G21 ──┤        (G21 独立)
  G4 ───┘        (G4 等 G3)

可立即并行的任务（同周内）

第 1 周：G7 + G1 + G18（按序完成，但 G1 启动后 G18 可同时开始）
第 2 周：G8 / G9+G10 / G13 / G14 / G2 / G26（六个并行）
第 4 周：G23 / G3 / G25(等G23) / G15 / G21 / G27（六个并行）

整体验收清单

所有 P0 任务 mvn clean compile 通过 + 单测 PASS
FamilyAccessInterceptorTest 全 PASS（G7）
调 /api/energy/score-history 返回时间序列（G1）
/api/assessment/compare/by-child 返回 delta（G18）
切回家长提示输密码（G8）
邀请码过期后 accept 返回 410（G9）
规划师绑定家庭家长需要 approve（G10）
订单 status=results_ready 触发模板消息（G2）
北京地址能选到街道（G13）
关闭 Dify 后能查历史对话（G14）
schema.sql 重建数据库可用（G25）
prod 启动含 test-mode=true 失败（G26）
"为什么推荐菠菜" 平台能答（G15）

风险与回滚策略

每个任务独立迁移：用 try-catch 包裹，失败不阻塞应用启动
G7 拦截器：先以日志模式上线（不实际拦截只打 warn），观察 3 天后切为强制模式
G8 视角切换合并：保留旧端点返回 308 redirect 一周，再删除
G13 地址数据：上线前先 SELECT 校验种子数据完整性，确保关键省/市/区无空缺
G3 结构化报告：保留 analysis_report TEXT 字段，新加 structured_analysis JSON 并行存在 3 个月，再淘汰旧字段
G14 Dify 镜像：先只写本地不切读取路径，观察 1 周数据完整后再 enable fallback read
G1 五维快照：探针期间每条线都计算 + persist；观察性能不降级再优化为异步

后续工作（不在本计划）

家长端可视化（趋势图对比图）—— 等 G1 数据积累 1 个月再返工前端图表
AI 健康助手对历史对话做 RAG 检索 —— 等 G14 数据 2 周
知识库与测评结果自动联动（G16）—— 等 G3 结构化分析上线后接入

修订记录

版本	日期	修订内容
v1.0	2026-07-10	首次发布，18 任务 4 优先级

2026-07-10-determinism-gap-fix-plan.md 36 KB 永久連結 文件歷史 原始文件

浠艾福平台 · 确定性差距修复实施计划

实施总览

P0 关键安全与根基（立即修）

G7. familyId 入参校验（最大隐私漏洞）

问题定位

修复步骤

验证

完成条件

G1. 五维能量分数持久化（解锁全部可视化叙事）

问题定位

修复步骤

验证

完成条件

G18. 首次 vs 最新测评对比端点

问题定位

修复步骤

验证

完成条件

P1 信任与数据闭环（本季度修）

G8. 视角切换统一为一套机制 + 密码校验

修复步骤

验证

完成条件

G9. 邀请码加过期+使用次数+吊销

修复步骤

验证

完成条件

G10. 规划师绑定家庭加审批

修复步骤

验证

完成条件

G2. 测评订单 → 结果 linkage + "results_ready" 状态

修复步骤

验证

完成条件

G13. 地址数据库全量导入 + 废弃静态列表

修复步骤

验证

完成条件

G14. Dify 会话本地镜像表

修复步骤

验证

完成条件

P2 数据质量与可维护性（下季度修）

G23. 迁移版本表 schema_versions

修复步骤

完成条件

G25. schema.sql 对账补齐

修复步骤

完成条件

G3. 测评报告核心结论结构化

修复步骤

完成条件

G26. test-mode 启动断言

修复步骤

完成条件

G15. 饮食推荐规则层 + 解释链 + 推荐日志

修复步骤

完成条件

P3 长期治理

G4. 清理死字段 / 接入消费者

修复步骤

完成条件

G21. PDF 解析多供应商抽象 + OCR 后备 + 置信度

修复步骤

完成条件

G27. sfms DataSource 唯读强制

修复步骤

完成条件

G22. 前端 mock 数据 fallback 处理

修复步骤

完成条件

待办依赖与并行机会图

可立即并行的任务（同周内）

整体验收清单

风险与回滚策略

后续工作（不在本计划）

修订记录

2026-07-10-determinism-gap-fix-plan.md 36 KB

永久連結文件歷史原始文件