归属:契约补建计划 P0「家长域剩余」· 核对时间 2026-11-07(EVD-13) 开工包:
docs/tdd/orchestration/parent-rest-kickoff-20261107.md(origin/cfclub @3d7044429) 核对对象:origin/cfclubcfc-backendcontroller 源码(工作树 HEAD = origin/cfclub3d7044429) 核对方法:类级@RequestMapping+ 方法级@PostMapping逐一比对(grep -rn '@RequestMapping|@PostMapping' cfc-backend/src/main/java/com/etotem/cfc/controller/实测定位,不假定包路径),逐端点记录存在性;对字面路径缺失者定位等价实现(防假 RED:契约声明的接口范围必须能在真实源码中找到实现)。开工包 10 个 ⚠ 待核实项全部实测回填。 命名注意:已 GREEN 键(health.report.upload/health.report.createReport/growth.history.view/langgraph.questionnaire.generate)映射到 SC 时复用既有键,仅登记不新建(O-2 方案 A 防键重复)。
health.report.upload(SC-P-20~23)、health.report.createReport(SC-P-23)、growth.history.view(SC-P-50)、langgraph.questionnaire.generate(SC-P-49)——仅登记不新建。开工包 30 个 SC 中 10 个标注 ⚠,会话实测回填结论如下(含候选类名与实际类名的命名差异,见 §2「端点载体(实测回填)」列):
| ⚠ 项 | 场景 | 实测结论 |
|---|---|---|
| SC-P-29 食谱收藏/调整 | 收藏/调整端点 | 调整已存在——MealRecommendController /api/meal/replace(换餐)、DietRecommendationController /api/diet/recommendation/update、/regenerate、/complete(对齐/重算);收藏无端点(全库无食谱收藏 Controller/端点;IndicatorFavoriteController /api/indicator/favorite/* 为指标收藏,非食谱)→ 见缺口 G-1 |
| SC-P-49 AI 健康管家对话 ⭐ | 载体跨组件待核实 | 已存在——AIChatController /api/ai:/chat/send、/health-coach/send、/nutrition/send、/butler/send、/gate、/health-coach/gate;底层 AiGateway.chat() → cfc-langgraph /api/v1/chat(chat_graph)。已 GREEN 键 langgraph.questionnaire.generate 复用登记(仅登记不新建,见 §3) |
| SC-P-51 成长里程碑 | 里程碑端点 | 无独立成长里程碑端点——GrowthController /api/growth 仅 recommendations / articles/ai-classify / products/ai-classify;RelationshipQualityController /api/family/relationship/milestones 是关系里程碑、`InviteMilestoneController /api/invite/milestone/list |
| SC-P-62 联系人分组/导入 | 分组/导入端点 | 导入已存在——ContactController /api/contact/import-phone(通讯录导入);分组无端点(ContactController、ContactMatchController 均无 group/分组端点)→ 见缺口 G-3。命名回填:开工包候选 ContactImportController 类名不存在,导入由 ContactController.import-phone 承载 |
| SC-P-65 消息通知/提醒设置 | 通知/提醒设置端点 | 已存在——`UserNotificationController /api/notification/list |
| SC-P-66 隐私设置 | 隐私端点 | 已存在——`ConsentController /api/consent/record |
| SC-P-71 账号注销 | 注销端点 | 已存在——UserController /api/user/deactivate(AccountCleanupService.deactivateAccount,数据匿名化/数据主权)+ /data-export(个保法数据可携带权导出) |
| SC-P-73 多孩子切换孩子上下文 | 上下文切换端点 | 已存在——FamilyMembersController /api/family/member/switch(切成员视角,SwitchMemberVO);`FamilyUserController /switch-mode |
| SC-P-79 推送/通知开关设置 | 通知开关端点 | 主语义已存在——`TaskReminderConfigController /api/task/reminder-config/get |
| SC-P-85 多端登录/会话互斥 | token 互斥端点 | 部分存在——AuthController /api/auth/* 登录族(phone-login/wechat-login/silent-login/auto-login/sso-login)+ /sso-ticket(SSO 一次性票据,SsoService.issueTicket/consumeTicket,跨系统握手);无单端互斥/旧会话踢出(JWT 无状态,JwtInterceptor 仅校验签名/过期,无会话注册表/踢出逻辑)→ 见缺口 G-5 |
核验口径:✅ = 候选/回填端点真实存在于工作树;⚠ = 主场景有端点但存在子能力缺口(详见 §4 实现缺口清单)。
| SC | 场景标题 | 端点载体(实测回填,origin/cfclub 工作树) | 核验 |
|---|---|---|---|
| SC-P-02 | 邀请成员 + 关系编辑 | FamilyMembersController /api/family/member/add(AddFamilyMemberDTO:generationLevel/peerType → FamilyRelationshipService.createRelationsForNewMember 自动建关系)、/update(关系编辑同载体);FamilyInviteController /api/family/invite/generate(复用同家庭未过期未用尽令牌)、/qrcode、/validate、/accept、/bind-inviter、/request-join-by-code;RelationshipQualityController `/api/family/relationship/scores |
pairwise(关系质量查询)。**命名回填**:开工包候选RelationshipController类名不存在,实际为RelationshipQualityController`(关系质量,非关系类型编辑) |
| SC-P-04 | 家庭成员列表查看 | FamilyMembersController /api/family/member/list(统一入口,visibleOnly/includeFamily 过滤) |
✅ |
| SC-P-05 | 编辑成员资料 | FamilyMembersController /api/family/member/update(nickname/phone/avatar/gender/birthday/generationLevel/peerType/isAdmin/isChild)+ /editable(可编辑检查) |
✅ |
| SC-P-20 | 健康报告 PDF 上传解析(上传报告)⭐ | HealthReportController /api/health/report/upload-only(生产上传入口:PDF→草稿 health_report_drafts(parse_status=collecting)→异步采集→返回 draftId)、/upload(兼容:自动执行「解析→确认」两阶段)、/parse(异步解析)、/collect/status+/collecting-list(采集进度轮询);GrowthRecordController /api/growth/record/upload-and-parse。复用 health.report.upload(已 GREEN),仅登记不新建 |
✅ |
| SC-P-21 | 报告类型识别 | HealthReportController /api/health/report/parse-preview(type=auto 识别 + type=image)、/report/indicators+/indicator/list+/indicators/rebuild(类型/指标驱动解析);ReportParserController /api/report-parser/detect、/types/links(类型识别/类型链接)。复用 health.report.upload 链(已 GREEN),仅登记不新建 |
✅ |
| SC-P-22 | 报告解析预览 | HealthReportController /api/health/report/parse-preview(type 参数)、/report/proxy-parse;DanAssessmentController /api/dan-assessment/report/parse-preview。复用 health.report.upload(已 GREEN),仅登记不新建 |
✅ |
| SC-P-23 | 报告确认入库 | HealthReportController /api/health/report/confirm、/report/discard、/report/audit/confirm、/report/audit/discard、/report/bind;DanAssessmentController /api/dan-assessment/report/confirm。复用 health.report.upload / health.report.createReport(已 GREEN),仅登记不新建 |
✅ |
| SC-P-28 | 食谱按食材筛选/忌口 | FoodRecommendController `/api/food/recommendation/index |
caution |
| SC-P-29 | 食谱收藏/调整 | 调整:MealRecommendController /api/meal/replace、DietRecommendationController `/api/diet/recommendation/update |
regenerate |
| SC-P-30 | 食谱与营养目标对齐 | FoodRecommendController `/api/food/recommendation/index |
caution;UserNutritionProfileController/api/nutrition/profile/get |
| SC-P-31 | 浏览测评类型(DAN 8 类) | DanAssessmentController `/api/dan-assessment/material/active |
list(测评材料=类型载体)、/points-config、/family/config`(家庭测评配置,material 绑定) |
| SC-P-49 | AI 健康管家对话 ⭐ | AIChatController /api/ai/chat/send、/health-coach/send、/health-coach/gate、/gate;AiGateway.chat() → cfc-langgraph /api/v1/chat(chat_graph)。已 GREEN 键 langgraph.questionnaire.generate 复用登记(仅登记不新建,见 §3) |
✅ |
| SC-P-50 | 成长记录查看 | GrowthRecordController /api/growth/record/list、/record/child/{memberId}、/record/child-records、/record/{id}、/record/{id}/supplements、/record/check-duplicate。复用 growth.history.view(已 GREEN),仅登记不新建 |
✅ |
| SC-P-51 | 成长里程碑 | GrowthController /api/growth 无里程碑端点;RelationshipQualityController /api/family/relationship/milestones(关系里程碑)、InviteMilestoneController `/api/invite/milestone/list |
claim`(邀请里程碑)均非成长里程碑 → 见缺口 G-2 |
| SC-P-54 | 加购/下单 | CartController `/api/cart/add |
list |
| SC-P-61 | 联系人添加 | ContactController `/api/contact/create |
list |
| SC-P-62 | 联系人分组/导入 | 导入:ContactController /api/contact/import-phone;分组无端点(ContactController/ContactMatchController 无 group 端点)→ 见缺口 G-3。命名回填:候选 ContactImportController 不存在,导入由 ContactController.import-phone 承载 |
⚠ |
| SC-P-63 | 联系人详情/权限 | ContactController `/api/contact/detail |
interaction |
| SC-P-64 | 个人资料编辑 | UserController `/api/user/update |
info |
| SC-P-65 | 消息通知/提醒设置 | UserNotificationController `/api/notification/list |
read;TaskReminderConfigController/api/task/reminder-config/get |
| SC-P-66 | 隐私设置 | ConsentController `/api/consent/record |
withdraw |
| SC-P-69 | 精准营养目标设定 | UserNutritionProfileController `/api/nutrition/profile/get |
save;HealthReportController/api/health/nutrition/profile |
| SC-P-70 | 舌诊/情绪照片采集 | HealthReportController /api/health/report/parse-preview(type=tongue → TongueDiagnosisService.parsePreview)、/report/confirm(type=tongue)、/report/discard、/report/collect/status+/collecting-list(采集进度);情绪:EmotionCheckinController `/api/mind/checkin/create |
list |
| SC-P-71 | 账号注销 | UserController /api/user/deactivate(AccountCleanupService.deactivateAccount,数据匿名化/数据主权)+ /data-export(个保法可携带权导出) |
✅ |
| SC-P-73 | 多孩子切换孩子上下文 | FamilyMembersController /api/family/member/switch(切成员视角);FamilyUserController `/switch-mode |
switch-to-child |
| SC-P-76 | 活动报名(名额/并发)⭐ | ActivityController /api/activity/register(单/批量:`registrationService.register |
batchRegister)、/cancel-registration |
| SC-P-78 | 消息中心/通知查看 | UserNotificationController `/api/notification/list |
read(未读优先,倒序);NoticeController/api/notices/list`(公告) |
| SC-P-79 | 推送/通知开关设置 | TaskReminderConfigController `/api/task/reminder-config/get |
save`(任务提醒开关/渠道/时机);站内通知无独立推送开关 → 观察项(见 §4) |
| SC-P-83 | 意见反馈/在线客服 | 反馈:HealthReportController `/api/health/feedback/submit |
list(报告反馈,ReportFeedbackService)、ActivityFeedbackController/api/activity/feedback/submit |
| SC-P-85 | 多端登录/会话互斥 | AuthController `/api/auth/phone-login |
wechat-login |
health.report.upload(P-20~23)、health.report.createReport(P-23)、growth.history.view(P-50)、langgraph.questionnaire.generate(P-49)——仅登记不新建(O-2 方案 A 防键重复)RelationshipController→RelationshipQualityController、ContactImportController→ContactController.import-phone、UserFoodPreferenceController→DietPreferencesController(diet 域)、FeedbackController→DailyFeedbackController+HealthReportController /feedback/*+ActivityFeedbackController开工包 18 个建议能力键,核验后定稿如下(已核对 docs/superpowers/api/API_REFERENCE.md 既有键避免冲突;4 个已 GREEN 键仅登记不新建):
| 建议能力键 | 绑定 SC | 覆盖端点(主载体) | 状态 |
|---|---|---|---|
family.member.list |
SC-P-04 | FamilyMembersController /api/family/member/list |
可映射 |
family.member.update |
SC-P-05 | FamilyMembersController /api/family/member/update、/editable |
可映射 |
family.invite.reissue |
SC-P-02 | FamilyInviteController /api/family/invite/generate(复用未过期令牌)+ member/add |
update 关系(FamilyRelationshipService) |
health.report.upload |
SC-P-20~23 | HealthReportController /report/upload-only、/upload、/parse、/parse-preview、/collect/status |
复用已 GREEN,仅登记不新建 |
health.report.createReport |
SC-P-23 | HealthReportController /report/confirm(确认入库) |
复用已 GREEN,仅登记不新建 |
food.recommend.filter |
SC-P-28 | FoodRecommendController /index、/caution;DietPreferencesController /save;DietIngredientController |
可映射 |
food.recommend.favorite |
SC-P-29 | (无收藏端点,G-1) | 暂缓(G-1 补齐后映射) |
food.recommend.align |
SC-P-30 | UserNutritionProfileController /save;DietRecommendationController /generate |
可映射 |
dan.assessment.typeList |
SC-P-31 | DanAssessmentController /material/list、/material/active、/points-config |
可映射(dan.assessment.* 既有键无 typeList,无冲突;如外部状态机已存在同名键则复用) |
ai.coach.chat |
SC-P-49 | AIChatController /health-coach/send、/chat/send;AiGateway.chat → LangGraph chat_graph |
复用 langgraph.questionnaire.generate(已 GREEN),仅登记不新建(O-2 防键重复,不新建 ai.coach.chat) |
growth.record.view |
SC-P-50 | GrowthRecordController /record/list、/record/child/*、/record/{id} |
复用 growth.history.view(已 GREEN),仅登记不新建 |
growth.milestone |
SC-P-51 | (无成长里程碑端点,G-2) | 暂缓(G-2 补齐后映射) |
contact.manage |
SC-P-61~63 | ContactController /create、/list、/detail、/import-phone、/interaction、/invite-to-family |
可映射(分组子能力 G-3 待补齐) |
user.profile.edit |
SC-P-64 | UserController /update、/info、/profile/backfill;FamilyUserController /update |
可映射 |
notice.manage |
SC-P-65/78/79 | UserNotificationController /list、/read;TaskReminderConfigController /get、/save;NoticeController /list |
可映射 |
privacy.setting |
SC-P-66 | ConsentController /record、/withdraw、/status;FamilyUserController /members/update-visibility |
可映射 |
nutrition.profile.set |
SC-P-69 | UserNutritionProfileController /save;HealthReportController /nutrition/profile |
可映射 |
report.photocollect |
SC-P-70 | HealthReportController /report/parse-preview(type=tongue)、/confirm、/collect/status;EmotionCheckinController /emotion/recognize |
可映射 |
account.cancel |
SC-P-71 | UserController /deactivate、/data-export(AccountCleanupService) |
可映射 |
family.child.switch |
SC-P-73 | FamilyMembersController /switch |
可映射 |
activity.register |
SC-P-76 | ActivityController /register;ActivityRegistrationService.occupyQuota(并发/名额) |
可映射 |
feedback.submit |
SC-P-83 | HealthReportController /feedback/submit;ActivityFeedbackController /submit;DailyFeedbackController /today |
可映射(在线客服 G-4 待确认) |
auth.session.exclusive |
SC-P-85 | (无互斥端点,G-5) | 暂缓(G-5 补齐后映射;现有 AuthController 登录族 + SSO 仅为部分载体) |
注 1:
food.recommend.favorite/growth.milestone/auth.session.exclusive三条键的完整契约证据需待缺口 G-1 / G-2 / G-5 补齐后回归补录(按 O-7 节奏,本契约仅登记缺口不落地实现)。 注 2:SC-P-54(加购/下单)载体已核验存在,能力键归属 EVD-4 商城-会员批次(order.*/product.*键域),本批不新建键(防重复);如 EVD-4 契约未含cart.add/order.create,由 EVD-4 契约补录,本批不重复登记。
按 O-7 裁决:契约核对为文档核对 + 端点比对(防假 RED),发现的端点缺失不落地实现,记入本节回传研发侧(研发负责人登记 TR-15 转测试侧补证据或建实现任务)。
| 编号 | 关联 SC | 缺口描述 | 影响 | 建议处置 |
|---|---|---|---|---|
| G-1 | SC-P-29 | 食谱「收藏」无端点:MealRecommendController(/api/meal)、DietRecommendationController(/api/diet/recommendation)、FoodRecommendController(/api/food/recommendation)、DietPreferencesController(/api/diet/preferences)均无 favorite/collect 端点;全库唯一收藏为 IndicatorFavoriteController /api/indicator/favorite/toggle(指标收藏,异构,非食谱)。「调整」已由 /api/meal/replace + `/api/diet/recommendation/update |
regenerate` 覆盖 | 食谱收藏语义缺失,用户无法收藏常吃食谱 |
| G-2 | SC-P-51 | 成长「里程碑」无独立端点:GrowthController /api/growth 仅 recommendations/articles-ai-classify/products-ai-classify;RelationshipQualityController /api/family/relationship/milestones(关系里程碑)、`InviteMilestoneController /api/invite/milestone/list |
claim`(邀请里程碑)均非成长记录里程碑;成长页「里程碑」(连续打卡/进行中挑战/档案完整度)为前端聚合计算 | 成长里程碑缺少后端可追溯记录,无法支撑成长激励闭环 |
| G-3 | SC-P-62 | 联系人「分组」无端点:ContactController /api/contact 仅 list/create/update/delete/detail/import-phone/interaction/invite-to-family,ContactMatchController /api/contact/match 仅 send/accept/reject/received/sent/matched;均无 group/分组端点(contact 表无分组字段承载) |
联系人分组/标签管理缺失,导入后无法归类 | 后端新增 POST /api/contact/group/*(分组 CRUD + contact 分组绑定)或 contact 表加 group 字段;需产品侧确认 |
| G-4 | SC-P-83 | 「在线客服」无专用端点:反馈已由 HealthReportController /feedback/submit、ActivityFeedbackController /submit、DailyFeedbackController /today 覆盖;全库无 kefu/客服端点(ServiceRoleApplicationController 为服务角色申请,非客服) |
意见反馈可提交,但在线客服(人工/工单)载体缺失 | 需产品侧确认「在线客服」验收方式(若接入客服系统走第三方/小程序客服能力,非本后端 REST 范畴) |
| G-5 | SC-P-85 | 「多端登录/会话互斥」无实现:AuthController /api/auth/* 登录族 + /sso-ticket//sso-login(SSO 跨系统一次性票据)存在,但无单端互斥——JWT 为无状态(JwtInterceptor 仅校验签名/过期),无会话注册表、无旧 token 吊销/踢出逻辑 |
多端同时登录无法互斥,账号共享风险 | 后端新增会话注册(Redis 存 user→token 唯一映射,新登录失效旧 token)+ POST /api/auth/logout;需产品侧确认是否需要(当前 SSO 票据已覆盖跨系统握手) |
另注观察项(非缺口):NoticeController 站内公告 /api/notices/list 用 GET+POST 双方法(违反统一 POST 规范,API_REFERENCE §3.6 已记录),不在本批改造范围;TaskReminderConfigController 已覆盖 SC-P-79「推送/通知开关」主语义(任务提醒开关/渠道/时机),站内通知无独立推送开关端点,建议后续如需站内推送开关并入 notice.manage 键。
产出后由研发负责人登记 TR-15,测试侧据此补契约 JUnit(MockMvc 风格沿用既有 ContractTest)+ 三类流执行证据(正常/异常/权限),重点场景:
POST /api/activity/register(单/批量)+ ActivityRegistrationService.occupyQuota:并发报名不超过 max_participants(原子 approved_count 自增),满员返回「名额已满」;重复报名/取消后名额释放;/api/auth/sso-ticket 一次性使用 + /sso-login 消费后失效(SsoService.consumeTicket),重复消费拒绝;单端互斥待 G-5 实现后补测;POST /api/user/deactivate 数据匿名化 + /data-export 导出可携带权数据;注销后登录/访问应受限(AccountCleanupService);/report/upload-only → 采集轮询 /collect/status → /report/parse-preview(type 识别)→ /report/confirm 入库;复用 health.report.upload/createReport 契约证据(不新建键,与既有契约对齐);/api/ai/health-coach/send → AiGateway.chat(LangGraph chat_graph)正常/异常/权限流;复用 langgraph.questionnaire.generate 键(仅登记,证据随既有契约);/api/family/member/add|update 关系写入(generationLevel/peerType → family_relationships)+ /switch 切孩子上下文权限(成员归属校验);/api/diet/recommendation/generate 按 UserNutritionProfileController /save 目标对齐;忌口(/api/food/recommendation/caution + /api/diet/preferences/save)过滤生效。