# 新编辑器与聊天面板集成方案

## 1. 现有应用架构

### 1.1 双面板布局

当前应用采用**ResizableLayout双面板布局**:

```
┌─────────────────────────────────────────────────────────┐
│                      Toolbar (顶部)                      │
│              [会话历史] [文档列表]                        │
├──────────────────────┬──────────────────────────────────┤
│  Chat Panel          │  右侧面板(动态切换):              │
│  (左侧 40%)          │  - ExportRecordList (默认)       │
│  - 消息列表          │  - EditorPanel (编辑文档时)      │
│  - 输入框            │  (右侧 60%)                      │
│  - 发送按钮          │                                  │
└──────────────────────┴──────────────────────────────────┘
```

### 1.2 当前编辑流程

```
用户在Chat中点击"预览"按钮
        ↓
MessageItem触发 onPreviewDocument(documentId)
        ↓
uiStore.openDocumentPreview(documentId, name)
        ↓
App.tsx检测到 previewDocumentId 变化
        ↓
右侧面板从ExportRecordList切换到EditorPanel
        ↓
EditorPanel加载文档并显示WYSIWYGEditor(MDXEditor)
```

### 1.3 关键组件

| 组件 | 路径 | 职责 |
|------|------|------|
| App.tsx | `src/App.tsx` | 根组件,布局编排 |
| ChatPanel | `src/components/ChatPanel/ChatPanel.tsx` | 聊天面板(左侧) |
| EditorPanel | `src/components/EditorPanel/EditorPanel.tsx` | 编辑器面板(右侧) |
| WYSIWYGEditor | `src/components/EditorPanel/WYSIWYGEditor.tsx` | MDXEditor编辑器(旧) |
| uiStore | `src/stores/uiStore.ts` | UI状态管理(预览文档ID等) |
| chatStore | `src/stores/chatStore.ts` | 聊天消息管理 |

---

## 2. 新编辑器集成策略

### 2.1 集成原则

- ✅ **保留聊天面板**: 左侧ChatPanel完全不变
- ✅ **保留双面板布局**: ResizableLayout结构不变
- ✅ **完全重写EditorPanel**: 删除旧的WYSIWYGEditor,直接集成BlockEditor
- ✅ **保持接口兼容**: documentId传递、打开/关闭逻辑保持一致

### 2.2 架构对比

**当前架构**:
```
App.tsx
├── ChatPanel (左)
└── EditorPanel (右)
    └── WYSIWYGEditor (MDXEditor) ❌ 删除
        └── markdown编辑
```

**新架构**:
```
App.tsx
├── ChatPanel (左) ✅ 不变
└── EditorPanel (右) ⭐ 完全重写
    └── BlockEditor (新) ⭐ 直接集成
        └── blocks编辑
```

---

## 3. 具体集成步骤

### 3.1 阶段1: 创建BlockEditor(在新分支开发)

**开发策略**: 在新Git分支开发,避免影响主分支

```bash
git checkout -b feature/new-block-editor
```

在`src/components/Editor/`目录创建新编辑器:

```
src/components/
├── Editor/                      # ⭐ 新目录
│   ├── BlockEditor.tsx          # 主编辑器
│   ├── BlockCanvas.tsx
│   ├── BlockRenderer.tsx
│   ├── blocks/
│   │   ├── HeadingBlock.tsx
│   │   ├── ParagraphBlock.tsx
│   │   ├── TableBlock.tsx
│   │   └── ImageBlock.tsx
│   └── toolbar/
│       ├── MainToolbar.tsx
│       └── FloatingToolbar.tsx
└── EditorPanel/                 # 现有目录(暂不动)
    ├── EditorPanel.tsx          # 旧外壳组件
    └── WYSIWYGEditor.tsx        # 旧编辑器
```

**验收**: 新编辑器在独立分支可运行,主分支功能不受影响

### 3.2 阶段2: 完全重写EditorPanel

**删除旧文件,创建新的EditorPanel**:

```bash
# 1. 备份旧文件(以防需要回滚)
git mv src/components/EditorPanel src/components/EditorPanel.backup

# 2. 创建新EditorPanel目录
mkdir src/components/EditorPanel

# 3. 创建新的EditorPanel.tsx
```

**新的EditorPanel.tsx**:

```tsx
// src/components/EditorPanel/EditorPanel.tsx
import React from 'react';
import { BlockEditor } from '../Editor/BlockEditor';
import './EditorPanel.css';

interface EditorPanelProps {
  documentId: string;
  initialDocumentName?: string;
  onClose?: () => void;
}

/**
 * EditorPanel - 文档编辑面板
 * 
 * 作为右侧面板组件,直接集成BlockEditor
 * Props接口保持与旧版本兼容,确保App.tsx无需修改
 */
export const EditorPanel: React.FC<EditorPanelProps> = ({
  documentId,
  initialDocumentName,
  onClose
}) => {
  return (
    <div className="editor-panel">
      <BlockEditor 
        documentId={documentId}
        onClose={onClose}
      />
    </div>
  );
};

export default EditorPanel;
```

