# Phase 8: 分页质量、缓存与性能采样 - Context

**Gathered:** 2026-05-23
**Updated:** 2026-05-23 (research corrected: D-01/D-02/D-04/D-05 already implemented)
**Status:** Ready for planning
**Source:** ARCHITECTURE-CONTEXT.md + REQUIREMENTS.md (QUAL-01 ~ QUAL-04) + 08-RESEARCH.md

---

<domain>
## Phase Boundary

Phase 8 在 Phase 6（页面几何）和 Phase 7（自定义属性闭环）之上，解决三个问题：

1. **缓存**：相同视口 + 排版配置下，同一章节不重复全量排版 (QUAL-01)
2. **分页质量**：复杂图文章节减少粗暴截断、孤行/寡行、图片留白异常 (QUAL-02, QUAL-03)
3. **性能诊断**：输出稳定的采样数据，确保不出现明显退化 (QUAL-04)

本阶段**不**涉及 CoreText 直接绘制迁移（v1.2+），**不**涉及字体系统。
实现时可直接参考读书 (WXRead) 的对应实现模式。

### 已完成的能力（研究发现）

以下能力在之前的 Phase 中已经实现，Phase 8 不需要重新实现：

- **D-01 分页引擎集成**: `RDEPUBTextBookBuilder.build()` 已调用 `content.rd_paginatedFrames(size:)`（非旧的 `ss_pageRanges`）
- **D-02 分页元数据暴露**: `RDEPUBTextPageMetadata` 已定义并包含 breakReason/blockKinds/semanticHints
- **D-04 CSS `<link>` 内联**: 已在渲染前处理 `<link>` 标签
- **D-05 5 层 CSS 级联**: `RDEPUBTextStyleSheetPackage`/`RDEPUBTextStyleSheetLayer` 已在使用

</domain>

<decisions>
## Implementation Decisions

### D-01: 分页缓存 — RDEPUBTextBook 序列化 [P0, QUAL-01]
按 `bookID + fontSize + lineHeightMultiple + contentInsets` 生成缓存 key，将完整 `RDEPUBTextBook` 序列化到磁盘。
- **WXRead 参考:** `WRChapterPageCount.currentCacheKeyWithBookId:` 按排版设置缓存
- **关键文件:** `RDEPUBTextBookBuilder.swift`，新增 `RDEPUBTextBookCache.swift`
- **技术决策:**
  - 缓存 key: `SHA256("\(bookID)_\(fontSize)_\(lineHeightMultiple)_\(contentInsets)")` + schema version
  - 存储格式: `NSKeyedArchiver`（`NSAttributedString` 支持 `NSCoding`，`NSRange` 同理）
  - 需运行时验证 DTCoreText 自定义属性在 `NSKeyedArchiver` 下的持久性
  - 失效策略: 参数变化自动失效 + schema version bump 强制失效
  - 存储位置: `Library/Caches` 子目录

### D-02: 分页质量增强 — 避让规则执行 [P0, QUAL-02]
`RDEPUBTextLayouter` 中 `avoidPageBreakInside` 的语义标记需要实际执行避让（当前仅有标记无行为），并增加孤行/寡行控制。
- **WXRead 参考:** `WRCoreTextLayoutFrame.avoidPageBreakInsideByRemovingLastLinesIfNeeded` — CSS `avoid-page-break-inside` 实现
- **关键文件:** `RDEPUBTextLayouter.swift`、`RDEPUBTextLayoutFrame.swift`
- **技术决策:**
  - `avoidPageBreakInside`: 检测 block 最后 1-2 行被切到下一页时，将整个 block 移到下一页
  - 孤行控制: 页首不允许出现段落最后一行（orphan），页尾不允许出现段落第一行（widow）
  - 增加 `RDEPUBTextLayoutConfig` 结构体封装分页配置（孤行/寡行阈值等），或先硬编码合理默认值

### D-03: 图片/附件处理规则 [P1, QUAL-03]
图片尺寸策略、暗色模式适配、页面背景类信息有明确处理规则和诊断证据。
- **WXRead 参考:** `wr-vertical-center-style`（图片垂直居中）、`DTPageBreakInsideAvoid`（断页避让）
- **关键文件:** `RDEPUBTextLayoutFrame.swift`、`RDEPUBTextRendererSupport.swift`、`RDEPUBDTCoreTextRenderer.swift`
- **技术决策:**
  - 图片 fit: 超过页面高度的图片按比例缩放到页面内，不跨页
  - 图片居中: 附件类 block 默认垂直居中处理
  - 暗色模式: 图片在暗色模式下保留原始颜色（不反色），但为纯文本装饰元素提供适配
  - 诊断: 每个 attachment block 输出尺寸、placement、是否触发缩放

