2026-10-26-report-trace-design.md 17 KB

后台「报告处理链路追踪 / 归因」功能设计

单一事实源(single source of truth)。 关联需求(用户原话):"现在有用户上传报告后,在小程序上查不到的情况,也无法对应到成员,在后台管理页面增加一个报告根据功能,查看上传的报告的处理情况,由哪个服务解析的解析出来的数据是什么,落在哪个成员身上了等等" 创建日期:2026-10-26 状态:设计完成,待派发


一、问题根因诊断(先确诊,再开功能)

1.1 两条上传主链路(已读源码确认)

链路 入口 草稿/记录表 解析服务 最终落库 成员归因方式
A. 健康报告(体检/菌群) POST /api/report-parser/upload → ReportParserController.uploadAndParse → 建 HealthReportDraft → ReportCollectService.collect() 异步 health_report_drafts 指纹判定 → LangGraphReportParseService(已知类型脚本 / 无指纹 detect)→ 失败回退 opencode 本地服务 health_reports + health_indicators / health_gut_flora / health_disease_risks 按 PDF 提取的 personName 调 HealthReportService.matchFamilyMemberByName(name, familyId) 命中成员;命中则 bindReportToMember
B. DAN 测评报告(专用) DanReportUploadService.uploadAndParse(userId, memberId, dimension, file)(由 DanReportController 等调用) dan_report_uploads DanReportParseService.parse(Java 同步解析) dan_assessment_results memberId 必填,上传即绑定 familyMemberId 与 familyId

注:链路 A 内部对"指纹识别为 dan_* 家族"的报告会调 collectDanReport 走 DAN 入库,但要求 draft.memberId 非空,而 /api/report-parser/upload 建草稿时 memberId=null → 必失败("请重新上传并选择报告归属成员")。即:经链路 A 上传的 DAN 报告必然卡在 failed。

1.2 "小程序查不到"的根因

健康报告要出现在小程序列表,必须进入 health_reports 且被成员/家庭作用域命中。以下任一即"查不到":

  1. 草稿卡在 collecting(异步采集未结束 / 卡死 / 线程池满)→ health_reports 无行。
  2. 草稿 parseStatus=failed(非 PDF、类型不符、指标校验未过、LangGraph/opencode 解析空、已知类型重试耗尽)→ 不入库。
  3. 草稿 status=pending/discarded(用户未确认 / 被丢弃)→ 不入库。
  4. 未知类型 → 落入 report_unknown_upload,永不进入用户可见列表。
  5. DAN 报告 draftStatus=pending(上传后未确认 confirmUpload)→ 不在已确认列表。

1.3 "无法对应到成员"的根因(核心)

  • 链路 A 建草稿时 familyId=null、memberId=null(ReportParserController.uploadAndParse 调用 createDraft(userId, null, "gut_flora", ...))。
  • ReportCollectService.insertReport 中:if (draft.getFamilyId() != null && payload.getSummary() != null && personName != null) subjectId = matchFamilyMemberByName(...) —— familyId 为 null 时整段跳过,subjectId 恒为 null。
  • 结果:health_reports.family_id=null、subject_id=null → 报告在家庭成员维度完全不可见(小程序按 family/member 过滤)。即便解析成功,用户也"查不到 / 对应不上成员"。
  • 即便 familyId 被正确传入,姓名匹配 matchFamilyMemberByName 也依赖 PDF 中 personName 与成员 nickname 精确/模糊命中;姓名缺失或不一致即归因失败(subjectId=null)。
  • DAN 链路因 memberId 必填,归因天然正确,但其数据在独立表,当前后台完全看不到处理状态(见 §1.4)。

1.4 现有后台能力的缺口(已读 ReportParseAdminController)

当前后台仅有 POST /api/admin/report-parse/{list,retry,backfill-food},只查 health_report_drafts(toRecordMap 字段:parseStatus/parseMethod/parseError/parseAttempt/nextRetryAt/confirmedReportId 等)。缺口:

  1. 看不到 DAN 上传(dan_report_uploads / dan_assessment_results)的处理状态。
  2. 看不到未知上传(report_unknown_upload / report_unknown_cluster)。
  3. 看不到"已入库但未归因"的健康报告(health_reports 中 subject_id=null 或 family_id=null 的孤儿报告)。
  4. 看不到成员归因结果本身(落在哪个成员、为何没落)。
  5. 无统一搜索——不能按 userId / familyId / memberId / fileHash / 文件名 / 时间区间跨表联查。
  6. 无解析数据摘要——看不到"解析出了什么"(指标数 / 菌群数 / 疾病风险数 / 综合分)。

