feat(ssa): Complete Phase V-A editable analysis plan variables

Features:
- Add editable variable selection in workflow plan (SingleVarSelect + MultiVarTags)
- Implement 3-layer flexible interception (warning bar + icon + blocking dialog)
- Add tool_param_constraints.json for 12 statistical tools parameter validation
- Add PATCH /workflow/:id/params API with Zod structural validation
- Implement synchronous parameter sync before execution (Promise chaining)
- Fix LLM hallucination by strict system prompt constraints
- Fix DynamicReport object-based rows compatibility (R baseline_table)
- Fix Word export row.map error with same normalization logic
- Restore inferGroupingVar for smart default variable selection
- Add ReactMarkdown rendering in SSAChatPane
- Update SSA module status document to v3.5

Modified files:
- backend: workflow.routes, ChatHandlerService, SystemPromptService, FlowTemplateService
- frontend: WorkflowTimeline, SSAWorkspacePane, DynamicReport, SSAChatPane, ssaStore, ssa.css
- config: tool_param_constraints.json (new)
- docs: SSA status doc, team review reports

Tested: Cohort study end-to-end execution + report export verified
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-02-24 13:08:29 +08:00
parent dc6b292308
commit 85fda830c2
27 changed files with 2732 additions and 154 deletions

View File

