104 lines
5.8 KiB
Markdown
104 lines
5.8 KiB
Markdown
# 路线图：ReadViewSDK v1.1
|
||
|
||
## 概述
|
||
|
||
`v1.1` 聚焦在 v1.0 已完成的 native reflowable EPUB 基础上继续深化 WXRead 对齐，不重新打开更大范围的架构重写。实施顺序固定为：先补页面级 layout frame 几何能力，再建立自定义分页属性闭环，然后收敛分页质量/缓存，最后把 native reflowable 的回归证据提升到自动化或稳定半自动化。`RDReaderView` 继续视为稳定容器，fixed layout / interactive EPUB 继续保留 `WKWebView` 路径。
|
||
|
||
## Phases
|
||
|
||
- [ ] **Phase 6: 页面几何与交互命中层** - 为 native text 建立可复用的 layout frame 几何能力，并让 reader 交互优先依赖该几何层
|
||
- [ ] **Phase 7: WXRead 自定义属性闭环** - 建立章节 HTML/CSS → attributed string → paginator 的自定义分页属性闭环
|
||
- [ ] **Phase 8: 分页质量、缓存与性能采样** - 改善复杂图文分页质量并加入缓存、暗色/附件规则和性能诊断
|
||
- [ ] **Phase 9: 自动化回归与证据标准化** - 把 native reflowable 主路径回归能力提升到自动化或稳定半自动化，并扩展样本矩阵
|
||
|
||
## Phase Details
|
||
|
||
### Phase 6: 页面几何与交互命中层
|
||
**Goal**: 为 native text 分页结果建立页面级 layout frame 几何查询能力，并把 reader 交互逐步迁移到显式几何层，而不是继续主要依赖 `UITextView` 的黑盒行为。
|
||
**Depends on**: Phase 5
|
||
**Requirements**: LAYOUT-01, LAYOUT-02, LAYOUT-03
|
||
**Success Criteria** (必须为 TRUE):
|
||
1. native text 页面可查询字符串范围矩形、矩形反查文本范围、截断与命中信息
|
||
2. 至少一条 reader 交互链路（如搜索命中、高亮或点击定位）优先消费 layout frame 几何结果
|
||
3. `pageStartOffset`、`pageEndOffset`、`fragmentOffsets`、`RDEPUBTextOffsetRangeInfo` 兼容语义保持稳定
|
||
**Plans**: 3 plans
|
||
|
||
Plans:
|
||
- [ ] 06-01：为 `RDEPUBTextLayoutFrame` / page model 补齐几何查询 API 与截断诊断
|
||
- [ ] 06-02：让 reader 的命中/定位链路优先消费 layout frame 几何层
|
||
- [ ] 06-03：验证 offset / fragment 兼容契约在新几何层下不回归
|
||
|
||
Cross-cutting constraints:
|
||
- 不替换 `RDReaderView`
|
||
- 不引入新的公开 reader 入口
|
||
- 优先增量接线，不一次性重写展示层
|
||
|
||
### Phase 7: WXRead 自定义属性闭环
|
||
**Goal**: 把章节 HTML/CSS 中的分页相关语义稳定地传导到 attributed string 与 paginator，让复杂块元素、图片和附件拥有更精细的分页控制。
|
||
**Depends on**: Phase 6
|
||
**Requirements**: ATTR-01, ATTR-02, ATTR-03
|
||
**Success Criteria** (必须为 TRUE):
|
||
1. 至少 `avoidPageBreakInside`、`pageBreakBefore`、`pageBreakAfter`、`pageRelate` 形成端到端闭环
|
||
2. 图片/附件垂直居中等语义在分页或展示阶段仍可被消费
|
||
3. 代码块、表格、列表、引用块等类别在分页诊断中可区分，并影响分页边界控制
|
||
**Plans**: 3 plans
|
||
|
||
Plans:
|
||
- [ ] 07-01：定义并接线分页相关自定义属性从 HTML/CSS 到 attributed string 的映射
|
||
- [ ] 07-02：补齐图片/附件语义与页面消费规则
|
||
- [ ] 07-03：为复杂块元素分类与分页规则建立诊断和验证路径
|
||
|
||
Cross-cutting constraints:
|
||
- 继续沿用现有 chapter preprocessing 与 renderer contract
|
||
- 不直接搬运读书私有实现
|
||
- 新属性必须可诊断、可回归，不是隐式魔法行为
|
||
|
||
### Phase 8: 分页质量、缓存与性能采样
|
||
**Goal**: 在新几何层与属性闭环之上提升复杂图文章节分页质量，并控制重复排版开销与主题/附件规则的一致性。
|
||
**Depends on**: Phase 7
|
||
**Requirements**: QUAL-01, QUAL-02, QUAL-03, QUAL-04
|
||
**Success Criteria** (必须为 TRUE):
|
||
1. 相同视口与排版配置下，同一章节不会重复全量排版
|
||
2. 复杂图文章节分页质量可见改善，减少粗暴截断、不合理留白、孤行/寡行
|
||
3. 图片尺寸策略、暗色模式适配、页面背景类信息有明确处理规则和诊断证据
|
||
4. 首屏时间、重分页耗时或交互流畅度不会出现明显退化，且有稳定采样数据
|
||
**Plans**: 3 plans
|
||
|
||
Plans:
|
||
- [ ] 08-01：为 layout frame / pagination 增加缓存键与失效策略
|
||
- [ ] 08-02：针对复杂样本收敛分页质量与图片/附件/背景规则
|
||
- [ ] 08-03：补充性能采样与质量诊断输出
|
||
|
||
Cross-cutting constraints:
|
||
- 先做缓存和局部优化，再考虑进一步扩展特性面
|
||
- 质量提升必须基于真实样本，而不是仅靠 synthetic case
|
||
- 保持与现有 offset-based consumer 的兼容
|
||
|
||
### Phase 9: 自动化回归与证据标准化
|
||
**Goal**: 建立覆盖 native reflowable 主路径的自动化或稳定半自动化回归能力，并把样本矩阵和运行时证据标准化。
|
||
**Depends on**: Phase 8
|
||
**Requirements**: AUTO-01, AUTO-02, AUTO-03
|
||
**Success Criteria** (必须为 TRUE):
|
||
1. native reflowable 至少覆盖打开书籍、分页完成、搜索命中、主题/字号切换、位置恢复
|
||
2. 样本矩阵持续覆盖复杂图文、代码/表格/列表、附件密集、fixed/interactive WebKit、TXT 五类路径
|
||
3. 每项核心能力都具备可重复证据：日志、断言、诊断摘要、UI 自动化步骤或稳定人工检查清单
|
||
**Plans**: 2 plans
|
||
|
||
Plans:
|
||
- [ ] 09-01：建立 native reflowable 关键交互自动化或稳定半自动化验证
|
||
- [ ] 09-02：扩展样本矩阵并统一证据标准、日志摘要与 rerun 清单
|
||
|
||
Cross-cutting constraints:
|
||
- 不为验证再造第二套 demo shell
|
||
- 优先复用 `ReadViewDemo`、现有日志和诊断输出
|
||
- WebKit / TXT 路径仍必须留在矩阵内，不能只测 native reflowable
|
||
|
||
## Progress
|
||
|
||
| Phase | Plans Complete | Status | Completed |
|
||
|---|---:|---|---|
|
||
| 6. 页面几何与交互命中层 | 0/3 | Not started | - |
|
||
| 7. WXRead 自定义属性闭环 | 0/3 | Not started | - |
|
||
| 8. 分页质量、缓存与性能采样 | 0/3 | Not started | - |
|
||
| 9. 自动化回归与证据标准化 | 0/2 | Not started | - |
|