**新的EditorPanel.css**:

```css
/* src/components/EditorPanel/EditorPanel.css */
.editor-panel {
  display: flex;
  flex-direction: column;
  height: 100%;
  width: 100%;
  background-color: #ffffff;
  overflow: hidden;
}
```

**验收**: 
- EditorPanel接口保持不变(Props兼容)
- 直接显示BlockEditor
- App.tsx无需修改
- 聊天面板和布局完全不受影响

### 3.3 阶段3: 合并到主分支并部署

**合并前准备**:

```bash
# 1. 在feature分支完成开发和测试
npm run test
npm run build

# 2. 确保所有测试通过
npm run test:integration

# 3. 合并到主分支
git checkout main
git merge feature/new-block-editor

# 4. 删除旧的EditorPanel备份(确认无问题后)
rm -rf src/components/EditorPanel.backup
```

**部署验证**:

1. 部署到测试环境
2. 验证聊天功能正常
3. 验证编辑功能正常
4. 验证布局和拖拽正常

**验收**: 
- 新EditorPanel正常工作
- 聊天面板功能完整
- 无遗留旧代码

### 3.4 阶段4: 数据兼容性(如需要)

如果后端同时存在新旧文档,在editorStore中添加兼容逻辑:

```typescript
// src/stores/editorStore.ts
export const useEditorStore = create<EditorStore>((set, get) => ({
  loadDocument: async (id: string) => {
    try {
      // 优先尝试加载blocks数据
      const blocks = await blockService.getBlocks(id);
      set({ blocks, documentId: id });
    } catch (error) {
      // 如果没有blocks数据,提示用户
      Modal.info({
        title: '文档格式提示',
        content: '此文档使用旧格式,暂不支持编辑。请联系管理员升级文档。'
      });
      throw error;
    }
  }
}));
```

**验收**: 
- 新文档正常加载和编辑
- 旧文档友好提示(如果存在)

---

## 4. 保持不变的部分

### 4.1 聊天面板完全不变

`ChatPanel`组件及其子组件**完全不受影响**:

- ✅ `ChatPanel/ChatPanel.tsx`
- ✅ `ChatPanel/MessageList.tsx`
- ✅ `ChatPanel/MessageItem.tsx`
- ✅ `ChatPanel/MessageInput.tsx`
- ✅ `chatStore.ts`

### 4.2 布局结构不变

- ✅ `ResizableLayout`组件
- ✅ 左侧40% / 右侧60%默认比例
- ✅ 拖拽调整分隔线
- ✅ 最小宽度300px限制

### 4.3 UI交互流程不变

```
用户在Chat中点击"预览"
        ↓
MessageItem.tsx: onPreviewDocument(documentId) ✅ 不变
        ↓
uiStore.openDocumentPreview(documentId) ✅ 不变
        ↓
App.tsx: previewDocumentId更新,切换右侧面板 ✅ 不变
        ↓
EditorPanel加载并显示 ✅ 外壳不变,内部替换编辑器
```

### 4.4 Store结构不变

- ✅ `uiStore`: 继续管理`previewDocumentId`、`previewDocumentName`
- ✅ `chatStore`: 继续管理消息列表
- ⭐ **新增** `editorStore`: 管理blocks数据

---

## 5. EditorPanel接口保持兼容

### 5.1 Props接口不变

```typescript
interface EditorPanelProps {
  documentId: string;              // ✅ 保持
  initialDocumentName?: string;    // ✅ 保持
  onClose?: () => void;            // ✅ 保持
}
```

### 5.2 关闭逻辑不变

```typescript
// App.tsx
const handleCloseEditor = useCallback(() => {
  closeDocumentPreview();  // ✅ uiStore方法保持不变
}, [closeDocumentPreview]);

// 传递给EditorPanel
<EditorPanel onClose={handleCloseEditor} />
```

### 5.3 打开逻辑不变

```typescript
// MessageItem.tsx
const handlePreviewClick = () => {
  onPreviewDocument(message.documentId, message.documentName);
  // ✅ 接口保持不变
};
```

---

## 6. 测试计划

### 6.1 集成测试清单

- [ ] 左侧ChatPanel正常显示消息
- [ ] 点击"预览"按钮打开右侧EditorPanel
- [ ] BlockEditor正确加载blocks数据
- [ ] 编辑操作不影响左侧聊天
- [ ] 关闭编辑器返回ExportRecordList
- [ ] ResizableLayout拖拽正常
- [ ] 切换环境变量后编辑器正确切换

### 6.2 回归测试清单

