2026-10-25-report-proxy-fix-plan.md 17 KB

后台「报告代传」功能修复方案(T29,分三批)

  • 背景:docs/报告代传功能核查报告.md(已合入 cfclub)运行态实锤 5 项 P0 + 8 项中低危缺陷,代传主链路完全不可用。
  • 基线:origin/cfclub 最新(派发时以 git fetch origin cfclub 为准)。
  • 派发方式:分 B1 / B2 / B3 三批独立派发、独立分支、独立核验;B2 基于「B1 已合入的 cfclub」,B3 基于「B2 已合入的 cfclub」。
  • 迁移:本任务全部不需要新迁移(proxy_uploader_id / proxy_upload_note 列已存在:schema.sql:1863-1864,实体 HealthReport.java:114/117)。

批次 B1(功能可用性 + 数据正确性)— 分支 feature/proxy-fix-b1-core

B1-1 🔴 打通 draftId:重构 proxyParsePreview(先决项,最高优先级)

现状(HealthReportController.java proxyParsePreview,约 :2617):

  • storeFile → callLangGraphParse(透传 LangGraph 原始返回)→ 从 result 取 draftId(恒 null)→ updateNote 分支被跳过 → 返回 lgData。
  • 根因:LangGraph /api/v1/report/parse 不建草稿、不返回 draftId;非代传链路是「Java 先建草稿 → 调 LangGraph → updatePayload → buildParseResultFromLg 组装」。

目标:复用非代传链路模式(照抄同文件 parseByDraftId :1055-1102 与 buildParseResultFromLg :1125-1163):

  1. 校验角色 + familyId 非空(保留现有 isProxyUploader)。
  2. storageService.storeFile(file, "health-reports") 存 OSS。
  3. 先建草稿:healthReportDraftService.createDraft(userId, familyId, reportType, fileUrl, originalFilename, null)(reportType 传参默认 "auto" 时落 "gut_flora";签名见 HealthReportDraftService.java:47-75)。
  4. 建草稿后立即 updateNote(draft.getId(), note)(note 非空时),确保草稿层带备注。
  5. storageService.getFilePath(fileUrl) → 调 LangGraph(复用 callLangGraphParse)。
  6. 解析成功 → 调 buildParseResultFromLg(lgData, draft, familyId) 组装返回体(自带 draftId/payload/matchedMemberId/extractedName/extractedGender/extractedAge/needBind/confidence/candidates)。
  7. 解析失败 → 调 parseLocalFallback(absolutePath, draft, familyId, userId)(同文件 :1164,本地 Java 兜底,签名一致可直接复用)。
  8. 返回体补 fileUrl / proxyUploaderId / proxyUploadNote(保持前端既有字段契约:ProxyReportUpload.vue:39-41 读 extractedName / extractedReportNumber / extractedReportDate —— 注意:buildParseResultFromLg 只 put extractedName/Gender/Age,没有 extractedReportNumber / extractedReportDate。需要补:从 lgData 的 overview(report_number / report_date)读出来一并 put 进 result,否则预览三行仍 '-')。

验收:proxy-parse 返回体含 draftId(非 null)、payload、extractedName/extractedReportNumber/extractedReportDate、matchedMemberId/needBind;数据库草稿表新增 1 行 pending 且 remark 带 note;LangGraph 不可用(可模拟超时)时代传仍能本地解析入库。

B1-2 代传备注落库:setProxyUploader 增加 note 参数

