AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/04-开发计划/08-Block-based动态结果渲染开发计划.md

Block-based 动态结果渲染开发计划

版本： v1.0
创建日期： 2026-02-20
状态： 📋 待开始
优先级： P0（架构级改进，影响所有后续工具开发）
关联文档： 06-开发记录/SSA-Pro 动态结果渲染与通信协议规范.md

---

1. 背景与动机

当前痛点

目前每个 R 工具返回独特的数据结构，导致：

• R 端：每个工具自定义 results 字段（T检验有 group_stats，Logistic有 coefficients，描述性统计有 variables）
• Node.js 后端：用 ...response.data.results 硬展开，手动拼装 plots、result_table 等字段
• 前端：为每种工具写 if (isDescriptive) / if (r?.coefficients) 等分支渲染逻辑
• 导出报告：Word 导出同样需要为每种工具写独立的构建逻辑

核心矛盾：R 工具数量增长（当前 7 个，目标 100+），但前端/后端的维护成本线性增长。

目标

采用 Block-based 协议，实现：

• R 端输出标准化的 report_blocks 数组
• Node.js 零维护透传
• 前端一个 DynamicReport 组件渲染所有工具的结果
• Word 导出一个 exportBlocksToWord 函数处理所有工具

---

2. 技术方案

2.1 四种 Block 类型

Block 类型	用途	典型场景
markdown	文本解读、警告、结论	AI 统计解读、护栏警告、方法说明
table	三线表、矩阵	分组统计表、回归系数表、列联表、描述性统计表
image	可视化图表	箱线图、森林图、直方图、马赛克图
key_value	核心统计量高亮	P值、统计量、效应量、AIC

2.2 协议结构

{
  "status": "success",
  "trace_log": ["..."],
  "reproducible_code": "library(ggplot2)...",
  "report_blocks": [
    {
      "type": "key_value",
      "title": "核心指标",
      "items": [
        {"label": "统计方法", "value": "Independent T-Test"},
        {"label": "t 值", "value": "2.45"},
        {"label": "P 值", "value": "0.015", "status": "significant"}
      ]
    },
    {
      "type": "table",
      "title": "Table 1. 分组统计",
      "data": {
        "headers": ["Group", "N", "Mean ± SD"],
        "rows": [["Drug", "60", "14.5 ± 3.2"], ["Placebo", "60", "8.2 ± 2.8"]]
      }
    },
    {
      "type": "image",
      "title": "Figure 1. 分布对比",
      "format": "base64",
      "src": "iVBORw0KGgo...",
      "caption": "箱线图展示两组分布"
    },
    {
      "type": "markdown",
      "content": "**AI 解读：** 两组差异具有统计学意义 (P = 0.015)..."
    }
  ]
}

---

3. 实施计划

Phase 1：基础设施（1 天）

任务	层级	说明	预估
1.1 创建 DynamicReport.tsx 组件	前端	4 个 Block 渲染子组件	2h
1.2 创建 exportBlocksToWord.ts	前端	Block 数组 → Word 文档	2h
1.3 后端透传 report_blocks	后端	WorkflowExecutorService 透传	0.5h
1.4 R 端辅助函数库 block_helpers.R	R	make_table_block(), make_image_block() 等	1h
1.5 SSAWorkspacePane 集成	前端	优先读 report_blocks，fallback 旧逻辑	1h

Phase 2：R 工具改造（2 天）

任务	R 工具	当前 Block 输出内容	预估
2.1	descriptive.R	summary key_value + 数值变量 table + 分类变量 table + 直方图/柱状图 image	1.5h
2.2	t_test_ind.R	核心指标 key_value + 分组统计 table + AI 解读 markdown + 箱线图 image	1h
2.3	logistic_binary.R	模型拟合 key_value + 回归系数 table + 森林图 image + AI 解读 markdown	1.5h
2.4	chi_square.R	核心指标 key_value + 列联表 table + 马赛克图 image	1h
2.5	correlation.R	核心指标 key_value + 散点图 image + AI 解读 markdown	1h
2.6	t_test_paired.R	核心指标 key_value + 配对差值 table + image	1h
2.7	mann_whitney.R	核心指标 key_value + 分组统计 table + image	1h

Phase 3：清理旧代码（0.5 天）

任务	说明	预估
3.1 移除 SSAWorkspacePane 中的自定义渲染逻辑	删除 isDescriptive、r?.coefficients 等分支	1h
3.2 移除 useAnalysis.ts 中的自定义导出逻辑	删除 isDescStep、classifyExportVar 等	1h
3.3 移除后端 result 字段展开逻辑	删除 ...response.data.results 拼装	0.5h
3.4 更新文档	更新开发指南、R 服务开发规范	0.5h

---

4. 向后兼容策略

采用 渐进式迁移，不一刀切：

1. R 工具同时返回 results（旧）和 report_blocks（新）
2. 前端优先读 report_blocks，如果不存在则 fallback 到旧的自定义渲染
3. 全部 7 个工具迁移完成后，再删除旧渲染代码

---

5. 预期收益

指标	改造前	改造后
新增 1 个 R 工具的前端开发量	50-100 行自定义渲染 + 50 行导出逻辑	0 行
新增 1 个 R 工具的后端开发量	10-20 行字段映射	0 行
前端结果渲染组件数	N 个（每种工具一个分支）	1 个 DynamicReport
Word 导出维护成本	每种工具单独处理	1 个通用函数

---

6. 总工时估算

Phase	工时
Phase 1：基础设施	6.5h
Phase 2：R 工具改造	8h
Phase 3：清理旧代码	3h
合计	~17.5h（约 2.5 天）

---

下一步： 待用户确认后开始 Phase 1 实施。