# 样书基线验证方案讨论

## 需求背景

`Doc/EPUB_MAINTENANCE.md` 已将“样书基线验证”列为 EPUB 阅读器下一阶段的高优先级能力之一。

当前阅读器已经具备：

1. EPUB 打开与解析
2. WebView / DTCoreText / fixed-layout 三条正文渲染路径
3. 目录跳转、阅读位置恢复、字号与主题调整
4. 高亮、划线、批注、搜索等阅读交互能力

但这些能力目前主要还是依赖“人手点一遍”来判断是否正常，缺少固定样书、固定流程、固定输出格式的基线验证机制。

因此，“样书基线验证”这项需求的目标，不是再增加几本 demo 书，而是基于当前已内置的四本 EPUB 样书，建立一套：

1. 可重复执行
2. 可横向比较
3. 可长期沉淀
4. 可逐步自动化

的阅读器基线验证机制。

## 代码事实

### 已有基础

当前仓库已经具备样书基线验证所需的基本条件：

1. `ReadViewSDKDemo/ReadViewSDKDemo/Resources/` 内已经内置四本 EPUB 样书
2. `RDReaderManager.bundledEPUBURLs(in:)` 会自动枚举 bundle 中所有 `.epub`
3. `RDReaderManager.demoBookItems(in:)` 已将这些样书接入 demo 书架入口
4. `ViewController` 支持通过 `-demo-book-title` 启动参数自动打开指定样书

这意味着当前并不缺“样书载体”或“执行入口”，更缺的是：

1. 哪本样书用于验证哪类能力
2. 每次验证时要记录哪些数据
3. 什么叫验证通过
4. 如何把结果沉淀成可比较的基线

### 当前实现存在的问题

#### 问题 1：四本样书当前只是 demo 资源，不是正式基线夹具

现在这四本书更多承担“可打开、可展示”的职责，但还没有被正式定义为：

1. 固定基线样书
2. 各自覆盖的风险场景
3. 必测能力清单
4. 异常归档与复验对象

#### 问题 2：当前没有统一的基线指标结构

`Doc/EPUB_MAINTENANCE.md` 已明确提到要补齐：

1. 分页耗时
2. 目录命中率
3. 末页事件
4. 设置恢复稳定性

但当前还没有统一规定：

1. 指标如何采集
2. 指标如何记录
3. 指标的通过标准是什么
4. 下次如何与这次比较

#### 问题 3：样书验证目标混杂了性能、正确性与兼容性

“样书基线验证”至少同时包含三类验证目标：

1. 性能基线：分页耗时、页数规模
2. 正确性基线：目录跳转、末页事件、位置恢复
3. 兼容性基线：不同 EPUB 类型在不同渲染路径下是否稳定

如果不拆开，执行时很容易退化成“随便翻一下，感觉没问题”。

## 需求拆解

建议把“样书基线验证”拆成四部分来推进。

### 1. 固定样书集

先把四本样书从“demo 资源”提升为“固定基线夹具”，后续版本迭代尽量不随意替换。

### 2. 固定样书职责

每本样书都明确它主要覆盖哪些风险，而不是所有书都做完全相同的验证。

### 3. 固定基线指标

每次验证时都按同一组字段记录结果，保证可比较。

### 4. 固定验证流程与输出模板

每轮验证都按统一步骤执行，并把结果写入统一模板，避免结论只停留在口头描述。

## 技术路线对比

### 路线 A：完全手工验证

思路：

1. 打开四本样书
2. 手工翻页、点目录、调字号
3. 用主观结论判断是否正常

优点：

1. 上手快
2. 不需要额外改工程

风险：

1. 结果不稳定
2. 不同人执行结论可能不同
3. 无法形成长期可比较的基线

### 路线 B：一开始就全量自动化

思路：

1. 直接把四本样书的打开、翻页、跳转、恢复全部接入 UI 自动化或脚本采集
2. 让基线数据自动产出

优点：

1. 理想状态下最规范
2. 长期收益高

风险：

1. 前期成本大
2. 当前测试基础设施还不完整
3. 部分阅读体验问题在第一阶段更适合半自动确认

### 路线 C：先建立半自动基线，再逐步自动化

思路：

1. 先固定样书矩阵与基线字段
2. 借助现有 demo 自动打开入口执行统一验证流程
3. 先沉淀结构化结果
4. 再将适合自动化的部分逐步纳入 XCTest / XCUITest

优点：

1. 投入和收益平衡更好
2. 能更快形成第一版基线
3. 不会被早期自动化建设阻塞

风险：

1. 需要纪律性执行模板
2. 初期仍有部分验证依赖人工操作

### 推荐结论

建议采用：

**主路线：路线 C，先建立半自动样书基线，再逐步自动化**

原因：

