ReadViewSDK/Doc/RDAIReaderView/RDAIReaderView-TEST-PLAN.md

RDAIReaderView 商用测试与发布计划

文档状态： Draft 0.1
最后更新： 2026-07-25
目标版本： RDAIReaderView 1.0

1. 目标

测试计划验证以下结论：

1. AI 模块不会破坏现有 PDF、EPUB、搜索、标注和 TTS。
2. 索引和引用在书籍更新、分页变化、OCR 和应用中断后仍然可靠。
3. Foundation Models 的输出有证据、可拒答、不剧透并可安全降级。
4. 性能、内存、耗电、隐私和可访问性达到商用要求。
5. Prompt 或系统模型更新后，可以通过可重复评测发现质量回归。

2. 测试层级

人工与 TestFlight 验收
        ↑
UI / 真机系统测试
        ↑
PDF / EPUB / TTS 集成测试
        ↑
AI 产品评测与 Prompt 回归
        ↑
Core / Storage / NLP 单元测试

确定性校验优先放在单元测试；非确定性生成质量使用固定数据集、多次运行和人工评审。

3. 测试目标与 Target

建议新增：

RDAIReaderViewCoreTests
RDAIReaderViewNaturalLanguageTests
RDAIReaderViewFoundationModelsTests
RDPDFReaderViewAITests
RDEpubReaderViewAITests
ReadViewDemoAIUITests

Foundation Models 真机测试与普通 CI 分离，避免不支持模型的 Runner 造成假失败。

4. 测试数据

4.1 数据来源

只使用：

• 公版书籍。
• 项目拥有测试授权的书籍。
• 团队自行编写的合成文本。
• 经过脱敏、明确允许进入测试仓库的样本。

不得把商业书籍全文或用户内容提交到测试仓库。

4.2 数据集组成

首版至少包含：

类型	最低数量	重点
中文小说章节	20	多人物、别名、代词、倒叙、否定关系
英文小说章节	10	名称大小写、代词、长句
中文技术/非虚构	10	术语、组织、事实问答
英文技术/非虚构	10	代码块、列表、表格
原生文本 PDF	5 本/50 页	单栏、双栏、页眉页脚
扫描 PDF	5 本/50 页	OCR 错字、旋转、低清晰度
EPUB	5 本/30 章	CFI、脚注、长章节、重排
无答案问题	20	拒答
剧透边界问题	20	已读/未读范围隔离
同名或别名关系	20	实体合并准确性

首版产品评测集不少于 100 个 Case。每个 Case 保存输入、允许范围、期望证据、可接受答案要点和禁止行为。

4.3 Case 格式

建议使用 JSONL：

{
  "id": "qa-zh-001",
  "task": "questionAnswering",
  "documentFixture": "novel-zh-01",
  "readScope": {
    "resourceOrderUpperBound": 3,
    "utf16UpperBound": 8200
  },
  "input": "林川为什么离开村庄？",
  "expectedPassageIDs": ["p-3-18", "p-3-19"],
  "requiredFacts": ["受到追捕"],
  "forbiddenFacts": ["第四章之后的身份揭示"],
  "expectedStatus": "answered"
}

测试结果不得把 fixture 原文写入可上传日志。

5. Core 单元测试

5.1 文本范围

• 空文本、空白文本和超长文本。
• Emoji、组合字符、代理对、中文标点和换行。
• UTF-16 范围与 Swift String Index 双向转换。
• 搜索规范化不能改变 source range。
• Passage 重叠不能产生错误 Locator。

5.2 哈希与失效

• 相同内容产生相同哈希。
• 只改变一个章节时只失效该资源。
• Prompt 版本变化只失效相关 Artifact。
• embedding 模型 revision 变化只重建对应向量。
• 阅读范围扩大不复用越界缓存。

5.3 存储与迁移

• 首次建库、重复打开和并发读取。
• 每个 Schema 版本向下一版本迁移。
• 迁移中断后恢复或回滚。
• 数据库损坏时保留诊断并可安全重建。
• 按书删除和删除全部数据。
• 登出/删书回调后无孤立 Passage、向量或 Artifact。

5.4 索引调度

• 当前章节优先。
• 暂停、恢复、取消和重复 prepare。
• 应用强制退出后从 checkpoint 恢复。
• 内存警告取消低优先级任务。
• 内容 Provider 释放后任务安全失败，不野指针或永久等待。

6. Natural Language 测试

6.1 语言与分句

• 中文、英文、中英混排。
• 无标点长段落。
• 缩写、小数、网址和引号。
• 句子范围与 RDSpeechReaderView 结果一致。
• 不支持语言的降级分块。

6.2 实体

按任务统计 Precision、Recall、F1：

precision = 正确识别实体 / 所有识别实体
recall    = 正确识别实体 / 所有标注实体
F1        = 2 * precision * recall / (precision + recall)

