# 需求：ReadViewSDK v1.1（WXRead 深化对齐）

**定义日期：** 2026-05-22  
**核心价值：** 在已完成的 reflowable EPUB 原生化基础上，继续补齐 WXRead 风格的页面级排版能力、阅读交互精度与回归可验证性。

## 背景

v1 已完成以下主目标：

- reflowable EPUB 已具备 WXRead 风格的五层 CSS 组织与章节级 render context
- 分页器已具备 block / attachment 边界感知与页面元数据输出
- reader 主流程、高亮、搜索、位置恢复、主题/字号/行高重分页已接回
- fixed layout / interactive EPUB 继续保持 `WKWebView` 路径

与 `Doc/WXRead/analysis/` 对照后，当前主要差距已不在“是否走原生管线”，而在以下深化能力：

- 页面级 layout frame 的几何查询与绘制能力不足
- 自定义 CSS / attributed string 属性到分页器的闭环仍不完整
- 分页质量、缓存、复杂块元素规则与自动化验证仍弱于 WXRead

## 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 自动化步骤或稳定的人工检查清单

## 成功标准

以下结论必须全部为 TRUE：

1. native reflowable 路径拥有可复用的页面几何查询能力，reader 交互不再主要依赖 `UITextView` 推断页面几何
2. 至少一组 WXRead 风格自定义分页属性已形成端到端闭环，并对复杂块元素分页产生可见收益
3. 同一批复杂样本在新一轮分页器深化后，分页质量优于当前 v1 完成态，而不是仅增加结构复杂度
4. 自动化或半自动化验证覆盖到 native text 的关键交互，不再主要依赖单次手工 spot check
5. fixed layout、interactive EPUB、TXT 和既有 `RDReaderView` 翻页容器不回归

## 非目标（本次明确不做）

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

## 风险与约束

- `RDReaderView`、现有 page curl / horizontal / vertical 交互逻辑继续视为稳定容器契约
- `RDEPUBReaderController` / `RDURLReaderController` 公开入口必须保持兼容
- 所有分页深化都必须保留 offset-based 兼容语义，避免破坏现有高亮、搜索、恢复位置数据
- 若要引入自绘或替换 `UITextView` 页面展示，需要以“先引入几何能力、再最小替换”的顺序推进
- 若性能采样显示分页深化明显拖慢主流程，应优先做缓存与局部优化，而不是继续扩展特性面

## 建议优先级

1. `LAYOUT-*`：先补 layout frame 几何能力
2. `ATTR-*`：再补自定义属性到分页器闭环
3. `QUAL-*`：随后做分页质量与缓存收敛
4. `AUTO-*`：最后把运行时验证补成自动化或稳定半自动化

## 候选 Phase 映射

| 需求 | 建议 Phase | 说明 |
|---|---:|---|
| LAYOUT-01 | Phase 6 | layout frame 几何 API 与截断检测 |
| LAYOUT-02 | Phase 6 | reader 交互从 `UITextView` 推断迁移到几何层 |
| LAYOUT-03 | Phase 6 | 保持 offset / fragment 兼容契约 |
| ATTR-01 | Phase 7 | 自定义分页属性闭环 |
| ATTR-02 | Phase 7 | 图片 / 附件布局语义 |
| ATTR-03 | Phase 7 | block type 分类与分页规则 |
| QUAL-01 | Phase 8 | layout frame / pagination cache |
| QUAL-02 | Phase 8 | 复杂样本分页质量提升 |
| QUAL-03 | Phase 8 | 图片暗色与页面背景类规则 |
| QUAL-04 | Phase 8 | 诊断与性能采样 |
| AUTO-01 | Phase 9 | native reflowable 自动化回归 |
| AUTO-02 | Phase 9 | 样本矩阵扩展 |
| AUTO-03 | Phase 9 | 证据标准化 |

**覆盖统计：**
- v1.1 需求总数：13
- 页面级布局：3
- 属性闭环：3
- 质量与性能：4
- 自动化验证：3

---
*Requirements defined: 2026-05-22*  
*Last updated: 2026-05-22 after WXRead gap analysis*