# 智能翻译文档对比页后端接口说明书

## 方案进度概述
- 当前阶段：正式接口说明书整理
- 目标：在不修改原有接口的前提下，新增少量、低冗余、可直接落地的后端接口，支撑前端页级懒加载渲染
- 原则：只保留渲染必须数据，合并可合并接口，去除重复字段和中间态字段
- 适用对象：后端开发、联调开发、接口测试

## 1. 需求背景
当前 `src/views/intelligentTranslation/merged_ans.json` 是完整合并结果，内部同时包含文档摘要、页信息、节点信息、布局信息、样式信息与富文本内容。若前端一次性加载整包数据，会造成：
- 首屏加载慢
- 响应体积大
- 页内 DOM 节点过多
- 富文本、图片、表格渲染成本高
- 用户感知“内容像被截断”

因此需要在**不改原有接口**的前提下，新增更适合页面渲染的接口。

## 2. 设计原则
1. 原有接口保持不变，继续兼容旧逻辑
2. 新接口尽量少，优先合并相近能力
3. 返回结果只保留前端渲染必须字段
4. 大字段、重复字段、可计算字段尽量不返回
5. 支持页级加载

## 3. 数据来源与拆分范围
### 3.1 主要数据来源
新接口的数据来源为 `merged_ans.json` 中的三类信息：
- `document_meta`：文档级信息
- `pages`：页级索引信息
- `merged_nodes`：页内节点信息

### 3.2 拆分目标
后端只需要输出前端实际渲染所需的数据：
- 文档摘要
- 页级索引
- 目录树
- 页内容

## 4. 字段说明
下面仅说明新增接口会使用到的关键字段。

### 4.1 文档级字段
| 字段 | 含义 | 是否必需 | 说明 |
|---|---|---:|
| `source_file_name` | 原始文件名 | 是 | 用于页面标题和调试 |
| `source_file_type` | 文件类型 | 是 | 如 pdf |
| `page_count` | 总页数 | 是 | 用于总览和分页 |
| `created_at` | 结果生成时间 | 否 | 用于记录与排查 |

### 4.2 页级字段
| 字段 | 含义 | 是否必需 | 说明 |
|---|---|---:|
| `page_idx` | 页码，从 0 开始 | 是 | 页唯一标识 |
| `width` | 页面宽度 | 是 | 用于坐标换算 |
| `height` | 页面高度 | 是 | 用于坐标换算 |
| `rotation` | 页面旋转角度 | 否 | 默认 0 |
| `node_ids` | 本页节点 id 列表 | 是 | 用于快速定位与页级懒加载 |
| `node_count` | 节点数量 | 否 | 统计信息 |
| `has_image` | 是否包含图片 | 否 | 用于渲染优化 |
| `has_table` | 是否包含表格 | 否 | 用于渲染优化 |

### 4.3 节点级字段
| 字段 | 含义 | 是否必需 | 说明 |
|---|---|---:|---|
| `node_id` | 节点唯一 id | 是 | 前端定位主键 |
| `page_idx` | 所属页码 | 是 | 用于归属与跳转 |
| `semantic_type` | 语义类型 | 是 | 决定节点渲染方式 |
| `reading_order` | 阅读顺序 | 是 | 页内排序依据 |
| `content_payload` | 内容载荷 | 是 | 仅保留必须字段 |
| `layout` | 布局信息 | 是 | 页内版式还原 |
| `style_spans` | 局部样式片段 | 否 | 富文本节点需要时再返回 |

### 4.4 `semantic_type` 建议枚举
| 值 | 含义 | 用途 |
|---|---|---|
| `heading` | 标题 | 目录生成、章节跳转 |
| `paragraph` | 正文段落 | 普通文本展示 |
| `list_item` | 列表项 | 列表渲染 |
| `table` | 表格 | 表格组件渲染 |
| `image` | 图片 | 图片组件渲染 |
| `caption` | 图注/表注 | 辅助说明 |
| `header` | 页眉 | 版式还原 |
| `footer` | 页脚 | 版式还原 |
| `unknown` | 未知 | 兜底 |

