# EPUB 审校器长期维护手册

## 目标与边界

本工具服务于中日双语 EPUB 的网页审校：长篇连续阅读、逐段修改中文译文、标记翻译问题、导出反馈与修订 EPUB。翻译质量规则仍由项目根目录的 `AGENTS.md`、`rules/translation_rules.md`、当前系列的 `series-style.md` 与术语表共同约束。

审校器不负责整卷首译流程，也不直接改正式术语表。用户在网页中留下的编辑、问题备注、长期规则建议，需要由 Codex 后续读取反馈文件后再沉淀到系列风格或候选术语中。

## 数据模型与会话目录

`--review-root` 是唯一需要备份的运行数据目录。典型结构：

```text
epub_review_sessions/
  app_state.json
  gpt_config.json
  <session-id>/
    source.epub
    extracted/
    review_state/
      epub_entries.json
      rows.json
      session.json
      state.json
    feedback/
      translation_feedback.jsonl
      feedback_for_codex.md
    exports/
```

兼容要求：

- `rows.json` 是初始解析结果，不应因用户编辑而重写。
- `state.json.edits` 保存用户修改与标记，字段缺省时必须能回退到原始译文。
- `session.json` 与 `app_state.json` 只保存会话定位信息。
- `gpt_config.json` 只属于本地运行环境，不写入 EPUB、不写入导出文件、不通过 API 回传密钥。

## 目录与插图

结构接口 `/api/structure` 应保持向后兼容：

- text chapter: `kind: "text"`、`parts`、`row_count`、`touched_count`、`marked_count`
- image chapter: `kind: "image"`、`images`、`parts: []`、`row_count: 0`
- 统计字段同时保留总数和细分：`chapter_count`、`text_chapter_count`、`image_chapter_count`、`image_count`、`asset_count`
- part 标题默认使用 `part0000` 形式，真实标题可保留在 `source_title`
- 插图通过 `/api/asset/<entry>` 读取，必须继续使用 `extracted_path()` 防止路径穿越；只把 raster 图片纳入 `/api/structure` 与 `/api/asset` 白名单，不能任意读取解包目录文件

章节来源优先级：

1. EPUB 内部目录页的中文条目
2. `nav.xhtml` / `toc.xhtml`
3. 正文标题
4. 文件名 fallback

## 阅读与侧栏交互

验收口径：

- 初始进入审校时，左侧侧栏隐藏，正文占主要空间。
- 顶部“目录”只打开目录，“检索”只打开搜索/段落列表，不合并成一个常驻面板。
- 目录可展开/收起章节，插图章节可点击阅读，文字 part 可点击定位。
- 阅读模式不显示每段编号、快速编辑、快速标记按钮。
- 点击正文段落打开右侧精修与重翻面板。
- 右侧面板打开或关闭导致正文宽度变化时，应恢复用户原来正在看的段落位置。
- 移动窄屏下，侧栏和右侧面板应以抽屉/底部面板方式显示，不遮死主要操作。

## 编辑、反馈与导出

保存本段时必须：

- sanitize 中文 HTML，但允许 `ruby/rb/rt/rp/mark/span` 等必要内联标签。
- 记录 `before_cn_html`、`after_cn_html`、问题类型、严重程度、标签、备注、长期规则建议。
- 更新 `feedback/translation_feedback.jsonl`。

生成反馈时必须：

- 写入 `feedback_for_codex.md`。
- 只汇总已编辑、已标记或有备注的段落。
- 保留日文原文、修改前、修改后，便于后续翻译规则复盘。

导出 EPUB 前必须先写回已保存的译文修改，插图文件保持原样。

## GPT 重翻

GPT 能力是可选增强，不应影响离线审校。

安全与配置：

- 支持 OpenAI 兼容的 `base_url`、`model`、`api_key`。
- API Key 优先读取 `gpt_config.json`，也支持环境变量 `OPENAI_API_KEY`。
- `/api/gpt/config` 不得返回 API Key。
- 未配置 Key 时，重翻接口应返回可读错误，不影响编辑保存。
- 重翻请求不得临时覆盖 `base_url` 或 `model` 后继续复用已保存密钥；要更换端点或模型必须先保存配置，避免把密钥发往未确认端点。

单段重翻流程：

1. 用户点击阅读段落，打开右侧面板。
2. 用户可填写额外重翻要求。
3. `/api/row/<row_id>/retranslate` 使用当前日文、当前中文、术语提示生成候选。
4. 候选只显示在面板里，不自动覆盖。
5. 用户点击“应用重翻”后写入编辑框，再点击保存才进入审校记录。

Prompt 硬规则：

- 输出简体中文轻小说文风。
- 意义优先，不贴日语语序硬译。
- 不合并、不拆分段落。
- 有意义 ruby 必须保留为真实 `<ruby><rb>...</rb><rt>...</rt></ruby>`，不要改成括号。
- Falchion / ファルシオン 固定译为“大砍刀”，不要译成“偃月刀”。

## 版本规则

版本号使用 `version = "0.1.0"` 格式：

| 层级 | 触发条件 |
| --- | --- |
| PATCH | 修复 bug 或兼容性小修 |
| MINOR | 新增向后兼容能力、API 字段或可选配置 |
| MAJOR | 破坏兼容的 API、配置或行为变更 |

发版时必须同步：

- `version.py`
- `static/index.html` 顶部版本徽标 fallback
- `README.md` 当前版本与版本说明

## 回归清单

每轮改动至少检查：

- `python -m py_compile tools/epub_review_editor/server.py tools/epub_review_editor/version.py`
- `node --check tools/epub_review_editor/static/app.js`
- `git diff --check`
- `/api/version`
- `/api/session`
- `/api/structure`
- `/api/gpt/config`
- 首个插图 `/api/asset/...` 返回 200 且浏览器可显示
- 非白名单或非 raster asset 不能被 `/api/asset/...` 读取
- 目录按钮、检索按钮、隐藏侧栏、点击段落打开右侧面板
- 阅读段落下方没有编号和“快速编辑/快速标记”
- 未配置 API Key 时重翻返回清晰错误
- 配置保存后 `/api/gpt/config` 不包含密钥字段