二、设计目标与范围

2.1 目标

在后台管理页提供统一的报告处理链路追踪与归因视图,让运营/客服一眼看清:某次上传→走了哪个解析服务→解析出什么数据→落到哪个成员(或为何没落)→当前卡在哪。

2.2 范围

  • 后台新增:ReportTraceAdminController + ReportTraceService + 前端 ReportTrace.vue(含详情抽屉、重试、手动归因)。
  • 复用既有能力(不重复造):
    • 健康草稿重试:ReportCollectService.submitAsyncCollect(draftId)、ReportParseAdminController.retry。
    • DAN 重解析:DanReportUploadService.reparseUpload(uploadId, dimension)。
    • 健康报告手动归因:HealthReportService.bindReportToMember(reportId, subjectId) 与 reassignReport(...)(已存在,第 ~1304 行)。
    • 未知上传重识别:调 ReportParserDispatchService.parseReport(pdfPath, fileName) 或 fingerprintService.detect 后重新入链。
  • 不做:不改小程序上传主链路(§四 根因修复单列任务,本功能先"看得见"再谈"修得上");不改动解析算法。

2.3 非目标

  • 不自动修复历史孤儿报告(提供手动归因 + 批量归因工具按钮,由人工确认)。
  • 不做实时流式进度(轮询现有 parseStatus 即可)。

三、统一 Trace 视图(数据模型)

3.1 Trace Node 归一化结构(后端 ReportTraceService 组装)

每个"上传事件"归一为一个 trace node:

TraceNode {
  traceId          // 全局唯一展示ID,形如 sourceType + ":" + 原表主键
  sourceType       // health_draft | health_report | dan_upload | unknown
  uploaderUserId   // 上传人
  uploaderName?    // 关联 users.realName/nickname(可选展示)
  familyId         // 归属家庭(可能 null)
  memberId         // 落地成员(可能 null)
  memberName?      // 成员昵称(subjectId 或 familyMemberId 解析)
  fileName         // 原始文件名
  fileUrl          // 文件地址
  fileHash?        // 去重用
  selectedType     // 用户/系统所选报告类型(reportType / dimension / typeId)
  parseService     // 解析服务:langgraph_script | langgraph_detect | opencode | dan_java | unknown_llm | (pending)
  parseStatus      // collecting | completed | failed | pending | confirmed | unknown | (null)
  parseError?      // 失败原因
  parseMethod?     // 来自草稿 parseMethod 字段,便于核对
  landedReportId?  // 最终落地报告主键(health_reports.id / dan_assessment_results.id)
  landedTable      // health_reports | dan_assessment_results
  attributed       // true/false:是否已正确落到成员(memberId 非空且 familyId 非空)
  attrReason?      // 未归因原因:familyId_null | name_no_match | member_not_selected | (null=已归因)
  dataSummary {    // 解析数据摘要
    overallScore?
    indicatorCount?
    gutFloraCount?
    diseaseRiskCount?
    itemCount?     // DAN items 数
    hasPayload?    // payload_json 是否存在
  }
  uploadedAt
  updatedAt
  detailApi        // 详情接口路径(后端内部路由)
}

3.2 四表 → TraceNode 映射要点

