B-2 报告闭环开工包 API 契约核对补全：新增 API_REFERENCE 4.59（report-parse/report-parse 解析中台、健康报告全链路、代传闭环 proxy-parse/proxy-confirm、报告权限/分享、DAN 报告模块、趋势与饮食推荐、LangGraph 依赖登记、契约缺口映射）+ PROJECT-OVERVIEW 追踪

docs/superpowers/api/API_REFERENCE.md

@@ -2537,3 +2537,223 @@ 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.59 报告闭环批次契约补写（B-2，2026-11-06 开工包核对）
+
+> 来源：`docs/tdd/orchestration/report-closedloop-kickoff-20261106.md`（23 SC → 19 能力键）。
+> 本批为**契约核对补全**：对照 `origin/cfclub` 实际 Controller 源码（`git show origin/cfclub:<路径>`），
+> 将开工包「契约接口范围」映射到**实际已存在端点**，补齐 API_REFERENCE 缺失条目。
+> 统一 `@PostMapping`、响应 `Result<T>`、JWT 鉴权（JwtInterceptor 拦截 `/api/**`）。
+> **未实现端点**（`/api/search/global`、`/api/provider/report-parse/connect`、`/api/health/report/{compare,trend,diet,share,refresh-dim}`）
+> 见 4.59.10 契约缺口。
+
+### 4.59.1 管理端-报告解析进度 / 解析中台（SC-A-02 `admin.reportParse.typeList`）
+
+> Controller：`ReportParseAdminController`（`/api/admin/report-parse`）+ `ReportParserAdminController`（`/api/admin/report-parser`）。
+> 鉴权：JwtInterceptor 对 `/api/**` 统一拦截；管理员角色校验在 `JwtInterceptor` 之后（admin 登录态）。
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/admin/report-parse/list` | `{page=1, size=20, parseStatus?, reportType?, keyword?}`（keyword 匹配 originalFilename/userId） | `{total, records[]}`；records 元素：`draftId/userId/reportType/originalFilename/fileHash/parseStatus/parseMethod/parseError/parseAttempt/nextRetryAt/parseStartedAt/parseFinishedAt/collectValidation/draftStatus/confirmedReportId/createdAt/updatedAt` | 草稿解析进度分页查询（按 updatedAt 倒序） |
+| `POST /api/admin/report-parse/retry` | `{draftId}` | `{draftId, parseStatus:"collecting"}` | 手动重试：重置解析进度（`resetForManualRetry`）并重新提交异步采集（`submitAsyncCollect`） |
+| `POST /api/admin/report-parse/backfill-food` | `{reportId}` | `{reportId, foodCount}`；失败返回 `Result.error(e.getMessage())` | 食材回填：重新解析报告并覆盖写入 foods（失败保留旧载荷）；`IllegalArgumentException`/`IllegalStateException` 转错误 |
+| `POST /api/admin/report-parser/dan/reparse` | `{uploadId, dimension}`（均必填） | `danReportUploadService.reparseUpload(...)` 结果 | DAN 报告按维度重新解析（`ReportParserAdminController`） |
+
+> `ReportParserAdminController` 其余端点（`types`/`types/save`/`types/toggle`/`types/delete`/`fingerprints/list`/`fingerprints/save`/`fingerprints/delete`/`imports`/`imports/import`/`imports/approve`/`imports/reject`/`unknown-clusters`/`unknown-uploads`/`generate-type`）已在 4.30 登记。
+
+### 4.59.2 健康报告全链路契约（SC-C-06 `health.report.view` / SC-X-02 `health.report.closedLoop`）
+
+> Controller：`HealthReportController`（前缀 `/api/health`）。报告归属由 `health_reports.subject_id`（family_members.id，可 null）表示；
+> 无归属报告不参与方案生成。成员级查看权限（管理员 / 本人 / 被授权成员）在 `list/detail/payload` 逐接口校验。
+> **两阶段入库**：Phase 1 上传建草稿（`/upload-only` 或 `/report/parse`）→ Phase 2 确认入库（`/report/confirm`）。
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/health/report/create` | body：`{memberId?, reportType, overallScore?, gutHealthScore?, chronicDiseaseScore?, nutritionScore?, gutAge?, gutType?, gutBalanceScore?, gutDiversityScore?, beneficialBacteriaScore?, harmfulBacteriaScore?, ...}`（reportType 必填：`physical_exam`/`gut_flora`） | `HealthReport`（含 id） | 创建健康报告（含指标明细）。付费墙：未购买「健康启航计划」返回 `code=4001`「请先购买健康启航计划体验包」；memberId 缺省取 `currentMemberId` |
+| `POST /api/health/report/latest` | `{memberId?}`（缺省 currentMemberId） | `HealthReport`（无则 null） | 获取成员最新健康报告 |
+| `POST /api/health/report/list` | `{memberId?, page?, size?}` | `page` 未传 → `List<HealthReport>`（兼容小程序）；`page` 传 → 分页结构 `{total, records[]}` | 报告列表。未传 memberId 返回当前家庭全部报告（按 `visibleIdentityIds` 权限过滤；管理员全部可见）；传 memberId 且无查看权限 → 空列表 |
+| `POST /api/health/report/detail` | `{reportId}` | `Map`：报告详情（含指标明细 + 菌群数据 + 疾病风险评估） | 完整详情；权限校验（本人/管理员/被授权成员），无权返回「无权查看该报告」 |
+| `POST /api/health/report/payload` | `{reportId}` | `Map`：报告 payload（编辑回填用，按需加载） | 同 detail 权限校验 |
+| `POST /api/health/report/edit` | `{reportId, subjectId?, payload}` | `"已更新"` | 编辑已发布报告（修正 AI 解析错误值）；subjectId 可 null 表示解绑，变更时重算旧/新成员维度分 |
+| `POST /api/health/report/delete` | `{reportId}` | `"已删除"` | 删除报告 |
+| `POST /api/health/report/download` | `{reportId}` | `{fileUrl, fileName}`（本地相对路径 `/uploads/**` 自动拼当前域名） | 报告文件下载信息（供 uni.downloadFile） |
+| `POST /api/health/report/upload` | multipart `file`（仅 PDF） | 兼容接口：自动执行「解析→确认」两阶段（内部 `pdfParseService.parse`） | 向后兼容旧调用；新链路走 `/upload-only` + `/report/parse` + `/report/confirm` |
+| `POST /api/health/report/parse` | `{draftId}` | 解析结果（draftId/payload/matchedMemberId/extracted/needBind 等） | Phase 1 按草稿 ID 触发解析：LangGraph 优先（`/api/v1/report/parse`），失败回退本地 Java 解析 |
+| `POST /api/health/report/confirm` | `{type="pdf", draftId, subjectId?, payload?}`；`type=tongue` 时 `{recordId, subjectId?, indicators?}` | `{reportId, ...}` | Phase 2 确认草稿入库：写正式表 → 归一化指标管道 → 绑定成员 → 刷新 7 维评分/指标当前值/食材推荐 → 自动生成方案（非 tongue 类型）。`payload` 可回传修改后指标（用户在线编辑后整体提交） |
+| `POST /api/health/report/discard` | `{type="pdf", draftId}`；`type=tongue` 时 `{recordId}` | `"草稿已放弃"` | 放弃草稿（仅草稿创建者本人） |
+| `POST /api/health/report/archive` | `{reportId}` | `"报告已归档"` | 归档报告（软删除） |
+| `POST /api/health/report/archive-batch` | `{reportIds:[Long]}` | `"已归档 N 份报告"` | 批量归档（管理端选中删除） |
+| `POST /api/health/report/audit/pending` | `{page=1, size=20}` | `List<HealthReportDraft>` | 管理端：待审核报告草稿列表 |
+| `POST /api/health/report/audit/confirm` | `{draftId, subjectId?}` | `{reportId, subjectId, ...}` | 管理端：审核确认入库。B2-3：平台角色（admin/AdminRoles）可确认任意草稿，非平台角色仅确认自己创建草稿；确认后刷新食材推荐 |
+| `POST /api/health/report/audit/discard` | `{draftId}` | `"报告已丢弃"` | 管理端：审核丢弃 |
+
+> 报告归属（reassign/unlinked/bind）见 4.36.1；报告跨家庭转移（transfer/request、approve、deny、list）为本链路的跨家庭归属场景，已实现（`reportTransferService`），契约随 4.36.1 口径（`{reportId}` → `{requestId, status}`）。
+
+### 4.59.3 报告代传闭环（SC-P-67 / SC-T-03 / SC-T-23 `health.report.proxyUpload` / SC-X-13 `health.report.proxyClosedLoop`）
+
+> 开工包建议路径 `/api/health/report/proxy-upload`，**实际实现为两阶段**：`/api/health/report/proxy-parse`（预览，仅解析不入库）+ `/api/health/report/proxy-confirm`（确认入库）。
+> Controller：`HealthReportController`。
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/health/report/proxy-parse` | multipart/query：`file`（新上传）**或** `fileUrl`（草稿过期后基于原文件重新解析，B3-2 降级），`familyId`（必填），`subjectId?`，`reportType=auto`（空/auto→`gut_flora`），`note?` | 预览结果：`{draftId, payload, matchedMemberId, extracted*, needBind, fileUrl, proxyUploaderId, proxyUploadNote, reparse, parseMethod("langgraph"/"local"), parseFallback}` | 代上传报告（预览模式）。权限三层校验：① `isProxyUploader`（admin/teacher/approved 营养师/approved 规划师，否则 `code=500`「无权限代上传报告…」）② `canProxyForFamily`（B2-2，非平台角色须 familyId ∈ 有效家庭集，否则「无权为该家庭代传报告」，不建草稿不写文件）③ `FamilyAccessInterceptor` 兜底（HTTP 403 `{"code":403,"message":"无权访问该家庭数据"}`）。建草稿拿 draftId → LangGraph 解析（失败回退本地 Java，`parseFallback=true`/`parseMethod="local"`） |
+| `POST /api/health/report/proxy-confirm` | `{draftId, subjectId?}` | `{reportId, subjectId, aiAnalysis?, aiAnalysisStatus("success"/reason), aiAnalysisMessage?}` | 代确认报告（入库）。B2-3：仅草稿创建者本人或平台角色可确认（`auditConfirm(draftId, subjectId, userId, isAdmin)`）；确认后写入 `health_reports.proxy_uploader_id`/`proxy_upload_note`（取草稿 remark）→ 刷新食材推荐 → 触发 AI 解读（T29-B1-5：失败不静默吞错，`aiAnalysisStatus`/`aiAnalysisMessage` 回传） |
+
+> 代传与自传共用同一「归属校验」口径：`subjectId` 绑定成员 + `health_reports.subject_id` 落库，跨角色闭环（家长/规划师代传 → 归属校验 → 确认入库）经 `proxy-parse`/`proxy-confirm` 完成，无独立 `proxy-upload` 端点。
+
+### 4.59.4 报告查看权限 / 分享（SC-P-84 `health.report.share`）
+
+> 开工包建议路径 `/api/health/report/share`，**实际实现**为「报告成员级权限管理」（`ReportMemberPermissionController` + `HealthReportController` `/report/permission/*`）+ 通用内容分享（`ShareController` `/api/share`）。
+
+#### 4.59.4.1 报告查看权限（`/api/health/report/member-permission/*`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/health/report/member-permission/list` | 无 body | `List<Map>`：家庭全部授权记录 | 家庭管理员操作；`IllegalArgumentException` 转 `Result.error` |
+| `POST /api/health/report/member-permission/members/{memberId}` | path `memberId` | `List<Long>`：已授权用户 ID 列表 | 查询某成员的已授权用户 |
+| `POST /api/health/report/member-permission/grant` | `{targetMemberId, granteeUserId}` | `Boolean` | 授权：让指定用户可查看某成员的报告 |
+| `POST /api/health/report/member-permission/revoke` | `{targetMemberId, granteeUserId}` | `Boolean` | 撤销授权 |
+| `POST /api/health/report/member-permission/visible-members` | 无 body | `Set<Long>`（null=管理员全部可见） | 查询用户可见的成员 ID 集合 |
+
+#### 4.59.4.2 报告级权限（`HealthReportController` `/report/permission/*`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/health/report/permission/add` | `{reportId, userId}` | `"权限添加成功"` | 添加报告查看权限（授权家庭成员查看该报告） |
+| `POST /api/health/report/permission/remove` | `{reportId, userId}` | `"权限移除成功"` | 移除报告查看权限 |
+| `POST /api/health/report/permission/check` | `{reportId, userId}` | `Boolean` | 检查用户是否有该报告查看权限 |
+
+#### 4.59.4.3 通用内容分享（`ShareController` `/api/share`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/share/create` | `{targetType, targetId, shareChannel="wechat", title=""}`（需登录） | `ShareEvent` | 创建分享记录（报告/方案/文章/商品统一入口，`targetType` 区分） |
+| `POST /api/share/click` | `{shareEventId}` | `null` | 记录分享点击 |
+| `POST /api/share/read` | `{shareEventId, duration=0}` | `{rewarded:Boolean}` | 记录分享阅读；首次阅读且登录 → 发放阅读奖励积分 |
+| `POST /api/share/my` | 无 body（需登录） | `List<ShareEvent>`（最多 50 条） | 我的分享记录 |
+| `POST /api/share/stats` | 无 body（需登录） | `Map`：分享统计 | 分享统计 |
+| `POST /api/share/family-footprint` | 无 body（familyId 由 JWT 注入） | `Map`：家庭健康足迹 | P3 分享页：家庭健康足迹 |
+| `POST /api/share/qrcode` | `{page, scene?}`（scene ≤32 字符，需登录） | `{qrCodeBase64:"data:image/png;base64,..."}` | 生成分享小程序码（商品/活动/文章详情页海报） |
+
+### 4.59.5 DAN 报告模块（SC-C-07 / SC-T-12 `dan.assessment.viewReport`、SC-T-11 `dan.assessment.uploadReport`、SC-P-39 `dan.assessment.viewResult`、SC-P-24 / SC-T-21 `health.report.compare`）
+
+#### 4.59.5.1 DAN 报告独立流程（`DanReportController` `/api/dan-report`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/dan-report/upload` | multipart：`file`（PDF）、`dimension`、`memberId` | `Map`：`uploadAndParse` 结果（预览 + 解析字段） | Phase 1 上传并预览 DAN PDF |
+| `POST /api/dan-report/{id}/edit` | body `DanReportEditDTO` | `DanReportUploadVO` | 编辑草稿 |
+| `POST /api/dan-report/{id}/confirm` | `{childName?, assessmentDate?}` | `DanReportUploadVO` | Phase 2 确认入库 |
+| `POST /api/dan-report/{id}/discard` | 无 body | `null` | 放弃草稿 |
+| `POST /api/dan-report/{id}/complete-analysis` | 无 body | `null` | 完成分析（标记） |
+| `POST /api/dan-report/{id}` | path `id` | `DanReportUploadVO` | 详情（权限：有归属成员须 `canViewMemberReports`；无归属仅上传者本人/家庭管理员） |
+| `POST /api/dan-report/list` | `{memberId?, dimension?}` | `List<DanReportUploadVO>` | 列表。未传 memberId 按可见身份过滤该家庭全部；传 memberId 校验 `canViewMemberReports`（无权限返回空列表） |
+| `POST /api/dan-report/compare` | `{uploadIdA, uploadIdB}` | `uploadService.compareUploads` 结果 | DAN 报告两版对比（按 uploaded_at 对齐 parsed/edited_items 算 delta） |
+
+#### 4.59.5.2 测评对比（`AssessmentComparisonController` `/api/assessment/compare`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/assessment/compare/by-child` | `{memberId?}`（缺省 currentMemberId） | `CompareResult`（首次 vs 最新测评对比） | 至少两次完成测评，否则 `Result.error("至少需要两次完成测评才能对比")` |
+| `POST /api/assessment/compare/by-child-dimension` | `{memberId, dimensionCode}` | `DimensionDelta`（单维度变化） | 数据不足 → `"暂无足够数据"` |
+| `POST /api/assessment/compare/by-family` | 无 body（familyId JWT 注入） | `List<CompareResult>` | 家庭所有成员首次 vs 最新；无家庭 → `Result.noFamily` |
+| `POST /api/assessment/compare/narrative` | `{memberId?}` | `String`（进步叙事） | 获取进步叙事 |
+
+#### 4.59.5.3 测评结果 / 报告查询（`guide/AssessmentController` `/api/assessment` + `AssessmentResultController`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/assessment/result/{id}` | path `id` | `DanAssessmentResult` | 测评报告详情。**仅 `role=teacher` 可查看**（否则「只有指导师可以查看测评报告」）；`canViewAssessment` 权限校验 |
+| `POST /api/assessment/my-results` | 无 body | `List<DanAssessmentResult>` | 指导师自己的测评报告列表（仅 teacher） |
+| `POST /api/assessment/child-results` | 无 body | `List<DanAssessmentResult>` | 下级指导师的测评报告列表（仅 teacher，`getAccessibleAssessments`） |
+| `POST /api/assessment/latest-result` | `{memberId?}`（缺省 currentMemberId） | `AssessmentResultDTO`（无则 null） | 成员最新认知测评结果（已在 4.10 登记，此处补 DTO 字段：memberId/childName/overallScore/attentionScore/focusScore/memoryScore/logicScore/perceptionScore/spatialScore/processingSpeedScore/analysisReport/growthSuggestions/assessmentDate） |
+| `POST /api/assessment/history` | `{memberId, size=5}` | `List<AssessmentHistoryItemDTO>`（assessmentDate/overallScore） | 成员测评历史（status=completed，按 assessmentDate 倒序） |
+
+#### 4.59.5.4 测评报告上传 / 指导意见 / 方案（`AssessmentReportController` `/api/dan-assessment/result`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/dan-assessment/result/plans/list` | query/body `{familyId?, childId?}`（缺省 JWT familyId） | `List<TaskPlanInstance>`（按 createdAt 倒序） | 家庭/成员已生成的测评方案列表；缺 familyId → `"缺少familyId参数…"` |
+| `POST /api/dan-assessment/result/upload` | multipart `file`（仅 PDF）、`memberId`、`notes?` | `DanAssessmentResult`（status=draft，异步解析） | 家庭主账号上传测评报告（已在 4.10 登记）；非 PDF → HTTP 415 `{code:415}` |
+| `POST /api/dan-assessment/result/{resultId}/guidance/save` | `{items:[GrowthGuidance]}`（非空） | `List<GrowthGuidance>` | 保存结构化指导意见（已在 4.10 登记） |
+| `POST /api/dan-assessment/result/{resultId}/guidance` | 无 body | `List<GrowthGuidance>` | 获取结构化指导意见 |
+| `POST /api/dan-assessment/result/{resultId}/confirm-inbox` | `{overallScore?}` | `DanAssessmentResult`（status=completed） | 用户确认报告入库并**自动生成测评方案**（无需规划师审核） |
+
+### 4.59.6 报告趋势 & 饮食推荐闭环（SC-P-25 `health.report.trend`、SC-P-26 `health.report.dietRecommend`、SC-X-10 `health.report.trendClosedLoop`）
+
+> 开工包建议路径 `/api/health/report/trend`、`/api/health/report/diet`；**实际实现**：趋势走 `/api/health/nutrition/trend`（报告营养趋势）与 `/api/food/recommendation/trend`（食材推荐趋势）；饮食推荐走 `/api/food/recommendation/*`、`/api/meal/*`、`/api/diet/*`（4.11 已登记）。
+
+#### 4.59.6.1 报告趋势（`HealthReportController` `/api/health/nutrition/trend`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/health/nutrition/trend` | `{memberId}` | `Map`（`childNutritionProfileService.getReportTrendData`） | 报告趋势数据（营养档案多期序列） |
+
+#### 4.59.6.2 食材推荐（`FoodRecommendController` `/api/food/recommendation`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/food/recommendation/index` | `{memberId?}` | 当前食材推荐指数列表 | 按成员取推荐（`foodRecommendService`） |
+| `POST /api/food/recommendation/history` | `{memberId?}` | 历史推荐 | 食材推荐历史 |
+| `POST /api/food/recommendation/by-family` | `{familyId?}`（JWT） | 家庭成员食材推荐汇总 | 家庭维度汇总 |
+| `POST /api/food/recommendation/caution` | `{memberId?}` | 慎用/忌口清单 | 食材提醒 |
+| `POST /api/food/recommendation/members` | `{familyId?}` | 家庭内参与成员 | 推荐参与成员列表 |
+| `POST /api/food/recommendation/trend` | `{memberId?}` | 推荐趋势 | 食材推荐多期趋势 |
+
+> 报告确认/代确认后 `foodRecommendService.recalculateForUser(subjectId)` 自动刷新食材推荐指数（见 4.59.2 `/report/confirm` 与 4.59.3 `/proxy-confirm`）。
+
+#### 4.59.6.3 餐食推荐（`MealRecommendController` `/api/meal`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/meal/recommend` | `{...}` | 推荐菜单 | 基于报告/偏好推荐餐食 |
+| `POST /api/meal/replace` | `{...}` | 替换后菜单 | 换一道菜 |
+| `POST /api/meal/log` | `{...}` | 保存结果 | 记录食用 |
+| `POST /api/meal/logs` | `{memberId?, date?}` | 记录列表 | 食用记录列表 |
+| `POST /api/meal/nutrition-summary` | `{memberId?, date?}` | 营养汇总 | 营养摄入汇总 |
+
+### 4.59.7 报告类型链接 / 检测（`ReportParserController` `/api/report-parser`，4.36 补充）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/report-parser/types/links` | 无 body | `List<{typeId, displayName, linkedProductId, productName}>` | 小程序公开：返回已激活且配置了商城商品链接的报告类型（`is_active=1 AND linked_product_id IS NOT NULL`），供「查看商品」入口；未配置链接的类型不出现在结果中 |
+| `POST /api/report-parser/detect` | `{...}` | 指纹检测结果 | 报告指纹检测（同步返回，供调用方识别类型） |
+
+### 4.59.8 报告摘要（`ReportSummaryController` / `ReportSummaryAdminController`）
+
+| 路径 | 请求 | 响应 `data` | 说明 |
+|------|------|-------------|------|
+| `POST /api/report-summary/list` | `{...}` | 摘要列表 | 报告摘要列表（C 端） |
+| `POST /api/report-summary/detail/{id}` | path `id` | 摘要详情 | 报告摘要详情 |
+| `POST /api/report-summary/download/{id}` | path `id` | 下载信息 | 报告摘要下载 |
+| `POST /api/admin/report-summary/list` | `{page?, size?, ...}` | 分页摘要 | 管理端摘要列表 |
+| `POST /api/admin/report-summary/sync` | `{...}` | 同步结果 | 管理端手动同步报告摘要 |
+
+### 4.59.9 LangGraph 报告解读依赖登记（SC-B-04 `coach.growthReport.interpret` / SC-B-11 `coach.growthReport.ask`）
+
+> **本批仅登记依赖，不做实现**（契约在 cfc-langgraph 侧）。Java 侧通过 `HealthReportController` 内 `restTemplate` 调用，
+> `langgraph.base-url`（报告解析）/ `python.base-url`（通用 AI）由 `application.yml` 配置。
+
+| LangGraph 端点 | 请求 | 用途 | Java 侧触发点 |
+|----------------|------|------|---------------|
+| `POST {langgraph}/api/v1/report/parse` | `{file_path, user_id, family_id?}` | 报告解析（PDF → 结构化载荷） | `/api/health/report/parse`、`/proxy-parse`（`callLangGraphParse`）；失败回退本地 Java 解析 |
+| `POST {langgraph}/api/v1/analyze` | `{report_id, user_id, focus}` | 报告 AI 解读（growthReport.interpret） | `/proxy-confirm` 的 `triggerAiAnalysis`（REPORT_READING 配额：BASIC 1 次/月，FAMILY 及以上不限；失败回传 `aiAnalysisStatus`） |
+| `POST {langgraph}/api/v1/chat` | 会话上下文 | 报告细节追问（growthReport.ask） | 对话链路（AIChatController / 报告反馈 `/api/health/feedback/*`，见 4.37） |
+
+> 依赖边界：报告解读/追问能力**不在 cfc-backend 实现**，由 cfc-langgraph graph 提供；本批只登记调用契约，不新增 Java 端点。
+
+### 4.59.10 契约缺口（开工包建议路径与现状不符，**待实现 / 等价物替代**）
+
+| 开工包建议路径 | 现状 | 说明 |
+|----------------|------|------|
+| `POST /api/search/global` | **不存在**（无 SearchController） | SC-P-82 `misc.globalSearch` 全局搜索（报告/方案/任务/商品）**未实现**；搜索需求当前分散：`/api/diet/ingredients/search`（食材）、文章/商品搜索各自接口。待实现时在本节登记 |
+| `POST /api/provider/report-parse/connect` | **不存在**（无 ProviderController） | SC-S-09 `provider.reportParse.connect` 商品服务商报告解析接入**未实现**；服务商（PROVIDER 角色）当前经 `/api/vendor/*`、`/api/admin/supply-*` 体系管理，无独立报告解析对接端点 |
+| `POST /api/health/report/compare` | **不存在** | SC-P-24/T-21 `health.report.compare` 报告对比由等价物承载：`/api/dan-report/compare`（DAN 两版对比）+ `/api/assessment/compare/*`（测评首次 vs 最新）。如需跨报告类型统一对比，待实现 |
+| `POST /api/health/report/trend` | **不存在** | SC-P-25 `health.report.trend` 由等价物承载：`/api/health/nutrition/trend` + `/api/food/recommendation/trend`（+ 既有 `/api/indicator/trend`、`/api/cognitive/trend`） |
+| `POST /api/health/report/diet` | **不存在** | SC-P-26 `health.report.dietRecommend` 由等价物承载：`/api/food/recommendation/*` + `/api/meal/*` + `/api/diet/*`（4.11） |
+| `POST /api/health/report/share` | **不存在** | SC-P-84 `health.report.share` 由等价物承载：`/api/share/*`（通用分享）+ `/api/health/report/member-permission/*`（成员级授权，4.59.4） |
+| `POST /api/health/report/refresh-dim` | **不存在** | SC-P-91 `health.report.refreshFiveDim` 无显式端点：五维能量重算在 `/report/confirm`、`/proxy-confirm`、`/report/reassign` 链内自动触发（`dimensionScoreService.refreshFromGutReport` + `refreshMemberIndicatorCurrent` + `recalculateForUser`）；如需手动重算入口待实现 |
+
+*文档更新：2026-11-06（B-2 报告闭环开工包契约核对补全：4.59.1 报告解析中台 `/api/admin/report-parse/*` + `dan/reparse`；4.59.2 健康报告全链路；4.59.3 代传闭环 `proxy-parse`/`proxy-confirm`；4.59.4 报告权限/分享；4.59.5 DAN 报告模块；4.59.6 趋势与饮食推荐；4.59.7 报告类型链接/检测；4.59.8 报告摘要；4.59.9 LangGraph 依赖登记；4.59.10 契约缺口与等价物映射）*