### 4.5 `content_payload` 建议字段
| 字段 | 含义 | 是否必需 | 说明 |
|---|---|---:|---|
| `type` | 内容类型 | 是 | text/html/table/image |
| `text` | 纯文本内容 | 是 | 标题、正文最常用 |
| `html` | 富文本 HTML | 否 | 仅必要节点返回 |
| `heading_level` | 标题级别 | 否 | 仅标题需要 |
| `table_body_html` | 表格 HTML | 否 | 仅表格需要 |
| `img_path` | 原图路径 | 否 | 仅图片需要 |
| `preview_img_path` | 预览图路径 | 否 | 图片懒加载使用 |
| `alt_text` | 图片替代文本 | 否 | 无障碍或兜底 |
| `caption` | 图注/表注 | 否 | 辅助说明 |

### 4.6 `layout` 建议字段
| 字段 | 含义 | 是否必需 | 说明 |
|---|---|---:|---|
| `bbox_norm` | 归一化坐标框 | 是 | 优先用于渲染 |
| `bbox` | 像素坐标框 | 否 | bbox_norm 缺失时兜底 |
| `angle` | 旋转角度 | 否 | 默认 0 |
| `reading_order` | 阅读顺序 | 是 | 页内排序 |
| `page_idx` | 页码 | 是 | 与节点归属一致 |

### 4.7 `style_spans` 建议字段
| 字段 | 含义 | 是否必需 | 说明 |
|---|---|---:|---|
| `start` | 起始字符下标 | 是 | 样式区间开始 |
| `end` | 结束字符下标 | 是 | 样式区间结束 |
| `style.bold` | 是否加粗 | 否 | 富文本样式 |
| `style.italic` | 是否斜体 | 否 | 富文本样式 |
| `style.underline` | 是否下划线 | 否 | 富文本样式 |
| `style.color_hex` | 字体颜色 | 否 | 富文本样式 |

## 5. 接口设计总览
> 说明：以下均为新增接口。旧接口保持不变。

考虑到“能合并尽量合并”的要求，后端最终只保留 **2 个新增接口**：

1. 文档摘要接口：返回文档基本信息、统计信息、页索引和目录树
2. 页内容接口：返回某一页可渲染的完整节点数据

---

## 6. 接口 1：文档摘要接口
### 6.1 接口名称
`GET /intelligent-translation/document-meta`

### 6.2 用途
一次性返回文档基础信息、统计信息、页索引摘要和目录树。前端初始化时优先调用该接口。

### 6.3 请求参数
无需额外参数。

### 6.4 返回参数
| 字段 | 类型 | 含义 | 是否必需 |
|---|---|---|---:|
| `document_meta` | object | 文档基础信息 | 是 |
| `statistics` | object | 统计信息 | 是 |
| `pages` | array | 页索引列表 | 是 |
| `outline` | array | 目录树 | 是 |

