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

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