Parcourir la source

docs(B-1): 测评-方案开工包 56 端点契约核对与补全(API_REFERENCE 4.58.B1 + PROJECT-OVERVIEW 同步)

- 数据源: docs/tdd/orchestration/dan-plan-kickoff-20261106.md(43 SC / 56 端点)
- 核对: 已覆盖 14 / 部分覆盖 2 / 完全缺失 40,补全 40 个缺失端点契约
- 补写: API_REFERENCE.md 4.58.B1(预约状态机/订单状态机/HealthPlan 状态机 + 鉴权/请求体/响应,DAN测评/方案/编排/规划师/会员/孩子执行 12 组)
- 登记 10 项遗留: /api/package/order/create 恒 410、payment/order/status 仅 PackageOrder 域、预约 cancel 无越权校验、迁移382 后无额度扣减、flow/plan 语义待用例定义、跨域/跨仓键拆分等
- 仅补接口文档,零 src/main 业务代码改动;mvn compile EXIT=0
Sisyphus il y a 1 semaine
Parent
commit
19384a2070
2 fichiers modifiés avec 246 ajouts et 0 suppressions
  1. 0 0
      docs/superpowers/PROJECT-OVERVIEW.md
  2. 246 0
      docs/superpowers/api/API_REFERENCE.md

Fichier diff supprimé car celui-ci est trop grand
+ 0 - 0
docs/superpowers/PROJECT-OVERVIEW.md


+ 246 - 0
docs/superpowers/api/API_REFERENCE.md

@@ -2537,3 +2537,249 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 - `cfc-frontend/utils/api.js`:`getVendorInviteCode` / `getVendorInviteInfo` / `joinVendorTeamByInvite`(各 URL 唯一规范入口)。
 
 *文档更新:2026-11-02(T38 团队邀请功能:supply_system_member 扩 invite_code + 邀请码生成/信息/凭码加入 3 接口 + 前端邀请入口与受邀确认页)*