@@ -1,13 +1,24 @@
# SSA智能统计分析模块 - 当前状态与开发指南
> **文档版本:** v3.4
> **文档版本:** v3.5
> **创建日期:** 2026-02-18
> **最后更新:** 2026-02-22
> **最后更新:** 2026-02-23
> **维护者:** 开发团队
> **当前状态:** 🎉 **QPER 主线闭环 + Phase I + Phase II + Phase III + Phase IV对话驱动分析 + QPER 集成)开发完成**
> **当前状态:** 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A分析方案变量可编辑化)开发完成**
> **文档目的:** 快速了解SSA模块状态为新AI助手提供上下文
>
> **最新进展2026-02-22 Phase IV 完成):**
> **最新进展2026-02-23 Phase V-A 变量可编辑化完成):**
> - ✅ **分析方案变量可编辑化** — 系统默认帮选变量,医生可在方案审查阶段修改/调整变量选择
> - ✅ **三层柔性拦截** — Layer 1 即时黄条警告 + Layer 2 步骤警告图标 + Layer 3 执行前阻断确认弹窗Informed Consent
> - ✅ **变量选择器 UI** — 单选下拉(按类型分组)+ 多选标签(分类=紫色 / 连续=蓝色)+ 全选分类/连续快捷按钮 + 不适配变量 ⚠️ 标记
> - ✅ **tool_param_constraints 配置** — 12 个统计工具参数约束表,前后端共用单一事实来源
> - ✅ **后端 PATCH API + Zod 防火墙** — PATCH /workflow/:id/params + 结构校验400 Bad Request/ 统计学校验交给 R 引擎
> - ✅ **同步阻塞执行** — 执行按钮 Promise Chainingawait PATCH -> 再触发执行 + loading 防连点
> - ✅ **inferGroupingVar 恢复** — LLM 未识别分组变量时,自动推断二分类变量填入默认值
> - ✅ **DynamicReport 增强** — 兼容 R 基线表对象格式 rowsWord 导出同步修复
> - ✅ **前后端集成测试通过** — 队列研究完整执行 + 报告导出验证
>
> **此前进展2026-02-22 Phase IV 完成):**
> - ✅ **Phase IV 全 5 批次完成** — ToolOrchestratorServicePICO hint 三层降级)+ handleAnalyze 重写plan→analysis_plan SSE→LLM 方案说明→ask_user 确认)+ AVAILABLE_TOOLS 配置化11 处改 toolRegistryService+ 前端 SSE 对接analysis_plan + plan_confirmed
> - ✅ **团队审查 H1-H3+B1-B2 全部落地** — H1 PICO hint 注入 / H2 幽灵卡片清除 / H3 SSE 严格串行 / B1 修改建议循环 / B2 旧 API 兼容
> - ✅ **SSA_ANALYZE_PLAN Prompt 入库** — 指导 LLM 用自然语言解释分析方案(步骤/理由/注意事项)
@@ -57,7 +68,7 @@
| **前端状态模型** | **Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps** |
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
| **目标用户** | 临床研究人员、生物统计师 |
| **开发状态** | 🎉 **QPER 主线闭环 + 智能对话架构设计完成Phase Deploy 待启动** |
| **开发状态** | 🎉 **QPER 主线闭环 + Phase I-IV + Phase V-A变量可编辑化完成** |
### 核心目标
@@ -159,7 +170,8 @@ AnalysisRecord {
| **Phase II** | **对话层 LLM + 意图路由器 + 统一对话入口** | **35h** | ✅ **已完成4 批次, 12 文件, E2E 38/38, H1-H4 落地)** | 2026-02-22 |
| **Phase III** | **method_consult + ask_user 标准化** | **20h** | ✅ **已完成5 批次, 12 文件, E2E 13/13+4skip, H1-H3+P1 落地)** | 2026-02-22 |
| **Phase IV** | **对话驱动分析 + QPER 集成** | **14h** | ✅ **已完成5 批次, 11 文件, E2E 25/25, H1-H3+B1-B2 落地)** | 2026-02-22 |
| **Phase V** | **反思编排 + 高级特性** | **18h** | 📋 待开始 | - |
| **Phase V-A** | **分析方案变量可编辑化** | **~6h** | **已完成9 文件, 团队双视角审查 V2, 三层柔性拦截)** | 2026-02-23 |
| **Phase V-B** | **反思编排 + 高级特性** | **18h** | 📋 待开始 | - |
| **Phase VI** | **集成测试 + 可观测性** | **10h** | 📋 待开始 | - |
### 已完成核心功能
@@ -181,7 +193,9 @@ AnalysisRecord {
| **Phase III 前端** | AskUserCard4 inputType + H1 跳过按钮)+ useSSAChat 扩展pendingQuestion + respondToQuestion + skipQuestion | ✅ |
| **Phase IV 后端** | ToolOrchestratorServiceplan+PICO hint 三层降级+formatPlanForLLM+ ChatHandlerService 重写handleAnalyze: plan→analysis_plan SSE→LLM 说明→ask_user 确认; handleAskUserResponse: confirm_plan/change_method+ AVAILABLE_TOOLS 配置化11 处→toolRegistryService+ ToolRegistryService+getVisibleTools+ AskUserService+metadata+ SSA_ANALYZE_PLAN Prompt 入库 | ✅ |
| **Phase IV 前端** | useSSAChatanalysis_plan+plan_confirmed SSE 处理+pendingPlanConfirm→executeWorkflow+ SSAChatPaneAskUserCard 渲染+幽灵卡片清除 H2 | ✅ |
| **测试** | QPER 端到端 40/40 + 集成测试 7 Bug 修复 + Phase I E2E 31/31 + Phase II E2E 38/38 + Phase III E2E 13/13+4skip + Phase IV E2E 25/25 | ✅ |
| **Phase V-A 后端** | PATCH /workflow/:id/paramsZod 结构校验防火墙)+ tool_param_constraints.json12 工具参数约束)+ inferGroupingVar 恢复(默认填充分组变量) | ✅ |
| **Phase V-A 前端** | WorkflowTimeline 可编辑化SingleVarSelect + MultiVarTags + 三层柔性拦截)+ ssaStore updateStepParams + SSAWorkspacePane 同步阻塞执行 + DynamicReport 对象 rows 兼容 + Word 导出修复 | ✅ |
| **测试** | QPER 端到端 40/40 + 集成测试 7 Bug 修复 + Phase I E2E 31/31 + Phase II E2E 38/38 + Phase III E2E 13/13+4skip + Phase IV E2E 25/25 + Phase V-A 前后端集成测试通过 | ✅ |
---
@@ -210,7 +224,8 @@ backend/src/modules/ssa/
│ ├── ConfigLoader.ts # 通用 JSON 加载 + Zod 校验
│ ├── tools_registry.json # R 工具注册表
│ ├── decision_tables.json # 四维匹配规则
── flow_templates.json # 流程模板
── flow_templates.json # 流程模板
│ └── tool_param_constraints.json # Phase V-A12 工具参数类型约束
├── types/
│ ├── query.types.ts # Q 层接口
│ ├── reflection.types.ts # R 层接口
@@ -324,7 +339,7 @@ npx tsx scripts/seed-ssa-phase4-prompts.ts # Phase IV: SSA_ANALYZE_PLAN
### 近期(优先级高)
1. **Phase V — 反思编排 + 高级特性18h / 3 天)**
1. **Phase V-B — 反思编排 + 高级特性18h / 3 天)**
- 错误分类器实现(可自愈 vs 不可自愈)
- 自动反思静默重试MAX 2 次)+ 手动反思用户驱动feedback 意图)
- write_report interpret 模式 + discuss 意图处理(深度解读已有结果)
@@ -335,7 +350,7 @@ npx tsx scripts/seed-ssa-phase4-prompts.ts # Phase IV: SSA_ANALYZE_PLAN
3. **Phase VI10h** — 集成测试 + 可观测性(含 QPER 透明化)
**详细计划:** `04-开发计划/11-智能对话与工具体系开发计划.md`v1.8Phase I-IV 完成,含架构约束 C1-C8 + 全部团队审查落地记录)
**详细计划:** `04-开发计划/11-智能对话与工具体系开发计划.md`v1.8Phase I-IV + Phase V-A 完成,含架构约束 C1-C8 + 全部团队审查落地记录)
---
@@ -380,7 +395,7 @@ npx tsx scripts/seed-ssa-phase4-prompts.ts # Phase IV: SSA_ANALYZE_PLAN
---
**文档版本:** v3.4
**最后更新:** 2026-02-22
**当前状态:** 🎉 QPER 主线闭环 + Phase I + Phase II + Phase III + Phase IV 已完成
**下一步:** Phase V反思编排 + 高级特性18h/3 天)
**文档版本:** v3.5
**最后更新:** 2026-02-23
**当前状态:** 🎉 QPER 主线闭环 + Phase I-IV + Phase V-A变量可编辑化已完成
**下一步:** Phase V-B(反思编排 + 高级特性18h/3 天)