# **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 改），本质上都是在向这个真理层发送指令和同步状态。”\*\*

现在，您可以拿着这份文档，很有底气地去和开发团队开工了。它已经堵上了最容易翻车的几个漏洞�?