Improve EPUB restoration, book terminology and Calibre QA workflow

doc/QA_2026-10-08.md

@@ -0,0 +1,28 @@
+# 2026-10-08 QA 记录
+
+环境：Mac mini，Python 3.14，Calibre 9.15；测试阶段依用户要求用 Luna 子 agent，未调用外部收费翻译 API。
+
+## 工程验证
+
+- 29 项回归测试通过：标签/实体/MathML/图片/脚注往返、希腊字母 φ、占位符缺失/重复/嵌套错位、未验证 HTML、重复输出 ID、网络失败、术语别名/家族语境、断点续译、异常 HTML、列表/表格、锚点、CSS 和资源保留。
+- 仓库 `input/` 的 11 本书共抽取 27,321 个单元；原文占位符还原失败 0，EPUB 往返新增结构问题 0。此项验证的是提取、格式与封装，不是全书译文质量。
+- 《To Explain the World》首次发现 15 段数学 φ 与协议分隔符冲突，改为保护原文字面 φ 后通过。
+- Luna 只读复核发现人物别名误伤 Son family，以及未校验译文静默跳过；均补充测试并修正。
+
+## 真实译文样例
+
+《Gambling Man》第 1 章连续 10 段，约 6,343 英文字符；由 Luna 子 agent 生成译文。孙正义、祖父和孙家按语境区分，脚注占位符原样保存。这是 10/1,575 个抽取单元的部分样例；没有声称该书完整翻译或所有人物别名都已覆盖。巴菲特术语有自动测试和示例配置，本轮真实书段未出现巴菲特。
+
+本地证据保存在 `.work/luna-qa/`（译文和语言复核）与 `.work/luna-final/`（最新封装、完整覆盖清单、视觉 QA）。这些输出不提交到 Git，以避免提交书籍摘录和大文件。
+
+视觉流程：Calibre 将测试章节转成 PDF，Poppler 生成 PNG，Codex 查看图片；源书的目录/脚注结构另由完整 EPUB 审计检查。发现原书 `p.ot::first-letter` 会放大中文“20 世纪”中的首个数字，已在译文样式中仅重置首字伪元素，原文保持原设计。
+
+最终视觉复查：最新译文 PNG 共 4 页，原文对照 3 页；逐页查看后未发现中文缺字、重叠或截断，首个数字的放大已消除。原生 Calibre 阅读器已打开最新双语样例，通过目录搜索跳转至 Chapter 1: Roots；中文段落中的脚注 1 点击后显示对应注释内容。最终视觉结论仅限这些样例页，不能推广为全书译文质量合格。
+
+CLI 主流程使用自制小 EPUB 完成无 API 冒烟验证；新增的输出预算、截断响应和串号测试也通过。真实供应商 API 的整书翻译没有在本轮调用。
+
+## 目前边界
+
+自动术语扫描依赖模型判断。完整名字和明确别名可约束；同姓人物、间接指称、未列入表的其他译名仍须语言 QA。`exclude_contexts` 与较长术语优先处理能减少误判，不能代替全书语义消歧。
+
+HTML5 解析可以修复结构，不能自动判断出版者本意；特别的固定版式、复杂 SVG/脚本内容和阅读器差异仍需具体样本。正常主流程遇到新增结构错误会停止并留下报告。原书问题单独留存，不用“没有新增问题”宣称原书符合所有 EPUB 标准。