- [ ] 发送消息功能正常
- [ ] 消息滚动和自动定位正常
- [ ] 导出记录列表显示正常
- [ ] 文档列表drawer打开关闭正常
- [ ] 会话历史drawer打开关闭正常
- [ ] 离线状态提示正常

---

## 7. 代码变更清单

### 7.1 新增文件

```
src/
├── components/
│   └── Editor/                   # 新目录
│       ├── BlockEditor.tsx
│       ├── BlockCanvas.tsx
│       ├── BlockRenderer.tsx
│       ├── blocks/*.tsx
│       └── toolbar/*.tsx
├── stores/
│   └── editorStore.ts            # 新Store
├── services/
│   └── blockService.ts           # 新Service
├── types/
│   └── editor.ts                 # 新类型定义
└── utils/
    ├── blockOperations.ts
    ├── richTextConverter.ts
    └── styleResolver.ts
```

### 7.2 重写文件

```
src/components/EditorPanel/
├── EditorPanel.tsx               # ⭐ 完全重写(删除旧代码)
└── EditorPanel.css               # ⭐ 新增样式文件
```

**删除文件**:
```
src/components/EditorPanel/
├── WYSIWYGEditor.tsx             # ❌ 删除
├── WYSIWYGEditor.css             # ❌ 删除
└── 其他MDXEditor相关文件          # ❌ 删除
```

### 7.3 保持不变的文件

```
src/
├── App.tsx                        # ✅ 不变
├── components/
│   ├── ChatPanel/                # ✅ 完全不变
│   │   ├── ChatPanel.tsx
│   │   ├── MessageList.tsx
│   │   ├── MessageItem.tsx
│   │   └── MessageInput.tsx
│   ├── Layout/
│   │   └── ResizableLayout.tsx   # ✅ 不变
│   └── ExportRecordList/         # ✅ 不变
├── stores/
│   ├── uiStore.ts                # ✅ 不变
│   └── chatStore.ts              # ✅ 不变
└── services/
    └── documentService.ts        # ✅ 不变(或小幅扩展)
```

---

## 8. 风险控制

### 8.1 回滚方案

**如果新编辑器出现严重问题**:

由于已完全删除旧编辑器,回滚需要恢复代码:

```bash
# 方案1: 从Git历史恢复
git revert <merge-commit-hash>

# 方案2: 从备份恢复
git checkout <pre-merge-commit> -- src/components/EditorPanel

# 方案3: 紧急降级(如果有保留备份)
mv src/components/EditorPanel.backup src/components/EditorPanel
```

**建议**: 在确认新编辑器稳定运行1-2周后,再删除`.backup`目录

### 8.2 数据安全

- 新编辑器只操作`document_blocks`表
- 后端应确保所有文档都已转换为blocks格式
- 如果有旧文档,后端提供一次性批量迁移脚本

### 8.3 性能监控

集成后监控指标:

- 右侧面板切换速度(<500ms)
- BlockEditor加载时间(<2s)
- 左侧聊天消息渲染不受影响
- 布局调整响应及时

---

## 9. 开发顺序建议

### Week 1-6: 独立开发BlockEditor(feature分支)
- 创建feature/new-block-editor分支
- 在`src/components/Editor/`创建新组件
- 独立开发和测试,不影响主分支

### Week 7: 重写EditorPanel并集成
- 备份旧EditorPanel
- 创建新的EditorPanel.tsx(极简外壳)
- 直接集成BlockEditor
- 本地完整测试

### Week 8: 合并和部署测试环境
- 合并到main分支
- 部署到测试环境
- 完整集成测试
- 团队内部试用

### Week 9: 生产环境部署
- 部署到生产环境
- 监控错误和性能
- 收集用户反馈

### Week 10: 清理和优化
- 确认稳定后删除备份文件
- 删除MDXEditor相关依赖
- 更新package.json
- 性能优化

---

## 10. FAQ

**Q1: 新编辑器会影响聊天功能吗?**

A: 不会。聊天面板(ChatPanel)完全独立,新编辑器只替换右侧EditorPanel内部的编辑器内核。

**Q2: 旧的WYSIWYGEditor完全删除了吗?**

A: 是的,EditorPanel完全重写,旧编辑器代码会被删除。但建议先备份(git mv)保留1-2周,确认无问题后再删除。

**Q3: 旧的markdown文档怎么办?**

A: 后端应在部署新编辑器前,将所有文档批量转换为blocks格式。前端不再处理markdown数据。

**Q4: ResizableLayout需要修改吗?**

A: 不需要。布局组件完全不变,只是右侧面板内部的编辑器换了。

**Q5: 如何确保不破坏现有功能?**

A: 
- 保持所有接口不变(Props、Store方法)
- 通过feature flag隔离新旧代码
- 完整的回归测试清单

---

**文档版本**: v1.0  
**创建日期**: 2026-07-03  
**状态**: 集成方案确认