# 架构分析：WXRead 参考 vs ReadViewSDK 当前

**分析日期：** 2026-05-23
**分析基础：** `Doc/WXRead/decompiled-doc.md`、`Doc/WXRead/resources-doc.md`、`Doc/WXRead/读书EPUB阅读器实现架构.md`
**状态：** Decisions captured

---

<domain>
## 分析范围

对比读书 (WeRead v10.0.3) 逆向架构与当前 ReadViewSDK 项目的结构性差距，聚焦四大方向：分页引擎集成、CSS 处理、渲染架构、字体系统。

读书 EPUB 渲染的核心架构特征：
- Path A (EPUB): 纯 CoreText 渲染 — `WRPageView.drawRect:` → `CTFrameDraw`，不用 UITextView/UILabel
- 4 级语义断页：`WRCoreTextLayouter` + `WRCoreTextLayoutFrame` (语义边界 > 附件边界 > 块边界 > 帧限制)
- 5 层 CSS 级联：`default.css < replace.css < dark.css < EPUB 内嵌 < 用户设置`
- 字符级位置精度：`WREpubPositionConverter` (fileIndex, row, column) ↔ 全局字符偏移
- 标注直接在 CTFrame 层叠加绘制，搜索高亮同理

</domain>

<decisions>
## 已决事项

### Area 1: 分页引擎集成（P0）

| 决策 | 说明 |
|------|------|
| 将 `RDEPUBTextLayouter` 集成到 `RDEPUBTextBookBuilder` | 内部调用 `rd_paginatedFrames(size:)` 替代旧的 `ss_pageRanges(size:)`，外部 API 不变 |
| 分页元数据暴露到 `RDEPUBTextPage` | 新增 `metadata: RDEPUBTextPageMetadata` 字段（含 breakReason/blockKinds/semanticHints），对外暴露分页质量数据 |
| `RDEPUBTextChapterPaginationDiagnostic` 增强 | 透传 RDEPUBTextLayoutFrame 的诊断信息 |
| 分页缓存 | 按 `bookID + fontSize + lineHeightMultiple + contentInsets` 生成缓存 key，缓存完整 `RDEPUBTextBook` 到磁盘 |

### Area 2: CSS `<link>` 外部样式表处理（P0）

| 决策 | 说明 |
|------|------|
| 预处理内联 CSS | 渲染前扫描 HTML 中 `<link>` 标签，从 EPUB 解压目录读取 CSS 内容，注入 `<style>` 替换 `<link>` |
| 实现 5 层 CSS 级联 | `RDEPUBTextStyleSheetBuilder` 实现 `default < replace < dark < epub-embedded < user` 五层合并，使用已定义的 `RDEPUBTextStyleSheetPackage`/`RDEPUBTextStyleSheetLayer` |

### Area 3: CoreText 直接绘制迁移（P1 — 大架构变更）

| 决策 | 说明 |
|------|------|
| 直接替换 UITextView | 新实现完全替代 `RDEPUBTextContentView`，不保留 UITextView 渐进迁移路径 |
| CoreText 原生选区 | `CTLineGetStringIndexForPosition` 坐标 hit test + 自定义选区绘制，不依赖 UITextView 选区 |
| 标注渲染：CGContext 装饰层 | drawRect 中 CTFrameDraw 绘制文本后，遍历当前页 RDEPUBHighlight，CGContext 绘制背景矩形（highlight）/ 下划线（underline） |
| 搜索高亮：CGContext 叠加绘制 | 不修改底层 attributedString，在 drawRect 中根据匹配范围直接绘制高亮背景 |

### Area 4: 字体系统（P1 — 延迟到后续版本）

| 决策 | 说明 |
|------|------|
| 方案：内嵌固定字体集 | SDK bundle 内嵌常用中文字体，Settings 面板新增字体选择。不做 CDN 动态下载 |
| 本版本范围：暂不做 | 字体切换功能延迟到后续迭代 |

</decisions>

<canonical_refs>
## 关键参考文档

**WXRead 逆向参考（必须阅读）：**
- `Doc/WXRead/decompiled-doc.md` — 44 个逆向文件的职责说明
- `Doc/WXRead/resources-doc.md` — CSS/JS 资源文件清单与职责
- `Doc/WXRead/读书EPUB阅读器实现架构.md` — 双渲染引擎架构总览
- `Doc/WXRead/decompiled/WRCoreTextLayoutFrame.m` — 跨页避让、装饰元素、搜索高亮实现
- `Doc/WXRead/decompiled/WRCoreTextLayouter.m` — 4 级语义断页配置
- `Doc/WXRead/decompiled/WRPageView.m` — CoreText 直接绘制参考
- `Doc/WXRead/decompiled/WREpubTypesetter.m` — CSS 级联合并参考
- `Doc/WXRead/resources/css/replace.css` — 5 层 CSS 参考

**当前项目代码（已有的基础设施）：**
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift` — 已实现 4 级语义断页，待集成
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift` — 帧模型，含 breakReason/semanticHints
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift` — 已定义 `RDEPUBTextStyleSheetPackage`/`RDEPUBTextStyleSheetLayer`，未完全使用
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` — 当前可能仍在用旧的 `ss_pageRanges`
- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift` — UITextView 实现，待替换为 CoreText

</canonical_refs>

<roadmap_mapping>
## 与现有 Roadmap 的映射

| 决策 | 对应 Phase | 说明 |
|------|-----------|------|
| RDEPUBTextLayouter 集成 | Phase 8 (08-02) | 分页质量改善的核心 |
| 分页元数据暴露 | Phase 8 (08-03) | 分页诊断输出的一部分 |
| 分页缓存 | Phase 8 (08-01) | 缓存键与失效策略 |
| CSS `<link>` 内联 | Phase 7 范畴外 | 当前 Roadmap 未覆盖，需新增 phase 或合并到 Phase 8 |
| 5 层 CSS 级联 | Phase 7 + Phase 8 | Phase 7 已完成属性闭环，级联是后续增强 |
| **CoreText 直接绘制** | **v1.2 或 v2.0** | **超出 v1.1 Roadmap，需要独立 milestone** |
| CoreText 原生选区 | 随 CoreText 迁移 | 同上 |
| 标注 CGContext 绘制 | 随 CoreText 迁移 | 同上 |
| 字体系统 | 未来版本 | 延迟 |

**关键发现：** CoreText 直接绘制迁移是最大的架构变更，超出 v1.1 的增量改进范围。建议作为 v1.2 独立 milestone 规划。

</roadmap_mapping>

<deferred>
## 延迟事项

- **字体系统**：内嵌固定字体集方案已决，延迟到后续版本
- **位置精度提升**（字符级锚点）：P2，与 CoreText 迁移关联
- **章节数据模型内聚**（WRChapterData 模式）：P2，架构清晰度改进
- **TTS / DRM / Pencil / 多栏排版**：P3，独立功能模块
- **翻页控制器健壮性**（UIPageViewController crash patch）：P2，当前未遇到相关崩溃

</deferred>

---

*分析范围：WXRead 逆向文档 → ReadViewSDK 架构差距*
*产出：4 个 Area、14 项决策、1 项延迟*