# 需求：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*