1. 当前仓库已经有四本固定样书和自动打开入口
2. 样书基线验证的第一目标是“有可比较的结果”，而不是“立刻完全自动化”
3. 自动化测试体系尚在建设中，先立住基线矩阵更划算

## 推荐方案

### 方案总览

样书基线验证第一阶段建议形成如下结构：

1. 固定四本样书，不随意替换
2. 每本样书绑定主要验证职责
3. 每轮版本验证按统一流程执行
4. 每次都输出结构化基线表
5. 对异常项保留备注与复验结论

### 四本样书矩阵

> 注：以下矩阵以当前样书名称和文档信息为基础，readingProfile 可在首次正式基线验证时补齐实测结果。

| 样书 | 主要定位 | 重点验证能力 | 适合记录的核心指标 |
|------|----------|--------------|--------------------|
| `爱忘事的熊爷爷.epub` | 轻量快速回归样书 | 打开成功、基础分页、目录基本可用、设置恢复 | 打开耗时、总页数、TOC 基本命中、设置恢复 |
| `张学良传.epub` | 标准长文 reflowable 样书 | 长文分页、目录跳转、字号变化后位置恢复 | 首次分页耗时、TOC 命中率、字号调整后恢复 |
| `宝山辽墓材料与释读.epub` | 复杂结构与学术内容样书 | 复杂 TOC / fragment 命中、图片与正文结构稳定性、搜索与标注抽样 | TOC 命中率、fragment 命中、搜索命中、高亮恢复 |
| `《凡人修仙传》精校版全本.epub` | 大体量长书与压力样书 | 大体量分页稳定性、持久化恢复、末页事件、长时阅读链路 | 分页耗时、总页数、末页事件、重进恢复稳定性 |

### 推荐验证维度

第一阶段建议围绕下面这些维度建立固定基线：

1. 打开是否成功
2. readingProfile 类型
3. spine 数量
4. 总页数是否合理
5. 首次分页耗时
6. TOC 是否可打开
7. TOC 抽样命中率
8. 末页事件是否正常触发
9. 字号调整后位置是否稳定恢复
10. 主题 / 设置是否稳定恢复
11. 重进后阅读位置是否恢复
12. 标注或高亮是否恢复

其中第一阶段最核心的四项，应与 `Doc/EPUB_MAINTENANCE.md` 对齐：

1. 分页耗时
2. 目录命中率
3. 末页事件
4. 设置恢复稳定性

## 推荐执行流程

建议每本样书都按同一流程执行，避免漏项。

### Step B1：冷启动打开样书

目标：

1. 验证样书可正常进入阅读器
2. 记录首次打开与首次分页表现

记录：

1. 是否打开成功
2. readingProfile
3. spine 数量
4. 总页数
5. 首次分页耗时

### Step B2：目录抽样验证

目标：

1. 验证 TOC 是否能正常打开
2. 验证典型目录项是否能跳转到正确章节或语义位置

建议：

1. 每本样书至少抽样 3 到 5 个目录项
2. 包含开头、中间、靠后位置
3. 如果目录层级复杂，额外抽样一个带 fragment 的条目

记录：

1. 抽样条目数
2. 命中数
3. 命中率
4. 失败条目与现象

### Step B3：末页事件验证

目标：

1. 验证阅读器到达末页时的状态变化是否正确
2. 检查不会提前触发或漏触发

记录：

1. 是否到达末页
2. 末页事件是否正常触发
3. 是否出现重复触发或不触发

### Step B4：设置恢复稳定性验证

目标：

1. 修改字号、主题或其他关键阅读设置
2. 验证设置变更后分页是否稳定
3. 验证退出重进后设置是否恢复

记录：

1. 修改的设置项
2. 修改后是否立即生效
3. 重进后是否恢复
4. 是否伴随位置飘移或异常白页

### Step B5：位置与标注恢复抽样验证

目标：

1. 在样书中间位置退出重进
2. 验证阅读位置恢复
3. 抽样验证一条高亮或标注恢复

记录：

1. 退出前位置
2. 重进后位置
3. 是否在同一章节或邻近语义位置
4. 高亮 / 标注是否仍存在

## 基线表模板

建议每轮验证都至少产出两张表：

1. 总览表
2. 单书详情表

### 模板 1：样书基线总览表

| 日期 | 版本 / 分支 | 样书 | readingProfile | spine 数量 | 总页数 | 首次分页耗时 | TOC 抽样 / 命中 | 末页事件 | 设置恢复 | 位置恢复 | 标注恢复 | 结论 | 备注 |
|------|--------------|------|----------------|------------|--------|--------------|-----------------|----------|----------|----------|----------|------|------|
| YYYY-MM-DD | branch / commit | 爱忘事的熊爷爷 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 通过 / 风险 / 失败 | 待填 |
| YYYY-MM-DD | branch / commit | 张学良传 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 通过 / 风险 / 失败 | 待填 |
| YYYY-MM-DD | branch / commit | 宝山辽墓材料与释读 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 通过 / 风险 / 失败 | 待填 |
| YYYY-MM-DD | branch / commit | 《凡人修仙传》精校版全本 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 待填 | 通过 / 风险 / 失败 | 待填 |

