# intelligentTranslation 重构方案（阶段任务清单版）

## 进度概述

- [ ] 阶段 1：静态数据适配层
- [ ] 阶段 2：左侧 PDF 原文预览
- [ ] 阶段 3：右侧 Tiptap 译文编辑器
- [ ] 阶段 4：页对应 / 段级高亮 / 导航跳转
- [ ] 阶段 5：Word 导出

执行规则：每完成一个阶段，必须先经用户验收确认，再更新本文档进度，然后才能进入下一阶段。

---

## 1. 目标

- 左侧使用 PDF 直接预览原文，不再用 JSON 反推版式。
- 右侧使用 Tiptap 编辑译文，按段块编辑。
- 原文与译文保持块级一一对应，支持段级高亮联动。
- 文本型 PDF 优先段级对应；扫描件退化为页级对应。
- 译文支持纯文本、表格可编辑、段落可新增/删除。
- 最终导出 Word。

---

## 2. 已确认边界

- 译文按段块编辑。
- 允许新增段落、删除段落。
- 不允许合并段落、拆分段落。
- 新增段落插在当前段后面，并自动继承上一段样式。
- 译文只允许纯文本。
- 表格仅改单元格文本，允许增删行列。
- 图片 / 公式先原样保留，不做编辑。
- 左原右译，右侧自然流式，但尽量与左侧页对齐。
- 滚动时左右页尽量同步。
- 导航粒度到章节标题。

---

## 3. 现有代码现状

- 页面入口：`src/views/intelligentTranslation/documentCompare.vue`
- 服务层：`src/views/intelligentTranslation/services/documentCompareService.js`
- 静态数据：`src/views/intelligentTranslation/merged_ans.json`
- 已有能力：
  - 页面数据按页获取
  - 章节大纲生成
  - 页面滚动容器
  - 节点选择 / 页面跳转基础逻辑

---

## 4. 推荐技术路线

- 原文：直接 PDF 预览。
- 译文：Tiptap。
- 数据层：把 `merged_ans.json` 适配成统一 block 模型。
- 导出：从 block 模型生成 Word。
- Markdown：仅作为辅助，不作为主模型。

---

## 5. 统一数据模型

### 必须保留的字段
- `id`
- `pageIdx`
- `type`
- `text`
- `level`
- `style`
- `sourceNodeId`
- `translationNodeId`
- `children`

### 基本映射
- `heading` → 标题块
- `paragraph` → 段落块
- `table` → 表格块
- `list` → 列表块
- `image` / `formula` → 只读占位块

### 页对应规则
- 有真实文本的 PDF：优先按 `pageIdx + 顺序` 对齐。
- 扫描件：只做页级对应。

---

## 6. 分阶段任务清单

### 阶段 1：静态数据适配层

目标：把 `merged_ans.json` 转成前端可消费的 block 数据。

任务：
- [ ] 提取页面、节点、章节大纲。
- [ ] 为每个节点保留稳定 ID。
- [ ] 生成统一 block schema。
- [ ] 生成页映射和章节映射。
- [ ] 生成右侧 Tiptap 初始文档数据。

验收：
- 能稳定拿到页、标题、段落、表格等块。
- 每个块都有唯一 ID。
- 页面和章节能正常定位。

---

### 阶段 2：左侧 PDF 原文预览

目标：左侧直接预览原始 PDF。

任务：
- [ ] 接入 PDF 预览组件或 PDF.js。
- [ ] 固定左侧页面渲染上下文。
- [ ] 保持缩放、滚动、页定位能力。
- [ ] 不再依赖 JSON 重建原文版式。

验收：
- 原文页面视觉接近 PDF 原图。
- 不再出现 JSON 重建导致的文字重叠。

---

### 阶段 3：右侧 Tiptap 译文编辑器

目标：实现按段块编辑的右侧译文区。

任务：
- [ ] 初始化 Tiptap。
- [ ] 支持正文、一级标题、二级标题等预设样式。
- [ ] 支持纯文本段落编辑。
- [ ] 支持段落新增。
- [ ] 支持段落删除。
- [ ] 支持表格单元格文本编辑。
- [ ] 支持增删表格行列。

验收：
- 右侧可编辑纯文本块。
- 样式仅通过预设切换。
- 表格能按要求编辑。

---

### 阶段 4：页对应 / 段级高亮 / 导航跳转

目标：建立原文与译文的联动。

任务：
- [ ] 用 `pageIdx` 建立页锚点。
- [ ] 建立原文块与译文块的一一映射。
- [ ] 点击目录跳转到章节。
- [ ] 点击块时高亮对应块。
- [ ] 滚动时同步更新当前页。
- [ ] 扫描件场景降级为页级对应。

验收：
- 章节跳转可用。
- 左右块能联动高亮。
- 滚动时页状态正确更新。

---

### 阶段 5：Word 导出

目标：将编辑结果导出为 docx。

任务：
- [ ] 从 block 模型生成 Word 结构。
- [ ] 保留标题层级。
- [ ] 保留表格结构。
- [ ] 图片 / 公式保持原样占位或原样保留。
- [ ] 生成下载文件。

验收：
- Word 内容正确。
- 标题层级正确。
- 表格尽量保留。
- 能正常导出下载。

---

## 7. 当前风险

- `page_idx` 可能不是绝对真实页码，需要验证。
- 右侧流式编辑与左侧页同步天然存在偏差。
- 扫描件无法做真正段级对齐。
- 复杂表格导出可能与原文存在差异。

---

## 8. 当前待确认项

- `page_idx` 是否为真实 PDF 页码。
- 表格单元格是否只允许纯文本。
- 图片 / 公式导出时是否保留原对象。
- Word 是否要求尽量分页一致。

---

## 9. 执行规则

1. 只做当前阶段，不提前做后续阶段。
2. 当前阶段完成后，先由用户验收。
3. 验收通过后，更新本文件进度，再进入下一阶段。
4. 所有后续改动必须围绕统一 block 模型展开。
