|
|
@@ -0,0 +1,154 @@
|
|
|
+# 家长域剩余批次 · 契约核对结论（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|claim` 是**邀请**里程碑（均非成长）；成长页「里程碑」（连续打卡/进行中挑战/档案完整度）为前端聚合计算 → 见缺口 G-2 |
|
|
|
+| SC-P-62 联系人分组/导入 | 分组/导入端点 | **导入已存在**——`ContactController /api/contact/import-phone`（通讯录导入）；**分组无端点**（`ContactController`、`ContactMatchController` 均无 group/分组端点）→ 见缺口 G-3。**命名回填**：开工包候选 `ContactImportController` 类名不存在，导入由 `ContactController.import-phone` 承载 |
|
|
|
+| SC-P-65 消息通知/提醒设置 | 通知/提醒设置端点 | **已存在**——`UserNotificationController /api/notification/list|read`（站内消息）+ `TaskReminderConfigController /api/task/reminder-config/get|save`（提醒开关/渠道/时机/偏移，前端 `pages/reminder-config`） |
|
|
|
+| SC-P-66 隐私设置 | 隐私端点 | **已存在**——`ConsentController /api/consent/record|withdraw|status|check`（隐私授权同意）+ `FamilyUserController /api/family/user/members/visible|update-visibility`（成员资料对家庭可见性）；隐私政策为前端静态页 `pages/policy/privacy.vue`（无独立后端端点，前端静态，非缺口） |
|
|
|
+| SC-P-71 账号注销 | 注销端点 | **已存在**——`UserController /api/user/deactivate`（`AccountCleanupService.deactivateAccount`，数据匿名化/数据主权）+ `/data-export`（个保法数据可携带权导出） |
|
|
|
+| SC-P-73 多孩子切换孩子上下文 | 上下文切换端点 | **已存在**——`FamilyMembersController /api/family/member/switch`（切成员视角，`SwitchMemberVO`）；`FamilyUserController /switch-mode|switch-to-child|switch-back-to-parent` 为已废弃替代（API_REFERENCE §3.2），统一走 `/switch` |
|
|
|
+| SC-P-79 推送/通知开关设置 | 通知开关端点 | **主语义已存在**——`TaskReminderConfigController /api/task/reminder-config/get|save`（任务提醒开关）；站内通知（`/api/notification`）无独立「推送开关」端点 → 观察项（非缺口，提醒开关已覆盖开关语义，见 §4 观察项） |
|
|
|
+| 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|members|trend|by-family`（忌口 caution）；`DietPreferencesController` `/api/diet/preferences/current-member|save`（忌口参数）；`DietIngredientController` `/api/diet/ingredients/suggest|search|add|remove`（食材筛选） | ✅ |
|
|
|
+| SC-P-29 | 食谱收藏/调整 | 调整：`MealRecommendController` `/api/meal/replace`、`DietRecommendationController` `/api/diet/recommendation/update|regenerate|complete`；**收藏无端点** → 见缺口 G-1 | ⚠ |
|
|
|
+| SC-P-30 | 食谱与营养目标对齐 | `FoodRecommendController` `/api/food/recommendation/index|caution`；`UserNutritionProfileController` `/api/nutrition/profile/get|save`（营养目标）；`DietRecommendationController` `/api/diet/recommendation/generate`（按目标生成/对齐） | ✅ |
|
|
|
+| 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|update|remove|count|combo-offer|replace-combo`；`ProductOrderController` `/api/product/order/create|pay|cancel|my|my/counts|detail|handlePaymentSuccess`。EVD-4 商城-会员批次已覆部分（`order.pay`/`product.browse` 键域），本批仅登记载体，不新建键 | ✅ |
|
|
|
+| SC-P-61 | 联系人添加 | `ContactController` `/api/contact/create|list|detail`（创建即入家庭联系人） | ✅ |
|
|
|
+| 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|invite-to-family`；可见性权限：`FamilyUserController` `/api/family/user/members/visible|update-visibility`、`ReportMemberPermissionController` `/api/health/report/member-permission/list|grant|revoke|visible-members`（报告查看权限） | ✅ |
|
|
|
+| SC-P-64 | 个人资料编辑 | `UserController` `/api/user/update|info|profile/backfill|profile-stats`；`FamilyUserController` `/api/family/user/update`；`ProfileController` `/api/profile/my|history` | ✅ |
|
|
|
+| SC-P-65 | 消息通知/提醒设置 | `UserNotificationController` `/api/notification/list|read`；`TaskReminderConfigController` `/api/task/reminder-config/get|save`（提醒开关/渠道/时机/偏移） | ✅ |
|
|
|
+| SC-P-66 | 隐私设置 | `ConsentController` `/api/consent/record|withdraw|status|check`（隐私授权同意）；`FamilyUserController` `/api/family/user/members/visible|update-visibility`（成员可见性）；隐私政策前端静态页 | ✅ |
|
|
|
+| SC-P-69 | 精准营养目标设定 | `UserNutritionProfileController` `/api/nutrition/profile/get|save`；`HealthReportController` `/api/health/nutrition/profile|deficiency|deficiency-summary|trend|mappings`；`NutritionProductController` `/api/nutrition/product/*`、`BeijingNutritionController` `/api/nutrition/beijing` | ✅ |
|
|
|
+| 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|latest|trend|stats|emotion/recognize` + `EmotionRecognitionController` / `EmotionAlertController` | ✅ |
|
|
|
+| 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|switch-back-to-parent`（已废弃，API_REFERENCE §3.2，统一走 `/switch`）+ `/children|children/list` | ✅ |
|
|
|
+| SC-P-76 | 活动报名（名额/并发）⭐ | `ActivityController` `/api/activity/register`（单/批量：`registrationService.register|batchRegister`）、`/cancel-registration|my-registrations|registration-roster|checkin`；`ActivityRegistrationService.occupyQuota`（**原子占用名额**：`approved_count < max_participants` 自增，并发安全）+ `releaseQuota`；`ActivityOrderController` `/api/activity/order/create|pay|status`（付费活动） | ✅ |
|
|
|
+| 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|list|my`、`DailyFeedbackController` `/api/feedback/today|read|recent`；**在线客服无专用端点** → 见缺口 G-4 | ⚠ |
|
|
|
+| SC-P-85 | 多端登录/会话互斥 | `AuthController` `/api/auth/phone-login|wechat-login|silent-login|auto-login|sso-login` + `/sso-ticket`（SSO 一次性票据，`SsoService`，跨系统握手）；**无单端互斥/旧会话踢出** → 见缺口 G-5 | ⚠ |
|
|
|
+
|
|
|
+### 核对统计
|
|
|
+
|
|
|
+- **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` 覆盖 | 食谱收藏语义缺失，用户无法收藏常吃食谱 | 后端新增 `POST /api/food/recommendation/favorite/toggle`（或复用 diet 域），建议对齐指标收藏实现；本契约仅登记 |
|
|
|
+| 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`（邀请里程碑）均非成长记录里程碑；成长页「里程碑」（连续打卡/进行中挑战/档案完整度）为前端聚合计算 | 成长里程碑缺少后端可追溯记录，无法支撑成长激励闭环 | 后端新增成长里程碑端点（如 `POST /api/growth/milestone/list`，聚合打卡/挑战/档案完整度），或明确里程碑=前端聚合即可接受；需产品侧确认验收方式 |
|
|
|
+| 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 节奏评估（契约核对不落地实现）。
|
Agnes Agent