2026-11-07-parent-rest-contract.md 27 KB

家长域剩余批次 · 契约核对结论(P 域剩余 30 SC · 防假 RED)

归属:契约补建计划 P0「家长域剩余」· 核对时间 2026-11-07(EVD-13) 开工包:docs/tdd/orchestration/parent-rest-kickoff-20261107.md(origin/cfclub @ 3d7044429) 核对对象:origin/cfclub cfc-backend controller 源码(工作树 HEAD = origin/cfclub 3d7044429) 核对方法:类级 @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 防键重复)。

0. 结论摘要

  • 30 个 SC 中 27 个存在可用 HTTP 端点载体(其中 22 个端点齐全、5 个端点存在但存在子能力缺口或需观察项:SC-P-29 / SC-P-51 / SC-P-62 / SC-P-79 / SC-P-83)。
  • 3 个 SC 无完整 HTTP 端点载体:SC-P-29(食谱收藏无端点,调整有)、SC-P-51(成长里程碑无独立端点)、SC-P-85(多端登录会话互斥无实现,仅 SSO 跨系统票据)。按 O-7 标注「无完整端点载体,需产品侧确认验收方式」,本批不落地实现。
  • 端点核对范围内 无「假 RED」:开工包 10 个 ⚠ 待核实项(P-29 / P-49 / P-51 / P-62 / P-65 / P-66 / P-71 / P-73 / P-79 / P-85)逐一实测回填,其中 7 项确认端点存在(P-49 / P-65 / P-66 / P-71 / P-73 / P-79 / P-85 部分)、3 项存在子能力缺口(P-29 收藏 / P-51 里程碑 / P-85 互斥),详见 §4。
  • 已 GREEN 键复用登记 4 处: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)——仅登记不新建。
  • 无新增 DB 迁移、未改动业务代码与测试文件(本批次仅新增本核对文档 + API_REFERENCE 增补段落 + 端点核验表回填)。

1. 核对方法(开工包 ⚠ 待核实项回填)

开工包 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

2. 端点核验表(30 SC)

核验口径:✅ = 候选/回填端点真实存在于工作树;⚠ = 主场景有端点但存在子能力缺口(详见 §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

核对统计

  • 30/30 SC 均有至少 1 个主场景真实端点可用(防假 RED 通过:无 SC 主载体为凭空假设)
  • 其中 27 个 SC 主端点齐全/可回填(含 10 个开工包 ⚠ 待核实项中 7 项确认存在)
  • 3 个 SC 存在子能力/端点缺口(SC-P-29 收藏、SC-P-51 成长里程碑、SC-P-85 会话互斥,见 §4);SC-P-62 分组、SC-P-83 在线客服为子能力缺口
  • 已 GREEN 键复用登记 4 处:health.report.upload(P-20~23)、health.report.createReport(P-23)、growth.history.view(P-50)、langgraph.questionnaire.generate(P-49)——仅登记不新建(O-2 方案 A 防键重复)
  • 命名差异回填 4 处:RelationshipController→RelationshipQualityController、ContactImportController→ContactController.import-phone、UserFoodPreferenceController→DietPreferencesController(diet 域)、FeedbackController→DailyFeedbackController+HealthReportController /feedback/*+ActivityFeedbackController

3. 建议能力键映射(定稿,按 O-2 方案 A)

开工包 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 契约补录,本批不重复登记。


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 键。


5. 转测试侧建议(TR-15 契约证据重点)

产出后由研发负责人登记 TR-15,测试侧据此补契约 JUnit(MockMvc 风格沿用既有 ContractTest)+ 三类流执行证据(正常/异常/权限),重点场景:

  1. SC-P-76 活动报名并发/名额——POST /api/activity/register(单/批量)+ ActivityRegistrationService.occupyQuota:并发报名不超过 max_participants(原子 approved_count 自增),满员返回「名额已满」;重复报名/取消后名额释放;
  2. SC-P-85 会话互斥(观察项)——/api/auth/sso-ticket 一次性使用 + /sso-login 消费后失效(SsoService.consumeTicket),重复消费拒绝;单端互斥待 G-5 实现后补测;
  3. SC-P-71 账号注销数据主权——POST /api/user/deactivate 数据匿名化 + /data-export 导出可携带权数据;注销后登录/访问应受限(AccountCleanupService);
  4. SC-P-20~23 报告上传闭环——/report/upload-only → 采集轮询 /collect/status → /report/parse-preview(type 识别)→ /report/confirm 入库;复用 health.report.upload/createReport 契约证据(不新建键,与既有契约对齐);
  5. SC-P-49 AI 对话——/api/ai/health-coach/send → AiGateway.chat(LangGraph chat_graph)正常/异常/权限流;复用 langgraph.questionnaire.generate 键(仅登记,证据随既有契约);
  6. SC-P-02/73 家庭成员与上下文——/api/family/member/add|update 关系写入(generationLevel/peerType → family_relationships)+ /switch 切孩子上下文权限(成员归属校验);
  7. SC-P-76 / SC-P-28 / SC-P-30 饮食对齐——/api/diet/recommendation/generate 按 UserNutritionProfileController /save 目标对齐;忌口(/api/food/recommendation/caution + /api/diet/preferences/save)过滤生效。

6. 待办衔接

  1. 本文档 + API_REFERENCE「4.61 家长域剩余」段落 + 端点核验表回填已提交 origin/cfclub(单文件精确提交,EVD-13);
  2. 研发负责人登记 TR-15 → 测试侧补契约 JUnit + 三类流证据 → sc-key-map.md 逐 SC 登记「已跑通」;
  3. G-1 / G-2 / G-3 / G-4 / G-5 五条缺口的实现决策由研发侧按 O-7 节奏评估(契约核对不落地实现)。