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