源 关键字段取数 特别注意
health_report_drafts userId, familyId(多为null), memberId(多为null), reportType, originalFilename, fileUrl, fileHash, parseStatus, parseMethod, parseError, confirmedReportId, createdAt, updatedAt attributed=false 当 familyId=null 或 (confirmedReportId 非空但对应 health_reports.subject_id=null)。parseService 取 parseMethod;landedReportId=confirmedReportId。
health_reports userId, familyId, subjectId, reportType, personName, overallScore, fileUrl, fileHash, createdAt 补捞"已入库但 subject_id=null/family_id=null"的孤儿报告(链路 A 的遗留产物),attrReason=familyId_null 或 name_no_match。dataSummary 取 overallScore + 关联 indicators/gutFlora/diseaseRisks 计数。
dan_report_uploads familyMemberId, familyId, uploaderUserId, dimension, fileName, fileUrl, parseStatus, draftStatus, reportType, parsedItems, parsedSummary, linkedResultId, uploadedAt, updatedAt attributed=true(memberId 必填)。parseService=dan_java。landedReportId=linkedResultId(dan_assessment_results.id)。dataSummary.itemCount=parsedItems JSON 数组长度。如 draftStatus=pending 则 parseStatus 沿用 parseStatus(pending/success/failed)。
report_unknown_upload clusterId, fileUrl, fileHash, llmResult, uploadedAt sourceType=unknown;parseService=unknown_llm;attributed=false;attrReason="未知类型未识别";landedReportId=null;dataSummary 取 llmResult 长度/字段。

3.3 联查与去重

  • 列表接口按入参(userId/familyId/memberId/fileHash/fileName 模糊/状态/时间区间/sourceType)分别查四表后内存归并排序(数据量小,避免跨表 JOIN 复杂度)。
  • fileHash 相同视为同一份文件的不同处理记录,可在前端聚合展示(同一文件可能既有 draft 又有 report,属正常)。
  • 分页:先按时间倒序取各表 top-N 再合并,简单可行;后续量大可改为按时间分桶。

四、后端接口设计

4.1 ReportTraceAdminController(/api/admin/report-trace)

方法 路径 说明
POST /list 统一联查列表,入参同 §3.3;返回 {total, records: TraceNode[]}
POST /detail 入参 traceId(或 sourceType + id);返回该上传的完整链路:草稿/记录原始字段 + payload_json 预览(截断) + 指标/菌群/风险计数 + 校验结果(collect_validation) + 关联落地报告 + 成员归属 + 失败原因 + 重试次数
POST /retry 入参 traceId;按 sourceType 路由重试:health_draft→reportCollectService.submitAsyncCollect;dan_upload→danReportUploadService.reparseUpload(id, dimension);unknown→重识别后入链
POST /bind-member 入参 reportId(health_reports.id) + memberId;对孤儿健康报告手动归因:healthReportService.bindReportToMember + 必要时回填 familyId + 刷新五维/食材推荐(复用 reassignReport 逻辑或简化版)。仅对 health_reports 的孤儿生效,需管理员二次确认(前端弹窗)
POST /unknown-list 查看 report_unknown_cluster(聚类)与明细,辅助"为什么识别不了"
POST /stats 概览:各 sourceType 总量、failed/collecting/未归因 数量、近 7 天趋势(运营看板用)

4.2 ReportTraceService(新建)

  • buildTraceList(params):四表联查 + 归一化 + 排序。
  • buildTraceDetail(...):调各 service 取完整数据(HealthReportDraftMapper / HealthReportMapper / DanReportUploadMapper / DanAssessmentResultMapper / ReportUnknownUploadMapper + indicator/gutFlora/diseaseRisk 计数)。
  • retryBySource(...) / bindMember(...):路由到既有能力。
  • 成员名解析:familyMemberMapper 取 nickname;userMapper 取 realName/nickname。
  • 孤儿识别:health_reports 中 subject_id is null 或 family_id is null → attributed=false。

4.3 复用与依赖(已在仓库,无需新建)

  • ReportCollectService.submitAsyncCollect / reparseReportFoods
  • DanReportUploadService.reparseUpload / confirmUpload
  • HealthReportService.bindReportToMember / reassignReport(~行 1304)
  • ReportParserDispatchService.parseReport / fingerprintService.detect
  • HealthReportDraftMapper.listPendingRetry / claimRetry(已有重试驱动器)

五、前端页面设计(cfc-web/src/views/admin/ReportTrace.vue)

5.1 布局

  • 顶部筛选区:userId / familyId / memberId / 文件名(模糊) / fileHash / sourceType(全部/健康草稿/健康报告/DAN/未知) / 状态(全部/采集中/失败/已入库未归因/未知) / 时间区间。
  • 结果表格(TraceNode 字段):上传人、类型、文件名、解析服务、解析状态(彩色徽标)、是否已归因(✓/✗+原因)、落地报告ID、数据摘要(指标数/菌群数/分数)、上传时间。
  • 行操作:详情(抽屉)、重试(失败/采集中时可用)、归因(健康报告孤儿时可用)、查看原报告。
  • 未知聚类区:/unknown-list 结果,展示 clusterKey / reportCount / status / 是否已生成类型。