### 模板 2：单书详细验证表

#### 样书信息

| 字段 | 值 |
|------|----|
| 样书名称 | 待填 |
| 文件大小 | 待填 |
| readingProfile | 待填 |
| spine 数量 | 待填 |
| TOC 条目数 | 待填 |
| 总页数 | 待填 |
| 验证日期 | 待填 |
| 验证版本 / 分支 | 待填 |

#### 核心基线结果

| 项目 | 结果 | 备注 |
|------|------|------|
| 打开成功 | 通过 / 失败 | 待填 |
| 首次分页耗时 | 待填 | 单位建议统一为 ms 或 s |
| TOC 打开 | 通过 / 失败 | 待填 |
| TOC 抽样命中率 | 待填 | 例如 `4/5` |
| 末页事件 | 通过 / 风险 / 失败 | 待填 |
| 字号调整后恢复 | 通过 / 风险 / 失败 | 待填 |
| 主题 / 设置恢复 | 通过 / 风险 / 失败 | 待填 |
| 重进后位置恢复 | 通过 / 风险 / 失败 | 待填 |
| 高亮 / 标注恢复 | 通过 / 风险 / 失败 | 待填 |

#### TOC 抽样记录

| 序号 | TOC 条目 | 预期目标 | 实际结果 | 是否命中 | 备注 |
|------|----------|----------|----------|----------|------|
| 1 | 待填 | 待填 | 待填 | 是 / 否 | 待填 |
| 2 | 待填 | 待填 | 待填 | 是 / 否 | 待填 |
| 3 | 待填 | 待填 | 待填 | 是 / 否 | 待填 |
| 4 | 待填 | 待填 | 待填 | 是 / 否 | 待填 |
| 5 | 待填 | 待填 | 待填 | 是 / 否 | 待填 |

#### 异常与复验记录

| 异常编号 | 场景 | 现象 | 复现条件 | 当前结论 | 备注 |
|----------|------|------|----------|----------|------|
| B-001 | 待填 | 待填 | 待填 | 待确认 / 已复现 / 已修复 | 待填 |

## 推荐输出规范

为了让基线真正可比较，建议每轮验证输出时统一遵守以下规范：

### 1. 样书集固定

第一阶段尽量只使用当前这四本 EPUB，不随意更换，避免基线漂移。

### 2. 字段命名固定

例如：

1. `首次分页耗时`
2. `TOC 抽样命中率`
3. `末页事件`
4. `设置恢复`
5. `位置恢复`

尽量不要每次换表头名称。

### 3. 结论分级固定

建议统一使用：

1. `通过`
2. `风险`
3. `失败`

其中：

1. `通过`：功能符合预期，无明显异常
2. `风险`：功能基本可用，但存在偏差、偶发不稳或需继续观察
3. `失败`：功能不符合预期，影响可用性

### 4. 差异说明固定

如果与上次基线相比发生变化，建议在备注中明确：

1. 是否变快
2. 是否变慢
3. 是否命中率下降
4. 是否新增异常
5. 是否已有异常被修复

## 风险与注意点

### 风险 1：把基线验证做成纯主观体验记录

如果只有“感觉正常”“翻起来没问题”这类结论，后续几乎无法比较。

### 风险 2：过度依赖绝对页码

页码会受到字号、行距、视口与渲染策略影响，样书基线更适合比较：

1. 是否能正常分页
2. 是否恢复到同章节或邻近语义位置
3. 是否出现明显回归

而不是执着于固定页号完全一致。

### 风险 3：样书职责不清导致验证重复或漏项

如果四本书都做完全相同的验证，会浪费时间；如果每本书都“随便点几下”，又会漏掉高风险场景。

## 推荐实施顺序

如果目标是“最小投入换最大稳定性提升”，建议按下面顺序推进：

1. 先将四本样书正式定义为固定基线样书
2. 先用本文件中的矩阵与模板跑第一轮人工基线
3. 在第一轮基线中补齐每本样书的实测 `readingProfile`、spine 数量、总页数等信息
4. 统一记录异常项与复验结论
5. 再将其中适合自动化的部分逐步并入 `XCTest / XCUITest`

## 推荐结论

“样书基线验证”这项需求，建议最终收敛为下面这句话：

**基于当前 demo 内置的四本固定 EPUB 样书，建立一套统一矩阵、统一流程、统一模板的基线验证机制，首期重点覆盖分页耗时、目录命中率、末页事件和设置恢复稳定性，并为后续自动化回归提供稳定样书夹具。**