# 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 协议结构

```json
{
  "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 实施。