269 lines
10 KiB
Markdown
269 lines
10 KiB
Markdown
# Phase 1 Strategy: Direct Refactor Entry Points for the Existing Reflowable Engine
|
||
|
||
**Phase:** 01-current-engine-boundaries
|
||
**Date:** 2026-05-21
|
||
**Purpose:** 把“旧引擎直接演进”的切入点、顺序和硬边界固定下来，供 Phase 2/3 实施使用。
|
||
|
||
## 1. Strategy in One Sentence
|
||
|
||
后续实现应保留现有 `RDURLReaderController -> RDEPUBReaderController -> RDReaderView` 外层契约不变，把升级集中在 `EPUBTextRendering` 内部：先增强 typesetter / CSS 分层，再增强页面级属性与分页语义，最后回接并验证 reader 兼容能力。
|
||
|
||
## 2. Why the Strategy Is “Direct Evolution,” Not “Parallel Engine”
|
||
|
||
根据当前源码审计，native `.textReflowable` 主路径已经具备以下骨架：
|
||
|
||
- `RDEPUBParser.readingProfile()` 已经把普通 reflowable EPUB 分到 `.textReflowable`
|
||
- `RDEPUBReaderController.paginatePublication()` 已经把 `.textReflowable` 接到 `RDEPUBTextBookBuilder`
|
||
- `RDEPUBDTCoreTextRenderer` 已经承担章节 HTML -> `NSAttributedString`
|
||
- `RDEPUBTextPaginationSupport.ss_pageRanges(size:)` 已经承担最小可用分页
|
||
- `RDEPUBTextContentView` 与 `RDReaderView` 已经承担原生页面展示
|
||
|
||
因此，新增第二套原生引擎只会制造双轨维护问题：
|
||
|
||
- duplicate reader integration
|
||
- duplicate location/highlight/search transport
|
||
- duplicate pagination data model
|
||
- duplicate regression matrix
|
||
|
||
正确策略是：**沿着现有 native text 路径升级内部能力，而不是复制一条新路径。**
|
||
|
||
## 3. Target Capability Map: WXRead -> Current Touchpoints
|
||
|
||
下表把 WXRead 目标能力映射到当前仓库中真正应该改动的触点。
|
||
|
||
| WXRead-style capability | Current touchpoint | Target phase | Why this file is the right entry point |
|
||
|-------------------------|-------------------|--------------|----------------------------------------|
|
||
| 五层 CSS 级联（default / replace / dark / epub / user） | `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift` | Phase 2 | 当前 renderer 已拥有 HTML、baseURL、style 三要素，是升级 stylesheet pipeline 的最直接入口。 |
|
||
| HTML 预处理与资源引用兜底 | `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` 或新建 `RDEPUBWXReadHTMLPreprocessor.swift` | Phase 2 | builder 已掌握章节原始 HTML 与章节 baseURL，适合做 `<link>` CSS 内联或章节级规范化。 |
|
||
| 统一 stylesheet 生成器 | 新建 `Sources/RDReaderView/EPUBTextRendering/RDEPUBWXReadStyleSheetBuilder.swift` | Phase 2 | 避免把 layered CSS 逻辑塞进 renderer，使样式层可测试、可替换、可调试。 |
|
||
| 页面级 attributed string 元数据 | `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`、`RDEPUBTextChapter`、`RDEPUBTextPage` | Phase 3 | 当前 page model 只有范围和 offset，后续页面语义需要在这里承接。 |
|
||
| 更强分页语义（块级避免断页、图片/附件边界） | `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift` | Phase 3 | 当前 `ss_pageRanges(size:)` 是唯一分页核心，增强必须从这里开始。 |
|
||
| Layout frame / layouter 责任分离 | 新建 `EPUBTextRendering` 内部 layouter/frame 类型 | Phase 3 | 不应把复杂页面布局逻辑继续堆在 `RDEPUBReaderController` 或 content view。 |
|
||
| Reader 兼容性回接（位置、高亮、搜索、重分页） | `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift` | Phase 4 | 这是现有 reader state 的唯一编排点，适合接回而不是承担新排版实现。 |
|
||
|
||
## 4. Phase 2 Entry Strategy: Upgrade Typesetter First
|
||
|
||
Phase 2 的目标不是“立刻实现 WXRead 全量布局器”，而是把渲染输入从“简单 DTCoreText options”升级为“WXRead 风格 typesetter”。
|
||
|
||
### 4.1 Primary code touchpoints
|
||
|
||
优先改动：
|
||
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift`
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`
|
||
- 新建 `Sources/RDReaderView/EPUBTextRendering/RDEPUBWXReadStyleSheetBuilder.swift`
|
||
|
||
### 4.2 Concrete target state
|
||
|
||
Phase 2 应把当前 renderer 升级到以下状态：
|
||
|
||
1. 合成 layered CSS
|
||
- SDK default CSS
|
||
- SDK replace/enhancement CSS
|
||
- dark theme override
|
||
- EPUB embedded CSS
|
||
- user CSS from `RDEPUBTextRenderStyle`
|
||
|
||
2. 使用章节目录 `baseURL`
|
||
- 保留当前 baseURL 计算方式
|
||
- 确保图片与章节级 CSS 相对路径继续可解析
|
||
|
||
3. 维持 fragment marker / fragment offset 体系
|
||
- 不能破坏 `injectFragmentMarkers`
|
||
- 不能破坏 `extractFragmentOffsets`
|
||
|
||
4. 不改 reader integration surface
|
||
- `RDEPUBTextBookBuilder.build(...)` 的高层职责保持不变
|
||
- `RDEPUBReaderController.paginatePublication()` 的分支结构保持不变
|
||
|
||
### 4.3 Why Phase 2 should stop there
|
||
|
||
如果在 Phase 2 就同时引入：
|
||
|
||
- 全新分页器
|
||
- 大量新 page model
|
||
- reader compatibility 回接修复
|
||
|
||
就会把“渲染输入提升”与“分页语义重构”混为一体，定位回归原因会非常困难。Phase 2 应该先把章节渲染输入变得更接近 WXRead，再观察真实样本书暴露的分页问题。
|
||
|
||
## 5. Phase 3 Entry Strategy: Upgrade Pagination Semantics
|
||
|
||
Phase 3 才是“把 pageRanges 模式升级为更强页面语义”的阶段。
|
||
|
||
### 5.1 Primary code touchpoints
|
||
|
||
优先改动：
|
||
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift`
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`
|
||
- `RDEPUBTextPage`
|
||
- `RDEPUBTextChapter`
|
||
- 必要时新建内部 layouter/layout-frame 类型
|
||
|
||
### 5.2 Concrete target state
|
||
|
||
Phase 3 应逐步实现：
|
||
|
||
1. 当前 range-only page model -> richer page metadata
|
||
- block boundaries
|
||
- image/attachment semantics
|
||
- page-level layout markers
|
||
- future page background or page-style metadata hooks
|
||
|
||
2. 当前 visible-range slicing -> stronger pagination semantics
|
||
- avoid page break inside for large blocks
|
||
- image and attachment boundary handling
|
||
- better page edge control than pure `CTFrameGetVisibleStringRange`
|
||
|
||
3. 保留 offset continuity
|
||
- `pageStartOffset`
|
||
- `pageEndOffset`
|
||
- chapter-level text continuity
|
||
- fragment offset compatibility
|
||
|
||
### 5.3 What not to do in Phase 3
|
||
|
||
不要把分页器升级等同于：
|
||
|
||
- 改写 `RDReaderView`
|
||
- 改写 fixed/interactive 渲染链路
|
||
- 绕开 `RDEPUBTextBook` 直接输出新的 UI 专用模型
|
||
|
||
Phase 3 的正确做法是：让更强的分页语义仍然最终落到现有 book/chapter/page 契约上，必要时是“扩展”这些模型，而不是抛弃它们。
|
||
|
||
## 6. Compatibility Surface That Must Be Preserved
|
||
|
||
以下能力必须视为后续 phase 的硬约束：
|
||
|
||
### 6.1 `WKWebView` retention boundary
|
||
|
||
保留不动：
|
||
|
||
- `webFixedLayout`
|
||
- `webInteractive`
|
||
- `RDEPUBWebView+FixedLayout.swift`
|
||
- `RDEPUBWebView+Reflowable.swift`
|
||
- `RDEPUBPaginator.swift` 所属的 WebView 测量职责
|
||
|
||
原因：
|
||
|
||
- Fixed layout 依赖 spread HTML 表示
|
||
- interactive EPUB 依赖 JS/bridge/iframe/form/multimedia 支持
|
||
- 它们不属于 native reflowable 的目标问题域
|
||
|
||
### 6.2 Stable reader container
|
||
|
||
`RDReaderView` 与现有翻页模式保持不变：
|
||
|
||
- page curl
|
||
- horizontal scroll
|
||
- vertical scroll
|
||
- page direction
|
||
- dual-page / cover page behavior
|
||
- orientation-driven container refresh
|
||
|
||
原因：
|
||
|
||
- 它是 native text 与 web content 的共同外壳
|
||
- 改它会同时扩大 regression surface
|
||
|
||
### 6.3 Reader capability continuity
|
||
|
||
以下链路必须继续通过现有 `RDEPUBReaderController` 契约工作：
|
||
|
||
- 阅读位置恢复
|
||
- `RDEPUBLocation` 映射
|
||
- 高亮 / 选区
|
||
- 搜索结果定位
|
||
- 字号/行高/主题切换后的重分页
|
||
|
||
这要求后续 phase 继续维护：
|
||
|
||
- `fragmentOffsets`
|
||
- `pageStartOffset`
|
||
- `pageEndOffset`
|
||
- `RDEPUBTextOffsetRangeInfo`
|
||
- `RDEPUBTextContentView` 所依赖的页内容语义
|
||
|
||
## 7. Recommended Implementation Sequence
|
||
|
||
建议执行顺序如下：
|
||
|
||
### Step 1: Strengthen renderer / typesetter
|
||
|
||
目标：
|
||
|
||
- layered CSS
|
||
- HTML preprocessing
|
||
- stable resource resolution
|
||
- normalized style injection
|
||
|
||
原因：
|
||
|
||
- 先把“输入质量”提升，才能判断现有分页问题到底是样式输入问题还是分页算法问题
|
||
|
||
### Step 2: Strengthen pagination semantics
|
||
|
||
目标：
|
||
|
||
- richer page metadata
|
||
- avoid-break logic
|
||
- attachment-aware page boundaries
|
||
|
||
原因：
|
||
|
||
- 在更稳定的 attributed string 输入上做分页升级，结果更可解释
|
||
|
||
### Step 3: Reconnect and validate reader capability chain
|
||
|
||
目标：
|
||
|
||
- 位置映射
|
||
- highlight/search
|
||
- repagination after settings change
|
||
|
||
原因：
|
||
|
||
- 这一步应基于已经稳定的 renderer + page model，而不是把所有问题都混在一起排查
|
||
|
||
## 8. File-Level Recommendations for Next Phases
|
||
|
||
### 8.1 Files Phase 2 should read first
|
||
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift`
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`
|
||
- `Doc/WXRead/analysis/EPUB渲染管线详解.md`
|
||
- `Doc/WXRead/analysis/DTCoreText自定义修改分析.md`
|
||
- `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md`
|
||
|
||
### 8.2 Files Phase 3 should read first
|
||
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift`
|
||
- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift`
|
||
- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift`
|
||
- `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md`
|
||
- `Doc/WXRead/analysis/02_符号恢复与核心算法.md`
|
||
|
||
### 8.3 Files Phase 4 should read first
|
||
|
||
- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift`
|
||
- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift`
|
||
- `Sources/RDReaderView/RDReaderView.swift`
|
||
- Any Phase 2/3 summaries produced from the pagination work
|
||
|
||
## 9. Non-Goals and Refusal Rules
|
||
|
||
后续 phase 默认拒绝以下方向，除非 roadmap 被显式修改：
|
||
|
||
1. 把 Fixed Layout EPUB 改成 native renderer
|
||
2. 把 interactive EPUB 改成 native renderer
|
||
3. 新建并长期维护第二套 reflowable 原生引擎
|
||
4. 修改 `RDReaderView` 的外部容器契约
|
||
5. 在还没完成 Phase 2 renderer 升级前，就全面重写 reader integration
|
||
|
||
## 10. Final Strategy Decision
|
||
|
||
最终策略决议如下：
|
||
|
||
> Phase 2 先把 `RDEPUBDTCoreTextRenderer` 从“简单 DTCoreText options”升级成“WXRead 风格 typesetter + layered CSS pipeline”；Phase 3 再升级 `RDEPUBTextPaginationSupport`、`RDEPUBTextBookBuilder` 与 page model 的页面语义；Phase 4 才处理 reader capability 链路的兼容回接。整个过程中，`WKWebView` 边界和 `RDReaderView` 容器契约都保持不变。
|