474 lines
13 KiB
Markdown
474 lines
13 KiB
Markdown
# 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. 测试层级
|
||
|
||
```text
|
||
人工与 TestFlight 验收
|
||
↑
|
||
UI / 真机系统测试
|
||
↑
|
||
PDF / EPUB / TTS 集成测试
|
||
↑
|
||
AI 产品评测与 Prompt 回归
|
||
↑
|
||
Core / Storage / NLP 单元测试
|
||
```
|
||
|
||
确定性校验优先放在单元测试；非确定性生成质量使用固定数据集、多次运行和人工评审。
|
||
|
||
## 3. 测试目标与 Target
|
||
|
||
建议新增：
|
||
|
||
```text
|
||
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：
|
||
|
||
```json
|
||
{
|
||
"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：
|
||
|
||
```text
|
||
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 建议
|
||
|
||
```text
|
||
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 灰度指标稳定。
|
||
|