### 6.5 返回示例
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "document_meta": {
      "source_file_name": "xxx.pdf",
      "source_file_type": "pdf",
      "page_count": 148,
      "created_at": "2026-04-21T11:00:39.246595Z"
    },
    "statistics": {
      "page_count": 148,
      "node_count": 1320,
      "heading_count": 86,
      "image_count": 34,
      "table_count": 12
    },
    "pages": [
      {
        "page_idx": 0,
        "width": 612,
        "height": 792,
        "rotation": 0,
        "node_ids": ["page0_node0", "page0_node1"],
        "node_count": 11,
        "has_image": true,
        "has_table": false
      }
    ],
    "outline": [
      {
        "id": "page0_node0",
        "title": "Office of Science ...",
        "page_idx": 0,
        "level": 1,
        "children": []
      }
    ]
  }
}
```

### 6.6 返回字段说明
- `document_meta`：文档基本属性
- `statistics`：文档整体统计
- `pages`：页级轻量索引，用于页壳渲染和跳页
- `outline`：标题目录树，用于导航

---

## 7. 接口 2：页内容接口
### 7.1 接口名称
`GET /intelligent-translation/document-page?page_idx=12`

### 7.2 用途
返回指定页的完整可渲染内容。前端在视口内挂载该页时调用。

### 7.3 请求参数
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---:|---|
| `page_idx` | number | 是 | 目标页码，从 0 开始 |

### 7.4 返回参数
| 字段 | 类型 | 含义 | 是否必需 |
|---|---|---|---:|
| `page` | object | 页基本信息 | 是 |
| `nodes` | array | 该页节点列表 | 是 |

### 7.5 `page` 字段说明
| 字段 | 含义 | 是否必需 |
|---|---|---:|
| `page_idx` | 页码 | 是 |
| `width` | 页面宽度 | 是 |
| `height` | 页面高度 | 是 |
| `rotation` | 页面旋转角度 | 否 |

### 7.6 `nodes` 字段说明
| 字段 | 含义 | 是否必需 |
|---|---|---:|
| `node_id` | 节点唯一 id | 是 |
| `semantic_type` | 语义类型 | 是 |
| `page_idx` | 所属页码 | 是 |
| `content_payload` | 内容载荷 | 是 |
| `layout` | 布局信息 | 是 |
| `style_spans` | 样式片段 | 否 |

### 7.7 `content_payload` 允许返回的最小字段
| 字段 | 用途 |
|---|---|
| `type` | 内容类型分发 |
| `text` | 纯文本渲染 |
| `html` | 富文本渲染 |
| `heading_level` | 目录/标题层级 |
| `table_body_html` | 表格渲染 |
| `img_path` | 图片渲染 |
| `preview_img_path` | 图片预览 |
| `alt_text` | 图片替代文本 |
| `caption` | 图注/表注 |

### 7.8 返回示例
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "page": {
      "page_idx": 12,
      "width": 612,
      "height": 792,
      "rotation": 0
    },
    "nodes": [
      {
        "node_id": "page12_node0",
        "semantic_type": "heading",
        "page_idx": 12,
        "content_payload": {
          "type": "text",
          "text": "Section Title",
          "html": "<b>Section Title</b>",
          "heading_level": 2
        },
        "layout": {
          "bbox": [119, 204, 880, 338],
          "bbox_norm": [0.12, 0.205, 0.881, 0.339],
          "angle": 0,
          "reading_order": 0,
          "page_idx": 12
        },
        "style_spans": []
      }
    ]
  }
}
```

### 7.9 使用场景
- 页面滚动进入某页时加载
- 目录跳转到某页时加载
- 页壳替换为真实内容时加载

## 8. 后端拆分规则
### 8.1 文档摘要接口返回什么
保留：
- 文档基本信息
- 统计信息
- 页索引
- 目录树

去除：
- 节点完整正文
- 大 HTML
- 重复的布局信息

### 8.2 页内容接口返回什么
保留：
- 页信息
- 页内节点完整可渲染数据

去除：
- 与当前页无关的其他页内容
- 文档级统计信息
- 目录树

## 9. 开发实现建议
1. 直接从现有 `merged_ans.json` 构造两个接口返回体
2. 先实现 `document-meta`，让前端可初始化
3. 再实现 `document-page`，支撑页级加载
4. 保持旧接口不变，避免历史页面受影响

## 10. 验收标准
### 10.1 接口正确性
- 各接口返回字段稳定
- 页索引与页内容一致
- 节点 id 可唯一定位

### 10.2 性能要求
- `document-meta` 返回体轻量
- `document-page` 只返回单页数据
- 不再出现整包大响应作为前端主入口

### 10.3 联调要求
- 前端可先拿摘要和目录
- 前端可按页加载内容

## 11. 结论
后端新增接口最终收敛为 2 个：
- `document-meta`
- `document-page`

其中 `document-meta` 已合并页索引和目录，避免重复接口。整体目标是：**只保留渲染必须数据，降低响应体积，支撑前端页级懒加载渲染。**
