Преглед на файлове

docs: 浠艾福谷禾新版解析与五维归因升级方案 v1.0(guhe_v2 解析 + Python 主路径 + 异常菌接口 + 归因归一化 + 红线落地)

Agnes Agent преди 10 часа
родител
ревизия
ef8eb62bed

+ 626 - 0
docs/浠艾福程序-谷禾新版解析与五维归因升级方案-v1.0.html

@@ -0,0 +1,626 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>浠艾福程序 · 谷禾新版解析与五维归因升级方案 v1.0</title>
+<meta name="description" content="把 bun-report-parser v1.3.1 与 socratic-coach v1.8.0 能力接入浠艾福线上上传-解析-五维归因-健康计划主链路:Java 指纹识别分流 + Python 主导解析 + 异常菌清单接口 + 归一化真数据填充 + 归因禁区落地。">
+<meta name="keywords" content="浠艾福,菌群报告解析,谷禾新版,guhe_v2,五维归因,本质归因,物种功能库,归因禁区,健康计划,升级方案">
+<style>
+:root{
+  --purple:#5B3A8E; --purple-d:#3B2460; --purple-l:#F5F1FB;
+  --amber:#B45309; --amber-l:#FEF3E2; --ink:#1F2430; --muted:#6B7280;
+  --line:#E6E1EF; --bg:#FFFFFF;
+}
+*{box-sizing:border-box}
+html{-webkit-text-size-adjust:100%}
+body{
+  margin:0; background:#F7F5FA; color:var(--ink);
+  font-family:"Microsoft YaHei","PingFang SC","Hiragino Sans GB",-apple-system,sans-serif;
+  font-size:15.5px; line-height:1.85; letter-spacing:.1px;
+}
+.page{max-width:1000px; margin:0 auto; background:var(--bg); padding:56px 64px 72px;
+  box-shadow:0 1px 3px rgba(31,36,48,.06);}
+h1{font-size:29px; line-height:1.4; margin:0 0 8px; color:var(--purple-d); letter-spacing:.5px;}
+h1 + blockquote{margin-top:18px}
+h2{font-size:22px; color:var(--purple-d); margin:44px 0 16px; padding:0 0 0 14px;
+  border-left:5px solid var(--purple); line-height:1.5;}
+h3{font-size:18px; color:var(--purple); margin:30px 0 12px;}
+h4{font-size:16px; color:var(--purple-d); margin:22px 0 10px;}
+p{margin:10px 0}
+strong{color:#141821; font-weight:700}
+a{color:var(--purple)}
+blockquote{margin:18px 0; padding:16px 20px; background:var(--purple-l);
+  border-left:4px solid var(--purple); border-radius:0 6px 6px 0; color:#3A3350;
+  font-size:14.6px; line-height:1.8;}
+blockquote p{margin:6px 0}
+blockquote strong{color:var(--purple-d)}
+ul,ol{padding-left:24px; margin:10px 0}
+li{margin:5px 0}
+hr{border:0; border-top:1px solid var(--line); margin:36px 0}
+table{width:100%; border-collapse:collapse; margin:16px 0 22px; font-size:14.2px; line-height:1.65;
+  table-layout:auto;}
+thead th{background:#EFE9F8; color:var(--purple-d); font-weight:700; text-align:left;
+  padding:9px 11px; border:1px solid var(--line); white-space:nowrap;}
+tbody td{padding:9px 11px; border:1px solid var(--line); vertical-align:top;}
+.page table th:first-child, .page table td:first-child{min-width:86px;}
+tbody tr:nth-child(even){background:#FAF8FD}
+tbody tr:hover{background:#F5F1FB}
+pre{background:#F7F5FA; border:1px solid var(--line); border-radius:8px; padding:16px 18px;
+  overflow:auto; font-size:13px; line-height:1.55;}
+pre code{font-family:"Cascadia Mono",Consolas,"Courier New",monospace; color:#2B2340;}
+code{background:#F1EDF8; padding:1.5px 5px; border-radius:4px; font-size:13.2px;}
+pre code{background:none; padding:0}
+figure.fig{margin:26px 0 30px; padding:12px; background:#FCFBFE; border:1px solid var(--line);
+  border-radius:10px;}
+figure.fig svg{width:100%; height:auto; display:block;}
+figure.fig figcaption{font-size:12.6px; color:var(--muted); text-align:center; margin-top:8px;}
+h1 + blockquote{background:linear-gradient(180deg,#F8F4FE,#FDFCFF)}
+@page{size:A4; margin:14mm 13mm 16mm;}
+@media print{
+  body{background:#fff; font-size:10.6pt; line-height:1.7}
+  .page{box-shadow:none; padding:0; max-width:none}
+  h1{font-size:19pt}
+  h2{font-size:13.5pt; page-break-after:avoid; margin-top:22pt}
+  h3{font-size:11.6pt; page-break-after:avoid}
+  table{font-size:8.4pt; page-break-inside:auto; width:100% !important; table-layout:auto; display:table !important; overflow:visible !important}
+  thead th{white-space:normal !important; word-break:break-word}
+  .page table th:first-child, .page table td:first-child{min-width:74px}
+  th,td{word-break:break-word; overflow-wrap:anywhere}
+  tr{page-break-inside:avoid}
+  thead{display:table-header-group}
+  blockquote{page-break-inside:avoid}
+  figure.fig{page-break-inside:avoid}
+  pre{page-break-inside:avoid; font-size:8.4pt}
+  a{color:inherit; text-decoration:none}
+}
+@media screen and (max-width:760px){
+  .page{padding:26px 18px 40px}
+  h1{font-size:23px} h2{font-size:19px} h3{font-size:16.5px}
+  body{font-size:14.8px}
+  table{font-size:13px; display:block; overflow-x:auto; white-space:nowrap}
+}
+
+@media print {
+  pre { white-space: pre-wrap !important; word-break: break-word; overflow: visible !important; }
+  pre code { white-space: pre-wrap !important; word-break: break-word; }
+}
+</style>
+</head>
+<body>
+<main class="page">
+<h1 id="_1">浠艾福线上程序 · 谷禾新版解析与五维归因升级方案</h1>
+
+<svg viewBox="0 0 680 268" width="100%" role="img" aria-label="浠艾福解析链路升级前后对比"
+     style="display:block;margin:14px 0 22px;font-family:'Noto Sans SC','Microsoft YaHei',sans-serif">
+  <rect x="0" y="0" width="680" height="268" fill="#FAF8FD" rx="10"/>
+  <text x="18" y="26" font-size="13" font-weight="700" fill="#5B3A8E">升级前:双链路,均无谷禾新版能力</text>
+
+  <g font-size="10.5" fill="#2C2438">
+    <rect x="18" y="40" width="150" height="46" rx="6" fill="#FFFFFF" stroke="#C9B8E4"/>
+    <text x="28" y="58" font-weight="700" fill="#5B3A8E">上传 PDF</text>
+    <text x="28" y="76">/api/health/report/upload</text>
+    <rect x="196" y="40" width="200" height="46" rx="6" fill="#FEECEC" stroke="#DC8A8A"/>
+    <text x="206" y="58" font-weight="700" fill="#9B2C2C">① Java 一步式解析</text>
+    <text x="206" y="76">PdfParseService · 白名单/triplet</text>
+    <rect x="424" y="40" width="238" height="46" rx="6" fill="#FEECEC" stroke="#DC8A8A"/>
+    <text x="434" y="58" font-weight="700" fill="#9B2C2C">② langgraph 异步兜底</text>
+    <text x="434" y="76">v5 移植 + LLM · 无物种功能库字段</text>
+  </g>
+  <g font-size="10.5">
+    <path d="M168 63 L196 63" stroke="#9B2C2C" stroke-width="1.5" fill="none"/>
+    <path d="M168 70 Q182 92 196 70" stroke="#9B2C2C" stroke-width="1.5" fill="none"/>
+  </g>
+
+  <text x="18" y="120" font-size="13" font-weight="700" fill="#5B3A8E">升级后:识别分流,guhe_v2 走 Python 主路径</text>
+
+  <g font-size="10.5" fill="#2C2438">
+    <rect x="18" y="134" width="120" height="46" rx="6" fill="#FFFFFF" stroke="#C9B8E4"/>
+    <text x="28" y="152" font-weight="700" fill="#5B3A8E">上传 PDF</text>
+    <text x="28" y="170">上传接口不变</text>
+    <rect x="158" y="134" width="140" height="46" rx="6" fill="#FEF3E2" stroke="#B45309"/>
+    <text x="168" y="152" font-weight="700" fill="#8A3F08">Java 指纹识别</text>
+    <text x="168" y="170">detectGuheV2()</text>
+    <rect x="318" y="134" width="164" height="46" rx="6" fill="#E9F5F1" stroke="#2F8F7A"/>
+    <text x="328" y="152" font-weight="700" fill="#1F6B58">guhe_v2 → Python 主路径</text>
+    <text x="328" y="170">复用 bun-report-parser v1.3.1</text>
+    <rect x="502" y="134" width="160" height="46" rx="6" fill="#FFFFFF" stroke="#C9B8E4"/>
+    <text x="512" y="152" font-weight="700" fill="#5B3A8E">完整 payload 落库</text>
+    <text x="512" y="170">35 键 + _解析自检</text>
+  </g>
+  <g font-size="10.5">
+    <path d="M138 157 L158 157" stroke="#B45309" stroke-width="1.5" fill="none"/>
+    <path d="M298 157 L318 157" stroke="#2F8F7A" stroke-width="1.5" fill="none"/>
+    <path d="M482 157 L502 157" stroke="#2F8F7A" stroke-width="1.5" fill="none"/>
+  </g>
+
+  <g font-size="10.5" fill="#2C2438">
+    <rect x="18" y="202" width="196" height="46" rx="6" fill="#E9F5F1" stroke="#2F8F7A"/>
+    <text x="28" y="220" font-weight="700" fill="#1F6B58">异常菌清单接口</text>
+    <text x="28" y="238">/abnormal-species · 12 条 ▲ 直出</text>
+    <rect x="234" y="202" width="188" height="46" rx="6" fill="#E9F5F1" stroke="#2F8F7A"/>
+    <text x="244" y="220" font-weight="700" fill="#1F6B58">归一化真数据填充</text>
+    <text x="244" y="238">17 份样本回归 → 百分位带</text>
+    <rect x="442" y="202" width="220" height="46" rx="6" fill="#E9F5F1" stroke="#2F8F7A"/>
+    <text x="452" y="220" font-weight="700" fill="#1F6B58">五维归因 + 健康计划</text>
+    <text x="452" y="238">§8.1 归因禁区 / §5.8 介导链路审计</text>
+  </g>
+  <g font-size="10.5">
+    <path d="M582 180 L582 192 L116 192 L116 202" stroke="#2F8F7A" stroke-width="1.5" fill="none"/>
+    <path d="M328 192 L328 202" stroke="#2F8F7A" stroke-width="1.5" fill="none"/>
+    <path d="M552 192 L552 202" stroke="#2F8F7A" stroke-width="1.5" fill="none"/>
+  </g>
+  <text x="18" y="264" font-size="10" fill="#6B7280">架构决策:Python 主导复用上游模块(约 2 人日) vs Java 重写解析(约 8–10 人日);归因禁区与介导链路纪律随 socratic-coach v1.8.0 一并落地</text>
+</svg>
+<p><strong>版本</strong>:v1.0(2026-11-16 起草)
+<strong>依据</strong>:<code>bun-report-parser v1.3.1</code>(物种功能库四键 + <code>_解析自检</code>)+ <code>socratic-coach v1.8.0</code>(§8.1 归因禁区 + 介导链路纪律)
+<strong>读者</strong>:浠艾福技术负责人 / 后端 / langgraph / 前端 / 产品</p>
+<blockquote>
+<p>口径提示(§1.2 事实源分级):本文所有结论分三级标注——<strong>〔代码〕</strong>=已读源码确认;<strong>〔配置〕</strong>=已读配置/JSON 确认;<strong>〔假设〕</strong>=基于现有能力的合理推断,待代码 review 或跑通验证。凡涉及医学/健康结论的行文一律「相关联 / 报告提示」,禁用「导致 / 治愈 / 改善」。</p>
+</blockquote>
+<hr>
+<h2 id="_2">一、目标与范围(一句话)</h2>
+<p>把已在本机实测通过的 <code>bun-report-parser v1.3.1</code>(谷禾 2026-11 新版 + 物种功能库四键 + 异常菌清单直出)与 <code>socratic-coach v1.8.0</code>(归因禁区 + 介导链路纪律)的能力,<strong>接入浠艾福线上「上传 → 解析 → 五维归因 → 健康计划」主链路</strong>,让浠艾福小程序用户上传的谷禾新版报告,不再只是存一个 payload 快照,而是能产出<strong>可归因、可展示、可干预</strong>的结构化结果。</p>
+<p>不在范围:DAN 心理测评解析、儿童报告特殊处理、付费/会员链路。</p>
+<hr>
+<h2 id="gap">二、现状与 gap</h2>
+<h3 id="21">2.1 现有链路(〔代码〕)</h3>
+<pre><code>用户上传 PDF
+    │
+    ├─(一步式)POST /api/health/report/upload
+    │      └─ Java PdfParseService.parse()           ← PDFBox + 白名单 + triplet/inline
+    │         └─ 落 health_reports / health_gut_flora /
+    │             health_disease_risk / health_indicators
+    │         └─ payload_json(全量快照)
+    │         └─ dimensionScoreService.refreshFromGutReport()
+    │         └─ foodRecommendService.recalculateForUser()
+    │
+    └─(异步式)POST /api/health/report/upload-only
+           └─ 存草稿 → submitAsyncCollect()
+              └─ POST langgraph /api/v1/report/parse
+                 └─ report_parse_agent → parse_report_pdf_with_fallback()
+                    └─ pdf_parser.py(v5 移植)+ LLM 兜底
+</code></pre>
+<h3 id="22-gap">2.2 三层 gap(〔代码〕〔配置〕)</h3>
+<table>
+<thead>
+<tr>
+<th>层</th>
+<th>现状</th>
+<th>缺口</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>格式识别</strong></td>
+<td>Java <code>PdfParseService.parseText()</code> 只认 <code>beijing</code> / <code>guhe</code>(旧 triplet/inline);Python <code>pdf_parser.py</code> 是 v5 标准报告逻辑</td>
+<td><strong>谷禾 2026-11 新版(guhe_v2)无识别、无解析</strong>——指纹(<code>疾病相似评估</code>、<code>厚壁菌比拟杆菌比值为</code>、<code>肠道菌群重要菌种</code>)在 Java/Python 全仓 0 命中</td>
+</tr>
+<tr>
+<td><strong>DTO / 表</strong></td>
+<td><code>ParsedReportResult</code> 字段:overallScore / gutFlora / diseaseRisks / indicators / foodSuitability / reportFormat;<code>health_gut_flora</code> 表字段:bacteria_name / value / normal_range / status / category / population_level / detection_rate / level</td>
+<td><strong>没有 <code>疾病相似评估表</code>、<code>物种功能库四键</code>、<code>异常菌清单</code>、<code>亚健康诊断</code>、<code>F/B 比值</code>、<code>香农指数</code>、<code>报告总结</code>、<code>_解析自检</code> 的字段</strong></td>
+</tr>
+<tr>
+<td><strong>归因归一化</strong></td>
+<td><code>attribution_norm_gut_flora.json</code>:<code>placeholder=true, data=[]</code>(注释「真实 710 条待业务侧填充」)〔配置〕;<code>FiveDimAttributionEngine</code> 已就位;<code>attribution_reports</code> 表已建</td>
+<td><strong>归因引擎目前跑不出真实百分位结论</strong>(空壳常模);即使解析出丰度也无法映射 P5/P25/P50/P75/P95</td>
+</tr>
+</tbody>
+</table>
+<h3 id="23">2.3 关键架构观察</h3>
+<ul>
+<li><code>bun-report-parser v1.3.1</code> 是<strong>纯 Python 实现</strong>,Java 侧重写 <code>extract_guhe_v2</code> 等价物成本高(多行状态机 + 批注对位 + CJK 部首归一化,已实测约 4–5 分钟/份)。</li>
+<li>Java 侧已有异步链路(<code>submitAsyncCollect → langgraph /api/v1/report/parse</code>),且失败可回退 Java 本地解析(<code>parseLocalFallback</code>)〔代码〕。</li>
+<li>langgraph 侧的 <code>report_parse_agent.py</code> 已有 LLM 兜底模板(GUT/GENERIC/BRAIN),但<strong>没有物种功能库 / 疾病相似表 字段定义</strong>〔代码〕。</li>
+</ul>
+<p><strong>架构结论</strong>:谷禾新版解析<strong>以 Python(langgraph 侧)为主路径</strong>,Java 只做「识别 + 转发 + 回填」。这是最低成本路径,也最易保持与 <code>bun-report-parser</code> 上游同步。</p>
+<hr>
+<h2 id="_3">三、修改点(按优先级)</h2>
+<h3 id="p0-1-java">P0-1 · 谷禾新版格式识别(Java)</h3>
+<p><strong>目标</strong>:<code>PdfParseService.parseText()</code> 在 <code>guhe</code> 分支内进一步识别 guhe_v2。</p>
+<p><strong>做法</strong>:新增指纹检测 <code>detectGuheV2(text)</code>:
+- 命中任一即判 v2:<code>疾病相似评估</code> / <code>厚壁菌比拟杆菌比值为</code> / <code>亚健康及营养饮食不合理</code> / <code>肠道菌群重要菌种</code> / <code>与健康相关菌评估</code> / <code>报告生成:YYYY-MM-DD</code>
+- 设置 <code>reportFormat="guhe_v2"</code>(旧版仍为 <code>guhe</code>)</p>
+<p><strong>落点</strong>:<code>ParsedReportResult.reportFormat</code> 增加枚举值 <code>guhe_v2</code>;<code>schema.sql</code> L1859 与 <code>DatabaseInitializer</code> 注释同步。</p>
+<p><strong>验证</strong>:拿已归档的 <code>591336962-毛静明.pdf</code>(170 页)与 <code>527406123-吴介洋.pdf</code>(第二份)做单测;拿旧 triplet/inline 样本(廖某人、侯、闫晗等)回归确认仍判 <code>guhe</code>。</p>
+<hr>
+<h3 id="p0-2-pythonjava">P0-2 · 解析主路径切到 Python(Java 转发)</h3>
+<p><strong>目标</strong>:<code>guhe_v2</code> 报告一律走 langgraph 异步解析,Java 不再尝试本地解析。</p>
+<p><strong>做法</strong>(〔代码〕基础上扩展):
+- <code>HealthReportController.uploadReport()</code>:识别到 <code>guhe_v2</code> 时,<strong>自动切换为 <code>upload-only</code> + <code>submitAsyncCollect()</code></strong>(复用现有异步链路),并在响应里返回 <code>draftId</code> + <code>parseMethod="langgraph"</code>,前端跳「解析中」等待页。
+- <code>LangGraphReportParseService.postParseWithReason()</code>:新增请求字段 <code>reportFormatHint="guhe_v2"</code>,Python 侧按此路由到 guhe_v2 专用提取器。
+- 异步采集失败的回退策略:<strong>不</strong>做 Java 本地兜底(Java 无 guhe_v2 能力),而是标记 <code>parse_error</code> + 通知用户「该报告格式暂不支持在线解析,可稍后重试或联系服务号」。</p>
+<p><strong>验证</strong>:跑通一次毛静明 PDF 的完整上传-异步解析-落库流程,看 <code>health_report_drafts.parse_status</code> / <code>parse_method</code> / <code>parse_error</code> 字段。</p>
+<hr>
+<h3 id="p0-3-python-bun-report-parser-v131">P0-3 · Python 侧接入 bun-report-parser v1.3.1</h3>
+<p><strong>目标</strong>:langgraph 的 <code>report_parse_agent</code> 在 <code>reportFormatHint="guhe_v2"</code> 时调用 <code>bun-report-parser</code> 的 <code>extract_guhe_v2</code>。</p>
+<p><strong>做法</strong>:
+1. 把 <code>C:/Users/liaoxg.DESKTOP-DGLN79N/.workbuddy/skills/bun-report-parser/scripts/</code> 下的 <code>extract_guhe_v2.py</code>、<code>unified_report_parser.py</code>、<code>extract_relations.py</code>、<code>extract_full_report_v5.py</code> 等模块,<strong>抽成 langgraph 内的 <code>app/parsers/guhe_v2/</code> 子包</strong>(或以 git submodule / pip install 方式引入),不复制粘贴——保证后续 v1.3.2/v1.4 升级可同步。
+2. <code>report_parse_agent.py</code> 新增分支:<code>reportFormatHint="guhe_v2"</code> → 调用 <code>guhe_v2.parse(pdf_bytes)</code>,返回的 JSON <strong>直接作为 <code>payload_json</code> 落库</strong>(保持与 <code>bun-report-parser</code> 输出一致),并映射必要字段到 DTO/表(见 P0-4)。
+3. <code>_解析自检</code> 字段透传:解析结果里的 <code>通过</code> / <code>P0告警数</code> / <code>P1提示数</code> / <code>告警</code> 落进 <code>health_report_drafts.collect_validation</code>(JSON 字符串),并暴露到 <code>GET /api/health/report/collect/status</code> 接口响应里。</p>
+<p><strong>关键决策</strong>:<strong>保留完整 payload</strong>(35 键),不裁剪——后续归因引擎 / 健康计划 / 前端展示都从 payload 取,避免后续每加一个功能就要重解析 PDF。</p>
+<p><strong>验证</strong>:单测——毛静明样本解析出的 JSON 与本机 v1.3.1 输出<strong>逐键一致</strong>;<code>_解析自检.通过=true, P0=0</code>。</p>
+<hr>
+<h3 id="p0-4-dto">P0-4 · DTO 与表结构扩展</h3>
+<p><strong>目标</strong>:把 guhe_v2 的关键字段从 payload 提出来,落到可查询的表里,供前端与归因引擎使用。</p>
+<p><strong>改动清单</strong>:</p>
+<table>
+<thead>
+<tr>
+<th>表 / DTO</th>
+<th>新增字段</th>
+<th>来源(payload 键)</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>health_reports</code></td>
+<td><code>fb_ratio</code>(F/B 比值,TEXT)、<code>shannon_index_norm</code>(分级文字)、<code>subhealth_label</code>(亚健康标签)、<code>parse_self_check</code>(JSON,<code>_解析自检</code>)</td>
+<td><code>厚壁菌拟杆菌比值</code> / <code>菌群多样性详情</code> / <code>亚健康诊断</code> / <code>_解析自检</code></td>
+</tr>
+<tr>
+<td><code>health_disease_risk</code></td>
+<td><code>similarity_level</code>(TEXT:低/中/高相似)</td>
+<td><code>疾病相似评估表[].status</code></td>
+</tr>
+<tr>
+<td><code>health_gut_flora</code></td>
+<td><code>reference_range</code>(参考范围原文)、<code>direction</code>(▲/▼)、<code>species_code</code>(拉丁名)、<code>functional_tag</code>(功能标签)</td>
+<td><code>肠道菌群重要菌种[].参考范围/方向/拉丁名/功能标签</code></td>
+</tr>
+<tr>
+<td>新表 <code>health_species_library</code></td>
+<td><code>report_id / species_no / cn_name / latin_name / function_tag / detection_rate / function_desc / improve_method / abundance / ref_range / status / direction</code></td>
+<td><code>肠道菌群重要菌种[]</code>(76 条全量,含知识层 + 个人层)</td>
+</tr>
+<tr>
+<td>新表 <code>health_abnormal_species</code></td>
+<td><code>report_id / species_no / cn_name / latin_name / abundance / ref_range / direction / category</code>(仅 ▲▼ 条目)</td>
+<td>从 <code>health_species_library</code> 派生,<code>direction IS NOT NULL</code></td>
+</tr>
+</tbody>
+</table>
+<p><strong>DTO</strong>:<code>ParsedReportResult</code> 新增 <code>List&lt;ParsedSpeciesLibrary&gt; speciesLibrary</code> 与 <code>List&lt;ParsedAbnormalSpecies&gt; abnormalSpecies</code>(由 Python 解析结果反序列化)。</p>
+<p><strong>验证</strong>:跑 12 条 ▲ 超标菌清单(毛静明样本)进 <code>health_abnormal_species</code>;<code>/api/health/report/detail?reportId=…</code> 返回新增字段。</p>
+<hr>
+<h3 id="p0-5">P0-5 · 归因归一化真实数据填充管线</h3>
+<p><strong>目标</strong>:让 <code>FiveDimAttributionEngine</code> 真正跑起来——目前 <code>attribution_norm_values</code> 是空表(<code>placeholder=true</code>)。</p>
+<p><strong>做法</strong>(这是把本次升级<strong>最大价值</strong>放大的点):
+1. 新建脚本 <code>scripts/import_norm_from_reports.py</code>:
+   - 输入:<code>591336962-毛静明.json</code>、<code>527406123-吴介洋.json</code>、<code>501999942-廖某人.json</code>、<code>530010234-侯.json</code>、<code>547982403.json</code> 等 17 份样本
+   - 输出:<code>attribution_norm_gut_flora.json</code> 的 <code>data[]</code> 填充
+   - 规则:每个菌种 / 疾病相关菌的 <code>正常范围{最小值,最大值}</code> → 映射 <code>p5=最小值, p95=最大值</code>;<code>处于人群%水平</code> → 推算 <code>p25/p50/p75</code>(线性插值);<code>年龄段带</code> 取 <code>all</code>,<code>gender</code> 取 <code>all</code>;<code>source="谷禾样本回归"</code>,<code>normVersion="v1"</code>。
+2. 更新 <code>attribution_norm_gut_flora.json</code>:<code>placeholder=false</code>、<code>schemaVersion="1.1"</code>,data 长度记录(预估 100+ 条,视去重)。
+3. <code>DatabaseInitializer.importAttributionNormGutFlora()</code> 首次启动自动导入(已有逻辑,只需 JSON 非空)〔代码〕。
+4. <strong>红线</strong>:样本数据 ≠ 人群常模。方案落地时在 <code>source</code> 字段写清楚「样本回归估算,非谷禾官方 710 常模」,避免归因结论夸大人群代表性(§5.7 证据码:DEV 层,非 PUB 层)。</p>
+<p><strong>验证</strong>:对毛静明报告跑 <code>POST /api/attribution/analyze</code>,返回的五维结论中至少有一条是「身体维度:某菌偏高/偏低,落在 P25 以下 / P75 以上」的真实百分位,而不是空。</p>
+<hr>
+<h3 id="p0-6">P0-6 · 异常菌清单接口(▲ 直出)</h3>
+<p><strong>目标</strong>:让前端能一键展示「你的报告有 12 条 ▲ 超标菌」,不用前端遍历 payload。</p>
+<p><strong>新增接口</strong>:
+- <code>GET /api/health/report/abnormal-species?reportId=…</code>
+- 响应:<code>[{speciesNo, cnName, latinName, abundance, refRange, direction, category, populationLevel}]</code>,按 <code>direction</code> 排序(▲ 优先)
+- <strong>口径约束</strong>:响应里附 <code>disclaimer</code>(关联非因果、测评 ≠ 诊断),供前端统一展示</p>
+<p><strong>验证</strong>:毛静明样本应返回 12 条(粪拟杆菌 / 脆弱拟杆菌 / 多形拟杆菌 / 楔形梭菌 / 共生梭菌 / 迟钝埃格特菌 / 大肠杆菌 / 产丁酸肠单胞菌 / 内脏臭气杆菌 / 狄氏副拟杆菌 / 活泼瘤胃球菌 / 产乳酸拟罗氏菌)。</p>
+<hr>
+<h3 id="p1-1-81">P1-1 · 健康计划生成红线(§8.1 归因禁区)</h3>
+<p><strong>目标</strong>:<code>health_plan_graph</code> 生成健康计划时,<strong>不得</strong>把器质性疾病、处方药增减、12 周内不可测指标写成改善目标(§8.1)。</p>
+<p><strong>做法</strong>:
+1. 在 <code>health_plan_graph.py</code> 的 prompt_service 里,为菌群归因场景追加约束段(§1.2 事实源:socratic-coach v1.8.0 §8.1 全文):
+   - 器质性诊断只作为<strong>前提约束</strong>,不作为<strong>改善目标</strong>
+   - 不得建议增减或停用处方药;涉及用药只做「请与开方医生确认」
+   - 12 周内不设不可测目标(骨密度、骨代谢标志物、器质性病变)
+   - 急症信号(晕厥 / 黑便 / 胸痛 / 静息心悸 / 进行性消瘦)只做<strong>转介</strong>,禁写成「方案见效后不再发作」
+   - 行为判读先排除医学约束(「她不能」≠「她不肯」)
+2. 在 Java <code>HealthPlanServiceImpl</code> 调用侧增加输入字段 <code>medical_constraints</code>(用户已有诊断、在服药物),Python 侧将其注入 prompt 约束。</p>
+<p><strong>验证</strong>:构造一个含「确诊二尖瓣脱垂 + 在服美托洛尔」的测试用例,确认生成的健康计划里没有「心脏问题会随方案改善」「可以停用美托洛尔」之类的措辞。</p>
+<hr>
+<h3 id="p1-2">P1-2 · 介导链路禁确定性因果</h3>
+<p><strong>目标</strong>:<code>analysis_graph</code> / <code>health_butler_graph</code> 的解读文案里,凡是涉及<strong>心 / 智维度</strong>的菌群 → 递质 → 情绪/认知链路,只作「上游信号」,不判能力。</p>
+<p><strong>做法</strong>:
+1. <code>analysis_agent.py</code> / <code>chat_agent.py</code> 的 system prompt 里追加 §5.8 红线段:
+   - ⚠ 介导链路(如「递质偏低 → 睡眠 → 记忆留存」「屏障失衡 → 炎症噪声 → 专注力」)只作<strong>上游信号</strong>,不判能力;
+   - 禁用措辞:<code>这正是…典型表现</code> / <code>正是…的根</code> / <code>拖了…后腿</code>;
+   - 必用措辞:<code>相关联</code> / <code>报告提示</code> / <code>可能与…有关</code> / <code>待进一步确认</code>。
+2. 输出侧加正则审计:<code>导致 / 治愈 / 改善 / 典型表现 / 正是.*的根</code> → 命中即重写或标记人工复核。</p>
+<p><strong>验证</strong>:跑一组归因问答,抓取输出中是否出现禁用词。</p>
+<hr>
+<h3 id="p1-3">P1-3 · 前端展示增强(可延后)</h3>
+<p><strong>目标</strong>:小程序端在报告详情页 / 归因页 / 健康计划页展示新增内容。</p>
+<p><strong>改动清单</strong>:
+- 报告详情页:新增「异常菌清单」卡片(▲▼ 分组展示 12 条),点击展开显示丰度 / 参考范围 / 功能描述
+- 报告详情页:新增「亚健康诊断」标签(如「亚健康及营养饮食不合理」)
+- 归因页:新增「菌群 → 五维」可视化(内联 SVG 相生相克图,主因链单独成图)
+- 健康计划页:底部固定免责声明(§5.8 红线)</p>
+<p><strong>依赖</strong>:P0-4(表结构)+ P0-6(接口)。改动文件预计:<code>components/report-upload-card.vue</code>、<code>pages/health-report/*</code>、<code>pages/attribution/*</code>、<code>utils/api.js</code>。</p>
+<hr>
+<h3 id="p2">P2 · 运营与监控(可独立推进)</h3>
+<ul>
+<li><code>_解析自检</code> 落库后建看板:<code>P0 命中率</code>、<code>P1 Top 5</code>(<code>健康问题索引</code> 摘录切头 / PAGEBREAK 残留 / ND 语义未区分 / 状态词缺失 / 索引切头),用于后续版本迭代。</li>
+<li>解析耗时监控:170 页大报告单次约 4–5 分钟(<code>bun-report-parser</code> 实测),异步队列要有超时与重试(<code>health_report_drafts.next_retry_at</code> 已有)。</li>
+<li>上游同步机制:<code>bun-report-parser</code> 每次 minor/major 升级(v1.3.2 / v1.4 / v1.5 …)需评估同步到 langgraph 子包,建立 changelog 订阅。</li>
+</ul>
+<hr>
+<h2 id="_4">四、技术决策</h2>
+<h3 id="1-python-java-a">决策 1 · 谷禾新版解析走 Python 而非 Java(推荐 A)</h3>
+<table>
+<thead>
+<tr>
+<th>方案</th>
+<th>优点</th>
+<th>缺点</th>
+<th>工作量</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>A. Python 主导</strong>(推荐)</td>
+<td>直接复用 v1.3.1 模块(已实测);后续上游升级可同步;双链路并存</td>
+<td>需保证 langgraph 服务稳定(已有回退机制)</td>
+<td>~2 人日</td>
+</tr>
+<tr>
+<td>B. Java 移植</td>
+<td>单体部署,无跨服务依赖</td>
+<td>重写多行状态机 + 批注对位 + CJK 归一化,风险高;每升级需重写</td>
+<td>~8–10 人日</td>
+</tr>
+<tr>
+<td>C. 调用独立 Python 服务</td>
+<td>解耦</td>
+<td>多一个服务要部署运维</td>
+<td>~3 人日</td>
+</tr>
+</tbody>
+</table>
+<p><strong>推荐 A</strong>,理由:langgraph 已是生产依赖(异步采集主路径),加一个 guhe_v2 分支不增加新组件;回退机制已有。</p>
+<h3 id="2-payload-vs-a">决策 2 · payload 完整保留 vs 裁剪(推荐 A)</h3>
+<table>
+<thead>
+<tr>
+<th>方案</th>
+<th>优点</th>
+<th>缺点</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>A. 保留完整 35 键 payload</strong>(推荐)</td>
+<td>后续功能(相似度、多样性、报告总结、自检)都从 payload 取,无需重解析</td>
+<td>payload_json 较大(约 300–500KB / 份)</td>
+</tr>
+<tr>
+<td>B. 只提取必要字段</td>
+<td>表小</td>
+<td>每加一个功能都要重解析 PDF</td>
+</tr>
+</tbody>
+</table>
+<p><strong>推荐 A</strong>,理由:<code>health_report_drafts.payload_json</code> 已是 TEXT,容量无硬约束;重解析成本远高于存储成本。</p>
+<h3 id="3-a-b">决策 3 · 归一化数据来源(推荐 A + 渐进升级到 B)</h3>
+<table>
+<thead>
+<tr>
+<th>方案</th>
+<th>来源</th>
+<th>局限</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>A. 样本回归估算</strong>(首期)</td>
+<td>已有 17 份样本的 <code>正常范围</code></td>
+<td>不是官方 710 常模,人群代表性有限</td>
+</tr>
+<tr>
+<td>B. 谷禾官方 710 常模(长期)</td>
+<td>需向谷禾采购或合作</td>
+<td>商务周期未知</td>
+</tr>
+</tbody>
+</table>
+<p><strong>推荐 A 先落地</strong>,同时在归因报告展示时加 <code>source="样本回归估算"</code> 与「人群代表性有限」提示,避免夸大(§5.7 证据码 DEV,非 PUB)。</p>
+<hr>
+<h2 id="ddl">五、表结构变更(DDL 草案)</h2>
+<pre><code class="language-sql">-- 1) health_reports 新增列(ALTER TABLE)
+ALTER TABLE health_reports ADD COLUMN fb_ratio TEXT NULL COMMENT 'F/B 比值原文(谷禾新版)';
+ALTER TABLE health_reports ADD COLUMN shannon_index_norm TEXT NULL COMMENT '香农指数分级文字';
+ALTER TABLE health_reports ADD COLUMN subhealth_label TEXT NULL COMMENT '亚健康标签(谷禾新版)';
+ALTER TABLE health_reports ADD COLUMN parse_self_check JSON NULL COMMENT '_解析自检 结果 JSON';
+
+-- 2) health_disease_risk 新增列
+ALTER TABLE health_disease_risk ADD COLUMN similarity_level TEXT NULL COMMENT '低/中/高相似(谷禾新版)';
+
+-- 3) health_gut_flora 新增列
+ALTER TABLE health_gut_flora ADD COLUMN reference_range TEXT NULL COMMENT '参考范围原文';
+ALTER TABLE health_gut_flora ADD COLUMN direction VARCHAR(2) NULL COMMENT '▲/▼/NULL';
+ALTER TABLE health_gut_flora ADD COLUMN species_code VARCHAR(128) NULL COMMENT '拉丁名';
+ALTER TABLE health_gut_flora ADD COLUMN functional_tag VARCHAR(64) NULL COMMENT '功能标签';
+
+-- 4) 新表 health_species_library
+CREATE TABLE IF NOT EXISTS health_species_library (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  report_id BIGINT NOT NULL,
+  species_no INT NOT NULL,
+  cn_name VARCHAR(128),
+  latin_name VARCHAR(128),
+  function_tag VARCHAR(64),
+  detection_rate VARCHAR(32),
+  function_desc TEXT,
+  improve_method TEXT,
+  abundance VARCHAR(32),
+  ref_range VARCHAR(64),
+  status VARCHAR(16),
+  direction VARCHAR(2),
+  KEY idx_report (report_id)
+) COMMENT='谷禾新版物种功能库(76 条/份,知识层 + 个人层)';
+
+-- 5) 新表 health_abnormal_species(可视图/派生表)
+CREATE OR REPLACE VIEW health_abnormal_species AS
+SELECT report_id, species_no, cn_name, latin_name, abundance, ref_range, direction
+FROM health_species_library
+WHERE direction IS NOT NULL;
+
+-- 6) health_report_drafts 已有 collect_validation 字段,无变更
+</code></pre>
+<hr>
+<h2 id="_5">六、接口契约变更</h2>
+<h3 id="61">6.1 上传接口</h3>
+<p><strong><code>POST /api/health/report/upload</code></strong>
+- 请求不变(<code>file</code> + <code>userId</code> + <code>familyId</code>)
+- 响应新增字段:<code>reportFormat</code>(<code>guhe</code> / <code>guhe_v2</code> / <code>beijing</code> / <code>aidefansi</code>)、<code>parseMethod</code>(<code>local</code> / <code>langgraph</code>)、<code>draftId</code>(异步时返回)</p>
+<p><strong><code>GET /api/health/report/collect/status?draftId=…</code></strong>
+- 响应新增:<code>parseSelfCheck</code>(JSON,<code>_解析自检</code>)</p>
+<h3 id="62">6.2 报告详情</h3>
+<p><strong><code>GET /api/health/report/detail?reportId=…</code></strong>
+- 响应新增:<code>abnormalSpecies</code>(数组)、<code>speciesLibrary</code>(数组,76 条)、<code>fbRatio</code>、<code>shannonIndexNorm</code>、<code>subhealthLabel</code>、<code>parseSelfCheck</code></p>
+<h3 id="63">6.3 新增接口</h3>
+<p><strong><code>GET /api/health/report/abnormal-species?reportId=…</code></strong> —— 见 P0-6</p>
+<h3 id="64">6.4 归因接口</h3>
+<p><strong><code>POST /api/attribution/analyze</code></strong>
+- 请求不变
+- 响应新增:<code>normSource</code>(<code>placeholder</code> / <code>sample_regression</code> / <code>official_710</code>)、<code>normVersion</code></p>
+<hr>
+<h2 id="_6">七、回归与验收</h2>
+<h3 id="71">7.1 单测</h3>
+<ul>
+<li>Java <code>PdfParseServiceTest</code>:新增 <code>test_detectGuheV2_guheV2()</code>、<code>test_detectGuheV2_oldGuhe()</code>、<code>test_detectGuheV2_beijing()</code>、<code>test_detectGuheV2_aidefansi()</code></li>
+<li>Java <code>HealthReportControllerTest</code>:<code>test_upload_guheV2_routes_to_langgraph()</code>、<code>test_upload_guheV2_async_parse_self_check()</code></li>
+<li>Python <code>test_report_parse.py</code>:<code>test_parse_guhe_v2_maojingming()</code>(比对 payload 逐键一致)、<code>test_parse_guhe_v2_self_check_pass()</code></li>
+</ul>
+<h3 id="72">7.2 集成回归</h3>
+<ul>
+<li>拿 17 份样本 PDF 各上传一次(毛静明 / 吴介洋 / 廖某人 / 侯 / 闫晗 / 曹丽君 / 王卫东 / 马安扬 / 马昕源 / 詹欣 / 小强 / 赵立辉 / 儿童示例 / 朱评估报告 / 北京移植前 / 北京移植后复测 / 艾德范思模板),校验:</li>
+<li><code>report_format</code> 识别正确</li>
+<li>payload_json 与 bun-report-parser 本地输出一致</li>
+<li><code>_解析自检.P0=0</code></li>
+<li>异步采集完成后 <code>health_report_drafts.parse_status='success'</code></li>
+</ul>
+<h3 id="73">7.3 验收标准</h3>
+<table>
+<thead>
+<tr>
+<th>项</th>
+<th>标准</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>谷禾新版格式识别准确率</td>
+<td>≥ 99%(17 份样本 + 历史样本回归)</td>
+</tr>
+<tr>
+<td>异常菌清单条数</td>
+<td>毛静明 = 12、吴介洋与历史样本按实际</td>
+</tr>
+<tr>
+<td>解析耗时</td>
+<td>单份 ≤ 6 分钟(异步,含队列)</td>
+</tr>
+<tr>
+<td>P0 自检告警</td>
+<td>全部 0</td>
+</tr>
+<tr>
+<td>健康计划禁用词命中</td>
+<td>0(P1-2 审计通过)</td>
+</tr>
+</tbody>
+</table>
+<hr>
+<h2 id="_7">八、风险与红线</h2>
+<h3 id="81-81">8.1 归因禁区(§8.1,破一条即失格)</h3>
+<ul>
+<li>器质性诊断不得纳入调理目标;处方药不得建议增减或停用;12 周内不设不可测目标;急症信号只做转介;行为判读先排除医学约束。</li>
+<li>落地:P1-1 的 prompt 约束 + Java 输入字段 <code>medical_constraints</code> + 输出正则审计。</li>
+</ul>
+<h3 id="82-58">8.2 介导链路禁确定性因果(§5.8)</h3>
+<ul>
+<li>菌群 → 递质 → 情绪/认知 的 ⚠ 介导链路只作<strong>上游信号</strong>,不判能力;行文一律「相关联 / 报告提示 / 可能与…有关」。</li>
+<li>落地:P1-2 的 system prompt 约束 + 输出正则审计。</li>
+</ul>
+<h3 id="83">8.3 归一化数据代表性</h3>
+<ul>
+<li>首期归一化数据来自 17 份样本回归,<strong>非官方 710 常模</strong>,人群代表性有限。展示时必须写 <code>source</code> 字段,禁写「符合人群 xx%」等断言。</li>
+</ul>
+<h3 id="84-payload">8.4 payload 完整性与隐私</h3>
+<ul>
+<li>payload 含姓名、编号、年龄、性别、检测数值,属个人健康数据(§5.7:不跨人比较、不外传)。前端展示加权限校验(已有 <code>health_report_permissions</code> / <code>report_member_permissions</code>)。</li>
+</ul>
+<h3 id="85">8.5 上游同步</h3>
+<ul>
+<li><code>bun-report-parser</code> 后续升级(v1.3.2 / v1.4 / v1.5 …)需评估同步到 langgraph 子包;建议建立 changelog 订阅或 submodule。</li>
+</ul>
+<hr>
+<h2 id="_8">九、里程碑(建议)</h2>
+<table>
+<thead>
+<tr>
+<th>里程碑</th>
+<th>内容</th>
+<th>依赖</th>
+<th>工期</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>M1</strong></td>
+<td>P0-1 Java 格式识别 + P0-2 异步切流</td>
+<td>无</td>
+<td>2 人日</td>
+</tr>
+<tr>
+<td><strong>M2</strong></td>
+<td>P0-3 Python 接入 bun-report-parser + P0-4 表结构 + P0-6 异常菌接口</td>
+<td>M1</td>
+<td>3 人日</td>
+</tr>
+<tr>
+<td><strong>M3</strong></td>
+<td>P0-5 归一化数据填充 + 归因引擎真实输出</td>
+<td>M2</td>
+<td>2 人日</td>
+</tr>
+<tr>
+<td><strong>M4</strong></td>
+<td>P1-1 健康计划红线 + P1-2 介导链路审计</td>
+<td>M2</td>
+<td>2 人日</td>
+</tr>
+<tr>
+<td><strong>M5</strong></td>
+<td>P1-3 前端展示增强</td>
+<td>M2</td>
+<td>3 人日</td>
+</tr>
+<tr>
+<td><strong>M6</strong></td>
+<td>P2 运营监控 + 灰度</td>
+<td>M3</td>
+<td>2 人日</td>
+</tr>
+</tbody>
+</table>
+<p><strong>合计约 14 人日</strong>(不含测试与上线)。建议灰度顺序:先内部测试号上传毛静明等 17 份样本 → 再小范围开放给已付费用户 → 再全面。</p>
+<hr>
+<h2 id="_9">十、附录:本方案用到的关键源码/资源路径</h2>
+<ul>
+<li>Java 入口:<code>E:\cfc\cfc-backend\src\main\java\com\etotem\cfc\controller\HealthReportController.java</code></li>
+<li>Java 解析:<code>E:\cfc\cfc-backend\src\main\java\com\etotem\cfc\service\PdfParseService.java</code></li>
+<li>Java 归因:<code>E:\cfc\cfc-backend\src\main\java\com\etotem\cfc\service\attribution\FiveDimAttributionEngine.java</code>、<code>NormCompareEngine.java</code></li>
+<li>归一化规则:<code>E:\cfc\cfc-backend\src\main\resources\norm\attribution_norm_gut_flora.json</code>(当前 placeholder=true)</li>
+<li>五维编码:<code>E:\cfc\cfc-backend\src\main\java\com\etotem\cfc\common\constant\DimensionCodeConstants.java</code>(5 根 33 子维)</li>
+<li>表结构:<code>E:\cfc\cfc-backend\src\main\resources\schema.sql</code>(health_reports L1853 / health_gut_flora L1988 / attribution_reports L5211)</li>
+<li>langgraph 入口:<code>E:\cfc\cfc-langgraph\app\api\report_parse.py</code>、<code>app\agents\report_parse_agent.py</code></li>
+<li>langgraph 解析:<code>E:\cfc\cfc-langgraph\app\parsers\pdf_parser.py</code>(v5 移植)</li>
+<li>langgraph 健康计划:<code>E:\cfc\cfc-langgraph\app\graphs\health_plan_graph.py</code></li>
+<li>上游解析器:<code>C:/Users/liaoxg.DESKTOP-DGLN79N/.workbuddy/skills/bun-report-parser/scripts/</code></li>
+<li>上游专家:<code>C:/Users/liaoxg.DESKTOP-DGLN79N/.workbuddy/plugins/marketplaces/my-experts/plugins/socratic-coach/agents/socratic-coach.md</code>(§5.8 / §8.1 红线)</li>
+<li>归因口径底稿:<code>E:\cfc\docs\参考资料\bun-report-parser-v1.3.1-修复说明与回归报告.md</code></li>
+</ul>
+<hr>
+<p><strong>下一步建议</strong>:把 M1(Java 格式识别 + 异步切流)拆成 sprint task,先落 1 个能跑通的 guhe_v2 报告(毛静明)作为端到端冒烟;端到端跑通后再并行推进 M2–M6。</p>
+</main>
+</body>
+</html>

+ 400 - 0
docs/浠艾福程序-谷禾新版解析与五维归因升级方案-v1.0.md

@@ -0,0 +1,400 @@
+# 浠艾福线上程序 · 谷禾新版解析与五维归因升级方案
+
+**版本**:v1.0(2026-11-16 起草)
+**依据**:`bun-report-parser v1.3.1`(物种功能库四键 + `_解析自检`)+ `socratic-coach v1.8.0`(§8.1 归因禁区 + 介导链路纪律)
+**读者**:浠艾福技术负责人 / 后端 / langgraph / 前端 / 产品
+
+> 口径提示(§1.2 事实源分级):本文所有结论分三级标注——**〔代码〕**=已读源码确认;**〔配置〕**=已读配置/JSON 确认;**〔假设〕**=基于现有能力的合理推断,待代码 review 或跑通验证。凡涉及医学/健康结论的行文一律「相关联 / 报告提示」,禁用「导致 / 治愈 / 改善」。
+
+---
+
+## 一、目标与范围(一句话)
+
+把已在本机实测通过的 `bun-report-parser v1.3.1`(谷禾 2026-11 新版 + 物种功能库四键 + 异常菌清单直出)与 `socratic-coach v1.8.0`(归因禁区 + 介导链路纪律)的能力,**接入浠艾福线上「上传 → 解析 → 五维归因 → 健康计划」主链路**,让浠艾福小程序用户上传的谷禾新版报告,不再只是存一个 payload 快照,而是能产出**可归因、可展示、可干预**的结构化结果。
+
+不在范围:DAN 心理测评解析、儿童报告特殊处理、付费/会员链路。
+
+---
+
+## 二、现状与 gap
+
+### 2.1 现有链路(〔代码〕)
+
+```
+用户上传 PDF
+    │
+    ├─(一步式)POST /api/health/report/upload
+    │      └─ Java PdfParseService.parse()           ← PDFBox + 白名单 + triplet/inline
+    │         └─ 落 health_reports / health_gut_flora /
+    │             health_disease_risk / health_indicators
+    │         └─ payload_json(全量快照)
+    │         └─ dimensionScoreService.refreshFromGutReport()
+    │         └─ foodRecommendService.recalculateForUser()
+    │
+    └─(异步式)POST /api/health/report/upload-only
+           └─ 存草稿 → submitAsyncCollect()
+              └─ POST langgraph /api/v1/report/parse
+                 └─ report_parse_agent → parse_report_pdf_with_fallback()
+                    └─ pdf_parser.py(v5 移植)+ LLM 兜底
+```
+
+### 2.2 三层 gap(〔代码〕〔配置〕)
+
+| 层 | 现状 | 缺口 |
+|---|---|---|
+| **格式识别** | Java `PdfParseService.parseText()` 只认 `beijing` / `guhe`(旧 triplet/inline);Python `pdf_parser.py` 是 v5 标准报告逻辑 | **谷禾 2026-11 新版(guhe_v2)无识别、无解析**——指纹(`疾病相似评估`、`厚壁菌比拟杆菌比值为`、`肠道菌群重要菌种`)在 Java/Python 全仓 0 命中 |
+| **DTO / 表** | `ParsedReportResult` 字段:overallScore / gutFlora / diseaseRisks / indicators / foodSuitability / reportFormat;`health_gut_flora` 表字段:bacteria_name / value / normal_range / status / category / population_level / detection_rate / level | **没有 `疾病相似评估表`、`物种功能库四键`、`异常菌清单`、`亚健康诊断`、`F/B 比值`、`香农指数`、`报告总结`、`_解析自检` 的字段** |
+| **归因归一化** | `attribution_norm_gut_flora.json`:`placeholder=true, data=[]`(注释「真实 710 条待业务侧填充」)〔配置〕;`FiveDimAttributionEngine` 已就位;`attribution_reports` 表已建 | **归因引擎目前跑不出真实百分位结论**(空壳常模);即使解析出丰度也无法映射 P5/P25/P50/P75/P95 |
+
+### 2.3 关键架构观察
+
+- `bun-report-parser v1.3.1` 是**纯 Python 实现**,Java 侧重写 `extract_guhe_v2` 等价物成本高(多行状态机 + 批注对位 + CJK 部首归一化,已实测约 4–5 分钟/份)。
+- Java 侧已有异步链路(`submitAsyncCollect → langgraph /api/v1/report/parse`),且失败可回退 Java 本地解析(`parseLocalFallback`)〔代码〕。
+- langgraph 侧的 `report_parse_agent.py` 已有 LLM 兜底模板(GUT/GENERIC/BRAIN),但**没有物种功能库 / 疾病相似表 字段定义**〔代码〕。
+
+**架构结论**:谷禾新版解析**以 Python(langgraph 侧)为主路径**,Java 只做「识别 + 转发 + 回填」。这是最低成本路径,也最易保持与 `bun-report-parser` 上游同步。
+
+---
+
+## 三、修改点(按优先级)
+
+### P0-1 · 谷禾新版格式识别(Java)
+
+**目标**:`PdfParseService.parseText()` 在 `guhe` 分支内进一步识别 guhe_v2。
+
+**做法**:新增指纹检测 `detectGuheV2(text)`:
+- 命中任一即判 v2:`疾病相似评估` / `厚壁菌比拟杆菌比值为` / `亚健康及营养饮食不合理` / `肠道菌群重要菌种` / `与健康相关菌评估` / `报告生成:YYYY-MM-DD`
+- 设置 `reportFormat="guhe_v2"`(旧版仍为 `guhe`)
+
+**落点**:`ParsedReportResult.reportFormat` 增加枚举值 `guhe_v2`;`schema.sql` L1859 与 `DatabaseInitializer` 注释同步。
+
+**验证**:拿已归档的 `591336962-毛静明.pdf`(170 页)与 `527406123-吴介洋.pdf`(第二份)做单测;拿旧 triplet/inline 样本(廖某人、侯、闫晗等)回归确认仍判 `guhe`。
+
+---
+
+### P0-2 · 解析主路径切到 Python(Java 转发)
+
+**目标**:`guhe_v2` 报告一律走 langgraph 异步解析,Java 不再尝试本地解析。
+
+**做法**(〔代码〕基础上扩展):
+- `HealthReportController.uploadReport()`:识别到 `guhe_v2` 时,**自动切换为 `upload-only` + `submitAsyncCollect()`**(复用现有异步链路),并在响应里返回 `draftId` + `parseMethod="langgraph"`,前端跳「解析中」等待页。
+- `LangGraphReportParseService.postParseWithReason()`:新增请求字段 `reportFormatHint="guhe_v2"`,Python 侧按此路由到 guhe_v2 专用提取器。
+- 异步采集失败的回退策略:**不**做 Java 本地兜底(Java 无 guhe_v2 能力),而是标记 `parse_error` + 通知用户「该报告格式暂不支持在线解析,可稍后重试或联系服务号」。
+
+**验证**:跑通一次毛静明 PDF 的完整上传-异步解析-落库流程,看 `health_report_drafts.parse_status` / `parse_method` / `parse_error` 字段。
+
+---
+
+### P0-3 · Python 侧接入 bun-report-parser v1.3.1
+
+**目标**:langgraph 的 `report_parse_agent` 在 `reportFormatHint="guhe_v2"` 时调用 `bun-report-parser` 的 `extract_guhe_v2`。
+
+**做法**:
+1. 把 `C:/Users/liaoxg.DESKTOP-DGLN79N/.workbuddy/skills/bun-report-parser/scripts/` 下的 `extract_guhe_v2.py`、`unified_report_parser.py`、`extract_relations.py`、`extract_full_report_v5.py` 等模块,**抽成 langgraph 内的 `app/parsers/guhe_v2/` 子包**(或以 git submodule / pip install 方式引入),不复制粘贴——保证后续 v1.3.2/v1.4 升级可同步。
+2. `report_parse_agent.py` 新增分支:`reportFormatHint="guhe_v2"` → 调用 `guhe_v2.parse(pdf_bytes)`,返回的 JSON **直接作为 `payload_json` 落库**(保持与 `bun-report-parser` 输出一致),并映射必要字段到 DTO/表(见 P0-4)。
+3. `_解析自检` 字段透传:解析结果里的 `通过` / `P0告警数` / `P1提示数` / `告警` 落进 `health_report_drafts.collect_validation`(JSON 字符串),并暴露到 `GET /api/health/report/collect/status` 接口响应里。
+
+**关键决策**:**保留完整 payload**(35 键),不裁剪——后续归因引擎 / 健康计划 / 前端展示都从 payload 取,避免后续每加一个功能就要重解析 PDF。
+
+**验证**:单测——毛静明样本解析出的 JSON 与本机 v1.3.1 输出**逐键一致**;`_解析自检.通过=true, P0=0`。
+
+---
+
+### P0-4 · DTO 与表结构扩展
+
+**目标**:把 guhe_v2 的关键字段从 payload 提出来,落到可查询的表里,供前端与归因引擎使用。
+
+**改动清单**:
+
+| 表 / DTO | 新增字段 | 来源(payload 键) |
+|---|---|---|
+| `health_reports` | `fb_ratio`(F/B 比值,TEXT)、`shannon_index_norm`(分级文字)、`subhealth_label`(亚健康标签)、`parse_self_check`(JSON,`_解析自检`) | `厚壁菌拟杆菌比值` / `菌群多样性详情` / `亚健康诊断` / `_解析自检` |
+| `health_disease_risk` | `similarity_level`(TEXT:低/中/高相似) | `疾病相似评估表[].status` |
+| `health_gut_flora` | `reference_range`(参考范围原文)、`direction`(▲/▼)、`species_code`(拉丁名)、`functional_tag`(功能标签) | `肠道菌群重要菌种[].参考范围/方向/拉丁名/功能标签` |
+| 新表 `health_species_library` | `report_id / species_no / cn_name / latin_name / function_tag / detection_rate / function_desc / improve_method / abundance / ref_range / status / direction` | `肠道菌群重要菌种[]`(76 条全量,含知识层 + 个人层) |
+| 新表 `health_abnormal_species` | `report_id / species_no / cn_name / latin_name / abundance / ref_range / direction / category`(仅 ▲▼ 条目) | 从 `health_species_library` 派生,`direction IS NOT NULL` |
+
+**DTO**:`ParsedReportResult` 新增 `List<ParsedSpeciesLibrary> speciesLibrary` 与 `List<ParsedAbnormalSpecies> abnormalSpecies`(由 Python 解析结果反序列化)。
+
+**验证**:跑 12 条 ▲ 超标菌清单(毛静明样本)进 `health_abnormal_species`;`/api/health/report/detail?reportId=…` 返回新增字段。
+
+---
+
+### P0-5 · 归因归一化真实数据填充管线
+
+**目标**:让 `FiveDimAttributionEngine` 真正跑起来——目前 `attribution_norm_values` 是空表(`placeholder=true`)。
+
+**做法**(这是把本次升级**最大价值**放大的点):
+1. 新建脚本 `scripts/import_norm_from_reports.py`:
+   - 输入:`591336962-毛静明.json`、`527406123-吴介洋.json`、`501999942-廖某人.json`、`530010234-侯.json`、`547982403.json` 等 17 份样本
+   - 输出:`attribution_norm_gut_flora.json` 的 `data[]` 填充
+   - 规则:每个菌种 / 疾病相关菌的 `正常范围{最小值,最大值}` → 映射 `p5=最小值, p95=最大值`;`处于人群%水平` → 推算 `p25/p50/p75`(线性插值);`年龄段带` 取 `all`,`gender` 取 `all`;`source="谷禾样本回归"`,`normVersion="v1"`。
+2. 更新 `attribution_norm_gut_flora.json`:`placeholder=false`、`schemaVersion="1.1"`,data 长度记录(预估 100+ 条,视去重)。
+3. `DatabaseInitializer.importAttributionNormGutFlora()` 首次启动自动导入(已有逻辑,只需 JSON 非空)〔代码〕。
+4. **红线**:样本数据 ≠ 人群常模。方案落地时在 `source` 字段写清楚「样本回归估算,非谷禾官方 710 常模」,避免归因结论夸大人群代表性(§5.7 证据码:DEV 层,非 PUB 层)。
+
+**验证**:对毛静明报告跑 `POST /api/attribution/analyze`,返回的五维结论中至少有一条是「身体维度:某菌偏高/偏低,落在 P25 以下 / P75 以上」的真实百分位,而不是空。
+
+---
+
+### P0-6 · 异常菌清单接口(▲ 直出)
+
+**目标**:让前端能一键展示「你的报告有 12 条 ▲ 超标菌」,不用前端遍历 payload。
+
+**新增接口**:
+- `GET /api/health/report/abnormal-species?reportId=…`
+- 响应:`[{speciesNo, cnName, latinName, abundance, refRange, direction, category, populationLevel}]`,按 `direction` 排序(▲ 优先)
+- **口径约束**:响应里附 `disclaimer`(关联非因果、测评 ≠ 诊断),供前端统一展示
+
+**验证**:毛静明样本应返回 12 条(粪拟杆菌 / 脆弱拟杆菌 / 多形拟杆菌 / 楔形梭菌 / 共生梭菌 / 迟钝埃格特菌 / 大肠杆菌 / 产丁酸肠单胞菌 / 内脏臭气杆菌 / 狄氏副拟杆菌 / 活泼瘤胃球菌 / 产乳酸拟罗氏菌)。
+
+---
+
+### P1-1 · 健康计划生成红线(§8.1 归因禁区)
+
+**目标**:`health_plan_graph` 生成健康计划时,**不得**把器质性疾病、处方药增减、12 周内不可测指标写成改善目标(§8.1)。
+
+**做法**:
+1. 在 `health_plan_graph.py` 的 prompt_service 里,为菌群归因场景追加约束段(§1.2 事实源:socratic-coach v1.8.0 §8.1 全文):
+   - 器质性诊断只作为**前提约束**,不作为**改善目标**
+   - 不得建议增减或停用处方药;涉及用药只做「请与开方医生确认」
+   - 12 周内不设不可测目标(骨密度、骨代谢标志物、器质性病变)
+   - 急症信号(晕厥 / 黑便 / 胸痛 / 静息心悸 / 进行性消瘦)只做**转介**,禁写成「方案见效后不再发作」
+   - 行为判读先排除医学约束(「她不能」≠「她不肯」)
+2. 在 Java `HealthPlanServiceImpl` 调用侧增加输入字段 `medical_constraints`(用户已有诊断、在服药物),Python 侧将其注入 prompt 约束。
+
+**验证**:构造一个含「确诊二尖瓣脱垂 + 在服美托洛尔」的测试用例,确认生成的健康计划里没有「心脏问题会随方案改善」「可以停用美托洛尔」之类的措辞。
+
+---
+
+### P1-2 · 介导链路禁确定性因果
+
+**目标**:`analysis_graph` / `health_butler_graph` 的解读文案里,凡是涉及**心 / 智维度**的菌群 → 递质 → 情绪/认知链路,只作「上游信号」,不判能力。
+
+**做法**:
+1. `analysis_agent.py` / `chat_agent.py` 的 system prompt 里追加 §5.8 红线段:
+   - ⚠ 介导链路(如「递质偏低 → 睡眠 → 记忆留存」「屏障失衡 → 炎症噪声 → 专注力」)只作**上游信号**,不判能力;
+   - 禁用措辞:`这正是…典型表现` / `正是…的根` / `拖了…后腿`;
+   - 必用措辞:`相关联` / `报告提示` / `可能与…有关` / `待进一步确认`。
+2. 输出侧加正则审计:`导致 / 治愈 / 改善 / 典型表现 / 正是.*的根` → 命中即重写或标记人工复核。
+
+**验证**:跑一组归因问答,抓取输出中是否出现禁用词。
+
+---
+
+### P1-3 · 前端展示增强(可延后)
+
+**目标**:小程序端在报告详情页 / 归因页 / 健康计划页展示新增内容。
+
+**改动清单**:
+- 报告详情页:新增「异常菌清单」卡片(▲▼ 分组展示 12 条),点击展开显示丰度 / 参考范围 / 功能描述
+- 报告详情页:新增「亚健康诊断」标签(如「亚健康及营养饮食不合理」)
+- 归因页:新增「菌群 → 五维」可视化(内联 SVG 相生相克图,主因链单独成图)
+- 健康计划页:底部固定免责声明(§5.8 红线)
+
+**依赖**:P0-4(表结构)+ P0-6(接口)。改动文件预计:`components/report-upload-card.vue`、`pages/health-report/*`、`pages/attribution/*`、`utils/api.js`。
+
+---
+
+### P2 · 运营与监控(可独立推进)
+
+- `_解析自检` 落库后建看板:`P0 命中率`、`P1 Top 5`(`健康问题索引` 摘录切头 / PAGEBREAK 残留 / ND 语义未区分 / 状态词缺失 / 索引切头),用于后续版本迭代。
+- 解析耗时监控:170 页大报告单次约 4–5 分钟(`bun-report-parser` 实测),异步队列要有超时与重试(`health_report_drafts.next_retry_at` 已有)。
+- 上游同步机制:`bun-report-parser` 每次 minor/major 升级(v1.3.2 / v1.4 / v1.5 …)需评估同步到 langgraph 子包,建立 changelog 订阅。
+
+---
+
+## 四、技术决策
+
+### 决策 1 · 谷禾新版解析走 Python 而非 Java(推荐 A)
+
+| 方案 | 优点 | 缺点 | 工作量 |
+|---|---|---|---|
+| **A. Python 主导**(推荐) | 直接复用 v1.3.1 模块(已实测);后续上游升级可同步;双链路并存 | 需保证 langgraph 服务稳定(已有回退机制) | ~2 人日 |
+| B. Java 移植 | 单体部署,无跨服务依赖 | 重写多行状态机 + 批注对位 + CJK 归一化,风险高;每升级需重写 | ~8–10 人日 |
+| C. 调用独立 Python 服务 | 解耦 | 多一个服务要部署运维 | ~3 人日 |
+
+**推荐 A**,理由:langgraph 已是生产依赖(异步采集主路径),加一个 guhe_v2 分支不增加新组件;回退机制已有。
+
+### 决策 2 · payload 完整保留 vs 裁剪(推荐 A)
+
+| 方案 | 优点 | 缺点 |
+|---|---|---|
+| **A. 保留完整 35 键 payload**(推荐) | 后续功能(相似度、多样性、报告总结、自检)都从 payload 取,无需重解析 | payload_json 较大(约 300–500KB / 份) |
+| B. 只提取必要字段 | 表小 | 每加一个功能都要重解析 PDF |
+
+**推荐 A**,理由:`health_report_drafts.payload_json` 已是 TEXT,容量无硬约束;重解析成本远高于存储成本。
+
+### 决策 3 · 归一化数据来源(推荐 A + 渐进升级到 B)
+
+| 方案 | 来源 | 局限 |
+|---|---|---|
+| **A. 样本回归估算**(首期) | 已有 17 份样本的 `正常范围` | 不是官方 710 常模,人群代表性有限 |
+| B. 谷禾官方 710 常模(长期) | 需向谷禾采购或合作 | 商务周期未知 |
+
+**推荐 A 先落地**,同时在归因报告展示时加 `source="样本回归估算"` 与「人群代表性有限」提示,避免夸大(§5.7 证据码 DEV,非 PUB)。
+
+---
+
+## 五、表结构变更(DDL 草案)
+
+```sql
+-- 1) health_reports 新增列(ALTER TABLE)
+ALTER TABLE health_reports ADD COLUMN fb_ratio TEXT NULL COMMENT 'F/B 比值原文(谷禾新版)';
+ALTER TABLE health_reports ADD COLUMN shannon_index_norm TEXT NULL COMMENT '香农指数分级文字';
+ALTER TABLE health_reports ADD COLUMN subhealth_label TEXT NULL COMMENT '亚健康标签(谷禾新版)';
+ALTER TABLE health_reports ADD COLUMN parse_self_check JSON NULL COMMENT '_解析自检 结果 JSON';
+
+-- 2) health_disease_risk 新增列
+ALTER TABLE health_disease_risk ADD COLUMN similarity_level TEXT NULL COMMENT '低/中/高相似(谷禾新版)';
+
+-- 3) health_gut_flora 新增列
+ALTER TABLE health_gut_flora ADD COLUMN reference_range TEXT NULL COMMENT '参考范围原文';
+ALTER TABLE health_gut_flora ADD COLUMN direction VARCHAR(2) NULL COMMENT '▲/▼/NULL';
+ALTER TABLE health_gut_flora ADD COLUMN species_code VARCHAR(128) NULL COMMENT '拉丁名';
+ALTER TABLE health_gut_flora ADD COLUMN functional_tag VARCHAR(64) NULL COMMENT '功能标签';
+
+-- 4) 新表 health_species_library
+CREATE TABLE IF NOT EXISTS health_species_library (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  report_id BIGINT NOT NULL,
+  species_no INT NOT NULL,
+  cn_name VARCHAR(128),
+  latin_name VARCHAR(128),
+  function_tag VARCHAR(64),
+  detection_rate VARCHAR(32),
+  function_desc TEXT,
+  improve_method TEXT,
+  abundance VARCHAR(32),
+  ref_range VARCHAR(64),
+  status VARCHAR(16),
+  direction VARCHAR(2),
+  KEY idx_report (report_id)
+) COMMENT='谷禾新版物种功能库(76 条/份,知识层 + 个人层)';
+
+-- 5) 新表 health_abnormal_species(可视图/派生表)
+CREATE OR REPLACE VIEW health_abnormal_species AS
+SELECT report_id, species_no, cn_name, latin_name, abundance, ref_range, direction
+FROM health_species_library
+WHERE direction IS NOT NULL;
+
+-- 6) health_report_drafts 已有 collect_validation 字段,无变更
+```
+
+---
+
+## 六、接口契约变更
+
+### 6.1 上传接口
+
+**`POST /api/health/report/upload`**
+- 请求不变(`file` + `userId` + `familyId`)
+- 响应新增字段:`reportFormat`(`guhe` / `guhe_v2` / `beijing` / `aidefansi`)、`parseMethod`(`local` / `langgraph`)、`draftId`(异步时返回)
+
+**`GET /api/health/report/collect/status?draftId=…`**
+- 响应新增:`parseSelfCheck`(JSON,`_解析自检`)
+
+### 6.2 报告详情
+
+**`GET /api/health/report/detail?reportId=…`**
+- 响应新增:`abnormalSpecies`(数组)、`speciesLibrary`(数组,76 条)、`fbRatio`、`shannonIndexNorm`、`subhealthLabel`、`parseSelfCheck`
+
+### 6.3 新增接口
+
+**`GET /api/health/report/abnormal-species?reportId=…`** —— 见 P0-6
+
+### 6.4 归因接口
+
+**`POST /api/attribution/analyze`**
+- 请求不变
+- 响应新增:`normSource`(`placeholder` / `sample_regression` / `official_710`)、`normVersion`
+
+---
+
+## 七、回归与验收
+
+### 7.1 单测
+
+- Java `PdfParseServiceTest`:新增 `test_detectGuheV2_guheV2()`、`test_detectGuheV2_oldGuhe()`、`test_detectGuheV2_beijing()`、`test_detectGuheV2_aidefansi()`
+- Java `HealthReportControllerTest`:`test_upload_guheV2_routes_to_langgraph()`、`test_upload_guheV2_async_parse_self_check()`
+- Python `test_report_parse.py`:`test_parse_guhe_v2_maojingming()`(比对 payload 逐键一致)、`test_parse_guhe_v2_self_check_pass()`
+
+### 7.2 集成回归
+
+- 拿 17 份样本 PDF 各上传一次(毛静明 / 吴介洋 / 廖某人 / 侯 / 闫晗 / 曹丽君 / 王卫东 / 马安扬 / 马昕源 / 詹欣 / 小强 / 赵立辉 / 儿童示例 / 朱评估报告 / 北京移植前 / 北京移植后复测 / 艾德范思模板),校验:
+  - `report_format` 识别正确
+  - payload_json 与 bun-report-parser 本地输出一致
+  - `_解析自检.P0=0`
+  - 异步采集完成后 `health_report_drafts.parse_status='success'`
+
+### 7.3 验收标准
+
+| 项 | 标准 |
+|---|---|
+| 谷禾新版格式识别准确率 | ≥ 99%(17 份样本 + 历史样本回归) |
+| 异常菌清单条数 | 毛静明 = 12、吴介洋与历史样本按实际 |
+| 解析耗时 | 单份 ≤ 6 分钟(异步,含队列) |
+| P0 自检告警 | 全部 0 |
+| 健康计划禁用词命中 | 0(P1-2 审计通过) |
+
+---
+
+## 八、风险与红线
+
+### 8.1 归因禁区(§8.1,破一条即失格)
+
+- 器质性诊断不得纳入调理目标;处方药不得建议增减或停用;12 周内不设不可测目标;急症信号只做转介;行为判读先排除医学约束。
+- 落地:P1-1 的 prompt 约束 + Java 输入字段 `medical_constraints` + 输出正则审计。
+
+### 8.2 介导链路禁确定性因果(§5.8)
+
+- 菌群 → 递质 → 情绪/认知 的 ⚠ 介导链路只作**上游信号**,不判能力;行文一律「相关联 / 报告提示 / 可能与…有关」。
+- 落地:P1-2 的 system prompt 约束 + 输出正则审计。
+
+### 8.3 归一化数据代表性
+
+- 首期归一化数据来自 17 份样本回归,**非官方 710 常模**,人群代表性有限。展示时必须写 `source` 字段,禁写「符合人群 xx%」等断言。
+
+### 8.4 payload 完整性与隐私
+
+- payload 含姓名、编号、年龄、性别、检测数值,属个人健康数据(§5.7:不跨人比较、不外传)。前端展示加权限校验(已有 `health_report_permissions` / `report_member_permissions`)。
+
+### 8.5 上游同步
+
+- `bun-report-parser` 后续升级(v1.3.2 / v1.4 / v1.5 …)需评估同步到 langgraph 子包;建议建立 changelog 订阅或 submodule。
+
+---
+
+## 九、里程碑(建议)
+
+| 里程碑 | 内容 | 依赖 | 工期 |
+|---|---|---|---|
+| **M1** | P0-1 Java 格式识别 + P0-2 异步切流 | 无 | 2 人日 |
+| **M2** | P0-3 Python 接入 bun-report-parser + P0-4 表结构 + P0-6 异常菌接口 | M1 | 3 人日 |
+| **M3** | P0-5 归一化数据填充 + 归因引擎真实输出 | M2 | 2 人日 |
+| **M4** | P1-1 健康计划红线 + P1-2 介导链路审计 | M2 | 2 人日 |
+| **M5** | P1-3 前端展示增强 | M2 | 3 人日 |
+| **M6** | P2 运营监控 + 灰度 | M3 | 2 人日 |
+
+**合计约 14 人日**(不含测试与上线)。建议灰度顺序:先内部测试号上传毛静明等 17 份样本 → 再小范围开放给已付费用户 → 再全面。
+
+---
+
+## 十、附录:本方案用到的关键源码/资源路径
+
+- Java 入口:`E:\cfc\cfc-backend\src\main\java\com\etotem\cfc\controller\HealthReportController.java`
+- Java 解析:`E:\cfc\cfc-backend\src\main\java\com\etotem\cfc\service\PdfParseService.java`
+- Java 归因:`E:\cfc\cfc-backend\src\main\java\com\etotem\cfc\service\attribution\FiveDimAttributionEngine.java`、`NormCompareEngine.java`
+- 归一化规则:`E:\cfc\cfc-backend\src\main\resources\norm\attribution_norm_gut_flora.json`(当前 placeholder=true)
+- 五维编码:`E:\cfc\cfc-backend\src\main\java\com\etotem\cfc\common\constant\DimensionCodeConstants.java`(5 根 33 子维)
+- 表结构:`E:\cfc\cfc-backend\src\main\resources\schema.sql`(health_reports L1853 / health_gut_flora L1988 / attribution_reports L5211)
+- langgraph 入口:`E:\cfc\cfc-langgraph\app\api\report_parse.py`、`app\agents\report_parse_agent.py`
+- langgraph 解析:`E:\cfc\cfc-langgraph\app\parsers\pdf_parser.py`(v5 移植)
+- langgraph 健康计划:`E:\cfc\cfc-langgraph\app\graphs\health_plan_graph.py`
+- 上游解析器:`C:/Users/liaoxg.DESKTOP-DGLN79N/.workbuddy/skills/bun-report-parser/scripts/`
+- 上游专家:`C:/Users/liaoxg.DESKTOP-DGLN79N/.workbuddy/plugins/marketplaces/my-experts/plugins/socratic-coach/agents/socratic-coach.md`(§5.8 / §8.1 红线)
+- 归因口径底稿:`E:\cfc\docs\参考资料\bun-report-parser-v1.3.1-修复说明与回归报告.md`
+
+---
+
+**下一步建议**:把 M1(Java 格式识别 + 异步切流)拆成 sprint task,先落 1 个能跑通的 guhe_v2 报告(毛静明)作为端到端冒烟;端到端跑通后再并行推进 M2–M6。

BIN
docs/浠艾福程序-谷禾新版解析与五维归因升级方案-v1.0.pdf