ReadViewSDK/.planning/REQUIREMENTS.md

需求：ReadViewSDK v1.1

定义日期： 2026-05-22
核心价值： 稳定可用的 EPUB/TXT 阅读体验

v1.1 需求（本次范围）

页面级布局与几何能力

• LAYOUT-01：为 native text 分页结果补齐页面级 layout frame 几何查询能力，至少包括字符串范围矩形查询、矩形反查文本范围、截断检测、命中定位所需的基础 API
• LAYOUT-02：阅读器侧的高亮、搜索命中、选区、点击定位等行为应优先建立在 layout frame 几何能力之上，而不是继续强依赖 UITextView 的黑盒行为
• LAYOUT-03：页面级模型需要继续保留并兼容 pageStartOffset、pageEndOffset、fragmentOffsets、RDEPUBTextOffsetRangeInfo 等既有语义

WXRead 自定义属性闭环

• ATTR-01：补齐一条从章节 HTML / CSS 到 NSAttributedString 再到分页器的自定义属性闭环，至少覆盖 avoidPageBreakInside、pageBreakBefore、pageBreakAfter、pageRelate
• ATTR-02：图片与附件相关排版需要支持类似 wr-vertical-center-style 的语义输入，并在分页 / 展示阶段保留可消费的信息
• ATTR-03：复杂块元素至少要能区分代码块、表格、列表、引用块等类别，以支持更精细的分页边界控制与诊断

分页质量与性能收敛

• QUAL-01：为 layout frame / 分页结果增加缓存机制，避免同一章节在相同视口与排版配置下重复全量排版
• QUAL-02：复杂图文章节的分页质量要进一步提升，减少不合理断页、孤行/寡行、图片前后留白异常、代码块/表格被粗暴截断等问题
• QUAL-03：图片与附件的尺寸策略、暗色模式适配、页面背景类信息需要具备可验证的处理规则，而不是依赖默认 DTCoreText 行为
• QUAL-04：分页深化后不能显著恶化首屏时间、重分页耗时或交互流畅度；若无法立即建立硬性指标，至少要输出稳定的诊断与采样数据

稳定性与自动化验证

• AUTO-01：建立覆盖 native reflowable 主路径的自动化回归能力，至少覆盖打开书籍、分页完成、搜索命中、主题/字号切换、位置恢复
• AUTO-02：样本矩阵需要持续覆盖复杂图文、代码/表格/列表、附件密集、fixed/interactive WebKit、TXT 五类路径
• AUTO-03：每项核心能力都应尽量附着到可重复证据：日志、断言、诊断摘要、UI 自动化步骤或稳定的人工检查清单

Future Requirements

后续增强（暂不进入 v1.1 roadmap）

• PERF-01：建立更严格的性能基线与持续采样门槛（首屏时间、重分页时间、内存峰值）
• GEOM-01：如果几何层成熟，进一步评估是否需要逐步替换 UITextView 展示层
• INTL-01：更完整的国际化排版增强（RTL、断字、多语种高级回退）

Out of Scope

功能	原因
重写或替换 RDReaderView 翻页容器	本次继续只深化 native reflowable 内核与页面几何能力
复刻 WXRead 的完整业务层能力（翻译/双语、免费试读、网络协议、DRM）	这些属于业务闭环，不是当前 SDK 与 WXRead 的主要技术差距
将 fixed layout / interactive EPUB 改为原生渲染	仍保持 WKWebView 路径以控制风险
直接拷贝读书私有 CSS / JS / 私有实现代码	仅参考设计思路，不直接搬运私有实现
一次性完整重写成自绘 WRPageView 等价体系	风险过大，优先通过 layout frame 几何层与局部 reader 接线演进

Traceability

Requirement	Phase	Status
LAYOUT-01	Phase 6	Pending
LAYOUT-02	Phase 6	Pending
LAYOUT-03	Phase 6	Pending
ATTR-01	Phase 7	Pending
ATTR-02	Phase 7	Pending
ATTR-03	Phase 7	Pending
QUAL-01	Phase 8	Pending
QUAL-02	Phase 8	Pending
QUAL-03	Phase 8	Pending
QUAL-04	Phase 8	Pending
AUTO-01	Phase 9	Pending
AUTO-02	Phase 9	Pending
AUTO-03	Phase 9	Pending

Coverage:

• v1.1 requirements: 13 total
• Mapped to phases: 13
• Unmapped: 0 ✓

---

Requirements defined: 2026-05-22
Last updated: 2026-05-22 after v1.1 milestone initialization