docs(01-02): complete refactor entry strategy plan

2026-05-21 21:58:52 +08:00 · 2026-05-21 21:58:52 +08:00 · 6d7f02debd
commit 6d7f02debd
parent cc2573552c
3 changed files with 358 additions and 3 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -6,7 +6,7 @@

 ## Phases

- [ ] **Phase 1: 对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力
+- [x] **Phase 1: 对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力 (completed 2026-05-21)
 - [ ] **Phase 2: 重构 typesetter 与 CSS 分层** - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强
 - [ ] **Phase 3: 重构属性体系与复杂分页器** - 引入页面级 attributed string 元数据与更强的分页/布局能力
 - [ ] **Phase 4: 接回现有 reader 能力链路** - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作
@ -27,7 +27,7 @@

 Plans:
 - [x] 01-01：审计当前 `.textReflowable` 路径（`RDEPUBDTCoreTextRenderer` / `RDEPUBTextBookBuilder` / `RDEPUBTextPaginationSupport` / `RDEPUBTextContentView`）
- [ ] 01-02：结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路
+- [x] 01-02：结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路

 ### Phase 2: 重构 typesetter 与 CSS 分层
 **Goal**: 在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强，让 renderer 输入具备更完整的排版语义。  
@ -93,7 +93,7 @@ Plans:

 | Phase | Plans Complete | Status | Completed |
 |---|---:|---|---|
-| 1. 对齐现状、边界与重构切入点 | 1/2 | In Progress|  |
+| 1. 对齐现状、边界与重构切入点 | 2/2 | Complete   | 2026-05-21 |
 | 2. 重构 typesetter 与 CSS 分层 | 0/3 | Not started | - |
 | 3. 重构属性体系与复杂分页器 | 0/3 | Not started | - |
 | 4. 接回现有 reader 能力链路 | 0/3 | Not started | - |
--- a/.planning/phases/01-current-engine-boundaries/01-02-SUMMARY.md
+++ b/.planning/phases/01-current-engine-boundaries/01-02-SUMMARY.md
@ -0,0 +1,87 @@
+---
+phase: 01-current-engine-boundaries
+plan: 02
+subsystem: testing
+tags: [epub, wxread, refactor, pagination, strategy]
+requires:
+  - phase: 01-current-engine-boundaries
+    provides: "当前 reflowable 引擎与 WebView 边界审计"
+provides:
+  - "旧引擎直接演进的实施顺序"
+  - "WXRead 能力到当前源码触点的映射"
+  - "后续 phase 的非目标与硬边界"
+affects: [phase-02, phase-03, phase-04, refactor-sequencing]
+tech-stack:
+  added: []
+  patterns: ["typesetter-first refactor", "page-model-preserving pagination upgrade"]
+key-files:
+  created:
+    - .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md
+  modified: []
+key-decisions:
+  - "Phase 2 只升级 renderer/typesetter 与 CSS 分层，不把分页器和 reader 回接一并混入。"
+  - "Phase 3 再升级 `RDEPUBTextPaginationSupport`、`RDEPUBTextPage` 与 `RDEPUBTextChapter` 的页面语义。"
+  - "Phase 4 才处理位置、高亮、搜索、主题切换后的重分页兼容回接。"
+patterns-established:
+  - "先提升 HTML/CSS 输入质量，再定位分页语义问题。"
+  - "扩展现有 `RDEPUBTextBook` 契约，而不是引入第二套 page model。"
+requirements-completed: [COMP-02]
+duration: 2min
+completed: 2026-05-21
+---
+
+# Phase 01 Plan 02: Refactor Entry Strategy Summary
+
+**把 WXRead 风格能力拆解成当前旧引擎可直接落地的文件触点与实施顺序，并固定了 `WKWebView` 与 `RDReaderView` 的非目标边界**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-05-21T13:56:10Z
+- **Completed:** 2026-05-21T13:58:09Z
+- **Tasks:** 2
+- **Files modified:** 1
+
+## Accomplishments
+- 建立了 `WXRead capability -> current file touchpoint -> target phase` 的执行映射
+- 固定了 Phase 2 先做 typesetter / CSS 分层，Phase 3 再做 page model / pagination semantics，Phase 4 再做 reader compatibility 回接的实施顺序
+- 把 `WKWebView` retention boundary、`RDReaderView` 不修改、位置/高亮/搜索/重分页兼容性列成后续 phase 的硬约束
+
+## Task Commits
+
+This plan was closed out with a documentation-only metadata commit after both tasks completed:
+
+1. **Task 1: 提炼 WXRead 目标能力到当前引擎触点** - included in final docs commit
+2. **Task 2: 固化范围边界和兼容性保留链路** - included in final docs commit
+
+**Plan metadata:** pending commit hash at close-out
+
+## Files Created/Modified
+
+- `.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md` - 旧引擎直接演进的切入策略文档
+
+## Decisions Made
+
+- 选择“typesetter first”而不是“pagination first”，避免把输入质量问题和布局语义问题混在一起排查
+- 把 `RDEPUBReaderController` 定义为 reader capability 编排点，而不是新的排版实现承载层
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- Phase 1 的审计与策略文档都已齐备，已能直接支撑 Phase 2 开始 renderer/typesetter 升级工作
+- 后续 phase 可以把 `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md` 和 `01-refactor-entry-strategy.md` 作为固定输入
+
+---
+*Phase: 01-current-engine-boundaries*
+*Completed: 2026-05-21*
--- a/.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md
+++ b/.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md
@ -0,0 +1,268 @@
+# 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` 容器契约都保持不变。