归属:契约补建计划 P0「成长规划师域」· 契约核对产出 2026-11-07 前置:O-7 契约补建工作流(主理人 2026-11-06 23:59 最终确认)——契约核对 = 文档核对 + 端点比对(防假 RED),产出契约文档后转测试侧(TR-13)补契约 JUnit + 三类流执行证据,渐进而非全量。 开工包:
docs/tdd/orchestration/planner-zone-kickoff-20261107.md核对基线:origin/cfclub@22cd721c3(工作树,cfc-backend controller 源码) 角色模型:成长规划师(role=teacher)双角色——可登录规划师端,也可切换回家长视角(/api/auth/switch-role)。
按开工包 32 个 SC(SC-T-01~32)逐条比对候选端点载体与 cfc-backend/src/main/java/com/etotem/cfc/controller/ 实际 Controller 映射(@RequestMapping + @PostMapping,另有少量 @RequestParam 型端点)。重点回填开工包 ⚠ 待核实三项:
| ⚠ 项 | 场景 | 实测结论 |
|---|---|---|
| SC-T-25 舌诊/情绪测评录入 | 舌诊录入端点 | 已存在——HealthReportController 舌诊链:POST /api/health/report/parse-preview(type=tongue → TongueDiagnosisService.parsePreview)、POST /api/health/report/confirm(type=tongue)、POST /api/health/report/discard(type=tongue);情绪测评 = EmotionCheckinController /api/mind/checkin/*(create/list/latest/trend/stats/weekly-report/emotion/recognize) |
| SC-T-27 家庭天盘解读 | 天盘聚合端点 | 已存在——TianpanController /api/tianpan/*(dashboard / member/{memberId} / compatibility / annual-energy / daily-fortune / related-items / recalibrate);另有 TraditionalMirrorController /api/mind/traditional/*(mirror / family-dashboard / compatibility)、MindFortuneController /api/mind/fortune/export(天盘周报 PDF 导出)、AdminFamilyOverviewController /api/admin/families/{id}/overview(管理端)。开工包候选 FamilyOverviewController 类名不存在,实际以 TianpanController 为家庭天盘主载体 |
| SC-T-29 客户档案数据导出 | 导出端点 | 主载体已存在——UserController POST /api/user/data-export(个保法数据可携带权导出,AccountCleanupService.exportUserData);管理端组织成员 AdminOrgMemberController /api/admin/org/member/*(list/add/remove/change-type)无 export 端点(见 §4 缺口 G-3) |
其余 29 个 SC 候选端点均已锚定到现有 Controller(含开工包候选类名与实际类名的命名差异,见 §2 表"载体回填"列)。
核验口径:✅ = 候选/回填端点真实存在于工作树;⚠ = 主场景有端点但存在子能力缺口(详见 §4 实现缺口清单)。
| SC | 场景标题 | 端点载体(实测回填,origin/cfclub 工作树) | 核验 |
|---|---|---|---|
| SC-T-01 | 规划师登录 + 切回家长 | AuthController /api/auth/*:phone-login / wechat-login / silent-login / auto-login / switch-role(切回家长,开工包已标 DONE) |
✅ |
| SC-T-02 | 绑定测试家庭 | GuideFamilyQueryController /api/guide/families/my-families(按 guideId 查绑定家庭);BindInviteController /api/guide/bind(规划师绑定邀请);TeacherFamilyBindingController /api/family/teacher-bindings/*(pending/approve/reject/my-requests/cancel);GuideFamilyListController /api/guide/family/list。命名回填:开工包候选 GuideFamilyController 不存在,由上述四类承担 |
✅ |
| SC-T-03 | 代传报告 + 确认入库 ⭐ | HealthReportController /api/health/report/*:proxy-parse(规划师代传解析,L2775)、proxy-confirm(L2945)、parse / confirm / discard / bind / reassign / transfer/* |
✅ |
| SC-T-04 | 方案审核列表 + 批准 | GuidePlanReviewController /api/guide/families/{familyId}/plans/*:pending / {planId}/approve / {planId}/reject / {planId}/update(IDOR 反查 + isBound);PlanReviewController /api/guide/plans/*:family-list / review / detail;ReviewCenterController /api/admin/review-center/summary(工作台摘要)。命名回填:开工包候选 AdminReviewCenterController 不存在,实际为 ReviewCenterController |
✅ |
| SC-T-05 | 激活方案拆任务(幂等)⭐ | PlanReviewController POST /api/guide/plans/activate → PlanActivationService.activate(planId, userId);前置 PlannerCertificationGuard.assertCertified(基础类别认证闸门)+ IllegalStateException 状态守卫(幂等) |
✅ |
| SC-T-06 | 家庭任务审核 | GuideFamilyTaskController /api/guide/families/{familyId}/*:tasks/{taskId}/review、tasks/batch-review、children/{memberId}/pending-review、tasks/{taskId}(更新)、tasks/{taskId}/delete |
✅ |
| SC-T-07 | 录入测评结果触发方案 ⭐ | DanAssessmentController /api/dan-assessment/*:result/record、record/create、record/complete、report/parse-preview、report/confirm、report/child(录入后触发方案生成链) |
✅ |
| SC-T-08 | 成长计划 / 套餐创建 | TrainingPlanController /api/guide/training-plans/*:create / update / list / detail / delete;GrowthPlanController /api/growth/plan/create。命名回填:开工包候选 GuideTrainingPlanController 不存在,实际为 TrainingPlanController |
✅ |
| SC-T-09 | 测评预约确认(状态守卫) | AssessmentAppointmentController /api/assessment/appointment/*:create / confirm/{id} / cancel/{id} / my-list / guide-list / assessor-list;DanAssessmentController /appointment/confirm(按 teacherId 确认,状态 0→1) |
✅ |
| SC-T-10 | 测评预约完成/未到 | 完成:DanAssessmentController /appointment/complete(状态→2);取消:/appointment/cancel(状态→3)。状态机含"未到(status=4)"(AssessmentAppointmentController.getStatusText case 4)但无独立设置端点 → 见缺口 G-1 |
⚠ |
| SC-T-11 | DAN 报告上传与解析 | DanReportController /api/dan-report/*:upload / {id}/edit / {id}/confirm / {id}/discard / {id}/complete-analysis / list / compare;DanAssessmentController /report/parse-preview / /report/confirm |
✅ |
| SC-T-12 | DAN 八类报告查看 | AssessmentReportController /api/dan-assessment/result/*:plans/list / upload / {resultId}/guidance / {resultId}/guidance/save / {resultId}/confirm-inbox;DanAssessmentController /result/{id} / my-results / child-results / results/{id}/structured |
✅ |
| SC-T-13 | 规划师视角数据隔离 | 授权源 guide_families.status='binding'(GuideFamilyService.isBound):GuideFamilyQueryController /my-families、GuideFamilyTaskController /bound-families + /{familyId}/*(isBound 校验)、PlanReviewController family-list(teacher 按 JWT familyId 过滤)+ JwtInterceptor 角色隔离(teacher 不能访问他人绑定家庭) |
✅ |
| SC-T-14 | 方案编辑(规划师侧) | GrowthPlanController /api/growth/plan/update(含 status/标题/内容/周期,teacher 可改);HealthPlanController /api/health/plan/save / generate / regenerate-section |
✅ |
| SC-T-15 | 套餐任务项管理 | TrainingPlanController /api/guide/training-plans/items/*:add / update / delete(任务项 CRUD) |
✅ |
| SC-T-16 | 客户健康总览 | GuideFamilyTaskController /api/guide/families/{familyId}/overview + /dashboard-stats;GuideFamilyQueryController /my-families |
✅ |
| SC-T-17 | 成长计划进度跟踪 | GuideFamilyTaskController /api/guide/families/{familyId}/children/{memberId}/tasks(成员任务列表);GrowthPlanController /child/{memberId}/active / /{id}(活跃方案/详情);GrowthRecordController /api/growth/record/* |
✅ |
| SC-T-18 | 批量任务下发 | TrainingPlanController POST /api/guide/training-plans/deploy(套餐部署/任务下发);PlanReviewController /activate(激活拆任务下发);GuideFamilyTaskController tasks/batch-review(批量审核) |
✅ |
| SC-T-19 | 消息推送客户 | TeacherMessageController /api/guide/messages/*:send / {messageId}/reply / list / unread-count / my(命名回填:开工包候选 GuideMessageController 不存在,实际为 TeacherMessageController,API_REFERENCE 4.47.1 已登记);UserNotificationController /api/notification/* |
✅ |
| SC-T-20 | 退出/切换账号 | AuthController /api/auth/switch-role(登录后切换家长视角);退出为前端清理 JWT(无服务端 logout 端点,无状态 JWT 设计,前端删除 token 即退出)。观察项:无 POST /api/auth/logout |
✅ |
| SC-T-21 | 报告对比分析 | AssessmentComparisonController /api/assessment/compare/*:by-child / by-child-dimension / by-family / narrative(命名回填:开工包候选 AssessmentCompareController 不存在,实际为 AssessmentComparisonController);DanReportController /api/dan-report/compare |
✅ |
| SC-T-22 | 方案归档 | 成长方案 GrowthPlanController、健康方案 HealthPlanController 均无 archive 专用端点;仅报告归档 HealthReportController /report/archive + /report/archive-batch(参考实现)→ 见缺口 G-2 |
⚠ |
| SC-T-23 | 报告代传(规划师代客户传)⭐ | HealthReportController /api/health/report/proxy-parse(L2775)、/proxy-confirm(L2945);报告归属转移 /transfer/request / /transfer/approve / /transfer/deny / /transfer/list、/reassign |
✅ |
| SC-T-24 | 解绑/重分配客户家庭 | GuideFamilyTaskController POST /api/guide/families/unbind(按 guide_families.id 解绑,置 status=cancelled,API_REFERENCE 4.45 已登记);TeacherFamilyBindingController(绑定审批流);BindInviteController /api/guide/bind |
✅ |
| SC-T-25 | 舌诊/情绪测评录入(规划师)⚠ | 舌诊:HealthReportController /api/health/report/parse-preview(type=tongue → TongueDiagnosisService)、/report/confirm(type=tongue)、/report/discard(type=tongue);情绪:EmotionCheckinController /api/mind/checkin/*(create/list/latest/trend/stats/weekly-report/emotion/recognize) |
✅ |
| SC-T-26 | 精准营养方案制定 | DietRecommendationController /api/diet/recommendation/*:today / generate / update / regenerate / complete;HealthReportController /api/health/nutrition/*(deficiency/profile/deficiency-summary/trend/mappings);NutritionProductController /api/nutrition/product/*、UserNutritionProfileController /api/nutrition/profile、BeijingNutritionController /api/nutrition/beijing。命名回填:开工包候选 NutritionController 不存在(nutrition 域为三个专项 Controller) |
✅ |
| SC-T-27 | 家庭天盘解读(规划师)⚠ | TianpanController /api/tianpan/*:dashboard / member/{memberId} / compatibility / annual-energy / daily-fortune / related-items / recalibrate;TraditionalMirrorController /api/mind/traditional/*;MindFortuneController /api/mind/fortune/export(天盘周报 PDF);AdminFamilyOverviewController /api/admin/families/{id}/overview |
✅ |
| SC-T-28 | AI 方案内容安全复核 | PlanReviewController /api/guide/plans/review(批准/驳回 + 审核记录);GuidePlanReviewController {planId}/approve / reject(AI 方案送审链);ReviewCenterController /api/admin/review-center/summary;内容安全检测 ContentFilterController /api/content/*、wechatService.checkImage |
✅ |
| SC-T-29 | 客户档案数据导出(合规)⚠ | 主载体:UserController POST /api/user/data-export(个保法数据可携带权,AccountCleanupService.exportUserData);管理端组织成员 AdminOrgMemberController /api/admin/org/member/* 无 export 端点 → 见缺口 G-3 |
⚠ |
| SC-T-30 | 测评录入触发五维维度变化 | DanAssessmentController /result/record(测评结果录入);EnergyController /api/energy/*:overview / logs / grant / score-history / family-score-history / configure(五维能量归因/变更) |
✅ |
| SC-T-31 | 手动维度打分覆盖/调整 | ManualDimensionScoreController /api/family/manual-score/*:submit / latest / history |
✅ |
| SC-T-32 | 五维自评录入与变化 | FiveDimensionSelfCheckController /api/family/self-check/*:questions / submit / latest / history / status / ignore / generate-plan / trend-analysis / ai-generate-questions(五维自评 → 变化落 EnergyController);EnergyController /api/energy/* |
✅ |
GuideFamilyController→GuideFamilyQueryController/BindInviteController、GuideTrainingPlanController→TrainingPlanController、GuideMessageController→TeacherMessageController、AdminReviewCenterController→ReviewCenterController、PlanActivationController→PlanActivationService(经 PlanReviewController.activate)、AssessmentCompareController→AssessmentComparisonController、FamilyOverviewController→TianpanController、NutritionController→nutrition 域三 Controller开工包 16 个建议能力键,核验后定稿如下(已核对 API_REFERENCE 既有键避免冲突:guide.* / family.parent.* / energy.* / dimension.* 未占用 teacher.* 空间;family.parent.switchRole 已 DONE 与 teacher.login.switch 职责不同,前者是家长切孩子视角,本键是规划师切家长视角,无冲突):
| 建议能力键 | 绑定 SC | 覆盖端点(主载体) | 状态 |
|---|---|---|---|
teacher.login.switch |
SC-T-01 / T-20 | AuthController /api/auth/*(switch-role) |
可映射 |
teacher.family.bind |
SC-T-02 / T-24 | GuideFamilyQueryController /my-families、BindInviteController /api/guide/bind、TeacherFamilyBindingController、GuideFamilyTaskController /unbind | 可映射 |
teacher.report.proxy |
SC-T-03 / T-23 | HealthReportController /report/proxy-parse、/proxy-confirm、/transfer/*、/reassign | 可映射 |
teacher.plan.review |
SC-T-04 / T-28 | PlanReviewController /review、GuidePlanReviewController approve/reject、ReviewCenterController /summary | 可映射 |
teacher.plan.activate |
SC-T-05 | PlanReviewController /activate(PlanActivationService + 认证闸门) | 可映射 |
teacher.task.review |
SC-T-06 / T-18 | GuideFamilyTaskController /tasks/{taskId}/review、/tasks/batch-review;TrainingPlanController /deploy | 可映射 |
teacher.assessment.record |
SC-T-07 / T-11 / T-12 | DanAssessmentController /result/record、DanReportController /upload、AssessmentReportController /plans/list | 可映射 |
teacher.plan.create |
SC-T-08 / T-14 | TrainingPlanController /create、GrowthPlanController /create、/update、HealthPlanController /save | 可映射(T-22 归档待 G-2 补齐后并入) |
teacher.appointment.guard |
SC-T-09 / T-10 | AssessmentAppointmentController /confirm/{id}、DanAssessmentController /appointment/confirm、/complete、/cancel | 可映射(T-10 未到待 G-1) |
teacher.data.isolation |
SC-T-13 | guide_families isBound + JwtInterceptor 角色隔离 | 可映射 |
teacher.family.overview |
SC-T-16 / T-17 / T-21 / T-27 | GuideFamilyTaskController /{familyId}/overview、GrowthPlanController /child/{memberId}/active、AssessmentComparisonController、TianpanController /api/tianpan/* | 可映射 |
teacher.message.push |
SC-T-19 | TeacherMessageController /send、/reply、/list;UserNotificationController | 可映射 |
teacher.mind.record |
SC-T-25 | EmotionCheckinController /api/mind/checkin/*、HealthReportController tongue 链 | 可映射 |
teacher.nutrition.plan |
SC-T-26 | DietRecommendationController /generate、HealthReportController /nutrition/* | 可映射 |
teacher.export |
SC-T-29 | UserController /data-export(个保法可携带权) | 可映射(org 导出待 G-3) |
teacher.dimension.score |
SC-T-30 / T-31 / T-32 | ManualDimensionScoreController /submit、FiveDimensionSelfCheckController /submit、EnergyController /grant | 可映射 |
注:
teacher.plan.create(T-22 方案归档)与teacher.appointment.guard(T-10 未到)两条键的完整契约证据需待缺口补齐后回归补录;映射入池方式按 O-2 方案 A 与现有拉力表对齐。
按 O-7 裁决:契约核对为文档核对 + 端点比对(防假 RED),发现的端点缺失不落地实现,记入本节回传研发侧(研发负责人登记 TR-13 转测试侧补证据或建实现任务)。
| 编号 | 关联 SC | 缺口描述 | 影响 | 建议处置 |
|---|---|---|---|---|
| G-1 | SC-T-10 | 预约"未到(no-show)"无独立设置端点:AssessmentAppointmentController.getStatusText 定义 status=4(未到),但 Controller 层仅提供 create/confirm/cancel/complete/my-list/guide-list/assessor-list,未看到将预约置为 status=4 的端点;DanAssessmentController /appointment/complete 固定置为完成(2),未发现可传参置"未到" |
规划师完成/未到闭环缺少"未到"分支 | 后端新增 POST /api/assessment/appointment/no-show/{id}(或 complete 支持 status 参数);此处置走研发实现任务,本契约仅登记 |
| G-2 | SC-T-22 | 成长方案/健康方案归档无专用端点:GrowthPlanController(/api/growth/plan:create/update/{id}/review/list/active)与 HealthPlanController(/api/health/plan:generate/save/confirm/delete/pending-review/*)均无 archive;现有 HealthReportController /report/archive + /report/archive-batch 是健康报告归档(非方案) |
规划师无法将过期/结案方案归档,方案列表无归档语义 | 后端新增 POST /api/growth/plan/archive(或复用 update status=archived 的语义固化);建议对齐报告归档实现(archiveReport) |
| G-3 | SC-T-29 | 管理端/规划师侧客户档案导出缺失:AdminOrgMemberController /api/admin/org/member/* 仅 list/add/remove/change-type,无 export;现有 UserController POST /api/user/data-export 是登录用户本人的个保法数据可携带权导出(AccountCleanupService),不覆盖"规划师导出其名下客户档案"的管理员场景 |
客户档案导出(合规)仅覆盖本人视角,缺机构视角批量导出 | 后端新增 POST /api/admin/org/member/export(可复用 accountCleanupService 或导出 CSV;注意 children 表生产缺 phone/id_card 两列的历史约束——见根 AGENTS.md「children 表标注冲突」,导出全字段 SELECT 需按现状处理) |
另注观察项(非缺口):AuthController 无服务端 logout 端点(SC-T-20),当前为 JWT 无状态设计、前端删除 token 即退出;如产品需要服务端会话失效(黑名单/吊销),另行评估,本契约不视为缺失。
产出后由研发负责人登记 TR-13,测试侧据此补契约 JUnit(MockMvc 风格沿用既有 ContractTest)+ 三类流执行证据(正常/异常/权限),重点场景:
{familyId} 端点应 403/拒绝(guide_families.status='binding' isBound 校验 + JwtInterceptor 角色);POST /api/guide/plans/activate 重复激活(已激活/状态非 generated)应被 PlanActivationService 状态守卫拒绝,不重复拆任务;status=0(待确认)可流转,重复 confirm 拒绝;complete/cancel 状态机边界;/report/proxy-parse + /report/proxy-confirm 代传代确认后报告归属 family_id/member_id 正确落库,无跨家庭越权;/report/parse-preview(type=tongue)→ /report/confirm(type=tongue)入库,非 tongue 类型不落入舌诊链;/api/tianpan/dashboard 家庭维度聚合 + member/{memberId} 权限隔离(viewerRole)。