通用报告块渲染引擎（report-blocks）设计

日期：2026-08-10 状态：已确认（用户已逐节批准）

背景与问题

肠道菌群报告详情页存在字段错位 bug：buildReportFromPayload（HealthReportController:1553-1593）只填充第二套评分字段（diversityScore 等），而前端 gut-flora-detail.vue 的 buildScores（242-252）读取第一套字段（gutDiversityScore 等）→ 5 个评分圆环（菌群多样性/平衡/有益菌/有害菌/核心菌属）永远为 null 不显示。

更深层的问题：系统存在多套并行报告链路（肠道菌群/体检/舌诊/DAN），每种报告各有一套页面、字段、接口，扩展成本高、易出字段错位类 bug。DAN 报告（独立 dan_report_uploads 表 + DanReportController）甚至没有独立详情页，只能复用上传页展示。

目标

构建通用报告块渲染引擎：

解析器输出统一 blocks 结构（JSON），前端按 block.type 通用渲染，前端零字段名耦合
覆盖报告类型：gut_flora / dan / physical_exam / tongue（体检/舌诊二期）
疾病风险按风险等级分组（重要风险 = 需注意/高风险/异常；其它风险 = 低风险），直接展示在详情页内
修复肠道菌群 9 项评分圆环显示问题（从源头消灭键名错位）
存量接口/页面零破坏（旧字段保留兼容，逐步迁移）

架构总览

解析器（LangGraph / Java fallback / DanReportParseService）
   ↓ 结构化数据（ParsedReportPayload / DanParsedReport）
ReportBlockAssembler —— 按 reportType 组装 blocks[]
   ↓ confirm/编辑保存时落库
report_blocks 表（report_type + report_id 复合唯一键 + blocks JSON）
   ↓ 查询
getReportDetail / DanReportController.detail —— 返回 reportType + blocks（旧字段保留）
   ↓
前端 report-detail 统一外壳 + <report-blocks-renderer> 通用渲染

表结构

