4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
shen 2026-05-21 21:58:52 +08:00
parent cc2573552c
commit 6d7f02debd
3 changed files with 358 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.planning/ROADMAP.md
View File

@ -6,7 +6,7 @@
## Phases ## Phases
- [ ] **Phase 1: 对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力 - [x] **Phase 1: 对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力 (completed 2026-05-21)
- [ ] **Phase 2: 重构 typesetter 与 CSS 分层** - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强 - [ ] **Phase 2: 重构 typesetter 与 CSS 分层** - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强
- [ ] **Phase 3: 重构属性体系与复杂分页器** - 引入页面级 attributed string 元数据与更强的分页/布局能力 - [ ] **Phase 3: 重构属性体系与复杂分页器** - 引入页面级 attributed string 元数据与更强的分页/布局能力
- [ ] **Phase 4: 接回现有 reader 能力链路** - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作 - [ ] **Phase 4: 接回现有 reader 能力链路** - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作
@ -27,7 +27,7 @@
Plans: Plans:
- [x] 01-01：审计当前 `.textReflowable` 路径（`RDEPUBDTCoreTextRenderer` / `RDEPUBTextBookBuilder` / `RDEPUBTextPaginationSupport` / `RDEPUBTextContentView`） - [x] 01-01：审计当前 `.textReflowable` 路径（`RDEPUBDTCoreTextRenderer` / `RDEPUBTextBookBuilder` / `RDEPUBTextPaginationSupport` / `RDEPUBTextContentView`）
- [ ] 01-02：结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路 - [x] 01-02：结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路
### Phase 2: 重构 typesetter 与 CSS 分层 ### Phase 2: 重构 typesetter 与 CSS 分层
**Goal**: 在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强，让 renderer 输入具备更完整的排版语义。 **Goal**: 在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强，让 renderer 输入具备更完整的排版语义。
@ -93,7 +93,7 @@ Plans:
| Phase | Plans Complete | Status | Completed | | Phase | Plans Complete | Status | Completed |
|---|---:|---|---| |---|---:|---|---|
| 1. 对齐现状、边界与重构切入点 | 1/2 | In Progress| | | 1. 对齐现状、边界与重构切入点 | 2/2 | Complete | 2026-05-21 |
| 2. 重构 typesetter 与 CSS 分层 | 0/3 | Not started | - | | 2. 重构 typesetter 与 CSS 分层 | 0/3 | Not started | - |
| 3. 重构属性体系与复杂分页器 | 0/3 | Not started | - | | 3. 重构属性体系与复杂分页器 | 0/3 | Not started | - |
| 4. 接回现有 reader 能力链路 | 0/3 | Not started | - | | 4. 接回现有 reader 能力链路 | 0/3 | Not started | - |

87
.planning/phases/01-current-engine-boundaries/01-02-SUMMARY.md Normal file
View File

@ -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*

268
.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md Normal file
View File

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