首版门槛：

• 人物候选 Precision ≥ 0.95。
• 人物候选 Recall ≥ 0.85。
• 地点/组织作为辅助信息，F1 ≥ 0.80。

人物候选宁可少召回，也不能大量创建虚假人物。

6.3 检索

• 关键词命中、同义表达、别名和错别字。
• Top 5 包含正确证据的 Recall@5 ≥ 0.90。
• 无 embedding 资源时词法检索仍可返回结果。
• 已读范围外 Passage 召回数必须为 0。
• 相同输入和索引版本的词法结果顺序稳定。

7. PDF Adapter 测试

• 原生文本 run 按 readingOrder 正确拼接。
• 双栏页面不会按几何坐标错误穿插。
• run 间换行计入 UTF-16 范围。
• Passage 范围映射回正确 normalized rects。
• characterRects 存在/缺失均可高亮。
• OCR 与原生文本来源正确标记。
• OCR 缓存命中、失败、取消和重试。
• 页面缓存裁剪后 Citation 仍可重新加载。
• 跳转后目标页和高亮正确。
• 旋转、横屏、竖滑、双页模式下高亮位置正确。
• 页面导航取消 OCR 时，AI 索引任务不应永久丢失。

PDF 引用定位有效率必须 ≥ 99%。

8. EPUB Adapter 测试

• href 规范化一致。
• UTF-16 range、rangeAnchor、CFI 和 rangeCFI 互相映射。
• 改字号、行距、边距、字体和横竖屏后 Citation 可恢复。
• 长章节按需加载时可提取目标资源。
• 脚注、列表、图片替代文本和代码块类型正确。
• EPUB 更新导致 source hash 变化时旧 Citation 标记 stale。
• CFI 缺失时 progression 只作兜底。
• 引用跳转复用标准位置恢复流程。
• 固定版式无文本章节返回明确不可分析状态。

EPUB 重排后引用定位有效率必须 ≥ 99%。

9. Foundation Models 产品评测

9.1 运行方式

• 每个 Case 至少运行 3 次，避免偶然结果掩盖问题。
• 按系统模型版本、系统语言和设备分桶。
• Prompt 新版本同时运行旧版和新版，生成差异报告。
• 代码校验先执行，再进入人工/模型评分。

9.2 摘要 Rubric

分数	标准
5	覆盖关键事件，全部有证据，无未读信息，表述简洁
3	基本正确但遗漏一项重要内容，或引用不够精确
1	包含无证据事实、重大误解或剧透

发布门槛：

• 平均分 ≥ 4.0。
• 任一剧透 Case 失败即阻断发布。
• 无证据事实比例 ≤ 2%。

9.3 问答 Rubric

检查：

• 是否回答用户问题。
• 每个事实是否被引用支持。
• 是否遗漏关键反证。
• 证据不足时是否拒答。
• 是否泄漏未读内容。

发布门槛：

• Context faithfulness ≥ 98%。
• 无答案正确拒答率 ≥ 95%。
• Citation validity ≥ 99%。
• Spoiler safety = 100%。

9.4 人物与关系 Rubric

检查：

• 人物真实出现。
• 别名有明确证据。
• 同名人物未误合并。
• 关系方向正确。
• confirmed 与 possible 分类合理。
• 冲突关系没有被静默覆盖。

发布门槛：

• Character precision ≥ 97%。
• Alias merge precision ≥ 98%。
• 关系证据覆盖率 = 100%。
• 无证据关系数 = 0。

9.5 LLM Judge

LLM Judge 只作为辅助：

• 使用固定 Rubric，不使用泛化“是否有帮助”问题。
• 先对至少 30 个 Case 与人工评分校准。
• Spearman/Pearson 相关性低于 0.7 时不得作为发布门禁。
• Judge 分歧、低分和边界 Case 必须人工复核。
• 若使用云端 Judge，测试原文必须为可上传的公版或合成数据。

10. 可用性与错误测试

覆盖：

• iOS 15/17：Foundation Models 模块不参与运行。
• iOS 26+ 不支持设备。
• Apple Intelligence 未开启。
• 模型正在下载或未准备。
• 当前语言不支持。
• context limit exceeded。
• guardrail 拒绝输入或输出。
• 生成中取消、切书、关闭页面、进入后台。
• 同一 session 并发请求。
• 低存储空间和数据库写入失败。

每种情况必须产生稳定枚举状态，并保持阅读器可操作。

11. UI 与可访问性

11.1 UI 自动化

• 打开/关闭 AI 面板。
• 当前章节索引状态。
• 发起问题、取消和重试。
• 点击引用并跳转高亮。
• 仅已读范围默认开启。
• 整本书模式确认。
• Foundation Models 不可用状态。
• 清除本书和全部 AI 数据。
• AI 结果交给 TTS 朗读。

11.2 可访问性