CREATE TABLE report_blocks (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  report_type VARCHAR(32) NOT NULL COMMENT 'gut_flora / dan / physical_exam / tongue',
  report_id   BIGINT NOT NULL COMMENT '各类型报告主键ID（health_reports.id 或 dan_report_uploads.id，各自序列不冲突）',
  blocks      JSON NOT NULL COMMENT '块数组 [{type,title,items,extra}]',
  version     INT DEFAULT 1,
  created_at  DATETIME,
  updated_at  DATETIME,
  UNIQUE KEY uk_report_type_id (report_type, report_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='报告通用展示块';

(report_type, report_id) 复合唯一键 → 各类型 id 序列互不干扰
落库用 upsert（存在则覆盖），幂等
迁移入口：DatabaseInitializer.runMigrations()（按 AGENTS.md 迁移工作流，同步 schema.sql）

blocks schema（6 种块类型）

[
  { "type": "score",       "title": "健康评分",
    "items": [ {"label":"综合","value":57,"max":100}, {"label":"菌群多样性","value":50,"max":100} ] },

  { "type": "risk_group",  "title": "重要风险",
    "items": [ {"name":"心脑血管疾病","value":"0.37","level":"注意"},
               {"name":"抑郁症","value":"0.27","level":"低风险"} ] },

  { "type": "indicator",   "title": "营养素",
    "items": [ {"name":"维生素D","value":"28.5","unit":"ng/mL","refRange":"30-100","status":"偏低"} ] },

  { "type": "list",        "title": "检出菌种",
    "columns": [ {"key":"name","label":"菌种"}, {"key":"value","label":"相对丰度"}, {"key":"status","label":"状态"} ],
    "items": [ {"name":"双歧杆菌","value":"12.4%","status":"正常"} ] },

  { "type": "text",        "title": "报告解读", "content": "..." },

  { "type": "chart",       "title": "维度雷达", "chartType": "radar", "data": {...} }
]

块类型	覆盖现有	前端渲染
`score`	肠道 9 项评分、DAN total_score/percentile	评分圆环组
`risk_group`	疾病风险（按等级分"重要风险/其它风险"两组）	风险卡片 + 等级徽章
`indicator`	营养素/肠道屏障指标（status 高亮）	指标卡片/表格
`list`	菌种列表、DAN 各维度得分 items	通用列表（columns 驱动）
`text`	报告解读、DAN summary/suggestions	段落
`chart`	雷达图（body-detail 的 radarDimensions）	预留（二期）

后端实现

ReportBlock 实体 + ReportBlockMapper

MyBatis-Plus，@TableName("report_blocks")，blocks 列存 JSON 字符串。提供 save(type, reportId, blocks)（upsert）与 getBlocks(type, reportId)。

ReportBlockAssembler Service

按 reportType 分发组装：

方法	输入	输出 blocks
`assembleGutFlora(ParsedReportPayload)`	LangGraph/Java fallback 的 payload	`score`(9 项评分) + `risk_group`(重要/其它两组) + `indicator`(营养素/肠道屏障) + `list`(菌种/病原菌/食物推荐) + `text`(解读)
`assembleDan(DanParsedReport)`	DAN 解析结果	`score`(total/percentile) + `list`(各维度得分按 category 分组) + `text`(summary/suggestions)
`assembleExam(payload)` / `assembleTongue(...)`	体检/舌诊（二期）	对应块

要点：

命名注意：report_blocks.report_type 是报告类别（gut_flora/dan/physical_exam/tongue）；DAN 子类型 A2/B4（DanReportUpload.reportType）不是类别，由组装器放入 blocks 的 extra（如 {"subType":"A2"}）供前端展示徽章，两者不得混淆
评分圆环：组装器从 payload 的第二套键（balanceScore/diversityScore/beneficialScore/harmfulScore/coreGenusScore + overallScore/gutHealthScore/chronicDiseaseScore/nutritionScore）组装 9 项，前端不再碰实体字段名
疾病风险分组：需注意/高风险/异常 → "重要风险"组；低风险 → "其它风险"组
组装失败不阻断 confirm：blocks 留空，详情页回退旧字段

落库挂点（3 处）

挂点	时机	写入
`confirmDraft`（HealthReportController:888 createReport 后）	肠道菌群/体检确认	`save('gut_flora', report.id, blocks)`
`confirmUpload`（DanReportUploadService）	DAN 确认	`save('dan', upload.id, blocks)`
`updateReportFromPayload` / `editHealthReport` / `DanReportController.edit`	编辑保存后	重新组装覆盖

接口

getReportDetail（HealthReportService:312）追加 detail.put("blocks", ...)，旧字段（report/indicators/gutFlora/diseaseRisks）全保留
DanReportController.detail 追加 blocks
现有页面（body-detail/health-report.vue 等）零破坏

前端实现

通用渲染器 `components/report-blocks-renderer.vue`

props: { blocks: [] }，v-for 按 block.type 分发 6 个子渲染组件：

score-block：评分圆环组（圆环 + 数值）
risk-group-block：风险卡片 + 等级徽章（重要风险红/橙，其它风险绿）
indicator-block：指标卡片（status 高亮）
list-block：通用列表（columns 驱动）
text-block：段落
chart-block：预留

纯展示组件，零字段名耦合。遵循小程序限制（禁可选链/禁 CSS Grid/禁 :key 表达式）。

统一详情页 `pages/health/report-detail.vue`

外壳：报告头（类型徽章/姓名/日期）+ blocks 渲染区。疾病风险直接展示在详情页内（risk_group 块），不用再跳子页。

入口切换

report-list.vue goToDetail（79-87）：gut_flora/dan → 新详情页 ?reportType=&reportId=；physical_exam/tongue 暂留原页面
DAN 维度页 viewDanReport（wisdom-detail:370 / mind-detail）：从 report-upload?draftId= 改为新详情页
旧详情页（gut-flora-detail 等）保留，验证通过后再删除

编辑策略

blocks 是只读视图模型。编辑走现有结构化接口（editHealthReport 等），保存后重新组装 blocks。渲染引擎不做编辑器。

风险编辑：新详情页内联等级/值编辑 → 调 editHealthReport → 刷新 blocks。

分期实施

阶段	内容	验证
1	后端全链：迁移建表 + Assembler(gut_flora+dan) + 3 个落库挂点 + 接口返回 blocks	`mvn clean compile` + Assembler 单元测试（断言 9 项评分/风险分组/DAN items）
2	前端：blocks-renderer + 统一详情页 + report-list 切换 gut_flora/dan	小程序模拟器打开 501999942 报告：9 项评分圆环全显示、风险两组卡片、营养素/菌种/解读
3	疾病风险内联编辑 + DAN 维度页跳转 + 兼容验证	编辑风险保存后 blocks 刷新；DAN A2/B4 报告在维度页正常渲染
4	（可选）体检/舌诊接入 + 旧页面收尾删除	回归

错误处理

blocks 空/缺失 → 详情页显示"暂无报告内容"并回退旧字段渲染（兼容期兜底）
组装失败 → 不阻断 confirm，blocks 留空
落库幂等（upsert）

测试

后端：ReportBlockAssemblerTest（gut_flora payload → blocks 断言：9 项评分齐全、风险分组正确、DAN items 映射）+ mvn clean compile
前端：语法/结构校验（node --check），不改动打包流程（HBuilderX 打包）

2026-08-10-report-blocks-renderer-design.md 10 KB

Permalink History Raw

通用报告块渲染引擎（report-blocks）设计

背景与问题

目标

架构总览

表结构

blocks schema（6 种块类型）

后端实现

ReportBlock 实体 + ReportBlockMapper

ReportBlockAssembler Service

落库挂点（3 处）

接口

前端实现

通用渲染器 `components/report-blocks-renderer.vue`

统一详情页 `pages/health/report-detail.vue`

入口切换

编辑策略

分期实施

错误处理

测试

相关文件

2026-08-10-report-blocks-renderer-design.md 10 KB Permalink History Raw

通用报告块渲染引擎（report-blocks）设计

背景与问题

目标

架构总览

表结构

blocks schema（6 种块类型）

后端实现

ReportBlock 实体 + ReportBlockMapper

ReportBlockAssembler Service

落库挂点（3 处）

接口

前端实现

通用渲染器 components/report-blocks-renderer.vue

统一详情页 pages/health/report-detail.vue

入口切换

编辑策略

分期实施

错误处理

测试

相关文件

2026-08-10-report-blocks-renderer-design.md 10 KB

Permalink History Raw

通用渲染器 `components/report-blocks-renderer.vue`

统一详情页 `pages/health/report-detail.vue`