任务号:EVD-9(孩子端 26 SC 开工包契约核对) 日期:2026-11-07 基线:
origin/cfclub@cd35657f6(本次 rebase 后);端点比对在原工作树0828de991上完成,git diff 0828de991..cd35657f6 -- cfc-backend/src/main cfc-frontend cfc-web/src为空,源码口径一致 核验方式:开工包逐条比对 + 端点实测(O-7 契约补建工作流),不写业务实现代码 主要依据:docs/tdd/orchestration/child-zone-kickoff-20261107.md(26 SC 开工包,含 6 个 ⚠ 待核实项) 辅助依据:tests/user-scenarios/应用场景总览.md§ 四(场景目标/流程/边界/模块)、sc-key-map.md(能力键状态)
EVD-9 启动时,docs/tdd/orchestration/child-zone-kickoff-20261107.md 在 origin/cfclub 及全部远端分支中尚不存在
(git log --all -- "docs/tdd/orchestration/child*" 为空、目录列举仅 6 个批次包)。
随后主理人在 802cbbce4(研发负责人第 31 轮汇报)补推该开工包,本文件已按开工包重新逐条复核,
下表「候选端点」列保留开工包原写法,「实测端点」列为本会话在源码中实际定位到的路径,两者不一致处标注 纠偏。
环境偏差:任务要求
E:/cfc为工作目录,本机只有 C 盘(Get-PSDrive仅 C),实际使用隔离 worktreeC:\code\cfc-child-zone-contract(分支feature/child-zone-contract-evd9,基于origin/cfclub新建,未合并主干)。
| 指标 | 结果 |
|---|---|
| SC 总数 | 26(SC-C-01 ~ SC-C-26) |
| 有承载端点 | 26/26(每个场景至少一个可调用的现有 @PostMapping) |
| 场景完整闭环 | 19/26 |
| 场景级实现缺口 | 7 个(C-10 / C-16 / C-17 / C-18 / C-20 / C-23 / C-26) |
| 开工包 ⚠ 待核实项 | 6 个(C-03 / C-09 / C-10 / C-18 / C-20 / C-21)→ 已全部给出实测结论(见 § 3) |
| 开工包候选载体需纠偏 | 6 个(C-07 / C-08 / C-12 / C-14 / C-22 / C-24,见 § 3.2) |
| 跨切面缺陷(权限/幂等/路径/绑定) | 5 项(G-08 ~ G-12) |
统计口径:
全部实测端点从
cfc-backend/src/main/java/**/*Controller.java全量提取(1935 个@PostMapping)后逐条比对, 未做包路径假定。{id}/{memberId}为@PathVariable。
| SC | 场景 | 开工包候选载体 | 实测端点(origin/cfclub) | 核验 |
|---|---|---|---|---|
| SC-C-01 | 孩子端登录(无家长入口) | AuthController /api/auth/*;JwtInterceptor 角色校验 |
POST /api/auth/silent-login、/wechat-login、/phone-login、/auto-login、/verify;视角切换 POST /api/family/member/switch({memberId,source} → SwitchMemberVO);JwtInterceptor 注入 userId/role/familyId/currentMemberId |
✅ |
| SC-C-02 | 执行任务 / 小游戏得积分 | TaskController /api/tasks/*;PointsController /api/points/*;小游戏路由 |
POST /api/tasks/today、/my-pending、/{id}/start、/{id}/complete、/{id}/complete-minigame;POST /api/mini-game/list、/mini-game/complete;POST /api/points/balance、/points/logs |
✅ |
| SC-C-03 | 小游戏成绩上报 | 小游戏 Controller(/api/game*,⚠ 待核实实际前缀) |
实测双前缀:POST /api/mini-game/complete(CompleteGameDTO{memberId,gameCode,completionTime,score})+ POST /api/game/record;查询 /api/game/history、/best、/stats、/leaderboard |
✅ |
| SC-C-04 | 提心愿 | WishController /api/wishes/* |
POST /api/wishes/create(CreateWishDTO)、/list、/{id}、/{id}/cancel;家长侧 /{id}/price、/{id}/approve-exchange、/{id}/reject、/{id}/fulfill、/{id}/confirm |
✅ |
| SC-C-05 | 任务打卡 ⭐ | TaskController 完成/打卡;DailyTaskController /api/daily-task/* |
POST /api/tasks/{id}/complete(CompleteTaskDTO{memberId?,photoUrl,content,contentType});POST /api/daily/checkin/create、/list;POST /api/daily-task/overview |
✅ |
| SC-C-06 | 查看能量与报告(只读) | EnergyController /api/energy/*(overview/logs) |
POST /api/energy/overview、/logs、/score-history、/sandbox(需过 SELF_CHECK 关卡);报告 POST /api/health/report/list、/latest、/detail |
✅ |
| SC-C-07 | 查看 DAN 测评报告 | DanAssessmentController /api/dan-assessment/*;/api/dan-assessment/result |
纠偏:/api/dan-assessment/result、/api/dan-assessment/list 均不存在。实测可用:POST /api/dan-report/list、/dan-report/{id}、/dan-report/compare;或 POST /api/dan-assessment/my-results、/child-results、/report/child、/result/{id} |
✅ |
| SC-C-08 | 方案打卡进度 | HealthPlanController /api/health/plan/*;GrowthPlanController /api/growth/plan/* |
POST /api/health/plan/list、/detail、/tasks(按 planId,含家庭归属校验);POST /api/growth/plan/list、/growth/plan/{id}、/growth/plan/child/{memberId};POST /api/daily/checkin/list |
✅ |
| SC-C-09 | 勋章墙 | 成就/勋章 Controller(achievement.*,⚠ 待核实前缀) |
实测无 AchievementController,实际为 BadgeController /api/badges/*:POST /api/badges/list、/member/list、/statistics/member、/ranking/family、/detail、/favorite |
✅ |
| SC-C-10 | 勋章解锁提醒 | 同上 + NotificationController /api/notification/* |
授予 POST /api/badges/grant;查询 /api/badges/member/list;通知 POST /api/notification/list、/read —— 但授予不等通知(见 § 3.2) |
⚠ |
| SC-C-11 | 成长记录查看(孩子视角) | GrowthController /api/growth/* |
POST /api/growth/record/list(本人)、/record/child/{memberId}、/record/child-records、/record/{id} |
⚠ 权限 |
| SC-C-12 | 饮食食谱查看 | DietRecommendationController /api/diet/recommendation/*、/api/diet/meals/* |
纠偏:/api/diet/meals/* 只有 config、config/save(配置,不是食谱)。实测食谱:`POST /api/diet/recommendation/today |
generate |
| SC-C-13 | AI 对话(孩子视角) | AIChatController /api/ai/* |
POST /api/ai/chat/send、/chat/conversations、/chat/messages;POST /api/ai/health-coach/send、/health-coach/gate |
✅ |
| SC-C-14 | 任务驳回重做 | TaskController 审核/驳回;ReviewController /api/review/* |
纠偏:/api/review/* 实测只有 order、order/detail、order/status(订单评价,非任务审核)。实测任务链:POST /api/tasks/{id}/review(approved=false → status=pending)+ POST /api/tasks/{id}/complete 重新提交;拒接 POST /api/tasks/reject/{id} |
✅ |
| SC-C-15 | 消息接收 | NotificationController /api/notification/* |
POST /api/notification/list(按 userId,未读优先,LIMIT 100)、/read;规划师消息 POST /api/guide/messages/my |
✅ |
| SC-C-16 | 个人资料查看(受限) | UserController /api/user/*(只读字段白名单) |
POST /api/user/info、/api/auth/info、/api/family/user/info —— 均返回完整 User,无字段白名单(见 § 5 G-02) |
⚠ |
| SC-C-17 | 退出登录 | AuthController 登出/token 失效 |
无 logout 端点;SecurityConfig 显式 logout().disable();仅 POST /api/auth/verify 校验 token |
⚠ |
| SC-C-18 | 设备/账号绑定校验 | AuthController + 微信登录态校验(⚠ 待核实) |
实测无设备维度:AuthController 18 个端点均无 deviceId;等价物 POST /api/auth/verify、/api/family/invite/check-family、/api/family/invite/validate、/api/family/user/switch-back-verify |
⚠ |
| SC-C-19 | 查看家人/规划师消息通知 | NotificationController;GuideMessage /api/guide/messages/* |
POST /api/notification/list、/read;POST /api/guide/messages/my、/unread-count |
✅ |
| SC-C-20 | 成长档案查看/家长代导出 | GrowthController;导出端点(⚠ 待核实) |
查看:POST /api/growth/record/list、/record/child/{memberId}、/record/{id};导出:POST /api/user/data-export(仅本人,无 memberId 入参) |
⚠ |
| SC-C-21 | 舌诊/情绪自拍采集(孩子端) | EmotionCheckinController /api/mind/checkin/*;舌诊采集端点(⚠ 待核实) |
情绪:POST /api/mind/emotion/analyze、/analyze-url、/api/mind/checkin/emotion/recognize、`/mind/checkin/create |
list |
| SC-C-22 | 商城浏览/积分兑换(孩子端消费) | ProductController /api/product/*;/api/admin/product-ppoint(ppoint 兑换) |
纠偏:/api/admin/product-ppoint/* 是管理端配置,非孩子端兑换。实测:POST /api/product/list、/product/detail;POST /api/points/exchange/product/list、/product/detail、/submit、/records、/stats;POST /api/points/balance、/logs |
✅ |
| SC-C-23 | 意见反馈(孩子端) | ActivityFeedbackController /api/activity/feedback/* |
实测 /api/activity/feedback/submit 为活动评价,/api/feedback/* 为家长→孩子每日反馈,/api/health/feedback/submit 为报告反馈 —— 均非通用意见反馈(见 § 5 G-06) |
⚠ |
| SC-C-24 | 小游戏/任务得分触发五维增长(仅自身可见) | EnergyController 行为计分链 + AdminEnergyBehaviorConfigController |
纠偏:/api/admin/energy-behavior/* 是配置 CRUD,不是计分触发。实测触发链:MiniGameService.completeGame → GameRecordService.saveRecord → EnergyService.awardEnergy(memberId,"game",...);查看 `POST /api/energy/overview |
logs |
| SC-C-25 | 方案任务打卡触发五维增长 | TaskController 完成 → Energy 归因链 |
POST /api/tasks/{id}/complete → TaskService 内 energyService.awardEnergy(memberId,"task",...);GrowthTaskService 打卡 awardEnergy(child,"growth_day",...);POST /api/daily/checkin/create |
✅ |
| SC-C-26 | 睡眠打卡:「正常」选项且由后台配置驱动 | sleep.config.tags(YELLOW);PublicConfigController + 后台配置项 |
记录 POST /api/health/sleep/list、/create;配置读 POST /api/config/public/value(key=sleep.quality.tags);配置维护 POST /api/admin/config/list、/update(通用) |
⚠ |
| 项 | 结论 |
|---|---|
| 实际前缀 | 两个:/api/mini-game/*(MiniGameController)与 /api/game/*(GameRecordController) |
| 上报入口 | POST /api/mini-game/complete(CompleteGameDTO);POST /api/game/record(裸 Map,可选 difficulty、pointsEarned) |
| 落库 | family_members.total_points、points_log、game_record、Redis ZSet 排行榜 |
| 异常分数拦截 | 缺失:calculatePoints 仅分 score<60 / >=60 两档,无上限;score=999999 可换巨额积分并直写排行榜 |
| 幂等 | 缺失:completeGame 每次调用都加分,无 (memberId, gameCode, 时间窗) 判重 |
| 归属 | 有 familyMemberMapper.selectById(memberId) 存在性校验,但未校验 memberId 与当前会话/家庭关系 |
| 项 | 结论 |
|---|---|
| 类名 | 无 AchievementController/MedalController,实际是 BadgeController(/api/badges) |
| 勋章墙(C-09) | /list(启用定义)+ /member/list(已得,收藏优先+获得时间倒序)+ /statistics/member + /ranking/family + /detail + /favorite → 可支撑 |
| 授予链路 | 仅 POST /api/badges/grant(人工);无任务/打卡自动聚合授予 |
| 判重 | grantBadge 先查 (memberId,badgeId),存在即 return ✅ |
| 解锁提醒(C-10) | 未实现:grantBadge 只写 member_badges,不写 user_notification、无推送;/api/notification/* 只负责读 |
| 结论 | C-09 墙成立;C-10 只完成"解锁","提醒/推送"缺失(G-01) |
| 项 | 结论 |
|---|---|
| 场景要求 | "登录设备校验;异常设备二次验证"(模块 AuthController) |
| 实测 | AuthController 全部端点无 deviceId/设备表/登录设备比对;JwtInterceptor 只校验 token 与用户存在性 |
| 易混淆 | /api/bind/*=家庭-规划师绑定;/api/family/invite/*=家庭邀请绑定;/api/health/report/proxy-parse 的 canProxyForFamily=代传家庭校验。三者都不是设备绑定 |
| 结论 | 无端点承载,C-18 整条待实现(G-04);建议先由产品确认是"设备绑定"还是"账号绑定" |
| 项 | 结论 |
|---|---|
| 端点 | POST /api/user/data-export(需登录) |
| 实现 | AccountCleanupService.exportUserData(userId):userInfo / children(family_members.user_id = userId)/ assessmentResults(按 familyMemberId = userId,口径可疑)/ healthReports / tasks |
| 代导出 | 不支持:方法签名无 memberId,家长无法指定导出某个孩子;"未成年人导出受限、需家长代办"无落点(G-05) |
| 项 | 结论 |
|---|---|
| 舌诊 | POST /api/health/report/upload-only?type=tongue(建草稿+预览,含 aiGateway.detectTongue 自动识别分支)、/report/parse-preview?type=tongue、/report/confirm?type=tongue(需 recordId+subjectId)、/report/discard?type=tongue |
| 情绪 | POST /api/mind/emotion/analyze、/analyze-url、/api/mind/checkin/emotion/recognize;记录 `/api/mind/checkin/create |
| 边界 | 文件类型/大小白名单在 upload-only;"模糊/非照片拒绝"依赖识别服务返回,无显式错误码契约;"隐私标注"属前端文案 |
| 结论 | 端点齐全,边界需测试侧用真实样本验证 |
| SC | 开工包写法 | 实测结论 |
|---|---|---|
| C-07 | /api/dan-assessment/result |
该路径不存在;用 /api/dan-report/* 或 /api/dan-assessment/my-results、/result/{id} |
| C-08 | /api/growth/plan/*(通用) |
存在,但无 /growth/plan/detail,详情是 /growth/plan/{id};主链路在 /api/health/plan/* |
| C-12 | /api/diet/meals/* |
只有 config/config/save(配置),食谱数据在 /api/diet/recommendation/* + /api/health/meal/* |
| C-14 | ReviewController /api/review/* |
那是订单评价;任务驳回重做在 /api/tasks/{id}/review |
| C-22 | /api/admin/product-ppoint |
管理端配置;孩子端兑换在 /api/points/exchange/* |
| C-24 | AdminEnergyBehaviorConfigController |
配置 CRUD;触发链是任务/游戏完成 → EnergyService.awardEnergy |
以下键取自开工包
child-zone-kickoff-20261107.md(权威建议),sc-key-map.md中 26 条 SC-C 的能力键当前均为—(C-26 关联sleep.config.tags)。 命名沿用child.*命名空间,与既有task.parent.*/energy.*/dimension.*不冲突。
| SC | 建议能力键 | 说明 |
|---|---|---|
| SC-C-01 | child.login |
含家长代管切视角 POST /api/family/member/switch |
| SC-C-02 | child.task.execute |
任务完成 + 小游戏完成 + 积分流水 |
| SC-C-03 | child.game.score |
成绩上报(需补上限/幂等才可 GREEN) |
| SC-C-04 | child.wish.create |
提心愿 + 撤销 |
| SC-C-05 | child.task.execute |
方案任务打卡 |
| SC-C-06 | child.energy.view |
五维能量只读(需补成员级可见性) |
| SC-C-07 | child.dan.report.view |
DAN 报告列表/详情/对比 |
| SC-C-08 | child.plan.progress |
方案任务进度 |
| SC-C-09 | child.achievement.view |
勋章墙 + 统计 + 家庭排行 |
| SC-C-10 | child.achievement.view |
解锁提醒(提醒子能力待实现) |
| SC-C-11 | child.growth.view |
成长记录只读(需补归属校验) |
| SC-C-12 | child.diet.view |
今日食谱/餐次 |
| SC-C-13 | child.ai.chat |
AI 对话多轮(适龄过滤待补) |
| SC-C-14 | child.task.reject |
驳回后重做再提交 |
| SC-C-15 | child.notification.view |
站内消息接收/已读 |
| SC-C-16 | child.profile.view |
受限资料投影(待实现) |
| SC-C-17 | child.login |
退出登录(前端清 token,后端待定) |
| SC-C-18 | child.login |
设备/账号绑定校验(待实现) |
| SC-C-19 | child.notification.view |
家人/规划师通知 |
| SC-C-20 | child.growth.view |
档案查看 + 家长代导出(待实现) |
| SC-C-21 | child.mind.capture |
舌诊 + 情绪自拍采集 |
| SC-C-22 | child.shop.redeem |
商城浏览 + 积分兑换 |
| SC-C-23 | child.feedback.submit |
意见反馈(待实现) |
| SC-C-24 | child.energy.view |
游戏得分 → 五维能量 |
| SC-C-25 | child.task.execute |
方案打卡 → 五维能量 |
| SC-C-26 | child.sleep.checkin |
关联既有状态机键 sleep.config.tags(别名 sleep.quality.tags,见 G-07) |
类型:
场景缺口= 该 SC 目标/边界无法被现有端点满足;跨切面= 影响多个 SC 的共性缺陷。 证据列给出文件:行,路径相对cfc-backend/src/main/java/com/etotem/cfc/。
| ID | 类型 | 关联 SC | 缺口描述 | 证据 | 建议 |
|---|---|---|---|---|---|
| G-01 | 场景缺口 | C-10 | 勋章解锁无通知、无推送;grantBadge 只写 member_badges |
service/BadgeService.java:76 |
grantBadge 内写 user_notification(type=badge_unlock)+ 订阅消息;或新增 /api/badges/unlock-notices |
| G-02 | 场景缺口 | C-16 | 个人资料无"受限"投影,三个 info 端点返回完整 User(仅密码置空) |
controller/UserController.java:80、controller/auth/AuthController.java:186、controller/family/FamilyUserController.java:47 |
增加 memberType=local/role=child 的字段裁剪 VO(隐藏 idCard/phone/realName/openid) |
| G-03 | 场景缺口 | C-17 | 无服务端 logout;JWT 无状态 | 全库无 /logout 映射;config/SecurityConfig.java:35 logout().disable() |
若需强制下线:加 token 黑名单/版本号;否则在契约中明确"退出=客户端清除" |
| G-04 | 场景缺口 | C-18 | 无设备绑定/异常设备二次验证 | controller/auth/AuthController.java(18 个端点均无设备参数) |
新增 device_bind 表 + /api/auth/device/verify;或由产品确认该 SC 降级为"账号绑定校验" |
| G-05 | 场景缺口 | C-20 | 无"家长代导出指定成员";exportUserData(userId) 不接受 memberId |
service/AccountCleanupService.java(exportUserData) |
/api/user/data-export 增加可选 memberId(家长/管理员校验);顺手修 assessmentResults 查询口径 |
| G-06 | 场景缺口 | C-23 | 无通用意见反馈端点/表/管理端;现有反馈均为专用方向 | controller/DailyFeedbackController.java:21、controller/ActivityFeedbackController.java:11、controller/HealthReportController.java:2660 |
新增 user_feedback 表 + POST /api/user/feedback/submit(避开 /api/feedback 前缀冲突)+ 管理端受理 |
| G-07 | 场景缺口 | C-26 | ①sleep_record 无 tags 列,标签被前端 buildRemark() 拼进 remark TEXT;②/api/health/sleep/tags 未实现;③/api/admin/sleep/tags 未实现;④key 命名 sleep.quality.tags(需求/用例)vs sleep.config.tags(sc-key-map);⑤sleep-checkin.vue 硬编码 8 项、无「正常」、未拉配置 |
entity/HealthSleepRecord.java(无 tags)、resources/schema.sql(sleep_record 无 tags 列)、controller/HealthSleepController.java(仅 list/create)、pages/growth/sleep-checkin.vue:188,405 |
迁移新增 sleep_record.tags;统一 key 为 sleep.quality.tags 并在 sc-key-map 加别名;补 /api/health/sleep/tags(默认 9 项含「正常」);前端拉配置 + 提交 tags 数组;补管理端页面 |
| G-08 | 跨切面 | C-01/C-17 | 前端路径与后端不一致:①/api/user/switch-to-child、/switch-back-to-parent、/switch-mode、/roles、/switch-role 在 UserController 无映射(404);②旧 /api/family/user/switch-* 已 @Deprecated + 410,现行只有 /api/family/member/switch;③child/tasks.vue、child/rewards.vue 仍调旧 switchBackToParent() |
cfc-frontend/utils/api.js:570-592、controller/family/FamilyUserController.java:123-136、controller/family/FamilyMembersController.java(/switch) |
孩子端两页改调 switchToFamilyMember(parentMemberId);api.js 删除废弃函数;api.test.js:530-536 同步改断言 |
| G-09 | 跨切面 | C-02/C-03/C-24 | 小游戏上报无幂等、无分数上限;/api/game/record 的 pointsEarned 前端可控 |
service/MiniGameService.java(completeGame/calculatePoints)、service/GameRecordService.java(saveRecord) |
加 (memberId,gameCode,date) 幂等键;score 限 0~100(或按游戏配置);pointsEarned 改服务端计算 |
| G-10 | 跨切面 | C-06/C-24 | 能量读取无成员级/家庭级校验:/api/energy/overview、/logs 只校验"当前用户有 familyId",随后直接按传入 memberId 查 → 可跨家庭读;/sandbox 仅同家庭成员可互读 |
controller/EnergyController.java:156-200、controller/EnergyController.java:48-122 |
overview/logs 校验 memberId 归属当前 familyId;sandbox 非家长/非本人返回 403 或裁剪 |
| G-11 | 跨切面 | C-11/C-20 | growth/record/child/{memberId} 与 /record/{id} 无归属校验,任一登录用户可按 id 读取他人档案 |
controller/growth/GrowthRecordController.java:136 |
补 familyId/currentMemberId 归属校验(参考 HealthPlanController /tasks) |
| G-12 | 跨切面 | C-02 | /api/tasks/accept 声明 @PathVariable Long id 但路径无 {id};前端按 {taskId, memberId} 传 body → 必抛 MissingPathVariableException |
controller/task/TaskController.java:312-327、cfc-frontend/utils/api.js:840、cfc-frontend/pages/tasks/tasks.vue:664 |
改读 @RequestBody.taskId,或路径改 /accept/{id} 并同步前端 |
child.* 键登记 sc-key-map.md,不要整批标 GREEN:C-10/C-16/C-17/C-18/C-20/C-23/C-26 标 YELLOW(契约缺口)。API_REFERENCE.md 4.61 节同批合入后,再按 --add-task 入池。# 1) 端点全量提取(1935 个 @PostMapping 实际路径)
Get-ChildItem -Recurse -Filter "*Controller.java" -Path cfc-backend/src/main/java |
ForEach-Object { Get-Content -Raw $_ | Select-String '@RequestMapping|@PostMapping' }
# 2) 开工包 ⚠ 项定位
git grep -n "@PostMapping(\"/complete\")" -- cfc-backend/src/main/java/com/etotem/cfc/controller/MiniGameController.java
git grep -n "grantBadge" -- cfc-backend/src/main/java/com/etotem/cfc/service/BadgeService.java
git grep -n "exportUserData" -- cfc-backend/src/main/java/com/etotem/cfc/service/AccountCleanupService.java
git grep -n "switch-back-to-parent" -- cfc-frontend cfc-backend
git grep -n "sleep.quality.tags" -- docs tests cfc-frontend cfc-backend
本文件由 EVD-9 契约核对会话产出;仅文档,不改业务源码、不新增 DB 迁移。