+
+---
+
+### 4.58.B1 B-1「测评-方案」批次 · 契约核对与补全(2026-11-06 开工包)
+
+> 数据源:`docs/tdd/orchestration/dan-plan-kickoff-20261106.md`(43 SC / 56 个契约端点,开工包「契约接口范围」列 1:1 提取)。核对口径:全 CFC 统一 `@PostMapping`(本批次全部端点均为 POST);鉴权标识(`userId` / `familyId` / `currentMemberId` / `role`)由 `JwtInterceptor` 从 JWT 注入 `@RequestAttribute`;请求体统一 `Map<String, Object>` 或具名 DTO;响应统一 `Result<T>`(`code/message/data`)。
+>
+> 核对结论:**已覆盖 14 / 部分覆盖 2 / 完全缺失 40 = 56**。已覆盖端点(§4.47 规划师工作台、§4.46 方案审核、§4.7 健康打卡、§4.15 通知)不再重复登记;本节登记全部缺失与需补全明细。
+
+#### 4.58.B1.1 A 组 · DAN 测评(`DanAssessmentController`,前缀 `/api/dan-assessment`)
+
+**积分配置 / 家庭启用**
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/dan-assessment/points-config` | 登录 | `{}` | `Result<AssessmentPointsConfig>` — 单行激活配置:`pointsValue`(P点)、`pointsValueYuan`(元),P点↔元换算读端点 |
+| `POST /api/dan-assessment/family/enable` | 登录,需 `familyId`(无则 `Result.noFamily`) | `{ materialId?, remindMonths?(默认6), createdBy? }` | `Result<String>`「启用成功/启用失败」— upsert `family_assessment_config`,`isEnabled=1` + 计算 `nextRemindAt` |
+
+> ⚠ **SC-P-35「获得测评额度」契约注记**:`points-config` 仅是 P点 ↔ 元换算配置读取,与「测评额度」无直接关系。2026-10-23 起(迁移 382)「BASIC 会员测评配额硬门禁」已移除(`AssessmentAppointmentService.createAppointment()` 注释原文),**预约创建不再消耗/校验任何额度**。能力键定义须按此口径,勿再按『额度扣减』编写。
+
+**预约(`/api/dan-assessment/appointment/*`)**
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/dan-assessment/appointment/create` | 登录 + `currentMemberId` | `{ memberId?, guideId?, packageId?, appointmentDate, appointmentTime, notes? }` | `Result<AssessmentAppointment>` — 默认 `status=0 待确认`;副作用:给 `memberId` 发放 10 能量(`appointment` 类型) |
+| `POST /api/dan-assessment/appointment/user` | 登录 | `{ userId }`(为空返「userId 不能为空」) | `Result<List<Map>>` — 字段:`id/userId/familyId/memberId/guideId/packageId/appointmentDate/appointmentTime/durationMinutes/status/appointmentType/notes/contactPhone/meetLink/createdAt/guideName`(`guideName` 按 `guideId` 回填 users.nickname) |
+| `POST /api/dan-assessment/appointment/cancel` | 登录 | `{ id }` | `Result<String>`「取消成功/取消失败」 — 直接置 `status=3 已取消` |
+| `POST /api/dan-assessment/appointment/confirm` | 登录 + 指派校验 | `{ id, teacherId }` | `Result<String>` — 仅当 `userId == (assessorId ?? guideId)` 才置 `status=1 已确认`,否则 `false→确认失败` |
+| `POST /api/dan-assessment/appointment/complete` | 登录 + 归属校验 | `{ id, teacherId }` | `Result<String>` — 仅 `teacherId == guideId` 才置 `status=2 已完成`;成功副作用:发 30 能量 |
+
+**预约状态机(`assessment_appointments.status`)**
+
+| 值 | 状态 | 写入点 |
+|---|---|---|
+| 0 | 待确认(pending) | `appointment/create` 默认;`AssessmentAppointmentService.confirmAppointmentByOrder` 随测评订单同样创建 `status=0` |
+| 1 | 已确认(confirmed) | `appointment/confirm`(须 `assessorId`/`guideId` 匹配) |
+| 2 | 已完成(completed) | `appointment/complete`(须 `guideId` 匹配,+30 能量) |
+| 3 | 已取消(cancelled) | `appointment/cancel` |
+| 4 | 未到(no-show) | 实体注释预留值,**当前无任何端点写入** |
+
+> ⚠ **SC-P-38「取消预约越权校验」缺口**:`cancelAppointment(id)` 服务无归属校验,传入 `id` 即可取消;控制器亦未注入 `familyId`/`guideId` 反查。若按 SC 语义「越权校验」实现,属**后续实现任务**,本契约仅登记现状。
+> ⚠ **SC-T-09/T-10 状态守卫**:confirm/complete 的身份匹配校验(`assessorId/g guideId`)即为现状守卫。注意 confirm 传参键名为 `teacherId`,实际比对 `assessorId ?? guideId`。
+
+**测评订单(`/api/dan-assessment/order/*`)**
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/dan-assessment/order/create` | 登录,需 `familyId` | `{ memberId?, guideId?, packageId?, guideName?, packageName?, totalPrice?(默认0), discountAmount?(默认0) }` | `Result<AssessmentOrder>` — `status=pending`,`orderNo` 服务端生成 |
+| `POST /api/dan-assessment/order/pay` | 登录 | `{ orderNo, payType, appointmentId? }` | `Result<VirtualPayParamsDTO>`(虚拟支付参数,`sessionKey` 服务端从登录态取);`testMode=true` 时直接置 `paid` 返回 `data=null`;会话失效 400;不可购 46001 |
+| `POST /api/dan-assessment/order/cancel` | 登录,需 `familyId` | `{ orderNo }` | `Result<String>`「取消成功/取消失败」 |
+| `POST /api/dan-assessment/order/detail` | 登录 | `?orderNo=`(`@RequestParam`) | `Result<AssessmentOrder>` |
+| `POST /api/dan-assessment/order/family` | 登录 | `?familyId=`(`@RequestParam`) | `Result<List<AssessmentOrder>>` |
+
+**`AssessmentOrder.status` 状态机**:`pending → paid / cancelled / refunded`(String)。
+
+> ⚠ **SC-P-33 契约注记(重要)**:`PackagePurchaseController` 的 `POST /api/package/order/create` 已 `@Deprecated` 且恒返 **`410 Gone`**(`"该接口已废弃,套餐购买请走组合商品下单"`),**不可作为「购买测评套餐/下单」的真实端点**。SC-P-33 的能力键应指向 `DanAssessmentController.order/create`(本节),而非 `/api/package/order/create`。
+
+**测评录入(`/api/dan-assessment/record/*`)**
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/dan-assessment/record/create` | 登录,需 `familyId`;`currentMemberId` 注入 | `{ memberId?(缺省取 currentMemberId), materialId? }` | `Result<AssessmentRecord>` — `status=pending` |
+| `POST /api/dan-assessment/record/complete` | 登录 | `{ recordId }` | `Result<String>`「完成成功/记录不存在」— 置 `status=completed` + `completedAt` |
+
+> ⚠ **SC-T-07「录入测评结果触发方案」注记**:`completeRecord` 仅置状态,**不触发任何方案生成副作用**。「录入→触发方案」需规划师侧另走 `recordResult`/LangGraph 管线,能力键定义时不得假设 `record/complete` 自动出方案。
+
+#### 4.58.B1.2 A 组 · 套餐价与支付(`PackagePurchaseController` + `PaymentController`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/package/price` | 登录 | `?packageId=&guideId?=&inviteCode?=`(`@RequestParam`) | `Result<Map>`(价格信息;模板不存在返「任务模板不存在」)|
+| `POST /api/package/available-guides` | 登录 | `?packageId=`(`@RequestParam`) | `Result<List<Map>>`(可售指导师列表) |
+| `POST /api/package/order/create` | — | `PackagePurchaseDTO` | **恒 `Result.error(410, ...)`**(已废弃,见上注记) |
+| `POST /api/payment/wechat/create` | 登录 | `{ orderNo, description, amount, openid }` | `Result<Map>`(微信 JSAPI 预支付参数,需 openid) |
+| `POST /api/payment/wechat/status` | 登录 | `{ orderNo }` | `Result<Boolean>` — `package_orders.status == "paid"` |
+| `POST /api/payment/order/status/{orderNo}` | 登录(路径变量) | — | `Result<PackageOrder>`;订单不存在返「订单不存在」 |
+
+> ⚠ **SC-P-34 契约注记**:`/api/payment/order/status/{orderNo}` 与 `/api/payment/wechat/status` 均基于 **`package_orders`(PackageOrder 实体,任务模板购买域)**,**不适用于 `assessment_orders`(DAN 测评订单)**。测评订单支付参数走 `dan-assessment/order/pay`,状态查询走 `dan-assessment/order/detail?orderNo=`。能力键 `dan.assessment.orderPay` 的测试用例必须使用正确的域端点。
+
+#### 4.58.B1.3 B 组 · 健康方案家长侧(`HealthPlanController`,前缀 `/api/health/plan`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/health/plan/generate` | 登录 + `familyId`;**付费墙**:`getMemberLevel(userId) != FREE` 或 `purchaseService.checkPurchase` 有效任一 | `{ memberIds?, dimensions, goal }`(dimensions/goal 为空报错) | `Result<Object>` — LangGraph 生成(`langgraphBaseUrl` 空 → `buildSamplePlan` fallback);未达付费墙返 `4001 请升级为家庭会员或购买健康启航计划` |
+| `POST /api/health/plan/regenerate-section` | 登录 + `familyId` | `{ section, feedback?, planJson }`(section/planJson 为空报错) | `Result<String>` — 新 plan JSON 文本 |
+| `POST /api/health/plan/save` | 登录,需 `familyId` | `{ planId?, memberIds?, dimensions, goal, planContent?, planJson?, memberName?, status?, teacherId?, totalDays?(1-365 有界) }` | `Result<Long>`(planId);`status` 缺省 → `pending_review`;`status=published` 时自动拆任务 |
+| `POST /api/health/plan/confirm` | 登录 | `{ planId }` | `Result<Long>` — 置 `published` + `generateDailyTasksFromPlan`(异常仅告警不阻塞) |
+| `POST /api/health/plan/detail` | 登录 | `{ planId }` | `Result<HealthPlan>` — 含非库字段 `tasks`(按 planId 从任务表回填) |
+| `POST /api/health/plan/list` | 登录,需 `familyId` | `{}` | `Result<List<HealthPlan>>` — 按 `family_id` + `created_at 倒序` |
+| `POST /api/health/plan/tasks` | 登录 + `familyId` 归属校验(跨家庭返「无权查看该方案任务」) | `{ planId }` | `Result<List<Task>>` |
+
+**`HealthPlan.status` 状态机**(String):
+
+| 值 | 含义 | 写入点 |
+|---|---|---|
+| `draft` | 草稿 | 报告确认入库自动生成 / `save(status=draft)` |
+| `pending_review` | 待审核 | `save` 缺省;报告生成默认 |
+| `published` | 已发布 | `confirm` / `pending-review/approve`(两者均触发任务生成,生成失败不回滚发布) |
+| `rejected` | 已驳回 | `pending-review/reject` |
+
+> **家长确认 vs 规划师审核双通道**:`save`/`confirm` 家长可直接调用(自确认通道,`confirm` 即发布);`pending-review/list|update|approve|reject` 仅 `role ∈ {teacher, admin}`(审核通道,§4.46 已登记)。两端点 `approve`(家长自审 `confirm` + 规划师 `approve`)语义等价于「发布 + 拆任务」。
+> ⚠ **幂等激活注记**:多次 `confirm`/`approve` 可重复触发任务生成,但生成器按 `source_type='health_plan' AND source_id=planId` 落库、直接实例型任务去重后计数,重复调用不会无限增殖;`PlanApproveResultDTO.taskCount` 每次重新统计,「部分成功」(`taskGenerated=false`)是合法终态,前端须显式提示。SC-T-05「幂等激活」测试须覆盖重复调用。
+
+#### 4.58.B1.4 B 组 · 编排(`OrchestrationController`,前缀 `/api/orchestration`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/orchestration/flow/save` | 仅 `role=admin`(其余「无权限」) | `TaskOrchestrationFlow`(完整 DTO,`creatorId` 服务端注入) | `Result<TaskOrchestrationFlow>` |
+| `POST /api/orchestration/flow/publish` | 仅 `role=admin` | `{ flowId }` | `Result<TaskOrchestrationFlow>` |
+| `POST /api/orchestration/flow/archive` | 仅 `role=admin` | `{ flowId }` | `Result<Boolean>` |
+| `POST /api/orchestration/execution/start` | 登录(`userId` 可选注入) | `{ flowId, familyMemberId }`(缺一报错) | `Result<Map>`(执行实例明细);`RuntimeException → Result.error` |
+
+> ⚠ **SC-P-45/P-46/P-81/T-22 注记**:当前 `TaskOrchestrationFlow` = **通用编排实例**(`flow` 模板 + `node_instance`),与 `HealthPlan` **两套独立概念**,无「flow ∋ plan」联动实现(生成完方案不会自动落 flow instance)。开工包「前置/风险」明确此为本批最大不确定性:能力键 `plan.parent.publish / activateTasks / draft / plan.guide.archive` 在用例定义前,**须先明确 flow 与 plan 的关系**;否则实现会在 plan 域误调 orchestration 接口。本契约仅登记现状语义:flow 是管理员编排模板,execution 是其执行实例。
+
+#### 4.58.B1.5 C 组 · 规划师方案激活/审核(`PlanReviewController`,前缀 `/api/guide/plans`)
+
+> ⚠ **命名冲突注记**:本节操作 `task_plan_instances`(`TaskPlanInstance`,训练方案实例),与 `health_plans`(`HealthPlan`,§4.46/§4.47)与 `/api/guide/families/{familyId}/plans/*`(§4.47 同源但路径不同)是**不同实体**。能力键与测试用例必须按实体区分,勿混用 planId 域。
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/guide/plans/activate` | `teacher`(须 `planner` 类别认证闸门,未认证返 403)+ `admin`;其余「无权限」 | `{ planId }` | `Result<String>`「方案已激活」;`IllegalStateException → Result.error(e.getMessage())` |
+| `POST /api/guide/plans/detail` | 登录 | `{ planId }` | `Result<TaskPlanInstance>`(无归属校验,仅按 id 查);不存在返「方案不存在」 |
+| `POST /api/guide/plans/review` | `teacher`/`admin` | `{ planId, approved, comment? }` | `Result<String>`「方案已批准/方案已驳回」— 仅 `status=generated` 可审核,置 `reviewed/rejected` + 记录 reviewer/时间/意见 |
+| `POST /api/guide/plans/family-list` | `teacher`/`admin` | `{ status?, familyId? }` | `Result<List<TaskPlanInstance>>` — teacher 取 JWT familyId(无则 `Result.noFamily`);admin 可传 familyId 全量 |
+
+#### 4.58.B1.6 C 组 · 规划师注册/认证 + 测评配置(`GuideManagementController` + `GuideAssessmentController`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/guide/register` | 登录 | `GuideRegisterDTO`(`userId/teacherNo/teacherPhoto/certificateImage/phone/idCard/address/realName/bankCard/bankName`) | `Result<Boolean>` — 更新 `users` 教师字段(`teacher_status=pending`)+ 创建 `guide_applications` draft(`new_apply/junior`)+ 追加 `teacher` 角色;`userId` 不存在返「用户不存在」 |
+| `POST /api/guide/application/submit` | 登录 | `{}` | `Result<Boolean>` — 取本人 `draft` 申请置 `pending`;无草稿返「未找到草稿申请」 |
+| `POST /api/guide/assessment/family/{familyId}` | 登录(路径变量) | — | `Result<Map>` — 家庭测评配置(`id/familyId/materialId/remindMonths/lastRemindAt/nextRemindAt/isEnabled` + 关联 `materialTitle/materialContent`);无配置返 `data=null` |
+| `POST /api/guide/assessment/family/enable` | 登录 + `familyId`;须 `assessor` 类别认证闸门 | `{ materialId?, remindMonths?(默认12) }` | `Result<Boolean>` — `materialId` 缺省取当前 active 材料 |
+
+> **规划师认证闸门清单**(`PlannerCertificationGuard`,与 §5 规划师培训认证一致):`guide/plans/activate`、`guide/messages/{messageId}/reply`、`guide/package/add|{packageId}/update`(套餐维护)→ `planner` 类别;`guide/assessment/family/enable` → `assessor` 类别。未完成认证返回 403 认证类错误码。
+
+#### 4.58.B1.7 C 组 · 数据授权(`DataPermissionController`,前缀 `/api/data-permission`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/data-permission/get` | 登录(未登录返「用户未登录」) | `{}` | `Result<UserDataPermission>`(`allowAiAnalysis / allowPersonalizedRecommend / allowShareTeacher / allowThirdPartyShare` 四开关) |
+| `POST /api/data-permission/update` | 登录 | `{ allowAiAnalysis?, allowPersonalizedRecommend?, allowShareTeacher?, allowThirdPartyShare? }`(布尔,缺省不改) | `Result<Boolean>` |
+
+> **SC-T-13 数据隔离边界**:`allowShareTeacher=true` 是规划师可读该用户 AI 分析/推荐/健康数据的**数据层前置同意**;`guide_families` 关系绑定(§4.47 `isBound`)是**关系层隔离**。两类隔离互补,`guide.family.dataIsolation` 测试用例须同时覆盖:关系层(非绑定家庭 403)+ 数据层(关了共享开关即使绑定也拿不到数据)。
+
+#### 4.58.B1.8 C 组 · 套餐任务项管理(`TrainingPlanController` + `TaskTemplatePackageController`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/guide/training-plans/items/add` | 登录 | `TrainingPlanItem`(`planId` 必填) | `Result<Long>`(itemId) |
+| `POST /api/guide/training-plans/items/update` | 登录 | `TrainingPlanItem`(`id` 必填) | `Result<Boolean>` |
+| `POST /api/guide/training-plans/items/delete` | 登录 | `{ itemId }` | `Result<Boolean>` |
+| `POST /api/guide/training-plans/deploy` | 登录 | `{ planId }` | `Result<List<Long>>`(生成的任务 ID 列表) |
+| `POST /api/guide/training-plans/execution-board` | 登录 | `{ planId }` | `Result<Map>`(执行看板聚合) |
+| `POST /api/packages/`(根) | 登录 | 无 body / 空对象 → 列表;有 body → 创建 | `Result<List<TaskTemplatePackage>>` 或 `Result<Long>` |
+| `POST /api/packages/create` | 登录 | `CreatePackageDTO` | `Result<Long>`(packageId) |
+| `POST /api/packages/{id}/items` | 登录 | `CreatePackageItemDTO`(`packageId` 服务端覆盖为路径 id) | `Result<Long>`(itemId) |
+| `POST /api/packages/{id}/item-list` | 登录 | 路径变量 | `Result<List<TaskTemplateItem>>` |
+| `POST /api/packages/{id}/submit` | 登录 | 路径变量 | `Result<Boolean>`(提交审核) |
+| `POST /api/packages/{id}/publish` | 登录 | `{ publish }` | `Result<Boolean>`(发布/下架) |
+| `POST /api/packages/{id}/update` | 登录 | `CreatePackageDTO` | `Result<Boolean>` |
+| `POST /api/packages/{id}` | 登录 | 路径变量 | `Result<TaskTemplatePackage>` |
+| `POST /api/packages/my` | 登录 | `{}` | `Result<List<TaskTemplatePackage>>` |
+| `POST /api/packages/items/{itemId}` | 登录 | `CreatePackageItemDTO` | `Result<Boolean>`(更新任务项) |
+| `POST /api/packages/items/{itemId}/delete` | 登录 | 路径变量 | `Result<Boolean>` |
+
+#### 4.58.B1.9 C 组 · 会员购买(`MembershipController`,前缀 `/api/membership`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/membership/orders` | 登录(`trial` 单直接开通) | `{ levelCode, paymentType, period?(默认 yearly), couponId?, openid? }` | `Result<Object>` — `paymentType=trial` → 直接 `status=paid`(`payType=none`);`testMode` → `PaymentOrderDTO`;否则虚拟支付参数 `VirtualPayParamsDTO`;会话失效 400;不可购 46001 |
+| `POST /api/membership/upgrade` | 登录 | `{ levelCode?(默认 FAMILY), paymentType, period?(默认 yearly), couponId? }` | `Result<PaymentOrderDTO>`(创建升级订单,未支付) |
+| `POST /api/membership/trial` | 登录 | `{}` | `Result<PaymentOrderDTO>`(FAMILY trial 订单) |
+| `POST /api/membership/orders/continue` | 登录 | `{ orderNo }` | `Result<Object>` — 拆单组下一未付期预支付参数;非拆单订单 400「该订单不支持续付」;全部付清 `{ done: true }`;会话失效 400;不可购 46001 |
+
+> 已登记:`/api/membership/compare`(§4.50)、`/api/membership/plans`(§4.50)、`/api/membership/gift-membership-progress`(§4.43)。`/api/membership/discount` 已 **410 Gone**(`@Deprecated`,`"会员商品价在下单时按会员价结算"`)。
+> SC-P-58「购买会员/套餐」建议映射 `membership/orders`(会员)+ 组合商品下单(套餐),`/api/package/order/create`(410)不可用。
+
+#### 4.58.B1.10 D 组 · 家长邀约 / 教练转接(`GuideController`,前缀 `/api/guide`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/guide/guide-packages` | 登录 | `{}` | `Result<List<GuidePackage>>`(激活套餐列表,`getActivePackages`) |
+| `POST /api/guide/parent-invite/generate` | 登录 + `familyId`(无则 `Result.noFamily`) | `{}` | `Result<Map>` — `{ id, code, type, refId, expiresAt }`(`invite_cards` type=`parent_invite`) |
+| `POST /api/guide/parent-invite/accept` | 登录 | `{ code }`(空返「邀请码不能为空」) | `Result<Map>` — 邀约结果(接受家长邀约) |
+
+> **SC-B-09 教练转接**:`parent-invite/generate`/`accept` 提供家长邀约卡片与接受;LangGraph 转接 graph 在 `cfc-langgraph`(跨仓、端口 9000),**不可与后端同批派发**(开工包「前置/风险」)。能力键 `coach.handoff.planner` 两类流证据须同时引用本仓(本节)与 cfc-langgraph 契约。
+
+#### 4.58.B1.11 D 组 · 营养 / 天盘 / 内容安全(`UserNutritionProfileController`、`NutritionistController`、`TianpanController`、`ContentFilterController`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/nutrition/profile/get` | 登录 | `{}` | `Result<UserNutritionProfile>` |
+| `POST /api/nutrition/profile/save` | 登录 | `{ budgetMonthly?, familyTastePreferences?, cuisineStyle?, mealCount?, cookingAbility? }` | `Result<String>`("ok");局部更新 upsert |
+| `POST /api/nutritionist/apply` | 登录 | `{ realName? }` | `Result<String>`(「营养师申请已提交…」);`nutritionist_status != rejected` 重复提交返「已有营养师申请…」;副作用 `users.nutritionist_status=pending` + 加 `nutritionist` 角色 + realName 回填 |
+| `POST /api/nutritionist/status` | 登录 | `{}` | `Result<Map>` — `{ nutritionistStatus, nutritionistRejectReason }` |
+| `POST /api/tianpan/dashboard` | 登录 + `familyId`(无则 `Result.noFamily`)+ 家庭归属校验 | `{ year?, daysAhead?(默认7), viewerRole? }` | `Result<TianpanDashboardVO>` |
+| `POST /api/tianpan/member/{memberId}` | 登录 + 归属校验(跨家庭 403) | `{ memberType?, viewerRole? }` | `Result<TianpanMemberVO>`;成员不存在 404 |
+| `POST /api/tianpan/compatibility` | 登录 + 同家庭校验(跨家庭 400「成员不属于同一家庭」) | `{ member1Id, member2Id, memberType1?(默认 family_member), memberType2?(默认 family_member) }` | `Result<CompatibilityResultVO>` |
+| `POST /api/tianpan/annual-energy` | 登录 + 归属校验 | `{ memberId, year? }` | `Result<MemberAnnualEnergyVO>` |
+| `POST /api/tianpan/daily-fortune` | 登录 + `familyId` | `{ year?, daysAhead? }` | `Result<DailyFortuneVO>` |
+| `POST /api/tianpan/related-items` | 登录 + `familyId` | `{ daysAhead?(默认7) }` | `Result<RelatedItemsVO>` |
+| `POST /api/tianpan/recalibrate` | 登录 + 归属校验 | `{ memberId, memberType?(默认 child), operator?(默认 system) }` | `Result<Map<String, Integer>>`(五维基础分) |
+| `POST /api/content/by-tags` | 登录 | `{ resultTags?:string[], problemDomainCode?, size?(默认10) }` | `Result<Map>` — `{ resultTags(含问题域扩展), articles[], knowledgeBases[], foods[] }` |
+
+> **SC-T-26/T-27/T-28 跨域注记**(开工包「前置/风险」):
+> - `plan.guide.nutritionPlan`:`nutrition` 线(profile 偏好 + nutritionist 认证)**非方案域原生能力**,建议拆独立任务、由 plan 侧聚合,不并入 plan.guide 单键。
+> - `plan.guide.tianpanReading`:天盘为独立域,`/api/tianpan/*` 本表补齐 7 个端点的详细鉴权/请求/响应(§4.17 仅清单无契约)。
+> - `plan.guide.contentSafeReview`:`/api/content/by-tags` 是**按 contentTags 过滤**内容(文章/知识库/饮食),**无审核语义**;AI 方案内容安全复核须指向 LangGraph 内容安全管线或规划师侧人工审核(`PlanReviewController`),能力键定义勿指向本端点。
+
+#### 4.58.B1.12 D 组 · 孩子执行(`DailyCheckinController` + `UserNotificationController`)
+
+| 路径 | 鉴权 | 请求体 | 响应 `data` |
+|---|---|---|---|
+| `POST /api/daily/checkin/list` | 登录 + `currentMemberId` 注入 | `{ memberId? }`(空返「memberId不能为空」) | `Result<List<DailyHealthCheckin>>` |
+| `POST /api/daily/checkin/create` | 登录 + `currentMemberId` 注入 | `DailyHealthCheckin`(`memberId` 缺省取 currentMemberId) | `Result<DailyHealthCheckin>`(已落库记录) |
+| `POST /api/notification/list` | 登录 | `{}` | `Result<List<UserNotification>>` — 按 `userId`,`is_read 升序(未读优先)+ created_at 倒序`,Limit 100 |
+| `POST /api/notification/read` | 登录 | `{ id? }` 或 `{ ids?:number[] }` 或 `{}`(缺省全部) | `Result<Boolean>` — 仅可标记**本人**通知(逐条 `userId` 匹配) |
+
+> **SC-C-25/T-30 五维触发注记**:`daily/checkin/create` 仅写打卡记录,**不触发五维增长**;五维增长写入在 `EnergyService`/`DimensionScoreService`(五维能量批 P0,dimension/energy 线)。能力键 `task.child.checkinTriggerFiveDim`、`dan.assessment.triggerFiveDim` 的**证据须引用五维能量批契约 sha**,避免重复建键(kickoff「前置/风险」)。
+
+#### 4.58.B1.13 B-1 批次核对统计与遗留清单
+
+**核对统计(56 = 已覆盖 14 + 部分覆盖 2 + 完全缺失 40)**
+
+| 分类 | 数量 | 说明 |
+|---|---|---|
+| 已覆盖(路径+鉴权+请求响应已有) | 14 | §4.47 `plans/pending` + `{planId}/approve` + `{planId}/update` + `my-families`(4);§4.45 `unbind`(1);§4.46 `pending-review/list` + `approve`(2);§4.7 `daily/checkin/list` + `create` + `mind/emotion/*`(3);§4.12 `content/*`(1);§4.15 `notification/list` + `read`(2);§4.47.1 `guide/messages/send`(1) |
+| 部分覆盖(仅通配路径或仅清单) | 2 | `/api/membership/*`(已有 compare/plans/gift-progress,缺 orders/upgrade/trial/continue → 本批 4.58.B1.9 补齐);`/api/tianpan/*`(§4.17 仅路径清单 → 本批 4.58.B1.11 补齐全契约) |
+| 完全缺失(本批补齐) | 40 | 4.58.B1.1–4.58.B1.12 全部端点 |
+| **合计** | **56** | 与开工包「契约接口范围」列 1:1 |
+
+**遗留清单(后续 SC 派发前需处理,本批只登记不改码):**
+
+1. `POST /api/dan-assessment/appointment/cancel` **无越权校验**(SC-P-38 要求)——服务层按 `id` 直接置 `status=3`,控制器无 `familyId`/`guideId` 反查。
+2. `POST /api/package/order/create` 恒 **410 Gone**,但 SC-P-33 / SC-P-58 仍列—能力键应改指 `DanAssessmentController.order/create`(测评订单)或组合商品下单(套餐)。
+3. `POST /api/payment/order/status/{orderNo}` 仅适用 `package_orders`(PackageOrder),SC-P-34 的测评订单状态须走 `dan-assessment/order/detail`。
+4. 「测评额度(SC-P-35)」与「创建预约消耗额度(SC-P-36)」随迁移 382 已废止配额门禁——能力键定义须与实际(无扣减、仅能量发放)对齐。
+5. `record/complete` 不触发方案生成(SC-T-07)——「录入→触发方案」需拆任务或规划师侧独立管线。
+6. `OrchestrationController` 的 flow/execution 语义(SC-P-45/46/81/T-22)无「flow=方案实例」化实现——用例定义前须明确 flow 与 plan 的关系(本批最大不确定性)。
+7. 跨域键(SC-T-26 nutrition / SC-T-27 tianpan / SC-T-28 content)按 kickoff 拆独立任务。
+8. 跨仓键(SC-B-09 / SC-B-12 LangGraph)与后端分批派发。
+9. SC-H-02 真人管家无既有 Controller——登记**契约待定**,不建伪键。
+10. SC-T-30 / SC-C-25 五维触发证据引用五维能量批契约 sha。
+
+*补写:2026-11-06(B-1「测评-方案」开工包 56 端点契约核对,补全 40 缺失端点;数据源 `docs/tdd/orchestration/dan-plan-kickoff-20261106.md`)*

Certains fichiers n'ont pas été affichés car il y a eu trop de fichiers modifiés dans ce diff