ReadViewSDK/.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md

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 容器契约都保持不变。