• VoiceOver 顺序和标签。
• Dynamic Type 最大辅助字号。
• Reduce Motion。
• 深色模式和高对比度。
• possible/conflicting 不只依赖颜色。
• 加载、取消和失败状态有可访问性公告。

12. 性能与资源测试

目标设备至少覆盖：

• 最低性能 iOS 15 支持设备。
• iOS 17 中档设备。
• 一台首代支持 Apple Intelligence 的设备。
• 一台当前系统的高性能设备。

基准：

指标	1.0 目标
当前章节基础索引 P95	≤ 2 秒
10 万中文字基础索引 P95	≤ 30 秒
本地检索 P95	≤ 300 ms
生成首个可展示结果 P95	≤ 5 秒
引用跳转 P95	≤ 500 ms，不含未缓存页面加载
索引峰值额外内存	目标 ≤ 150 MB，按真机基线确认
空闲内存释放	30 秒内释放 embedding 和大文本缓存
AI crash-free session	≥ 99.9%

测试同时记录：

• CPU time。
• 主线程卡顿。
• thermal state。
• 电量变化。
• 数据库大小/万字。
• embedding 资源加载耗时。
• 缓存命中率。

性能基线变化超过 15% 时 CI 或发布报告必须提示。

13. 隐私与安全测试

• 网络抓包确认默认实现不上传书籍或问题。
• 搜索日志、控制台日志和 crash breadcrumbs 不含原文。
• 清除 AI 数据后数据库、缓存和临时文件均删除。
• 删除书籍和退出账户触发相同清除路径。
• Scope 过滤在检索前和生成后均执行。
• 构造伪造 Passage ID，确认 Citation Validator 拒绝。
• 构造路径、超长查询和大量 Tool 参数，确认边界限制。
• Tool Calling 最大次数和重复调用检测生效。
• 数据库迁移和诊断包不泄漏原文。

14. 回归测试

每次合入必须运行：

• Core 单元测试。
• Natural Language 确定性测试。
• PDF/EPUB Adapter fixture 测试。
• 现有 PDF、EPUB 和 TTS 编译。
• git diff --check 和公共 API 兼容检查。

每日或候选发布运行：

• UI smoke。
• 完整 AI 评测集。
• 大书索引性能。
• Foundation Models 真机矩阵。
• 现有 ReadViewDemoUITests 回归。

15. CI 建议

PR:
  lint/diff-check
  Core unit tests
  NLP unit tests
  Adapter tests
  build iOS 15 target
  build iOS 26 FoundationModels target

Nightly:
  Full reader UI regression
  AI deterministic evals
  Performance fixtures

Release candidate:
  Foundation Models physical-device eval
  Human review sample
  Privacy/network audit
  Migration matrix

设备模型评测结果应保存以下元数据：

• OS 版本。
• 模型版本或可识别 profile。
• Prompt identifier/version。
• fixture version。
• SDK commit。
• 各指标与失败 Case ID。

不得保存生产用户原文。

16. 缺陷分级

P0

• 泄漏书籍内容或阅读历史。
• 绕过已读范围造成剧透。
• 删除用户原书、标注或笔记。
• 大面积崩溃或数据库不可恢复损坏。

P1

• 无引用或错误引用的事实作为确定答案展示。
• 人物关系大面积误合并。
• Foundation Models 不可用导致阅读器不可用。
• 引用跳转到错误章节/页面。

P2

• 摘要遗漏、检索质量下降、局部 UI 或性能问题。
• 可重试且不影响阅读主流程的生成失败。

发布时 P0/P1 必须为 0；P2 必须有明确接受记录和后续版本计划。

17. TestFlight 灰度

阶段 A：内部

• 团队和测试设备。
• 至少 7 天。
• 完整日志仅限脱敏元数据。

阶段 B：5%

• 只开启摘要和问答。
• 观察 crash-free、取消率、拒答率、引用点击成功率。
• 人物关系仍受远程/本地 feature flag 控制。

阶段 C：25%

• 开启人物卡片。
• 关系图只对达到索引完整度的书籍开放。
• 至少稳定 7 天。

阶段 D：100%

• 所有发布门禁持续达标。
• 保留快速关闭 Foundation Models 功能的配置，但关闭后基础阅读和 NLP 正常。

18. 最终发布门禁

• 五份开发文档与实现一致。
• 公共 API 兼容检查通过。
• Core/NLP/Adapter 单元和集成测试通过。
• 现有 Reader 与 TTS 回归通过。
• 100+ AI Case 全量运行并达到指标。
• Foundation Models 支持与不支持路径均完成真机测试。
• PDF/EPUB Citation validity ≥ 99%。
• Context faithfulness ≥ 98%。
• Spoiler safety = 100%。
• AI crash-free session ≥ 99.9%。
• 隐私和网络审计通过。
• 无 P0/P1 缺陷。
• TestFlight 灰度指标稳定。