feat(ssa): Complete T-test end-to-end testing with 9 bug fixes - Phase 1 core 85% complete. R service: missing value auto-filter. Backend: error handling, variable matching, dynamic filename. Frontend: module activation, session isolation, error propagation. Full flow verified.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-19 20:57:00 +08:00
parent 8137e3cde2
commit 49b5c37cb1
86 changed files with 21207 additions and 252 deletions
--- a/docs/03-业务模块/SSA-智能统计分析/06-开发记录/Week1-开发总结报告.md
+++ b/docs/03-业务模块/SSA-智能统计分析/06-开发记录/Week1-开发总结报告.md
@@ -0,0 +1,260 @@
+# SSA-Pro 模块 Week 1 开发总结报告
+
+> **版本：** v1.0  
+> **日期：** 2026-02-19  
+> **编写：** AI 开发助手  
+> **状态：** ✅ Week 1 完成
+
+---
+
+## 📋 目录
+
+1. [开发目标](#1-开发目标)
+2. [完成工作清单](#2-完成工作清单)
+3. [关键决策与讨论](#3-关键决策与讨论)
+4. [技术挑战与解决方案](#4-技术挑战与解决方案)
+5. [代码审查与规范对齐](#5-代码审查与规范对齐)
+6. [产出物清单](#6-产出物清单)
+7. [遗留问题与后续工作](#7-遗留问题与后续工作)
+
+---
+
+## 1. 开发目标
+
+Week 1 的核心目标是**搭建 SSA-Pro 模块的技术骨架**，包括：
+
+- R 统计服务 Docker 环境
+- 后端 SSA 模块结构
+- 前端 SSA 模块结构
+- 数据库 Schema 设计
+
+---
+
+## 2. 完成工作清单
+
+### 2.1 R 统计服务 (r-statistics-service)
+
+| 任务 | 状态 | 说明 |
+|------|------|------|
+| Dockerfile 编写 | ✅ 完成 | 基于 `rocker/r-ver:4.3`，包含完整系统依赖 |
+| plumber.R API 入口 | ✅ 完成 | 健康检查、工具列表、技能执行 |
+| data_loader.R | ✅ 完成 | 支持 inline 数据和预签名 URL |
+| guardrails.R | ✅ 完成 | 正态性、方差齐性、样本量检验 |
+| error_codes.R | ✅ 完成 | 友好错误映射 |
+| result_formatter.R | ✅ 完成 | APA 格式化 |
+| t_test_ind.R 示例工具 | ✅ 完成 | 独立样本 T 检验 |
+| Docker 镜像构建 | ✅ 完成 | `ssa-r-statistics:1.0.1`，1.81GB |
+
+### 2.2 后端模块 (backend/src/modules/ssa)
+
+| 任务 | 状态 | 说明 |
+|------|------|------|
+| 模块目录结构 | ✅ 完成 | 标准模块结构 |
+| index.ts 入口 | ✅ 完成 | 使用 `authenticate` 中间件 |
+| session.routes.ts | ✅ 完成 | 会话管理 API |
+| analysis.routes.ts | ✅ 完成 | 分析执行 API，OSS 存储集成 |
+| consult.routes.ts | ✅ 完成 | 咨询模式 API，LLM 网关集成 |
+| config.routes.ts | ✅ 完成 | 配置管理 API |
+| RClientService.ts | ✅ 完成 | R 服务客户端，预签名 URL 支持 |
+
+### 2.3 前端模块 (frontend-v2/src/modules/ssa)
+
+| 任务 | 状态 | 说明 |
+|------|------|------|
+| 模块目录结构 | ✅ 完成 | 标准模块结构 |
+| index.tsx 入口 | ✅ 完成 | 主布局组件 |
+| useAnalysis.ts Hook | ✅ 完成 | 使用 apiClient 认证 |
+| 组件骨架 | ✅ 完成 | DataUploader, PlanConfirm 等 |
+
+### 2.4 数据库 Schema
+
+| 任务 | 状态 | 说明 |
+|------|------|------|
+| Prisma Schema 定义 | ✅ 完成 | 9 个 SSA 相关模型 |
+| Migration SQL | ✅ 完成 | 手动创建并应用 |
+
+---
+
+## 3. 关键决策与讨论
+
+### 3.1 OSS 访问方案
+
+**讨论背景：**
+- 开发团队审查报告建议 R 服务实现 OSS 签名（`oss_signer.R`）
+- 这需要 R 服务持有 OSS 密钥
+
+**最终决策：** ❌ 不采用 R 直接签名方案
+
+**采用方案：** 预签名 URL
+```
+Node.js 生成预签名 URL → 传递给 R 服务 → R 直接 GET 下载
+```
+
+**理由：**
+1. 符合平台 OSS 存储规范（密钥集中管控）
+2. R 服务无需持有敏感密钥
+3. 简化 R 代码复杂度
+
+### 3.2 生产环境性能优化
+
+**问题：** `plumber.R` 每次请求都 `source()` 工具脚本
+
+**解决方案：**
+```r
+# 生产环境：启动时预加载到 TOOL_CACHE
+if (!DEV_MODE) {
+  preload_tools()  # 缓存 run_analysis 函数
+}
+```
+
+### 3.3 安全加固
+
+| 问题 | 解决方案 |
+|------|----------|
+| Docker Root 权限 | 添加 `USER appuser` |
+| 路径遍历攻击 | `tool_code` 正则白名单 `^[A-Z][A-Z0-9_]*$` |
+
+---
+
+## 4. 技术挑战与解决方案
+
+### 4.1 Prisma Migration Drift
+
+**问题：** `prisma migrate dev` 检测到 drift，要求 `migrate reset`
+
+**解决方案：**
+1. 手动创建 SQL 文件
+2. 直接执行 SQL
+3. 使用 `prisma migrate resolve --applied` 标记已应用
+
+### 4.2 Docker 构建依赖问题
+
+**问题链：**
+```
+zlib.h 缺失 → httpuv 编译失败
+cmake 缺失 → nloptr 编译失败
+ggplot2 版本冲突 → cowplot 安装失败
+```
+
+**解决方案：**
+1. 添加系统依赖：`zlib1g-dev`, `cmake`, `libnlopt-dev`, `gfortran`
+2. 放弃 renv，直接 `install.packages()` 让 R 自动解决依赖
+
+### 4.3 PowerShell 重定向问题
+
+**问题：** `<` 操作符在 PowerShell 中被保留
+
+**解决方案：**
+```powershell
+Get-Content "file.sql" | docker exec -i postgres psql ...
+```
+
+---
+
+## 5. 代码审查与规范对齐
+
+Week 1 后期进行了一次重要的**规范对齐审查**，确保新代码遵循平台规范。
+
+### 5.1 发现的问题
+
+| 文件 | 问题 | 修复 |
+|------|------|------|
+| `useAnalysis.ts` | 使用原生 fetch，无认证 | 改用 `apiClient` |
+| `ssa/index.ts` | 自定义 authenticate | 使用平台 `authenticate` 中间件 |
+| `RClientService.ts` | 直接传 OSS key | 使用 `storage.getUrl()` 预签名 |
+| `ConsultChat.tsx` | 自定义 Chat 组件 | 删除，使用平台 `AIStreamChat` |
+| 各 routes | 手动获取 userId | 使用 `getUserId(request)` |
+
+### 5.2 参考规范文档
+
+- `docs/02-通用能力层/00-通用能力层清单.md`
+- `docs/04-开发规范/10-模块认证规范.md`
+- `docs/04-开发规范/11-OSS存储开发规范.md`
+
+---
+
+## 6. 产出物清单
+
+### 6.1 代码文件
+
+```
+r-statistics-service/
+├── Dockerfile           # 生产就绪
+├── docker-compose.yml   # 本地开发
+├── plumber.R            # API 入口
+├── utils/
+│   ├── data_loader.R    # 预签名 URL 方案
+│   ├── guardrails.R     # Block/Warn/Switch
+│   ├── error_codes.R
+│   └── result_formatter.R
+├── tools/
+│   └── t_test_ind.R     # 示例工具
+└── tests/fixtures/
+    └── normal_data.csv
+
+backend/src/modules/ssa/
+├── index.ts
+├── routes/
+│   ├── session.routes.ts
+│   ├── analysis.routes.ts
+│   ├── consult.routes.ts
+│   └── config.routes.ts
+├── executor/
+│   └── RClientService.ts
+└── types/
+
+frontend-v2/src/modules/ssa/
+├── index.tsx
+├── components/
+├── hooks/
+│   └── useAnalysis.ts
+└── types/
+```
+
+### 6.2 Docker 镜像
+
+| 镜像名 | 版本 | 大小 | 状态 |
+|--------|------|------|------|
+| `ssa-r-statistics` | 1.0.1 | 1.81 GB | ✅ 本地构建成功 |
+
+### 6.3 数据库 Schema
+
+- `ssa_schema` 命名空间
+- 9 个新表：`SsaSession`, `SsaMessage`, `SsaTool`, `SsaExecutionLog` 等
+
+---
+
+## 7. 遗留问题与后续工作
+
+### 7.1 待完成任务
+
+| 任务 | 优先级 | 说明 |
+|------|--------|------|
+| 后端主路由注册 | P0 | 将 SSA 路由加入 `index.ts` |
+| 前端模块注册 | P0 | 加入 `moduleRegistry.ts` |
+| T 检验数据格式调试 | P1 | JSON 转 data.frame 格式问题 |
+| 配置中心 Excel 模板 | P1 | 决策表、参数映射等 |
+
+### 7.2 Week 2 计划
+
+1. **完成模块注册** - 后端/前端路由注册
+2. **端到端测试** - 数据上传 → 计划生成 → 执行
+3. **配置中心实现** - DecisionTableLoader, RCodeLibraryService
+4. **Planner 引擎** - LLM 方法推荐逻辑
+
+---
+
+## 附录：关键文件变更记录
+
+| 文件 | 变更类型 | 变更内容 |
+|------|----------|----------|
+| `data_loader.R` | 重构 | OSS 签名 → 预签名 URL |
+| `plumber.R` | 增强 | 生产预加载 + tool_code 校验 |
+| `Dockerfile` | 增强 | 非特权用户 + 健康检查 |
+| `RClientService.ts` | 修复 | 使用 storage.getUrl() |
+| `useAnalysis.ts` | 修复 | 使用 apiClient |
+| `ssa/index.ts` | 修复 | 使用平台 authenticate |
+
+---
+
+**Week 1 开发总结完成。**