### D-04: 性能采样与诊断输出 [P1, QUAL-04]
分页深化后不显著恶化首屏时间、重分页耗时或交互流畅度；输出稳定采样数据。
- **关键文件:** `RDEPUBTextBookBuilder.swift`
- **技术决策:**
  - 采样点: 每章渲染耗时、每章分页耗时、全书构建总耗时、缓存命中/未命中
  - 输出方式: `RDEPUBTextBookBuilder` 回调中新增 `buildDiagnostics` 字段，包含耗时和缓存状态
  - 不引入外部性能监控库，使用 `CFAbsoluteTimeGetCurrent()` 采样

### Claude's Discretion
- 缓存存储的线程安全策略（串行队列 vs 锁）
- `RDEPUBTextLayoutConfig` 是新增结构体还是扩展已有类型
- 性能诊断的阈值告警（可选，初期仅输出数据不告警）

### 强制约束：编译验证
每个 task 代码编写完成后，**必须**通过 XcodeBuildMCP 工具执行编译验证，确认无编译错误后方可标记 task 完成。若有编译问题需立即修复并重新验证。
- 工具: XcodeBuildMCP (`build_sim` / `run_build_sim`)
- 配置: workspace = `ReadViewDemo/ReadViewDemo.xcworkspace`, scheme = `ReadViewDemo`, simulator = `iPhone 17 Pro`
- 流程: 代码修改 → XcodeBuildMCP build → 有错误则修复 → 重新 build → 通过后继续

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Phase 8 核心文件
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` — 书籍构建器，已调用 rd_paginatedFrames
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift` — 分页支持
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift` — CoreText 分页引擎，4 级语义断页
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayoutFrame.swift` — 帧模型
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift` — 渲染协议、样式表类型
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift` — DTCoreText 渲染实现
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRendererSupport.swift` — 片段标记、属性标准化

### WXRead 逆向参考（实现时可直接参考）
- `Doc/WXRead/decompiled-doc.md` — 44 个逆向文件的职责说明
- `Doc/WXRead/resources-doc.md` — CSS/JS 资源文件清单与职责
- `Doc/WXRead/读书EPUB阅读器实现架构.md` — 双渲染引擎架构总览

### 架构文档
- `.planning/ARCHITECTURE-CONTEXT.md` — 4 Area 决策总览
- `Doc/架构对比分析_WXRead_vs_ReadViewSDK.md` — 10 维度对比
- `08-RESEARCH.md` — 研究产出（本目录下）

### 前置 Phase 成果
- Phase 6 SUMMARY: 页面几何与交互命中层
- Phase 7 SUMMARY: 自定义属性闭环（avoidPageBreakInside/pageBreakBefore/pageBreakAfter/pageRelate 已注入 attributedString）

</canonical_refs>

<specifics>
## Specific Ideas

### 缓存 key 设计
```
cacheKey = SHA256("\(bookID)_\(fontSize)_\(lineHeightMultiple)_\(contentInsets.top)_\(contentInsets.left)_\(contentInsets.bottom)_\(contentInsets.right)_v\(schemaVersion)")
```
- schemaVersion = 1，代码变更导致缓存格式不兼容时 bump
- 失效条件：参数变化自动失效 + schema version bump 强制失效
- 存储：Library/Caches/RDEPUBTextBookCache/ 目录

### 性能采样点
- 每章渲染耗时（DTHTMLAttributedStringBuilder）
- 每章分页耗时（CTFramesetter pagination）
- 全书构建总耗时
- 缓存命中/未命中计数

### avoidPageBreakInside 执行策略
```
当 CTFrame 可见范围尾部落在 avoidPageBreakInside block 内部时：
1. 向前扫描找到 block 起始位置
2. 将分页点移到 block 起始之前
3. 将整个 block 推到下一页
```

</specifics>

<deferred>
## Deferred Ideas

- **CoreText 直接绘制迁移**: v1.2/v2.0，超出本阶段范围
- **字体系统**: 内嵌固定字体集，后续版本
- **字符级位置精度**: P2，与 CoreText 迁移关联
- **章节数据模型内聚**: P2，独立重构
- **TTS / DRM / Pencil / 多栏排版**: P3，独立功能模块
- **NSKeyedArchiver 对 DTCoreText 属性持久性验证**: 需运行时测试，若失败则降级为 decomposed JSON 策略

</deferred>

---

*Phase: 08-pagination-quality-cache-performance*
*Context gathered: 2026-05-23*
*Updated after research: D-01/D-02/D-04/D-05 confirmed already implemented*