Files

HaHafeng 66255368b7 feat(admin): Add user management and upgrade to module permission system

Features - User Management (Phase 4.1):
- Database: Add user_modules table for fine-grained module permissions
- Database: Add 4 user permissions (view/create/edit/delete) to role_permissions
- Backend: UserService (780 lines) - CRUD with tenant isolation
- Backend: UserController + UserRoutes (648 lines) - 13 API endpoints
- Backend: Batch import users from Excel
- Frontend: UserListPage (412 lines) - list/filter/search/pagination
- Frontend: UserFormPage (341 lines) - create/edit with module config
- Frontend: UserDetailPage (393 lines) - details/tenant/module management
- Frontend: 3 modal components (592 lines) - import/assign/configure
- API: GET/POST/PUT/DELETE /api/admin/users/* endpoints

Architecture Upgrade - Module Permission System:
- Backend: Add getUserModules() method in auth.service
- Backend: Login API returns modules array in user object
- Frontend: AuthContext adds hasModule() method
- Frontend: Navigation filters modules based on user.modules
- Frontend: RouteGuard checks requiredModule instead of requiredVersion
- Frontend: Remove deprecated version-based permission system
- UX: Only show accessible modules in navigation (clean UI)
- UX: Smart redirect after login (avoid 403 for regular users)

Fixes:
- Fix UTF-8 encoding corruption in ~100 docs files
- Fix pageSize type conversion in userService (String to Number)
- Fix authUser undefined error in TopNavigation
- Fix login redirect logic with role-based access check
- Update Git commit guidelines v1.2 with UTF-8 safety rules

Database Changes:
- CREATE TABLE user_modules (user_id, tenant_id, module_code, is_enabled)
- ADD UNIQUE CONSTRAINT (user_id, tenant_id, module_code)
- INSERT 4 permissions + role assignments
- UPDATE PUBLIC tenant with 8 module subscriptions

Technical:
- Backend: 5 new files (~2400 lines)
- Frontend: 10 new files (~2500 lines)
- Docs: 1 development record + 2 status updates + 1 guideline update
- Total: ~4900 lines of code

Status: User management 100% complete, module permission system operational

2026-01-16 13:42:10 +08:00

45 KiB

Raw Blame History

工具C（Tool C）- 科研数据编辑器 - 当前状态与开发指南

最后更新: 2025-12-22
当前版本: Day 5-10 MVP + 功能按钮 + NA处理 + Pivot优化 + UX重大改进 + 多指标转换 + 异步架构✅ + 性能优化✅
开发进度: Python微服务 ✅ | Session管理 ✅ | AI代码生成 ✅ | 前端完整 ✅ | 通用组件 ✅ | 功能按钮✅（7个）| NA处理✅ | Pivot优化✅ | UX优化✅ | 多指标转换✅ | Postgres-Only异步架构✅ | 性能优化✅（-99%）

📊 模块整体进度

组件	进度	代码行数	状态
Python微服务	100%	~1800行	✅ Day 1完成 + Day 6扩展 + NA处理优化 + 全量数据处理
Node.js后端	100%	~3500行	✅ Day 2-3完成，Day 5-8增强优化 + 全量返回
前端界面	99%	~4000行	✅ Day 4-8完成，筛选/行号/滚动条/全量数据加载
通用 Chat 组件	100%	~968行	✅ Day 5完成（重大成就）
功能按钮	100%	~2800行	✅ Day 6完成7个功能 + NA处理 + Pivot优化
数据库Schema	100%	2表	✅ Day 2-3完成
端到端测试	90%	-	✅ 核心功能全部测试通过
总体进度	98%	~15000行	✅ MVP完成 + 7个功能按钮 + NA处理 + Pivot优化 + UX重大改进！

✅ 已完成功能（Day 1-10）

🏆 Day 10 Postgres-Only异步架构 + 性能优化（2025-12-22）✅

1. 核心改造：文件上传异步处理架构

问题背景：

❌ 大文件（3339行×151列，4MB）上传超时（47秒 > 30秒限制）
❌ 后端同步解析导致HTTP请求阻塞
❌ getPreviewData/getFullData 每次重复解析（耗时43秒）
❌ 用户体验差：长时间等待，无进度反馈

解决方案：Postgres-Only 异步架构

架构层	实现	耗时	改善
上传接口	快速上传OSS + 推送队列 + 立即返回	3秒	✅ -94%（47→3秒）
Worker处理	pg-boss异步解析 + 保存clean data	53秒	后台执行
前端轮询	React Query智能轮询 + 进度条	实时反馈	体验优秀
数据读取	优先读取clean data缓存	0.5秒	✅ -99%（43→0.5秒）

2. 技术实现

2.1 Prisma Schema改动

model DcToolCSession {
  // 新增字段
  cleanDataKey String?  // 清洗后的数据（避免重复计算）
  
  // 字段改为可选（异步填充）
  totalRows Int?
  totalCols Int?
  columns Json?
}

2.2 后端异步架构

✅ SessionService.createSession：上传OSS + 推送任务（<3秒）
✅ parseExcelWorker：后台解析 + 保存clean data（53秒）
✅ SessionController.getSessionStatus：状态查询API（轮询用）
✅ SessionService.getPreviewData：优先读clean data（0.5秒）
✅ SessionService.getFullData：优先读clean data（0.5秒）
✅ SessionService.saveProcessedData：同步更新clean data

2.3 前端React Query轮询

✅ useSessionStatus Hook：智能轮询（自动串行、防并发）
✅ 进度条UI：实时显示0-100%
✅ useEffect监听：status='ready'时自动加载数据

2.4 性能优化

✅ 智能清洗算法：边界检测 + 安全阀（3000列、500万单元格限制）
✅ 轻量级验证：validateFile不做完整解析（<1秒）
✅ clean data缓存：Worker保存，所有操作复用

3. 关键技术突破

技术点	问题	解决方案
幽灵列	16384列中只有151列有效	边界检测算法，裁剪右侧空列
幽灵行	格式污染导致虚高	过滤全空行
队列名称	`asl:screening:batch` 不合法	改为 `asl_screening_batch`（下划线）
轮询风暴	同时15+并发请求	React Query自动串行
重复计算	每次操作重新解析（43秒）	clean data缓存复用（0.5秒）
MemoryQueue	不支持异步持久化	环境变量 `QUEUE_TYPE=pgboss`

4. 性能提升对比

单次操作：

上传+预览：96秒 → 53.5秒（-44%）
筛选操作：44秒 → 2.5秒（-94%）
Pivot操作：45秒 → 2.5秒（-94%）
并发请求：15+个 → 1个（-93%）

完整工作流（上传+7次操作）：

之前：96秒 + 44秒×7 = 404秒（6.7分钟）
现在：53秒 + 2.5秒×7 = 70.5秒（1.2分钟）
改善：-83%

5. 代码统计

文件类型	新增/修改	代码量
Worker	parseExcelWorker.ts（新建）	~410行
Hook	useSessionStatus.ts（新建）	~90行
后端修改	SessionService/Controller	~200行
前端修改	index.tsx（重构轮询）	~100行
数据库	clean_data_key字段	1字段
文档	异步任务处理指南	~588行
总计		~1388行

6. 测试验证

测试场景	结果	说明
11KB小文件	✅ 通过	3秒上传 + 数据加载
4MB大文件（3339×151）	✅ 通过	不再超时，数据正确
16384列幽灵列文件	✅ 通过	智能裁剪到151列
轮询机制	✅ 通过	单个串行请求，无并发
clean data缓存	✅ 通过	getPreviewData 0.5秒
7大功能性能	✅ 通过	每次操作2-3秒
导出功能	✅ 通过	导出处理后的数据

🎉 Day 9 多指标转换功能（2025-12-21）✅

1. 功能概述

医学研究专用的多指标重复测量数据转换工具，支持两个转换方向：

转换方向	输入格式	输出格式	适用场景
方向1：分析格式	宽表	时间点→行，指标→列	统计分析、混合效应模型、GEE、数据可视化
方向2：展示格式	宽表	时间点→列，指标→行	临床报告、数据审查表、CRF核对、单受试者数据审查

2. 核心功能 ✅

2.1 智能自动分组 ✅

✅ 自动检测列名中的指标名称和时间点
✅ 智能识别分隔符（___、__、_、-、.等）
✅ 公共前缀智能扩展（修复"FMA总得分___基线"识别问题）
✅ 时间点一致性验证
✅ 置信度评分

示例：

输入列名：FMA总得分___筛选及基线、FMA总得分___随访(2周)、ADL总分___基线、ADL总分___随访(2周)
自动检测：
  ✓ 3个指标：FMA总得分、ADL总分、FM疗效
  ✓ 8个时间点：筛选及基线、随访(2周)、随访(1个月)...
  ✓ 分隔符："___"

2.2 方向1：多指标转长表（时间点为行，指标为列） ✅

✅ 适用场景：R/Python统计分析、ggplot2/seaborn可视化、机器学习
✅ 列顺序优化：ID列 → Event_Name → 各指标列
✅ 保持原始Record ID顺序
✅ 自动处理缺失值（outer join）

示例：

输入（宽表）：
Record_ID | FMA总得分_基线 | FMA总得分_随访1 | ADL总分_基线 | ADL总分_随访1
4         | 58            | 67             | 40          | 95
5         | 61            | 79             | 35          | 85

输出（长表）：
Record_ID | Event_Name | FMA总得分 | ADL总分
4         | 基线       | 58       | 40
4         | 随访1      | 67       | 95
5         | 基线       | 61       | 35
5         | 随访1      | 79       | 85

2.3 方向2：多指标转矩阵（时间点为列，指标为行） ✅

✅ 适用场景：临床报告、数据审查、CRF核对
✅ 列顺序优化：ID列 → 指标名列 → 各时间点列
✅ 保持原始Record ID顺序
✅ 时间点列按原始顺序排列

示例：

输入（宽表）：
Record_ID | FMA总得分_基线 | FMA总得分_随访1 | ADL总分_基线 | ADL总分_随访1
4         | 58            | 67             | 40          | 95

输出（矩阵）：
Record_ID | 指标名     | 基线 | 随访1
4         | FMA总得分  | 58  | 67
4         | ADL总分    | 40  | 95

3. UX优化 ✅

功能	说明	状态
转换方向选择	Radio组件，两个选项，带场景说明	✅
全选/清空按钮	快速选择所有值列	✅
实时预览	选择列后自动生成预览（前10行）	✅
智能表单	根据转换方向动态显示不同的输入框	✅
可视化分组结果	Tag标签展示检测到的指标和时间点	✅
置信度提示	检测置信度<1.0时显示警告	✅

4. 技术架构 ✅

4.1 Python层（metric_time_transform.py）

✅ detect_metric_groups() - 自动分组检测（300行）
✅ apply_multi_metric_to_long() - 方向1转换（150行）
✅ apply_multi_metric_to_matrix() - 方向2转换（180行）
✅ 智能排序：保持原始Record ID顺序

4.2 Python API（main.py）

✅ POST /api/operations/multi-metric/detect - 检测指标分组
✅ POST /api/operations/multi-metric/to-long - 执行方向1转换
✅ POST /api/operations/multi-metric/to-matrix - 执行方向2转换

4.3 Node.js Backend

✅ QuickActionService.ts - 3个新方法
✅ QuickActionController.ts - 支持2个新action
✅ 路由注册：/multi-metric/detect

4.4 Frontend（MultiMetricPanel.tsx）

✅ 转换方向选择（Radio组件）
✅ 智能表单（动态显示）
✅ 实时检测和预览
✅ 完整的错误处理

5. 关键技术突破 ✅

技术点	问题	解决方案
列名识别	"FMA总得分___基线" 被错误识别为 "FMA"	智能修正算法：扩展公共前缀
列顺序	Event_Name位置随机	强制列顺序：ID → Event_Name → 指标
Record ID顺序	转换后按字典序排序（4,10,11,5,6）	添加临时列 `_original_order` 保持原始顺序
分隔符识别	不支持三重下划线 `___`	优先级列表：`['___', '__', '_', '-', '.']`
时间点提取	`.lstrip()` 错误移除字符	使用 `.startswith()` 精确匹配

6. 测试覆盖 ✅

测试场景	测试数据	状态
单ID列，多指标	Record_ID: 4,5,6,10,11	✅
三重下划线分隔符	`FMA总得分___筛选及基线`	✅
括号时间点	`随访(2周)`	✅
中文列名	`FMA疗效`	✅
空值处理	outer join保留所有时间点	✅
原始顺序保持	4→5→6→10→11	✅

7. 代码统计 ✅

文件	新增代码	说明
`metric_time_transform.py`	~600行	Python核心算法
`main.py`	~150行	3个API端点
`QuickActionService.ts`	~100行	3个新方法
`QuickActionController.ts`	~50行	Action支持
`MultiMetricPanel.tsx`	~530行	完整UI组件
`TransformDialog.tsx`	~30行	Tab集成
总计	~1460行	完整功能实现

🚀 Day 7-8 NA处理优化 + Pivot列顺序优化（2025-12-09~10）

1. NA（空值）处理优化 ✅

4个功能支持空值处理：

功能	NA处理选项	状态
数值映射	保持NA / 映射为指定值 / 删除行	✅
高级筛选	为空 / 不为空条件	✅（原有支持）
生成分类变量	保持为空 / 标记为"缺失" / 分配到指定组	✅
条件生成列	为空 / 不为空运算符	✅

2. Pivot列顺序优化 ✅

✅ 保留未选择的列（可选功能，UI复选框控制）
✅ 未选列聚合方式（取第一个值/取众数/取均值）
✅ 保持原始列顺序（转换后列按原文件顺序排列）
✅ 透视列值按首次出现顺序排列

3. 计算列方案B实施 ✅

解决特殊字符列名问题：

✅ 前端安全列名映射（col_0, col_1...）
✅ 后端columnMapping存储和传递
✅ Python端使用columnMapping计算
✅ 支持中文括号、逗号等特殊字符列名

4. UX优化 ✅

✅ 列头tooltip（鼠标悬停显示完整列名）
✅ 50行预览提示可关闭
✅ 页面滚动条优化（内部滚动，无整页滚动）

🎉 Day 8 UX重大改进（2025-12-10晚上）✅

1. 用户体验全面优化 ✅

7项核心改进：

功能	改进内容	状态
预览提示	删除"表格仅展示前50行"提示条	✅
行号列	添加固定行号列（#列头，灰色背景，左侧固定）	✅
列头筛选	Excel风格筛选（Community版本，中文本地化，显示值计数）	✅
全量数据加载	不再限制50行，Session加载全量数据	✅
全量数据返回	所有快速操作全量返回（筛选/映射/分箱/条件/删NA/计算/Pivot）	✅
滚动条修复	修改MainLayout为固定高度，整个页面无滚动条	✅
计算列修复	全角字符自动转换 + 完善列别名机制	✅

2. 列头筛选功能 ✅

✅ AG Grid Community版本（agTextColumnFilter / agNumberColumnFilter）
✅ 中文本地化（"筛选..."、"清除"、"应用"等）
✅ 显示唯一值及计数（类似Excel）
✅ 筛选对话框美化（白色背景，圆角，阴影）
✅ 筛选基于全量数据（精确筛选）

3. 滚动条终极修复 ✅

问题根源：MainLayout使用 min-h-screen，内容超出时产生页面级滚动条

解决方案：

✅ 修改 MainLayout.tsx：min-h-screen → h-screen + overflow-hidden
✅ 两层都添加 overflow-hidden：顶层 + 内容区
✅ 效果：整个浏览器窗口无滚动条，只有AG Grid内部滚动

4. 全量数据处理 ✅

修改范围：

✅ SessionService.ts - getPreviewData() 返回全量数据
✅ QuickActionController.ts - 3处移除 slice(0, 50)
✅ AICodeService.ts - 1处移除 slice(0, 50)
✅ 前端API注释更新 - getPreviewData 说明返回全量

影响评估：

✅ 内存占用：可控（Node.js堆内存充足）
✅ 网络传输：略增（但在可接受范围）
✅ 筛选精度：大幅提升（基于全量数据）
✅ 用户体验：显著优化（无需担心"仅50行"）

🚀 Day 6 功能按钮开发（2025-12-08）

1. 预写Python函数架构 ✅

重大架构重构：从动态代码生成改为预写函数

✅ 创建 extraction_service/operations/ 模块
✅ 7个预写函数文件（~1500行）
✅ 完整的类型注解和文档
✅ 严格的安全验证
✅ 智能类型转换（字符串→数值）

2. 7个核心功能上线 ✅

功能	Python函数	前端Dialog	状态
高级筛选	filter.py	FilterDialog.tsx	✅ +为空/不为空
数值映射	recode.py	RecodeDialog.tsx	✅ +NA处理
生成分类变量	binning.py	BinningDialog.tsx	✅ +NA处理
条件生成列	conditional.py	ConditionalDialog.tsx	✅ +为空/不为空
删除缺失值	dropna.py	DropnaDialog.tsx	✅
计算列	compute.py	ComputeDialog.tsx	✅ 方案B
Pivot转换	pivot.py	PivotDialog.tsx	✅ +保留未选列+列顺序

3. 问题修复与优化 ✅

✅ NaN序列化错误（统一处理）
✅ 自动类型转换（字符串数字→数值）
✅ 中英文逗号支持
✅ 分箱边界自动添加
✅ 列名特殊字符处理（方案B）
✅ Ant Design警告修复
✅ 分箱"nan"字符串显示问题修复

🎉 Day 5 重大成就（2025-12-07）

1. Ant Design X 集成 ✅

✅ 升级到 Ant Design 6.0.1
✅ 安装 @ant-design/x (2.1.0) - UI 组件库
✅ 安装 @ant-design/x-sdk (2.1.0) - 数据流管理

2. 前端通用能力层建设 ✅

创建 frontend-v2/src/shared/components/Chat/：

✅ ChatContainer.tsx（163行）- 核心容器组件
✅ MessageRenderer.tsx（64行）- 消息渲染器
✅ CodeBlockRenderer.tsx（71行）- 代码块渲染器
✅ types.ts（151行）- 完整类型定义
✅ chat.css（144行）- 样式文件
✅ README.md（297行）- 使用文档

总计：~968行，可复用于 AIA、PKB、Tool C 等模块

3. Tool C MVP 完成 ✅

✅ 文件上传 → 显示数据表格
✅ AI 对话 → 生成代码
✅ 手动执行 → 更新表格
✅ 支持简单问答（不生成代码）
✅ UI 优化（7个问题修复）
✅ 端到端测试通过

Day 1: Python微服务扩展 ✅

1. Python微服务扩展

文件结构

extraction_service/
├── services/
│   └── dc_executor.py              # 427行 ✅ 新增
├── main.py                          # 617行（新增2个端点）✅
├── test_module.py                   # 27行（测试脚本）✅
├── quick_test.py                    # 64行（快速测试）✅
└── test_execute_simple.py           # 51行（简单测试）✅

核心功能

1.1 AST静态代码检查 ✅

模块: dc_executor.py::validate_code()
功能:
- 解析Python代码的抽象语法树（AST）
- 检测危险模块导入（os, sys, subprocess等）
- 检测危险函数调用（eval, exec, open等）
- 检测是否操作df变量

安全黑名单:

DANGEROUS_MODULES = {
    'os', 'sys', 'subprocess', 'shutil', 'glob',
    'socket', 'urllib', 'requests', 'http',
    'pickle', 'shelve', 'dbm',
    'importlib', '__import__',
    'eval', 'exec', 'compile',
    'open', 'input', 'file',
}

DANGEROUS_BUILTINS = {
    'eval', 'exec', 'compile', '__import__',
    'open', 'input', 'file',
    'getattr', 'setattr', 'delattr',
    'globals', 'locals', 'vars',
}

1.2 Pandas代码沙箱执行 ✅

模块: dc_executor.py::execute_pandas_code()
功能:
- 创建安全的执行环境（限制可用函数）
- 执行Pandas数据处理代码
- 捕获print输出
- 30秒超时保护
- 返回执行结果和元数据
安全措施:
- 限制可用内置函数（仅允许安全函数如len, range等）
- 禁止文件操作
- 禁止网络访问
- 禁止系统调用
- 超时自动终止（Unix系统）

1.3 FastAPI端点 ✅

端点1: POST /api/dc/validate
- 功能：代码安全验证
- 请求：{"code": "..."}
- 响应：{"valid": bool, "errors": [], "warnings": []}
端点2: POST /api/dc/execute
- 功能：Pandas代码执行
- 请求：{"data": [...], "code": "..."}
- 响应：{"success": bool, "result_data": [...], "output": "", ...}

测试验证结果

✅ 测试1：正常代码执行

# 输入
data = [{"age": 25}, {"age": 65}, {"age": 45}]
code = "df['old'] = df['age'] > 60"

# 输出
{
  "success": true,
  "result_data": [
    {"age": 25, "old": false},
    {"age": 65, "old": true},
    {"age": 45, "old": false}
  ],
  "execution_time": 0.004,
  "result_shape": [3, 2]
}

✅ 测试2：危险代码拦截

# 输入
code = "import os"

# 输出
{
  "valid": false,
  "errors": ["🚫 禁止导入危险模块: os (行 1)"],
  "warnings": ["⚠️  代码中未使用 df 变量，可能无法操作数据"]
}

✅ 测试3：医疗数据清洗

# 输入
data = [
  {"patient_id": "P001", "age": 25, "sbp": 120, "dbp": 80},
  {"patient_id": "P002", "age": 65, "sbp": 150, "dbp": 95},
  {"patient_id": "P003", "age": None, "sbp": 160, "dbp": 100}
]
code = """
import numpy as np
df['age'] = df['age'].apply(lambda x: np.nan if x is None or x > 120 else x)
df['hypertension'] = df.apply(
    lambda row: '高血压' if row['sbp'] >= 140 or row['dbp'] >= 90 else '正常',
    axis=1
)
"""

# 输出
{
  "success": true,
  "result_data": [
    {"patient_id": "P001", "age": 25, "sbp": 120, "dbp": 80, "hypertension": "正常"},
    {"patient_id": "P002", "age": 65, "sbp": 150, "dbp": 95, "hypertension": "高血压"},
    {"patient_id": "P003", "age": null, "sbp": 160, "dbp": 100, "hypertension": "高血压"}
  ],
  "execution_time": 0.008
}

Day 3: AI代码生成服务 ✅

文件结构（新增）

backend/src/modules/dc/tool-c/
├── services/
│   ├── PythonExecutorService.ts    # 177行 ✅ Day 1
│   ├── SessionService.ts           # 383行 ✅ Day 2
│   ├── DataProcessService.ts       # 303行 ✅ Day 2
│   └── AICodeService.ts            # 550行 ✅ Day 3 新增
├── controllers/
│   ├── TestController.ts           # 131行 ✅ Day 1
│   ├── SessionController.ts        # 300行 ✅ Day 2
│   └── AIController.ts             # 257行 ✅ Day 3 新增
└── routes/
    └── index.ts                    # 85行 ✅ Day 3 更新

核心功能

3.1 AICodeService ✅

功能: AI代码生成核心服务

方法:

class AICodeService {
  generateCode(sessionId, userMessage): Promise<GenerateCodeResult>
  executeCode(sessionId, code, messageId): Promise<ExecuteCodeResult>
  generateAndExecute(sessionId, userMessage, maxRetries): Promise<ProcessResult>
  getHistory(sessionId, limit): Promise<Message[]>
}

特性:
- ✅ 复用LLMFactory（通用能力层）
- ✅ 10个Few-shot示例（Level 1-4）
- ✅ 自我修正机制（最多3次重试）
- ✅ 对话历史管理（最近5轮）
- ✅ 从Session获取真实数据执行
- ✅ 详细System Prompt（含环境说明）

3.2 AIController ✅

功能: AI功能API端点
端点:
- POST /ai/generate - 生成代码（不执行）✅
- POST /ai/execute - 执行代码 ✅
- POST /ai/process - 生成并执行（一步到位）✅
- GET /ai/history/:sessionId - 获取对话历史 ✅

3.3 数据库表 ✅

表名: dc_schema.dc_tool_c_ai_history
字段: 14个（id, session_id, user_id, role, content, generated_code, code_explanation, execute_status, execute_result, execute_error, retry_count, model, created_at）
索引: 3个（主键 + session_id + user_id）
迁移脚本: backend/scripts/create-tool-c-ai-history-table.mjs

AI功能测试结果（Day 3）

✅ 测试通过率: 9/11 (81.8%) 达到MVP标准

成功场景（9个）：

✅ 统一缺失值标记
✅ 分类变量编码
✅ 连续变量分箱
✅ BMI计算
✅ 条件筛选
✅ 缺失值填补
✅ 统计汇总
✅ 复杂分类
✅ 对话历史获取

待优化场景（2个，已记录技术债务TD-C-006）：

❌ 数值列清洗（复杂字符串处理）
❌ 智能去重（日期解析+排序）

关键修复：

✅ NaN序列化问题（Python端转None）
✅ 数据传递问题（从Session获取真实数据）
✅ System Prompt优化（明确告知环境信息）
✅ Few-shot示例调整（移除import语句）

Day 4: 前端基础框架 ✅

文件结构（新增）

frontend-v2/src/modules/dc/pages/tool-c/
├── index.tsx                        # 258行 ✅ 主入口
├── components/
│   ├── Header.tsx                   # 91行 ✅ 顶部栏
│   ├── Toolbar.tsx                  # 104行 ✅ 工具栏
│   ├── DataGrid.tsx                 # 111行 ✅ AG Grid表格
│   ├── Sidebar.tsx                  # 149行 ✅ 右侧栏（简化版）
│   └── ag-grid-custom.css           # 113行 ✅ 自定义样式
├── types/
│   └── index.ts                     # 62行 ✅ 类型定义
api/
└── toolC.ts                         # 218行 ✅ API封装（6个方法）

总代码：~1106行

核心功能

4.1 AG Grid集成 ✅

组件: DataGrid.tsx
版本: AG Grid Community 31.0.0
功能:
- ✅ Excel风格表格渲染
- ✅ 列排序、过滤、调整宽度
- ✅ 缺失值高亮显示（红色）
- ✅ 数值右对齐
- ✅ 斑马纹背景
- ✅ 空状态提示
- ⏸️ 单元格编辑（Day 6）

4.2 页面布局 ✅

主入口: index.tsx
布局: 左右分栏（flex布局）
- 左侧：Toolbar + DataGrid（flex-1）
- 右侧：Sidebar（固定420px宽度）
特性:
- ✅ 响应式高度（h-screen）
- ✅ 溢出滚动控制
- ✅ Emerald绿色主题

4.3 API封装 ✅

文件: api/toolC.ts

方法数: 8个

// Session管理
uploadFile(file)
getSession(sessionId)
getPreviewData(sessionId)
updateHeartbeat(sessionId)

// AI功能
generateCode(sessionId, message)
executeCode(sessionId, code, messageId)
processMessage(sessionId, message)  // ⭐ 核心API
getChatHistory(sessionId, limit)

4.4 路由集成 ✅

路径: /data-cleaning/tool-c
状态: Portal已启用（status: 'ready'）
懒加载: 使用React.lazy()
测试: Portal卡片可点击进入

Day 4完成状态

✅ 基础框架100%完成:

✅ Header（返回按钮、文件名、导出）
✅ Toolbar（7个快捷按钮、搜索框）
✅ DataGrid（AG Grid完整集成）
✅ Sidebar（骨架版本，待Day 5完善）
✅ API封装（8个方法）
✅ 路由配置（Portal → Tool C）

⏸️ 待Day 5完成:

⏸️ MessageItem组件（消息渲染）
⏸️ CodeBlock组件（代码高亮）
⏸️ InputArea组件（输入框）
⏸️ InsightsPanel组件（数据洞察）
⏸️ 文件上传完整流程
⏸️ AI对话完整交互
⏸️ 端到端测试

Day 2: Session管理 + 数据处理 ✅

文件结构（新增）

backend/src/modules/dc/tool-c/
├── services/
│   ├── PythonExecutorService.ts    # 177行 ✅ Day 1
│   ├── SessionService.ts           # 383行 ✅ Day 2 新增
│   └── DataProcessService.ts       # 303行 ✅ Day 2 新增
├── controllers/
│   ├── TestController.ts           # 131行 ✅ Day 1
│   └── SessionController.ts        # 300行 ✅ Day 2 新增
└── routes/
    └── index.ts                    # 62行 ✅ Day 2 更新

核心功能

2.1 SessionService ✅

功能: Session生命周期管理

方法:

class SessionService {
  createSession(userId, fileName, buffer): Promise<SessionData>
  getSession(sessionId): Promise<SessionData>
  getPreviewData(sessionId): Promise<PreviewDataResponse>
  getFullData(sessionId): Promise<any[]>
  deleteSession(sessionId): Promise<void>
  updateHeartbeat(sessionId): Promise<Date>
  cleanExpiredSessions(): Promise<number>
}

特性:
- ✅ 零落盘：Excel内存解析，直接上传OSS
- ✅ 10分钟过期机制
- ✅ 心跳延长功能
- ✅ 自动清理过期Session
- ✅ 完整的错误处理

2.2 DataProcessService ✅

功能: Excel文件解析和验证

方法:

class DataProcessService {
  parseExcel(buffer): ParsedExcelData
  validateFile(buffer, fileName): ValidationResult
  inferColumnTypes(data): ColumnType[]
  formatFileSize(bytes): string
}

特性:
- ✅ 内存解析（零落盘）
- ✅ 10MB文件大小限制
- ✅ 支持.xlsx, .xls, .csv
- ✅ 列类型推断（可选）

2.3 SessionController ✅

功能: Session管理API端点
端点:
- POST /sessions/upload - 上传Excel创建Session ✅
- GET /sessions/:id - 获取Session信息 ✅
- GET /sessions/:id/preview - 获取预览数据（前100行）✅
- GET /sessions/:id/full - 获取完整数据 ✅
- DELETE /sessions/:id - 删除Session ✅
- POST /sessions/:id/heartbeat - 更新心跳 ✅

2.4 数据库表 ✅

表名: dc_schema.dc_tool_c_sessions
字段: 12个（id, user_id, file_name, file_key, total_rows, total_cols, columns, encoding, file_size, created_at, updated_at, expires_at）
索引: 3个（主键 + user_id + expires_at）
迁移脚本: backend/scripts/create-tool-c-table.mjs

API测试结果（Day 2）

✅ 测试数据:

文件名: test-medical-data.xlsx
数据: 8行 x 7列医疗数据
列名: patient_id, name, age, gender, diagnosis, sbp, dbp
文件大小: 17.42 KB

✅ 测试结果:

测试项	状态	说明
上传文件创建Session	✅	返回201，Session创建成功
获取Session信息	✅	元数据正确返回
获取预览数据（前100行）	✅	8行数据全部返回
获取完整数据	✅	从OSS读取成功
更新心跳	✅	过期时间延长10分钟
删除Session	✅	OSS+DB清理成功
验证删除	✅	返回404确认删除
总计	7/7 (100%)	所有测试通过

✅ 云原生规范检查:

✅ 使用 storage 服务（零落盘）
✅ 使用 logger 服务（结构化日志）
✅ 使用 prisma 全局实例
✅ Excel内存解析，无本地文件存储
✅ 无硬编码配置

2. Node.js后端集成（Day 1）

文件结构

backend/src/modules/dc/tool-c/
├── services/
│   └── PythonExecutorService.ts    # 177行 ✅ 新增
├── controllers/
│   └── TestController.ts           # 131行 ✅ 新增
├── routes/
│   └── index.ts                    # 29行 ✅ 新增
└── README.md                        # 172行（技术文档）✅

核心服务

2.1 PythonExecutorService ✅

功能: 封装Python微服务HTTP调用

方法:

class PythonExecutorService {
  validateCode(code: string): Promise<ValidateCodeResponse>
  executeCode(data: any[], code: string): Promise<ExecuteCodeResponse>
  healthCheck(): Promise<boolean>
}

特性:
- 完整的错误处理和重试机制
- 30秒超时控制
- 连接状态检测
- 详细的日志记录

2.2 TestController ✅

功能: Day 1测试端点控制器
端点:
- GET /test/health - 测试Python服务健康
- POST /test/validate - 测试代码验证
- POST /test/execute - 测试代码执行

2.3 路由注册 ✅

前缀: /api/v1/dc/tool-c
状态: 已在 dc/index.ts 中注册
可访问: ✅ 服务启动后即可调用

⏸️ 待开发功能（Day 2-15）

Week 1: 基础架构（Day 2-5）

Day 2: 数据库 + Session管理 ✅

数据库Schema（已创建）:

// dc_tool_c_sessions 表 ✅
model DcToolCSession {
  id            String    @id @default(uuid())
  userId        String
  fileName      String
  fileKey       String    // OSS存储key
  totalRows     Int
  totalCols     Int
  columns       Json      // 列名数组
  encoding      String?   // 编码格式
  fileSize      Int
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt
  expiresAt     DateTime  // 过期时间
  
  @@index([userId])
  @@index([expiresAt])
  @@map("dc_tool_c_sessions")
  @@schema("dc_schema")
}

已完成服务:

SessionService.ts - Session管理（383行）✅
- createSession() - 创建会话（上传Excel到OSS）
- getSession() - 获取会话元数据
- getPreviewData() - 获取预览数据（前100行）
- getFullData() - 获取完整数据（从OSS）
- deleteSession() - 删除会话（OSS+DB）
- updateHeartbeat() - 更新心跳（延长10分钟）
- cleanExpiredSessions() - 清理过期Session
DataProcessService.ts - 数据处理（303行）✅
- Excel文件解析（xlsx库，内存解析）
- 文件验证（大小、格式、内容）
- 列类型推断（可选）
- 文件大小限制（10MB）
SessionController.ts - Session控制器（300行）✅
- 6个API端点全部实现

Day 3: AI代码生成服务 ⏸️

待开发服务:

AICodeService.ts - AI代码生成
- 集成LLMFactory
- System Prompt设计（含10个Few-shot示例）
- 代码生成和自我修正
- 上下文管理（Session元数据）

System Prompt要点:

const systemPrompt = `
你是一个医疗科研数据清洗专家，负责生成Pandas代码。

数据集信息：
- 文件名：${fileName}
- 行数：${totalRows}
- 列数：${totalCols}
- 列名：${columns.join(', ')}

安全规则：
1. 只能操作df变量
2. 禁止导入os、sys等危险模块
3. 禁止使用eval、exec等危险函数
4. 必须进行异常处理

Few-shot示例：
[示例1] 标记老年组
用户: 把年龄大于60的标记为老年组
代码: df['age_group'] = df['age'].apply(lambda x: '老年' if x > 60 else '非老年')
...
`;

Day 3-5: AI代码生成和控制器 ⏸️

待开发控制器:

AIController.ts
- POST /ai/chat - AI对话生成代码
- POST /ai/execute - 执行AI生成的代码
- GET /ai/history/:sessionId - 获取对话历史

待开发服务:

AICodeService.ts - AI代码生成
- 集成LLMFactory
- System Prompt设计（10个Few-shot）
- 上下文管理
- 自我修正机制

Week 2: 前端开发（Day 6-10）

待开发组件:

ToolCEditor.tsx - 主编辑器页面
DataGrid.tsx - AG Grid数据表格
AICopilot.tsx - AI助手侧边栏
FileUpload.tsx - 文件上传组件
CodeBlock.tsx - 代码显示组件
ActionCard.tsx - AI操作卡片

Week 3: 测试优化（Day 11-15）

测试任务:

15个医疗数据清洗场景测试
性能测试（10MB文件）
并发测试（多用户）
安全测试（代码沙箱）
UI/UX测试

🗄️ 数据库状态

当前表结构

dc_schema 中的表:

-- Tool B相关表（已存在）
dc_schema.dc_templates                    -- 预设模板 ✅
dc_schema.dc_extraction_tasks             -- 提取任务 ✅
dc_schema.dc_extraction_items             -- 提取记录 ✅
dc_schema.dc_health_checks                -- 健康检查 ✅

-- Tool C相关表
dc_schema.dc_tool_c_sessions              -- ✅ 已创建（Day 2）
dc_schema.dc_tool_c_ai_history            -- ✅ 已创建（Day 3）

创建方式（已完成）:

# Day 2 已执行
cd backend
node scripts/create-tool-c-table.mjs  # ✅ 成功
npx prisma generate                    # ✅ 成功

表结构详情:

-- dc_tool_c_sessions 表（12字段，3索引）
CREATE TABLE dc_schema.dc_tool_c_sessions (
  id UUID PRIMARY KEY,
  user_id VARCHAR(255),
  file_name VARCHAR(500),
  file_key VARCHAR(500),        -- OSS路径
  total_rows INTEGER,
  total_cols INTEGER,
  columns JSONB,                -- ["age", "gender", ...]
  encoding VARCHAR(50),
  file_size INTEGER,
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  expires_at TIMESTAMP           -- 10分钟过期
);

🔌 API端点清单

Python微服务 (http://localhost:8000)

方法	端点	功能	状态	说明
GET	`/api/health`	健康检查	✅	检查服务状态
POST	`/api/dc/validate`	代码验证	✅	AST安全检查
POST	`/api/dc/execute`	代码执行	✅	Pandas代码执行

Node.js后端 (http://localhost:3000)

测试端点（Day 1）

方法	端点	功能	状态	说明
GET	`/api/v1/dc/tool-c/test/health`	测试Python服务	✅	Day 1测试用
POST	`/api/v1/dc/tool-c/test/validate`	测试代码验证	✅	Day 1测试用
POST	`/api/v1/dc/tool-c/test/execute`	测试代码执行	✅	Day 1测试用

Session管理端点（Day 2 已完成）✅

方法	端点	功能	状态	测试
POST	`/api/v1/dc/tool-c/sessions/upload`	上传Excel	✅	201 成功
GET	`/api/v1/dc/tool-c/sessions/:id`	获取Session	✅	200 成功
GET	`/api/v1/dc/tool-c/sessions/:id/preview`	获取预览数据	✅	200 成功
GET	`/api/v1/dc/tool-c/sessions/:id/full`	获取完整数据	✅	200 成功
DELETE	`/api/v1/dc/tool-c/sessions/:id`	删除Session	✅	200 成功
POST	`/api/v1/dc/tool-c/sessions/:id/heartbeat`	心跳更新	✅	200 成功

AI功能端点（Day 3已完成）✅

方法	端点	功能	状态	测试
POST	`/api/v1/dc/tool-c/ai/generate`	生成代码	✅	✅ 通过
POST	`/api/v1/dc/tool-c/ai/execute`	执行代码	✅	✅ 通过
POST	`/api/v1/dc/tool-c/ai/process`	生成并执行	✅	✅ 81.8%通过
GET	`/api/v1/dc/tool-c/ai/history/:sessionId`	获取历史	✅	✅ 通过

⚙️ 环境配置

必需环境变量

在 backend/.env 中配置：

# Python微服务地址（必需）
EXTRACTION_SERVICE_URL=http://localhost:8000

# OSS存储（Day 2使用）
OSS_REGION=your-region
OSS_BUCKET=your-bucket
OSS_ACCESS_KEY_ID=your-key-id
OSS_ACCESS_KEY_SECRET=your-secret

# LLM配置（Day 3使用）
LLM_PROVIDER=openai
LLM_API_KEY=your-api-key
LLM_MODEL=gpt-4

服务启动顺序

启动Python微服务 (必需)

cd extraction_service
.\venv\Scripts\activate
python main.py
# 服务运行在 http://localhost:8000

启动Node.js后端 (必需)

cd backend
npm run dev
# 服务运行在 http://localhost:3000

启动前端 (Day 6后)

cd frontend-v2
npm run dev
# 服务运行在 http://localhost:5173

📂 代码结构

Python微服务

extraction_service/
├── services/
│   ├── dc_executor.py              # DC代码执行模块 ✅
│   ├── pdf_extractor.py            # PDF提取
│   ├── docx_extractor.py           # Docx提取
│   └── txt_extractor.py            # Txt提取
├── main.py                          # FastAPI主文件 ✅
├── requirements.txt                 # Python依赖
└── venv/                            # 虚拟环境

Node.js后端

backend/src/modules/dc/tool-c/
├── services/
│   ├── PythonExecutorService.ts    # Python调用服务 ✅
│   ├── SessionService.ts           # Session管理 ⏸️
│   ├── AICodeService.ts            # AI代码生成 ⏸️
│   └── DataProcessService.ts       # 数据处理 ⏸️
├── controllers/
│   ├── TestController.ts           # 测试控制器 ✅
│   ├── SessionController.ts        # Session控制器 ⏸️
│   └── AIController.ts             # AI控制器 ⏸️
├── routes/
│   └── index.ts                    # 路由定义 ✅
└── utils/
    └── (待添加)

前端

frontend-v2/src/modules/dc/pages/tool-c/
├── index.tsx                        # 258行 ✅ Day 4（主入口+状态管理）
├── components/
│   ├── Header.tsx                   # 91行 ✅ Day 4（顶部栏）
│   ├── Toolbar.tsx                  # 104行 ✅ Day 4（7个快捷按钮）
│   ├── DataGrid.tsx                 # 111行 ✅ Day 4（AG Grid表格）
│   ├── Sidebar.tsx                  # 149行 ✅ Day 4（骨架版）
│   ├── ag-grid-custom.css           # 113行 ✅ Day 4（Emerald主题）
│   ├── MessageItem.tsx              # ⏸️ Day 5（消息渲染）
│   ├── CodeBlock.tsx                # ⏸️ Day 5（代码高亮）
│   ├── InputArea.tsx                # ⏸️ Day 5（输入框）
│   └── InsightsPanel.tsx            # ⏸️ Day 5（数据洞察）
├── hooks/
│   └── useToolC.ts                  # ⏸️ Day 5（核心Hook，可选）
├── types/
│   └── index.ts                     # 62行 ✅ Day 4（类型定义）
└── (API封装在 ../../api/toolC.ts)   # 218行 ✅ Day 4（8个方法）

✅ Day 4完成：~1106行
⏸️ Day 5待完成：~400-600行（Chat组件）

🧪 测试清单

Day 1 测试（已完成）✅

Python服务健康检查
AST代码验证（正常代码）
AST代码验证（危险代码拦截）
Pandas代码执行（简单场景）
Pandas代码执行（医疗数据清洗）
Node.js服务集成
HTTP通信正常

Day 2-15 测试（待执行）⏸️

基础功能测试

Excel文件上传（<10MB）
文件编码检测
Session创建和删除
OSS存储读写
心跳机制

AI功能测试

LLM代码生成
代码自我修正
Few-shot效果验证
上下文理解准确性

15个医疗数据清洗场景

基础场景（成功率>90%）:

场景1：标记老年组（age > 60）
场景2：删除缺失患者ID的行
场景3：性别编码（男1女0）
场景4：计算BMI
场景5：删除缺失率>50%的列

中等场景（成功率>80%）:

场景6：血压分类（正常/高血压）
场景7：计算住院天数
场景8：删除重复患者ID
场景9：清理异常年龄值（>120）
场景10：按性别分组统计

高级场景（成功率>60%）:

场景11：复杂分组聚合
场景12：时间序列分析
场景13：医学规则验证
场景14：多列联合清洗
场景15：缺失值智能填充

🚀 快速开始

开发者快速上手

启动Python微服务

cd extraction_service
.\venv\Scripts\activate
python main.py

测试Python服务

# PowerShell测试
Invoke-WebRequest -Uri "http://localhost:8000/api/health"

启动Node.js后端

cd backend
npm install  # 首次运行
npm run dev

测试Node.js集成

curl http://localhost:3000/api/v1/dc/tool-c/test/health

API调用示例

代码验证:

curl -X POST http://localhost:3000/api/v1/dc/tool-c/test/validate \
  -H "Content-Type: application/json" \
  -d '{"code":"df[\"age_group\"] = df[\"age\"] > 60"}'

代码执行:

curl -X POST http://localhost:3000/api/v1/dc/tool-c/test/execute \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{"age": 25}, {"age": 65}],
    "code": "df[\"old\"] = df[\"age\"] > 60"
  }'

📝 开发记录

日期	里程碑	详细记录
2025-12-06	Day 1完成	2025-12-06_工具C_Day1开发完成总结.md
2025-12-06	Day 2完成	2025-12-06_工具C_Day2开发完成总结.md
2025-12-07	Day 3完成	2025-12-06_工具C_Day3开发完成总结.md ✅ 后端MVP完成
2025-12-07	Day 4完成	2025-12-07_工具C_Day4前端基础完成.md ✅ AG Grid集成
2025-12-07	Day 5完成	2025-12-07_Day5_Ant-Design-X重构完成.md ✅ Ant Design X集成
2025-12-07	UI优化	2025-12-07_完整UI优化与功能增强.md ✅ 7个问题修复

🎯 下一步行动

✅ Week 1 已完成（Day 1-5）

完成Python微服务扩展 ✅
完成Session管理和数据处理 ✅
完成AI代码生成服务 ✅
完成后端所有API端点 ✅
完成前端基础框架 ✅
完成AI Chat面板 ✅
集成 Ant Design X ✅
开发通用 Chat 组件 ✅
端到端流程测试通过 ✅

✅ Week 2 已完成（Day 6-8）

7个功能按钮开发 ✅
NA处理优化（4个功能）✅
Pivot列顺序优化 ✅
计算列方案B实施 ✅
UX优化（tooltip、滚动条、预览提示）✅

Week 3 计划（Day 9-15）

缺失值填补功能（均值/中位数/众数/固定值）
多重插补（MICE）- 高优先级
性能优化（大数据集）
错误处理增强
用户手册文档

📚 相关文档

需求文档: PRD：Tool C - 科研数据编辑器 (MVP V1.1).md
技术设计: 技术设计文档：工具 C - 科研数据编辑器 (V7 云端沙箱抗风险版).md
开发计划: 工具C_MVP开发计划_V1.0.md
TODO清单: 工具C_MVP开发_TODO清单.md
UI原型: 工具C_原型设计V6.html

🔐 安全说明

代码执行安全

✅ AST静态检查拦截危险操作
✅ 沙箱环境限制可用函数
✅ 30秒超时保护
✅ 禁止文件和网络操作
⏸️ 资源使用限制（待实现）

数据安全

✅ 10MB文件大小限制
⏸️ OSS加密存储（待实现）
⏸️ 10分钟Session过期（待实现）
⏸️ 用户隔离（待实现）

已知问题：

🐛 MICE多重插补DataFrame shape不匹配问题（正在调试中）
建议：优先使用6种简单填补方法（均值/中位数/众数/固定值/前向/后向），MICE待修复后使用

维护者: AI Assistant
联系方式: 请查看项目README
最后更新: 2025-12-10

45 KiB Raw Blame History Unescape Escape

工具C（Tool C）- 科研数据编辑器 - 当前状态与开发指南

📊 模块整体进度

✅ 已完成功能（Day 1-10）

🏆 Day 10 Postgres-Only异步架构 + 性能优化（2025-12-22）✅

1. 核心改造：文件上传异步处理架构

2. 技术实现

3. 关键技术突破

4. 性能提升对比

5. 代码统计

6. 测试验证

🎉 Day 9 多指标转换功能（2025-12-21）✅

1. 功能概述

2. 核心功能 ✅

3. UX优化 ✅

4. 技术架构 ✅

5. 关键技术突破 ✅

6. 测试覆盖 ✅

7. 代码统计 ✅

🚀 Day 7-8 NA处理优化 + Pivot列顺序优化（2025-12-09~10）

1. NA（空值）处理优化 ✅

2. Pivot列顺序优化 ✅

3. 计算列方案B实施 ✅

4. UX优化 ✅

🎉 Day 8 UX重大改进（2025-12-10晚上）✅

1. 用户体验全面优化 ✅

2. 列头筛选功能 ✅

3. 滚动条终极修复 ✅

4. 全量数据处理 ✅

🚀 Day 6 功能按钮开发（2025-12-08）

1. 预写Python函数架构 ✅

2. 7个核心功能上线 ✅

3. 问题修复与优化 ✅

🎉 Day 5 重大成就（2025-12-07）

1. Ant Design X 集成 ✅

2. 前端通用能力层建设 ✅

3. Tool C MVP 完成 ✅

Day 1: Python微服务扩展 ✅

1. Python微服务扩展

文件结构

核心功能

测试验证结果

Day 3: AI代码生成服务 ✅

文件结构（新增）

核心功能

AI功能测试结果（Day 3）

Day 4: 前端基础框架 ✅

文件结构（新增）

核心功能

Day 4完成状态

Day 2: Session管理 + 数据处理 ✅

文件结构（新增）

核心功能

API测试结果（Day 2）

2. Node.js后端集成（Day 1）

文件结构

核心服务

⏸️ 待开发功能（Day 2-15）

Week 1: 基础架构（Day 2-5）

Day 2: 数据库 + Session管理 ✅

Day 3: AI代码生成服务 ⏸️

Day 3-5: AI代码生成和控制器 ⏸️

Week 2: 前端开发（Day 6-10）

Week 3: 测试优化（Day 11-15）

🗄️ 数据库状态

当前表结构

🔌 API端点清单

Python微服务 (http://localhost:8000)

Node.js后端 (http://localhost:3000)

测试端点（Day 1）

Session管理端点（Day 2 已完成）✅

AI功能端点（Day 3已完成）✅

⚙️ 环境配置

必需环境变量

服务启动顺序

📂 代码结构

Python微服务

Node.js后端

前端

🧪 测试清单

45 KiB

Raw Blame History