HaHafeng
8be741cd52
Summary: - Update Tool C MVP Development Plan (V1.3) * Clarify Python execution as core feature * Add 15 real medical data cleaning scenarios (basic/medium/advanced) * Enhance System Prompt with 10 Few-shot examples * Discover existing Python service (extraction_service) * Update to extend existing service instead of rebuilding - Create Tool C MVP Development TODO List * 3-week plan with 30 tasks (Day 1-15) * 4 core milestones with clear acceptance criteria * Daily checklist and risk management * Detailed task breakdown for each day Key Changes: - Python service: Extend existing extraction_service instead of new setup - Test scenarios: 15 scenarios (5 basic + 5 medium + 5 advanced) - Success criteria: Basic >90%, Medium >80%, Advanced >60%, Total >80% - Development time: Reduced from 3 weeks to 2 weeks (reuse infrastructure) Status: Planning complete, ready to start Day 1 development
108 lines
5.8 KiB
Markdown
108 lines
5.8 KiB
Markdown
# **PRD：Tool C \- 科研数据编辑器 (MVP V1.1)**
|
||
|
||
| 文档版本 | V1.1 (工程细化版) |
|
||
| :---- | :---- |
|
||
| **产品形态** | **Web 端数据编辑器 (AG Grid \+ AI Chat)** |
|
||
| **核心策略** | **"AI-First" \+ "Server-side State"**。依靠 AI 生成 Python 代码完成清洗；以服务端 DataFrame 为单一数据源，前端负责渲染和轻量编辑。 |
|
||
| **技术底座** | React \+ AG Grid \+ Node.js BFF \+ Python Sandbox (FastAPI) \+ DeepSeek-V3 |
|
||
| **变更记录** | V1.1: 增加数据同步机制、撤销回滚策略、会话生命周期定义。 |
|
||
|
||
## **一、 MVP 核心目标 (Objectives)**
|
||
|
||
1. **验证闭环：** 跑通 “自然语言 \-\> Python 代码 \-\> 后端执行 \-\> 前端刷新” 的完整链路。
|
||
2. **数据一致性：** 确保手动编辑与 AI 操作不冲突，状态可追溯。
|
||
3. **可用性：** 解决中文乱码、会话超时等实际工程问题。
|
||
|
||
## **二、 详细功能需求 (Functional Requirements)**
|
||
|
||
### **1\. 界面框架与会话 (Shell & Session)**
|
||
|
||
* **P0: 左右分栏布局：** 左侧 AG Grid (70%)，右侧 AI Chat (30%)。
|
||
* **P0: 会话初始化 (Session Init):**
|
||
* 用户上传文件 \-\> 后端开启 Python 进程/容器 \-\> 加载 df \-\> 返回 sessionId。
|
||
* **编码检测：** 后端必须尝试 utf-8 和 gbk 解码，防止中文乱码。
|
||
* **P1: 心跳与保活 (Keep-alive):**
|
||
* 前端每 30s 发送心跳。
|
||
* **超时策略：** 若超过 30min 无操作，后端释放内存。用户再次操作时，提示“会话已过期，请重新加载文件”。
|
||
|
||
### **2\. 超级网格 (The Grid) \- *前端交互***
|
||
|
||
* **P0: 数据展示 (View):**
|
||
* 通过 API 分页拉取数据（预览模式，仅取前 100-500 行）。
|
||
* **列类型推断：** 前端根据后端返回的 dtypes 渲染列头图标（数值/文本/日期）。
|
||
* **P0: 手动编辑 (Manual Edit):**
|
||
* 支持双击修改单元格。
|
||
* **关键逻辑（脏数据标记）：** 用户修改后，单元格右标红，数据暂存在前端 dirtyRows 队列中。
|
||
* **P0: 状态锁 (UI Locking):**
|
||
* 当 AI 正在执行时，Grid 变为 **只读 (Read-only)**，显示 Loading 遮罩。
|
||
|
||
### **3\. AI Copilot 智能助手 (The Brain) \- *后端驱动***
|
||
|
||
#### **3.1 交互流程 (Chat Loop)**
|
||
|
||
1. **用户输入：** “把年龄大于60的设为老年组”。
|
||
2. **前置同步 (Auto-Sync):** **(V1.1 新增)**
|
||
* **判定：** 前端检查是否有未保存的手动修改 (dirtyRows).
|
||
* **动作：** 如果有，先静默发送 PATCH /api/data 将手动修改同步给后端 df。确保 AI 基于最新数据操作。
|
||
3. **代码生成：** 后端调用 DeepSeek，生成 Pandas 代码。
|
||
4. **预操作确认 (Action Card):**
|
||
* 展示：代码预览 \+ 摘要。
|
||
* 按钮：\[运行\] | \[取消\]。
|
||
|
||
#### **3.2 执行与回滚 (Execute & Rollback) \- (V1.1 核心)**
|
||
|
||
* **P0: 自动快照 (Auto-Checkpoint):**
|
||
* 在执行 exec(code) 之前，后端必须先对当前 df 进行内存快照（或序列化备份）。
|
||
* 记录操作日志：ActionID: 101, Type: AI\_CODE, Code: "..."。
|
||
* **P0: 执行反馈:**
|
||
* 成功：返回新的预览数据 \-\> 刷新 Grid \-\> 添加一条“操作成功”消息。
|
||
* 失败：捕获 Python Traceback \-\> 让 AI 尝试自我修复 (Self-Correction) 一次 \-\> 若仍失败，向用户展示错误原因。
|
||
* **P0: 撤销操作 (Undo):**
|
||
* 聊天框每条成功记录下显示 \[撤销\] 按钮。
|
||
* 逻辑：调用后端 rollback(action\_id) \-\> 恢复到该操作前的快照 \-\> 刷新 Grid。
|
||
|
||
### **4\. 快捷指令 (Prompt Chips)**
|
||
|
||
* **P0:** 顶部工具栏按钮（生成变量、长宽转换等），点击仅作为“快捷短语”填入输入框，不触发独立 UI 逻辑，保持架构统一。
|
||
|
||
### **5\. 导出 (Export)**
|
||
|
||
* **P0:** 导出 Excel。
|
||
* 逻辑：后端直接将当前的 df (包含所有 AI 修改和手动修改) 写入 Excel 流并返回。
|
||
|
||
## **三、 异常处理规范 (Error Handling)**
|
||
|
||
| 异常场景 | 前端表现 | 后端处理 |
|
||
| :---- | :---- | :---- |
|
||
| **中文乱码** | 提示“编码格式识别失败，请手动选择” | 尝试 chardet 检测，失败则报错 |
|
||
| **AI 代码报错** | Chat 气泡变红，显示“AI 正在尝试修复...” | 捕获 stderr，将错误反喂给 AI 重试 (Max 1次) |
|
||
| **会话过期** | 全屏遮罩“会话已过期” | 清理 Redis/内存，返回 401/404 |
|
||
| **手动修改冲突** | 提示“正在同步数据...” | 优先处理手动 Patch，再执行 AI 任务 |
|
||
|
||
## **四、 开发与测试重点 (QA Focus)**
|
||
|
||
1. **一致性测试：**
|
||
* 先手动改一个值，再让 AI 删一行，确认那个值还在不在（或者是否正确被删）。
|
||
* 先让 AI 改一列，再撤销，确认是否完全恢复。
|
||
2. **边界测试：**
|
||
* 上传空文件。
|
||
* 上传全中文列名的文件。
|
||
* 让 AI 计算一个不存在的列。
|
||
3. **性能测试：**
|
||
* 连续快速发送 5 条指令，确保后端是**串行队列**处理，而不是并发搞乱数据。
|
||
|
||
## **五、 附录：数据同步 API 定义 (简版)**
|
||
|
||
* POST /api/sync: 前端 \-\> 后端。发送手动修改的 Diff。
|
||
* Payload: \[{ rowId: "P001", col: "age", value: 66 }\]
|
||
* POST /api/run: 前端 \-\> 后端。发送 AI 代码执行请求。
|
||
* Payload: { code: "df\['new'\] \= 1", snapshot: true }
|
||
* POST /api/undo: 前端 \-\> 后端。
|
||
* Payload: { step: \-1 }
|
||
|
||
\#\#\# 给开发团队的一句话总结
|
||
|
||
\*\*“V1.1 的核心在于‘状态管理’。请务必保证后端 Python 内存里的 \`DataFrame\` 是唯一的‘真理来源 (Source of Truth)’。前端的所有操作（无论是手改还是 AI 改），本质上都是在向这个真理层发送指令和同步状态。”\*\*
|
||
|
||
现在，您可以拿着这份文档，很有底气地去和开发团队开工了。它已经堵上了最容易翻车的几个漏洞。
|