ReadViewSDK/Doc/FeatureSolution/样书基线验证方案讨论.md

样书基线验证方案讨论

需求背景

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 样书，建立一套统一矩阵、统一流程、统一模板的基线验证机制，首期重点覆盖分页耗时、目录命中率、末页事件和设置恢复稳定性，并为后续自动化回归提供稳定样书夹具。