261 lines
7.3 KiB
Markdown
261 lines
7.3 KiB
Markdown
# 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 开发总结完成。**
|