4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
46fa9fceff
ReadViewSDK/.planning/ROADMAP.md

5.8 KiB
Raw Blame History

路线图：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 -