docs: update planning for direct reflowable engine rewrite

2026-05-21 21:08:21 +08:00
parent c95d80e257
commit 43c3381e9b
4 changed files with 125 additions and 64 deletions
@@ -2,63 +2,97 @@

 ## 概述

-本次路线图以“**在不扩大范围的前提下**，将 reflowable EPUB 渲染路径替换为参考 `Doc/WXRead/` 的微信读书（WXRead）原生渲染方式”为主线。Fixed Layout 与交互式 EPUB 保持 `WKWebView` 路径不变；除渲染替换所必需的最小改动外，其它能力暂不主动调整。每个 Phase 都以“可验证的稳定性”为完成标准。
+本次路线图围绕“**直接重构现有 reflowable EPUB 旧引擎**”展开，而不是继续在轻量 renderer 外壳上做增量增强，也不是维护并行的第二套原生引擎。Fixed Layout 与交互式 EPUB 保持 `WKWebView` 路径不变；reflowable EPUB 则在现有 `.textReflowable` 主路径上逐步引入 WXRead 风格的 CSS 分层、自定义 DTCoreText 属性体系、页面级元数据与复杂分页能力，最终完成对旧内核的直接演进。

 ## Phases

- [ ] **Phase 1：对齐现状与改造边界** - 明确 reflowable/Fixed/交互式 的判定与现有路径，锁定不做范围
- [ ] **Phase 2：WXRead 渲染管线方案落地（reflowable）** - 依据 `Doc/WXRead/` 设计并落地原生渲染入口与最小可用链路
- [ ] **Phase 3：集成与稳定性回归** - 集成到现有 reader 入口，确保主流程与常见内容稳定可用
+- [ ] **Phase 1：对齐现状、边界与重构切入点** - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力
+- [ ] **Phase 2：重构 typesetter 与 CSS 分层** - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强
+- [ ] **Phase 3：重构属性体系与复杂分页器** - 引入页面级 attributed string 元数据与更强的分页/布局能力
+- [ ] **Phase 4：接回现有 reader 能力链路** - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作
+- [ ] **Phase 5：回归验证与稳定性收敛** - 以样本书和主流程为核心完成回归、修复与验收

 ## Phase Details

-### Phase 1：对齐现状与改造边界
-**Goal**：明确 reflowable EPUB 当前渲染/分页路径与切换点，制定替换策略与不做边界，确保 `WKWebView` 场景不被误伤。  
+### Phase 1：对齐现状、边界与重构切入点
+**Goal**：把“当前旧引擎是什么、哪些能力必须保留、哪些路径绝对不能动”说清楚，形成直接重构旧引擎的实施基线。  
 **Depends on**：Nothing (first phase)  
-**Requirements**：REND-02  
+**Requirements**：COMP-02  
 **Success Criteria**（必须为 TRUE）：
-  1. 能明确判定一本 EPUB 属于 reflowable / Fixed Layout / 交互式（以工程实现为准）
-  2. 固定版式与交互式 EPUB 仍走 `WKWebView`，并形成清晰的“保持不改”约束
-  3. 输出一份可执行的实现策略：将 reflowable EPUB 切换到 WXRead 风格原生渲染
+  1. 能准确描述当前 `.textReflowable` 的真实调用链与数据流
+  2. Fixed Layout / 交互式 EPUB 的 `WKWebView` 边界不含糊，且不被纳入本次重构
+  3. 输出一份针对“旧引擎直接演进”的重构切入策略，而不是双引擎方案
 **Plans**：2 plans

 Plans:
- [ ] 01-01：阅读 `Doc/WXRead/analysis/*` 与关键 decompiled 符号，提炼“原生渲染”最小管线与可替换点
- [ ] 01-02：审计现有 `Sources/RDReaderView/EPUBCore` reflowable 渲染/分页路径，确定切入点与迁移策略
+- [ ] 01-01：审计当前 `.textReflowable` 路径（`RDEPUBDTCoreTextRenderer` / `RDEPUBTextBookBuilder` / `RDEPUBTextPaginationSupport` / `RDEPUBTextContentView`）
+- [ ] 01-02：结合 `Doc/WXRead/analysis/*` 提炼旧引擎可直接演进的切入点与必须保留的兼容链路

-### Phase 2：WXRead 渲染管线方案落地（reflowable）
-**Goal**：在 SDK 内为 reflowable EPUB 引入 WXRead 风格的原生渲染入口，跑通最小可用链路（可在 Demo 中验证）。  
+### Phase 2：重构 typesetter 与 CSS 分层
+**Goal**：在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强，让 renderer 输入具备更完整的排版语义。  
 **Depends on**：Phase 1  
-**Requirements**：REND-01, REND-03  
+**Requirements**：REND-01, REND-02  
 **Success Criteria**（必须为 TRUE）：
-  1. reflowable EPUB 可不依赖现有 `WKWebView` 渲染路径完成排版/分页/展示
-  2. 渲染结果在 Demo 中可稳定展示（最小支持：段落/标题/基础样式/图片）
-  3. 切换判定逻辑清晰、可测，且 Fixed/交互式路径未被影响
+  1. reflowable EPUB 的章节渲染输入不再只是“简单 DTCoreText 默认 builder + 少量 options”
+  2. CSS 五层策略（`default / replace / dark / epub / user`）能够在旧引擎路径中落地
+  3. 章节级 baseURL、资源解析与样式注入策略清晰、可验证
 **Plans**：3 plans

 Plans:
