单一事实源(single source of truth)。 关联需求(用户原话):"现在有用户上传报告后,在小程序上查不到的情况,也无法对应到成员,在后台管理页面增加一个报告根据功能,查看上传的报告的处理情况,由哪个服务解析的解析出来的数据是什么,落在哪个成员身上了等等" 创建日期:2026-10-26 状态:设计完成,待派发
| 链路 | 入口 | 草稿/记录表 | 解析服务 | 最终落库 | 成员归因方式 |
|---|---|---|---|---|---|
| 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。
健康报告要出现在小程序列表,必须进入 health_reports 且被成员/家庭作用域命中。以下任一即"查不到":
collecting(异步采集未结束 / 卡死 / 线程池满)→ health_reports 无行。parseStatus=failed(非 PDF、类型不符、指标校验未过、LangGraph/opencode 解析空、已知类型重试耗尽)→ 不入库。status=pending/discarded(用户未确认 / 被丢弃)→ 不入库。report_unknown_upload,永不进入用户可见列表。draftStatus=pending(上传后未确认 confirmUpload)→ 不在已确认列表。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 过滤)。即便解析成功,用户也"查不到 / 对应不上成员"。matchFamilyMemberByName 也依赖 PDF 中 personName 与成员 nickname 精确/模糊命中;姓名缺失或不一致即归因失败(subjectId=null)。ReportParseAdminController)当前后台仅有 POST /api/admin/report-parse/{list,retry,backfill-food},只查 health_report_drafts(toRecordMap 字段:parseStatus/parseMethod/parseError/parseAttempt/nextRetryAt/confirmedReportId 等)。缺口:
dan_report_uploads / dan_assessment_results)的处理状态。report_unknown_upload / report_unknown_cluster)。health_reports 中 subject_id=null 或 family_id=null 的孤儿报告)。在后台管理页提供统一的报告处理链路追踪与归因视图,让运营/客服一眼看清:某次上传→走了哪个解析服务→解析出什么数据→落到哪个成员(或为何没落)→当前卡在哪。
ReportTraceAdminController + ReportTraceService + 前端 ReportTrace.vue(含详情抽屉、重试、手动归因)。ReportCollectService.submitAsyncCollect(draftId)、ReportParseAdminController.retry。DanReportUploadService.reparseUpload(uploadId, dimension)。HealthReportService.bindReportToMember(reportId, subjectId) 与 reassignReport(...)(已存在,第 ~1304 行)。ReportParserDispatchService.parseReport(pdfPath, fileName) 或 fingerprintService.detect 后重新入链。parseStatus 即可)。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 // 详情接口路径(后端内部路由)
}
| 源 | 关键字段取数 | 特别注意 |
|---|---|---|
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 长度/字段。 |
fileHash 相同视为同一份文件的不同处理记录,可在前端聚合展示(同一文件可能既有 draft 又有 report,属正常)。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 天趋势(运营看板用) |
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。ReportCollectService.submitAsyncCollect / reparseReportFoodsDanReportUploadService.reparseUpload / confirmUploadHealthReportService.bindReportToMember / reassignReport(~行 1304)ReportParserDispatchService.parseReport / fingerprintService.detectHealthReportDraftMapper.listPendingRetry / claimRetry(已有重试驱动器)cfc-web/src/views/admin/ReportTrace.vue)详情(抽屉)、重试(失败/采集中时可用)、归因(健康报告孤儿时可用)、查看原报告。/unknown-list 结果,展示 clusterKey / reportCount / status / 是否已生成类型。ReportParseAdminController 现有页一致);状态色:collecting=蓝、completed/confirmed=绿、failed=红、unknown=橙、未归因=红。为让"查不到"的用户能自查,建议在 C 端报告上传/列表页增加状态提示:上传后返回一个 traceToken,用户可在"我的上传"看到 collecting/解析中/解析失败(原因)/已入库;失败/未归因时引导联系客服并提供 traceId。后端可复用 health_report_drafts.parseStatus 与本文 traceId。本功能以后台为第一优先级,小程序提示作为 P2 后续。
dan_report_uploads)与未知上传(report_unknown_upload)的处理状态(此前不可见)。health_reports 中 subject_id=null 的孤儿报告,归因后小程序可见。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 拍板项)以便远端智能体取用。
health_reports.family_id=null 的孤儿,本功能"看得见"后需人工/批量归因;不要在后台功能里自动改 familyId(需管理员确认归属家庭,避免错绑)。health_report_drafts 量级大,列表需加索引(userId+parseStatus+updatedAt)或限时间区间。/api/admin/** 的 JwtInterceptor 拦截,无需新增鉴权。ReportParseAdminController、ReportCollectService、DanReportUploadService 的公开行为(仅调用)。