5.2 详情抽屉

  • 链路时间线:上传 → 解析服务/方式 → 解析结果摘要 → 入库/失败 → 成员归属。
  • 原文/解析数据预览(payload_json 折叠,超长截断)。
  • 失败原因、重试次数、校验结果(collect_validation)。
  • 成员归因面板:当前 subjectId/memberId + 名称;未归因显示醒目"未落到成员"红标 + 一键归因按钮(弹窗选成员)。

5.3 配色与纪律

  • 复用后台既有 UI 框架(与 ReportParseAdminController 现有页一致);状态色:collecting=蓝、completed/confirmed=绿、failed=红、unknown=橙、未归因=红。
  • 不改变既有页面,新增独立菜单项"报告链路追踪"。

六、小程序侧辅助(可选,建议同步做)

为让"查不到"的用户能自查,建议在 C 端报告上传/列表页增加状态提示:上传后返回一个 traceToken,用户可在"我的上传"看到 collecting/解析中/解析失败(原因)/已入库;失败/未归因时引导联系客服并提供 traceId。后端可复用 health_report_drafts.parseStatus 与本文 traceId。本功能以后台为第一优先级,小程序提示作为 P2 后续。


七、验收标准

  1. 后台"报告链路追踪"页可按 userId/familyId/memberId/文件名/hash 跨四表联查,列表含:解析服务、解析状态、是否已归因+原因、落地报告ID、数据摘要。
  2. 详情抽屉能展示某次上传的完整链路(上传→服务→数据→落地成员/失败原因)。
  3. 能看清 DAN 上传(dan_report_uploads)与未知上传(report_unknown_upload)的处理状态(此前不可见)。
  4. 能列出并手动归因 health_reports 中 subject_id=null 的孤儿报告,归因后小程序可见。
  5. 失败/采集中记录可在后台一键重试(路由到正确服务)。
  6. 不动小程序上传主链路与解析算法;既有 report-parse 管理接口保持可用。

八、任务分解(供派发)

子任务 内容 模块
T1 ReportTraceService + 四表联查归一化(buildTraceList/buildTraceDetail) backend
T2 ReportTraceAdminController 六个接口(list/detail/retry/bind-member/unknown-list/stats) backend
T3 孤儿健康报告手动归因(bind-member 落地:回填 familyId + bindReportToMember + 刷新五维/食材) backend
T4 DAN / 未知 重试路由实现 backend
T5 前端 ReportTrace.vue(筛选+表格+详情抽屉+重试/归因按钮) frontend
T6 联调 + mvn/npm 构建 + 自测(含一条孤儿归因、一条 DAN、一条 unknown 的端到端验证) 联调
T7(P2) 小程序"我的上传"状态提示(traceToken) frontend

派发纪律:本设计文档定稿后登记入 tasks_backlog.json(pending,批次 R1),由定时巡检按完成进度派发;不直接派发。关联 plan 文档需先 push 至 origin/cfclub(lead_backlog 拍板项)以便远端智能体取用。


九、风险与注意

  1. familyId=null 的遗留报告:链路 A 历史已产生大量 health_reports.family_id=null 的孤儿,本功能"看得见"后需人工/批量归因;不要在后台功能里自动改 familyId(需管理员确认归属家庭,避免错绑)。
  2. DAN 经链路 A 上传必失败:这是独立 bug,应在溯源报告中单独列出,可单列修复任务(上传时若识别为 DAN 自动引导走 DAN 专用链路 / 要求选成员),不在本功能范围。
  3. 性能:四表内存归并仅适合当前数据量;若 health_report_drafts 量级大,列表需加索引(userId+parseStatus+updatedAt)或限时间区间。
  4. 权限:接口走既有 /api/admin/** 的 JwtInterceptor 拦截,无需新增鉴权。
  5. 不破坏既有:新增独立 Controller/Service/页面,不改动 ReportParseAdminController、ReportCollectService、DanReportUploadService 的公开行为(仅调用)。