- [ ] 02-01：定义并实现 reflowable EPUB 的“原生渲染”模块边界（typesetter/layouter/page model 等）
- [ ] 02-02：对接现有解析与资源加载（manifest/spine/资源寻址），保证图片/CSS/字体等基础资源可用
- [ ] 02-03：在现有 reader 入口处接入新渲染路径（保持对外 API 尽量不变）
+- [ ] 02-01：设计并实现旧引擎中的 WXRead 风格 stylesheet builder / HTML 预处理增强
+- [ ] 02-02：改造 `RDEPUBDTCoreTextRenderer` 与相邻渲染链路，使其承接新的样式分层与章节上下文
+- [ ] 02-03：验证章节级图片/CSS/基础资源在新渲染输入下可正常解析

-### Phase 3：集成与稳定性回归
-**Goal**：把新 reflowable 渲染路径完整集成到阅读器体验中，保证主流程稳定可用，并建立最小回归保障。  
+### Phase 3：重构属性体系与复杂分页器
+**Goal**：在旧引擎路径中引入页面级 attributed string 元数据与更复杂的分页/页面布局能力，替代当前简单 `pageRanges` 切页模式。  
 **Depends on**：Phase 2  
+**Requirements**：REND-03, REND-04  
+**Success Criteria**（必须为 TRUE）：
+  1. 自定义 DTCoreText 属性体系可承载分页、块元素、图片、页面语义等布局信息
+  2. 新分页器具备明显强于当前 `CTFrameGetVisibleStringRange` 切页的页面布局能力
+  3. 分页结果可为后续 reader 集成提供稳定的页面范围与页面语义
+**Plans**：3 plans
+
+Plans:
+- [ ] 03-01：定义并实现页面级 attributed string 元数据与自定义属性键
+- [ ] 03-02：在旧引擎基础上重构分页器，使其具备接近 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 的核心能力
+- [ ] 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作
+
+### Phase 4：接回现有 reader 能力链路
+**Goal**：让新内核在不新增并行原生引擎的前提下，继续服务现有 reader UI、阅读位置、高亮、搜索与主题切换能力。  
+**Depends on**：Phase 3  
+**Requirements**：COMP-01, COMP-03  
+**Success Criteria**（必须为 TRUE）：
+  1. `RDURLReaderController` / `RDEPUBReaderController` 主流程在新内核下继续可用
+  2. 阅读位置映射、高亮/选区、搜索结果定位可继续工作
+  3. 字号/行高/主题切换可驱动正确的重新分页，而不是破坏状态链路
+**Plans**：3 plans
+
+Plans:
+- [ ] 04-01：将新内核接回 `RDEPUBTextBookBuilder` / `RDEPUBTextContentView` / `RDEPUBReaderController`
+- [ ] 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力
+- [ ] 04-03：验证字体、行高、主题切换后的重新分页与状态恢复
+
+### Phase 5：回归验证与稳定性收敛
+**Goal**：围绕样本书和主流程做回归，收敛分页正确性、位置映射稳定性与关键阅读交互问题。  
+**Depends on**：Phase 4  
 **Requirements**：STAB-01, STAB-02  
 **Success Criteria**（必须为 TRUE）：
-  1. `RDURLReaderController` 打开 `.epub`/`.txt` 的主流程不回归
-  2. reflowable EPUB 在常见内容下不出现崩溃/白屏/卡死等关键稳定性问题
-  3. Demo 可用于复现与回归验证（至少包含 2-3 本典型 reflowable EPUB 用例）
+  1. 至少 3 类样本书验证通过：纯文本/小说类、含图片与复杂段落样式、含外链与多个 CSS 文件引用
+  2. `.epub` / `.txt` 打开主流程、Fixed Layout、交互式 EPUB 不回归
+  3. 新内核下不出现崩溃、白屏、无限加载、严重错页或关键交互链路失效
 **Plans**：2 plans

 Plans:
- [ ] 03-01：补齐关键回归用例与诊断手段（日志/开关/快速回退策略）
- [ ] 03-02：对 reflowable 渲染在真实内容上的问题做收敛与修复，形成可持续迭代基线
+- [ ] 05-01：构建样本书验证矩阵与诊断手段（日志/断言/复现清单）
+- [ ] 05-02：收敛分页、位置映射、图片/块元素分页与主题切换后的稳定性问题

 ## Progress

 | Phase | Plans Complete | Status | Completed |
 |---|---:|---|---|
-| 1. 对齐现状与改造边界 | 0/2 | Not started | - |
-| 2. WXRead 渲染管线方案落地（reflowable） | 0/3 | Not started | - |
-| 3. 集成与稳定性回归 | 0/2 | Not started | - |
+| 1. 对齐现状、边界与重构切入点 | 0/2 | Not started | - |
+| 2. 重构 typesetter 与 CSS 分层 | 0/3 | Not started | - |
+| 3. 重构属性体系与复杂分页器 | 0/3 | Not started | - |
+| 4. 接回现有 reader 能力链路 | 0/3 | Not started | - |
+| 5. 回归验证与稳定性收敛 | 0/2 | Not started | - |