docs/报告代传功能核查报告.md(已合入 cfclub)运行态实锤 5 项 P0 + 8 项中低危缺陷,代传主链路完全不可用。origin/cfclub 最新(派发时以 git fetch origin cfclub 为准)。proxy_uploader_id / proxy_upload_note 列已存在:schema.sql:1863-1864,实体 HealthReport.java:114/117)。feature/proxy-fix-b1-coreproxyParsePreview(先决项,最高优先级)现状(HealthReportController.java proxyParsePreview,约 :2617):
storeFile → callLangGraphParse(透传 LangGraph 原始返回)→ 从 result 取 draftId(恒 null)→ updateNote 分支被跳过 → 返回 lgData。/api/v1/report/parse 不建草稿、不返回 draftId;非代传链路是「Java 先建草稿 → 调 LangGraph → updatePayload → buildParseResultFromLg 组装」。目标:复用非代传链路模式(照抄同文件 parseByDraftId :1055-1102 与 buildParseResultFromLg :1125-1163):
familyId 非空(保留现有 isProxyUploader)。storageService.storeFile(file, "health-reports") 存 OSS。healthReportDraftService.createDraft(userId, familyId, reportType, fileUrl, originalFilename, null)(reportType 传参默认 "auto" 时落 "gut_flora";签名见 HealthReportDraftService.java:47-75)。updateNote(draft.getId(), note)(note 非空时),确保草稿层带备注。storageService.getFilePath(fileUrl) → 调 LangGraph(复用 callLangGraphParse)。buildParseResultFromLg(lgData, draft, familyId) 组装返回体(自带 draftId/payload/matchedMemberId/extractedName/extractedGender/extractedAge/needBind/confidence/candidates)。parseLocalFallback(absolutePath, draft, familyId, userId)(同文件 :1164,本地 Java 兜底,签名一致可直接复用)。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 不可用(可模拟超时)时代传仍能本地解析入库。
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)。现状(HealthReportService.buildReportFromPayload,约 :1630 附近):report.setRemark("募极生物肠道菌群检测报告") 硬编码。
目标:改为 String remark = (draft.getRemark() != null && !draft.getRemark().isEmpty()) ? draft.getRemark() : "募极生物肠道菌群检测报告";(非代传草稿 remark 为空 → 行为不变)。
验收:代传草稿带 remark 时,正式报告 remark = 草稿 remark。
现状:后端 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解读,不再全是 '-'。
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", ...)。验收:代传确认响应体含 aiAnalysis(成功时)/ aiAnalysisStatus + aiAnalysisMessage(失败时);后端日志不再吞掉 analyze 异常。
现状:
listAllReportsForAdmin(HealthReportService.java:1174-1216 附近):map 无 title/createdAt/proxyUploaderName → ProxyReportUpload.vue:92(prop="title")、:97(formatTime(row.createdAt))恒空。/report/list 返回 List<HealthReport> 实体:实体无 subjectName/proxyUploaderName → ProxyReport.vue:94(row.subjectName || row.userName)、:112(row.proxyUploaderName)恒 '-'。目标(实现方式按项目既有惯例,先看同项目类似列表怎么补展示字段的,不要自创):
title(可用 personName + reportType 标签 拼或报告编号,前端有 typeLabel)、createdAt(报告创建时间)、proxyUploaderName(proxy_uploader_id join users 取姓名,无则 '-')。subjectName(subjectId → family_members 或 users 姓名)、proxyUploaderName。验收:admin 端「标题」「上传时间」列有值;teacher 端「报告对象」「代上传人」列有真实姓名。
feature/proxy-fix-b2-security⚠️ 全局影响面:B2-4(FamilyAccessInterceptor 空集拒绝)是全局安全策略变更,影响所有带 familyId 的路由(不止代传)。B2 会话必须:
grep -rn "familyId" cfc-backend/src/main/java/.../controller/ | grep -i mapping等穷举带 familyId 的路由清单;- 对每条路由判断「请求带 familyId 且用户有效家庭集为空」时,改后会被 403 —— 是否有正常业务依赖这种组合(例如新注册无家庭用户、DAN 报告、A2 采集);
- 若发现正常路径依赖「空集放行」,停下回报主理人裁决,不要擅自给拦截器加白名单绕过。
/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,且不新建任何家庭行。proxyParsePreview 增加 familyId 绑定校验(P1-2)现状:只校验角色,不校验 familyId 与代传人绑定关系;实际兜底靠 FamilyAccessInterceptor(对空有效家庭集放行 → 越权缺口)。
目标:在 B1 重构后的 proxyParsePreview 中,角色校验后、建草稿前,增加显式绑定校验(复用 AdminController.getFamilies 行级隔离口径;admin 跳过):familyId 不在调用者有效家庭集内 → return Result.error("无权为该家庭代传报告")。不依赖拦截器兜底(multipart body 不走 body 递归解析,见 B2-4 注)。
验收:未绑定家庭的 teacher/营养师账号代传 → 明确错误提示,不再成功。
proxyConfirm 校验草稿归属与可确认者(P1-2 补充)现状:auditConfirm 用前端传的 subjectId 直接匹配,不校验 subjectId 是否属于草稿 familyId;「代上传模式跳过草稿归属校验」注释即风险点。
目标:
auditConfirm(draftId, subjectId, auditorId) 内(或在 proxyConfirm 调用前):校验 draft.familyId 与 subjectId 对应成员所属家庭一致(family_members.family_id),不一致 → 明确错误。FamilyAccessInterceptor 空有效家庭集拒绝(P2-7,全局安全策略)现状(FamilyAccessInterceptor.java:60-63):effectiveFamilyIds 为 null/空 → return true 放行。空集 = 未绑定任何家庭的账号 → 权限反而最宽松,是本次实锤越权的根因。
目标:改为空集也继续校验:effectiveFamilyIds == null || isEmpty 时,若 collectFamilyIds(request) 非空 → 一律 403「无权访问该家庭数据」(enforcement 模式);requestedFamilyIds 为空则维持放行(不携带 familyId 的请求不受影响)。
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 的既有路由:报告列表/成员列表/任务等)。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。
proxyParsePreview 里加注释块说明三层校验编排:① 角色(isProxyUploader)② familyId 绑定(B2-2 显式校验)③ 拦截器兜底(B2-4)——明确「哪层失败返回什么码」。feature/proxy-fix-b3-robustanalysisResult 逻辑;按 B1-5 返回的 aiAnalysisStatus / aiAnalysisMessage 在确认成功后提示「AI 解读未完成:原因」而非静默。getActiveDraftOrThrow 抛错信息保持;前端确认失败时区分「草稿不存在或已过期」→ 提示重新上传,且支持基于 fileUrl 重新解析(复用原文件,不重新传 PDF):新增或复用接口按 fileUrl 重新 createDraft + 解析(本批实现时先看 /report/upload + /report/parse 两阶段链路能否复用;能复用则代传页改为「上传→预览→确认」三段式,不重建轮子)。parseLocalFallback 接进代传链路;本批验证该路径在 LangGraph 不可用时的真实表现,补齐错误提示文案(「解析服务暂不可用,已用本地解析」等)。/report/list 只收 size 忽略 page,返回 List → 前端 res.data.records 判断失败、翻页重复。page/size 返回分页结构(对齐项目分页惯例),或 teacher 页改走 admin-list 同款分页接口;两者选一,前端同步改。application.yml:134-138 附近 langgraph.base-url 默认 localhost:9000、生产需 LANGGRAPH_BASE_URL;uploads 目录需与 LangGraph 容器共享 volume。docs/ 部署/运维文档(找到现有部署文档,没有就追加到 AGENTS.md 或新建 docs/deployment/ 小节)补强制检查项清单。updateNote 命名澄清(4.8)HealthReportDraftService.updateNote(draftId, note) 实际写 remark 列(无 note 列)。updateRemark(draftId, remark) 并同步所有调用点;或保留方法名但加明确注释「写入 health_report_drafts.remark 列」。二选一,优先重命名(改动点少)。mvn -pl cfc-backend -am compile 通过(Java 8 + Spring Boot 2.7)。cfc-web 构建通过(本批若只改 .vue 且不影响构建,至少 npm run build 相关校验或跳过并在回报中说明)。192.168.16.251:3306,测试数据用完即删,照核查报告 §4.7 纪律)。T29-Bn 与改动摘要)并 git push -u origin feature/proxy-fix-bN-*。docs/superpowers/plans/2026-10-25-report-proxy-fix-plan.md,在 origin/cfclub)。开工第一步先读它,按文档实现,不要自行发挥。git fetch origin cfclub → 基于 B1: origin/cfclub / B2: 已含 B1 的 origin/cfclub / B3: 已含 B2 的 origin/cfclub 新建对应分支,不要合并主干 cfclub。git add 自己新增/修改的文件(禁止 git add .),提交前 git diff --cached --stat 自查。mvn -pl cfc-backend -am compile 通过,再做前端构建。git commit(提交信息写明 T29-Bn 与改动摘要)并 git push -u origin feature/proxy-fix-bN-*——无需等待主理人确认即可提交推送。