HaHafeng
428a22adf2
Phase 2A: WorkflowPlannerService, WorkflowExecutorService, Python data quality, 6 bug fixes, DescriptiveResultView, multi-step R code/Word export, MVP UI reuse. V11 UI: Gemini-style, multi-task, single-page scroll, Word export. Architecture: Block-based rendering consensus (4 block types). New R tools: chi_square, correlation, descriptive, logistic_binary, mann_whitney, t_test_paired. Docs: dev summary, block-based plan, status updates, task list v2.0. Co-authored-by: Cursor <cursoragent@cursor.com>
154 lines
5.5 KiB
Markdown
154 lines
5.5 KiB
Markdown
# 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 实施。
|