现状(HealthReportService.java:2059-2066):只写 proxyUploaderId,proxy_upload_note 无任何写入路径。 目标:

  • 改签名 setProxyUploader(Long reportId, Long proxyUploaderId, String proxyUploadNote),内部 report.setProxyUploadNote(proxyUploadNote)。
  • HealthReportController.proxyConfirm(约 :2696):在 auditConfirm 前先 healthReportDraftService.getDraftById(draftId) 取 remark,confirm 后调用时传入。
  • 全仓库搜 setProxyUploader( 调用点,一并改签名(改签名必须同步所有调用点,禁止留下旧签名调用)。 验收:代传确认后 health_reports.proxy_upload_note = 代传时填的 note(实测查库确认,不再 NULL)。

B1-3 正式报告 remark:代传场景优先草稿 remark

现状(HealthReportService.buildReportFromPayload,约 :1630 附近):report.setRemark("募极生物肠道菌群检测报告") 硬编码。 目标:改为 String remark = (draft.getRemark() != null && !draft.getRemark().isEmpty()) ? draft.getRemark() : "募极生物肠道菌群检测报告";(非代传草稿 remark 为空 → 行为不变)。 验收:代传草稿带 remark 时,正式报告 remark = 草稿 remark。

B1-4 两个代传页「报告详情」弹窗字段全空

现状:后端 getReportDetail 返回嵌套 {report:{...}, indicators, ...};前端 ProxyReportUpload.vue:261 与 ProxyReport.vue 都 self.detailReport = res.data 按扁平取字段 → 全 undefined。 目标:两页都改为 self.detailReport = res.data.report || res.data(正确先例 admin/HealthReportEdit.vue:269 用 detail.report || {})。 验收:点「查看」弹窗显示报告ID/类型/编号/日期/总分/菌群分/肠型/肠道年龄/AI解读,不再全是 '-'。

B1-5 proxyConfirm 返回体带 AI 解读 + 失败状态

现状:auditConfirm 返回仅 {reportId, subjectId, status};triggerAiAnalysis(约 :2752)为 void,LangGraph analyze 失败被 catch 吞掉(log.warn),用户与主流程均无感知;实测 analyze 返回 500(部分可能是本地桩件环境,代码级缺陷「静默吞错」与运行环境无关,确定要修)。 目标:

  • triggerAiAnalysis 改为返回 Map<String,Object> aiResult:成功含 success=true, analysis, traceId;配额不足含 success=false, reason="quota", toast;LangGraph 失败含 success=false, reason="langgraph_failed", message。
  • proxyConfirm 把该结果并入返回体:result.put("aiAnalysis", analysis)(前端 res.data.aiAnalysis 已有读取逻辑,ProxyReportUpload.vue:216 / ProxyReport.vue:286)、result.put("aiAnalysisStatus", ...)、result.put("aiAnalysisMessage", ...)。
  • ⚠️ 本批只修代码层(失败不再静默 + 结果回传);「analyze 500 的生产环境复测」属部署验证,不属本批代码范围,方案末尾如实标注。

验收:代传确认响应体含 aiAnalysis(成功时)/ aiAnalysisStatus + aiAnalysisMessage(失败时);后端日志不再吞掉 analyze 异常。

B1-6 两个列表补字段(admin 标题/上传时间/代上传人;teacher 报告对象/代上传人)

现状:

  • admin 列表 listAllReportsForAdmin(HealthReportService.java:1174-1216 附近):map 无 title/createdAt/proxyUploaderName → ProxyReportUpload.vue:92(prop="title")、:97(formatTime(row.createdAt))恒空。
  • teacher 列表走 /report/list 返回 List<HealthReport> 实体:实体无 subjectName/proxyUploaderName → ProxyReport.vue:94(row.subjectName || row.userName)、:112(row.proxyUploaderName)恒 '-'。

目标(实现方式按项目既有惯例,先看同项目类似列表怎么补展示字段的,不要自创):

  • admin 列表:每行补 title(可用 personName + reportType 标签 拼或报告编号,前端有 typeLabel)、createdAt(报告创建时间)、proxyUploaderName(proxy_uploader_id join users 取姓名,无则 '-')。
  • teacher 列表:每行补 subjectName(subjectId → family_members 或 users 姓名)、proxyUploaderName。
  • 分页问题(/report/list 忽略 page 返回 List)不在本批处理,留 B3-4,本批只补字段。

验收:admin 端「标题」「上传时间」列有值;teacher 端「报告对象」「代上传人」列有真实姓名。


批次 B2(权限与越权 + 安全)— 分支 feature/proxy-fix-b2-security

⚠️ 全局影响面:B2-4(FamilyAccessInterceptor 空集拒绝)是全局安全策略变更,影响所有带 familyId 的路由(不止代传)。B2 会话必须:

  1. grep -rn "familyId" cfc-backend/src/main/java/.../controller/ | grep -i mapping 等穷举带 familyId 的路由清单;
  2. 对每条路由判断「请求带 familyId 且用户有效家庭集为空」时,改后会被 403 —— 是否有正常业务依赖这种组合(例如新注册无家庭用户、DAN 报告、A2 采集);
  3. 若发现正常路径依赖「空集放行」,停下回报主理人裁决,不要擅自给拦截器加白名单绕过。

B2-1 /api/family/member/list 支持 familyId + 行级隔离(P1-1)

现状(FamilyMembersController.java:62-81):完全忽略请求体 familyId,只按 @RequestAttribute("userId") 返回调用者自己家庭成员;无家庭时 ensureUserFamily(userId) 兜底自动建空家庭。teacher 选目标家庭后取成员被 FamilyAccessInterceptor 403 拦。 目标:

  • params.familyId 非空时:按该 familyId 返回家庭成员,并校验调用者访问权——admin 任意;teacher/营养师/规划师复用 AdminController.getFamilies(约 :767-805)的行级隔离口径(teacher_family_ids / 绑定关系)。
  • 删除 ensureUserFamily 兜底建家庭:无家庭/无可见成员 → 返回空列表,绝不静默建空家庭(排查 listMembers 全调用链,前端依赖空列表兜底的页面不受影响)。 验收:teacher 传自己的绑定 familyId → 返回该家庭全部成员;传无关 familyId → 空列表/403,且不新建任何家庭行。

B2-2 proxyParsePreview 增加 familyId 绑定校验(P1-2)

现状:只校验角色,不校验 familyId 与代传人绑定关系;实际兜底靠 FamilyAccessInterceptor(对空有效家庭集放行 → 越权缺口)。 目标:在 B1 重构后的 proxyParsePreview 中,角色校验后、建草稿前,增加显式绑定校验(复用 AdminController.getFamilies 行级隔离口径;admin 跳过):familyId 不在调用者有效家庭集内 → return Result.error("无权为该家庭代传报告")。不依赖拦截器兜底(multipart body 不走 body 递归解析,见 B2-4 注)。 验收:未绑定家庭的 teacher/营养师账号代传 → 明确错误提示,不再成功。

B2-3 proxyConfirm 校验草稿归属与可确认者(P1-2 补充)

现状:auditConfirm 用前端传的 subjectId 直接匹配,不校验 subjectId 是否属于草稿 familyId;「代上传模式跳过草稿归属校验」注释即风险点。 目标:

  • auditConfirm(draftId, subjectId, auditorId) 内(或在 proxyConfirm 调用前):校验 draft.familyId 与 subjectId 对应成员所属家庭一致(family_members.family_id),不一致 → 明确错误。
  • 草稿只能被「创建者本人」或「admin」确认;teacher/营养师只能确认自己创建的草稿。注意与正常审核链路(admin 审核他人草稿)兼容:admin 不受限。 验收:篡改 subjectId 为其他家庭成员 → 确认失败带原因;他人草稿非 admin 确认 → 拒绝。

B2-4 FamilyAccessInterceptor 空有效家庭集拒绝(P2-7,全局安全策略)

现状(FamilyAccessInterceptor.java:60-63):effectiveFamilyIds 为 null/空 → return true 放行。空集 = 未绑定任何家庭的账号 → 权限反而最宽松,是本次实锤越权的根因。 目标:改为空集也继续校验:effectiveFamilyIds == null || isEmpty 时,若 collectFamilyIds(request) 非空 → 一律 403「无权访问该家庭数据」(enforcement 模式);requestedFamilyIds 为空则维持放行(不携带 familyId 的请求不受影响)。

  • 注意 multipart 代传请求:collectFamilyIds 的 body 分支依赖 RequestBodyCachingFilter(只缓存 application/json),multipart 表单的 familyId 走 request.getParameter("familyId")(已有该分支)—— B2 实现时给 collectFamilyIds 补注释说明,并验证 multipart 路径能取到 familyId。 验收:按报告 §4.6 复现路径(family_id NULL + teacher_family_ids 空的新账号传 familyId=2009)→ 403;不带 familyId 的既有正常请求不受影响(回归抽查几条带 familyId 的既有路由:报告列表/成员列表/任务等)。

B2-5 proxy-parse / proxy-confirm 移入 LOGIN_REQUIRED_PATHS(P2-6)

现状(JwtInterceptor.java:80-81):两接口不在 PUBLIC 也不在 LOGIN_REQUIRED;无 token 请求被 setAnonymousUser 放行到 Controller 再返业务 500「无权限」——前端不跳登录。 目标:加入 LOGIN_REQUIRED_PATHS(该数组语义 = 无 token 直接 401)。 验收:无 token 调 proxy-parse → HTTP 401。

B2-6 权限校验编排说明(P1-2/P2-7 关系收口)

  • 在 B1 重构后的 proxyParsePreview 里加注释块说明三层校验编排:① 角色(isProxyUploader)② familyId 绑定(B2-2 显式校验)③ 拦截器兜底(B2-4)——明确「哪层失败返回什么码」。
  • 复现测试账号注意:测试后删除,不留残留(照核查报告 §4.7 纪律)。

批次 B3(健壮性与体验)— 分支 feature/proxy-fix-b3-robust

B3-1 配额不足/解读失败的 toast 文案前端化(P2-1)

  • 前端两页已有 analysisResult 逻辑;按 B1-5 返回的 aiAnalysisStatus / aiAnalysisMessage 在确认成功后提示「AI 解读未完成:原因」而非静默。

B3-2 草稿过期降级(P2-2)

  • 后端:getActiveDraftOrThrow 抛错信息保持;前端确认失败时区分「草稿不存在或已过期」→ 提示重新上传,且支持基于 fileUrl 重新解析(复用原文件,不重新传 PDF):新增或复用接口按 fileUrl 重新 createDraft + 解析(本批实现时先看 /report/upload + /report/parse 两阶段链路能否复用;能复用则代传页改为「上传→预览→确认」三段式,不重建轮子)。

B3-3 LangGraph 失败本地兜底(P2-4)

  • B1-1 已把 parseLocalFallback 接进代传链路;本批验证该路径在 LangGraph 不可用时的真实表现,补齐错误提示文案(「解析服务暂不可用,已用本地解析」等)。

B3-4 teacher 端列表分页修复(P1-4 分页部分)

  • /report/list 只收 size 忽略 page,返回 List → 前端 res.data.records 判断失败、翻页重复。
  • 目标:支持 page/size 返回分页结构(对齐项目分页惯例),或 teacher 页改走 admin-list 同款分页接口;两者选一,前端同步改。
  • ⚠️ 该接口同时被小程序报告列表页使用——改动必须兼容小程序端现有调用(默认不传 page 时行为与现一致)。

B3-5 部署文档补环境依赖(P2-8)

  • application.yml:134-138 附近 langgraph.base-url 默认 localhost:9000、生产需 LANGGRAPH_BASE_URL;uploads 目录需与 LangGraph 容器共享 volume。
  • 在 docs/ 部署/运维文档(找到现有部署文档,没有就追加到 AGENTS.md 或新建 docs/deployment/ 小节)补强制检查项清单。

B3-6 updateNote 命名澄清(4.8)

  • HealthReportDraftService.updateNote(draftId, note) 实际写 remark 列(无 note 列)。
  • 目标:重命名为 updateRemark(draftId, remark) 并同步所有调用点;或保留方法名但加明确注释「写入 health_report_drafts.remark 列」。二选一,优先重命名(改动点少)。

验收与自检清单(每批通用)

  1. mvn -pl cfc-backend -am compile 通过(Java 8 + Spring Boot 2.7)。
  2. 前端改动页无语法错误;cfc-web 构建通过(本批若只改 .vue 且不影响构建,至少 npm run build 相关校验或跳过并在回报中说明)。
  3. 运行态验证:按批次验收口径逐条实测(测试库用 192.168.16.251:3306,测试数据用完即删,照核查报告 §4.7 纪律)。
  4. 每批独立 commit(信息含 T29-Bn 与改动摘要)并 git push -u origin feature/proxy-fix-bN-*。

交付纪律(三批通用,违反=退回重做)

  1. 规格文档:本文件(docs/superpowers/plans/2026-10-25-report-proxy-fix-plan.md,在 origin/cfclub)。开工第一步先读它,按文档实现,不要自行发挥。
  2. 基线:git fetch origin cfclub → 基于 B1: origin/cfclub / B2: 已含 B1 的 origin/cfclub / B3: 已含 B2 的 origin/cfclub 新建对应分支,不要合并主干 cfclub。
  3. 只 git add 自己新增/修改的文件(禁止 git add .),提交前 git diff --cached --stat 自查。
  4. 先 mvn -pl cfc-backend -am compile 通过,再做前端构建。
  5. 完成后自行 git commit(提交信息写明 T29-Bn 与改动摘要)并 git push -u origin feature/proxy-fix-bN-*——无需等待主理人确认即可提交推送。
  6. 不要自行合并 cfclub(合入由主理人分批执行)。
  7. 若规格与代码实际不符(找不到对应文件/接口形态与描述明显不同),停下并回报,不要凭空实现。
  8. ⚠️ 本任务不涉及删数据/删行/迁移外键/改 UNIQUE 约束/新建表(无迁移)。若实现中发现必须做这些不可逆操作,先停下回报主理人确认。
  9. ⚠️ B2-4 为全局策略变更,若发现正常业务依赖旧「空集放行」行为,停下回报,不擅自白名单。

回报内容要求(会话完成时)

  • 分支名 + commit 哈希(逐个 commit 列出)
  • 改动文件清单(按 B 批内条目号组织,如 B1-1 ~ B1-6)
  • 编译/构建结果(mvn compile 输出摘要)
  • 运行态验证逐条结论(每项 AC:通过/未验证/失败+原因)
  • 遗留问题与风险(含「analyze 500 需生产复测」的明确标注)