diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 1ca1b4e..2bed7a7 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -2,7 +2,7 @@ ## 这是什么 -`ReadViewSDK` 是一个 iOS 阅读 SDK(`RDReaderView`),提供 EPUB/TXT 的打开、分页与阅读器 UI,并包含一个用于演示集成的 Demo 工程(`ReadViewDemo`)。本次初始化面向 **brownfield(已有代码)**,目标是在尽量控制影响面的前提下完成一次“核心渲染路径”的大改。 +`ReadViewSDK` 是一个 iOS 阅读 SDK(`RDReaderView`),提供 EPUB/TXT 的打开、分页与阅读器 UI,并包含一个用于演示集成的 Demo 工程(`ReadViewDemo`)。当前项目面向 **brownfield(已有代码)**,目标是对现有 reflowable EPUB 阅读内核做一次直接重构:在旧引擎基础上演进为参考微信读书(WXRead)的原生渲染方案,而不是保留并行的第二套原生引擎。 ## 核心价值 @@ -15,42 +15,46 @@ - ✓ 支持通过 `RDURLReaderController` 以 URL 打开 `.epub` / `.txt` 并进入阅读器(现有) - ✓ 具备 `RDEPUBReaderController` 作为主阅读器控制器,负责加载/分页/状态管理(现有) - ✓ 具备 `RDReaderView` 作为分页容器视图,支持翻页/滚动等呈现模式(现有) -- ✓ reflowable EPUB 目前走 `WKWebView` 辅助分页/渲染的管线(现有实现;本次将改造) +- ✓ reflowable EPUB 当前主路径已是基于 `DTCoreText` / `NSAttributedString` / CoreText 的原生文本渲染与分页;但其样式分层、资源解析与分页策略仍较基础,本次将增强为更接近 WXRead 的实现(现有实现;本次将改造) - ✓ 固定版式(Fixed Layout)与交互式内容存在 `WKWebView` 相关能力与桥接(现有) - ✓ TXT 通过 `RDPlainTextBookBuilder` / `RDEPUBTextBook` 路径进入同一阅读器 UX(现有) - ✓ 默认使用 `UserDefaults` 进行部分阅读器状态/设置持久化(现有) ### 进行中(本次范围) -- [ ] 将 **reflowable EPUB** 的渲染/排版/分页路径改为参考 `Doc/WXRead/` 的“微信读书(WXRead)渲染方式”(原生排版为主),并在 SDK 内稳定落地且可回归验证 +- [ ] 将 **reflowable EPUB** 的现有旧引擎直接重构为参考 `Doc/WXRead/` 的“微信读书(WXRead)原生渲染方案”,覆盖 CSS 分层、自定义 DTCoreText 属性体系、页面级元数据、复杂分页与 reader 集成能力,并在 SDK 内稳定落地且可回归验证 ### 不做(明确排除) - Fixed Layout EPUB:继续使用 `WKWebView`,不切换到 WXRead 渲染方式 - 交互式 EPUB(含 JS / 音视频 / 表单 / iframe / 外链 / 脚本桥接等):继续使用 `WKWebView`,不切换到 WXRead 渲染方式 -- 除 reflowable EPUB 渲染改造所必需的最小改动外,其它功能/交互/持久化协议/对外 API 暂不做主动修改 +- 直接拷贝使用微信读书私有 JS/CSS/私有实现代码:不做 +- 同时保留两套 reflowable 原生引擎:不做 ## 背景与上下文 - 仓库形态:iOS SDK + Demo App;Demo 通过 CocoaPods 以本地 `:path` 引入 SDK。 -- 当前分层:`EPUBCore`(解析/分页/状态)、`EPUBUI`(阅读器 UX)、`EPUBTextRendering`(TXT/TextBook)、以及 `LegacyRDReaderController`(历史实现并存)。 +- 当前分层:`EPUBCore`(解析/分页/状态)、`EPUBUI`(阅读器 UX)、`EPUBTextRendering`(TXT/TextBook / reflowable 原生文本渲染)、以及 `LegacyRDReaderController`(历史实现并存)。 - WXRead 参考资料位于 `Doc/WXRead/`,包含对微信读书 EPUB 阅读器的逆向分析文档与相关符号/源码片段。 +- 当前 `.textReflowable` 主路径已基于 `DTCoreText` / `NSAttributedString` / CoreText 分页,但分页能力、页面语义、自定义属性体系与复杂块元素处理仍远弱于 WXRead。 ## 约束 - **平台**:iOS 15+(Podspec 声明 iOS 15.0;工程中常见 15.6)— 现有基线 - **语言与风格**:代码标识符保持英文;文档/计划使用中文(见 `CONTEXT.md`)— 项目约束 - **依赖管理**:CocoaPods 为主(`RDReaderView.podspec`、`Podfile`、`ReadViewDemo/Podfile`)— 现状约束 -- **范围控制**:仅替换 reflowable EPUB 渲染方式;Fixed Layout 与交互式内容保持 `WKWebView` — 本次目标边界 +- **引擎策略**:必须基于现有旧引擎直接演进,不新增并行原生引擎 — 本次关键约束 +- **范围控制**:仅重构 reflowable EPUB 原生渲染内核;Fixed Layout 与交互式内容保持 `WKWebView` — 本次目标边界 +- **兼容性**:阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页必须继续可用 — 核心功能约束 - **稳定性优先**:任何改造需以“可回归验证、不破坏现有打开/阅读主流程”为前提 — 核心价值驱动 ## 关键决策 | 决策 | 原因 | 结果 | |---|---|---| -| reflowable EPUB 改为 WXRead 风格原生渲染 | 追求更稳定可控的排版/分页与一致性 | — Pending | +| reflowable EPUB 旧引擎直接重构为 WXRead 风格原生渲染 | 需要页面级排版能力,而不是继续在轻量 renderer 外壳上打补丁 | — Pending | | Fixed Layout 与交互式 EPUB 继续使用 `WKWebView` | 降低风险与范围,避免破坏既有能力 | — Pending | -| 其它能力暂不修改 | 控制重构半径,集中资源在核心渲染替换 | — Pending | +| 不保留并行 reflowable 原生引擎 | 避免双引擎长期维护成本,把演进压力集中在现有主路径上 | — Pending | ## 演进 diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 9b6d1e0..3c0f02f 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -5,47 +5,59 @@ ## v1 需求(本次范围) -### 渲染(Reflowable EPUB) +### 渲染内核重构(Reflowable EPUB) -- [ ] **REND-01**:reflowable EPUB 的正文渲染/排版/分页改为参考 `Doc/WXRead/` 的“微信读书(WXRead)渲染方式”,不再依赖现有 reflowable 的 `WKWebView` 渲染路径 -- [ ] **REND-02**:Fixed Layout EPUB 与交互式 EPUB 继续使用 `WKWebView`,行为不因本次改造产生回归 -- [ ] **REND-03**:reflowable EPUB 新旧渲染切换具备清晰的判定条件(例如:固定版式/交互式走 `WKWebView`;普通正文走原生渲染),且可通过 Demo 明确验证 +- [ ] **REND-01**:直接重构当前 `.textReflowable` 路径,使 reflowable EPUB 不再依赖当前“简单 `DTCoreText` renderer + `pageRanges` 切页”模式,而是具备 WXRead 风格的页面级原生排版能力 +- [ ] **REND-02**:在旧引擎基础上引入 WXRead 风格的 CSS 分层策略(`default / replace / dark / epub / user`),并让样式作用于章节级 HTML → `NSAttributedString` 转换过程 +- [ ] **REND-03**:在旧引擎基础上引入自定义 DTCoreText 属性体系与页面级 `NSAttributedString` 元数据,能够承载分页、块元素、图片、页面语义等布局信息 +- [ ] **REND-04**:将当前简单的 CoreText 切页逻辑升级为具备页面语义的复杂分页器,具备与 `WRCoreTextLayouter / WRCoreTextLayoutFrame` 核心能力等价的分页与页面布局控制能力 -### 稳定性(回归保障) +### 兼容性与主流程 -- [ ] **STAB-01**:不破坏现有“通过 `RDURLReaderController` 打开 `.epub` / `.txt` 并进入阅读器”的主流程 -- [ ] **STAB-02**:改造后的 reflowable EPUB 在常见内容(图片、基础 CSS、段落/标题、链接等)下渲染稳定,不出现崩溃/白屏/无限加载等关键问题 +- [ ] **COMP-01**:`RDURLReaderController` / `RDEPUBReaderController` 作为公开入口继续可用,`.epub` / `.txt` 打开主流程不回归 +- [ ] **COMP-02**:Fixed Layout EPUB 与交互式 EPUB 继续使用 `WKWebView`,行为不因本次改造产生回归 +- [ ] **COMP-03**:reflowable EPUB 的阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页在新内核下继续可用 + +### 稳定性与验证 + +- [ ] **STAB-01**:至少 3 类样本书验证通过:纯文本/小说类、含图片与复杂段落样式的章节、含外链与多个 CSS 文件引用的章节 +- [ ] **STAB-02**:以上样本在新内核下不出现崩溃、白屏、无限加载、严重错页或关键交互链路失效 ## v2 需求(延期) -### 功能扩展(暂不进入本次路线图) +### 后续增强(不进入当前路线图) -- **PERF-01**:定义并达成明确的性能指标(首屏、翻页耗时、内存峰值)与持续监控方案 -- **QA-01**:补齐系统化的自动化测试矩阵(渲染对齐、分页一致性、回归用例集合) +- **PERF-01**:定义并达成明确性能指标(首屏、翻页耗时、内存峰值)与持续监控方案 +- **INTL-01**:更完整的国际化排版增强(如更细粒度 RTL / 连字符断字 / 多语种高级回退) ## 不做(防止范围漂移) | 功能 | 原因 | |---|---| -| Fixed Layout EPUB 切换到原生渲染 | 本次明确保留 `WKWebView` 路径以控制风险 | -| 交互式 EPUB 切换到原生渲染 | 交互能力(JS/音视频/表单/iframe/外链/bridge)更适配 `WKWebView`,本次不改 | -| 除 reflowable EPUB 渲染改造外的大范围功能/交互/持久化重做 | 控制改动半径,聚焦核心渲染替换 | +| Fixed Layout EPUB 改为原生渲染 | 本次明确保留 `WKWebView` 路径以控制风险 | +| 交互式 EPUB 改为原生渲染 | 交互能力(JS/音视频/表单/iframe/外链/bridge)更适配 `WKWebView`,本次不改 | +| 直接拷贝使用微信读书私有 JS/CSS/私有实现代码 | 只能参考设计与行为,不直接搬运私有实现 | +| 同时保留两套 reflowable 原生引擎 | 本次要求直接演进旧引擎,不维护双轨 | ## 可追溯性(需求 ↔ Phase) | 需求 | Phase | 状态 | |---|---:|---| | REND-01 | Phase 2 | Pending | -| REND-02 | Phase 1 | Pending | -| REND-03 | Phase 2 | Pending | -| STAB-01 | Phase 3 | Pending | -| STAB-02 | Phase 3 | Pending | +| REND-02 | Phase 2 | Pending | +| REND-03 | Phase 3 | Pending | +| REND-04 | Phase 3 | Pending | +| COMP-01 | Phase 4 | Pending | +| COMP-02 | Phase 1 | Pending | +| COMP-03 | Phase 4 | Pending | +| STAB-01 | Phase 5 | Pending | +| STAB-02 | Phase 5 | Pending | **覆盖统计:** -- v1 需求总数:5 -- 已映射到 phases:5 +- v1 需求总数:9 +- 已映射到 phases:9 - 未映射:0 ✓ --- *Requirements defined: 2026-05-21* -*Last updated: 2026-05-21 after initial definition* +*Last updated: 2026-05-21 after scope update* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b70d4ef..4b125a5 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -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 | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 6231a69..87bdcc6 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -8,13 +8,22 @@ 参见:`.planning/PROJECT.md`(更新于 2026-05-21) **核心价值:** 稳定可用的 EPUB/TXT 阅读体验 -**当前关注:** Phase 1(对齐现状与改造边界) +**当前关注:** Phase 1(对齐现状、边界与重构切入点) ## 当前结论(摘要) -- 本次“大改”的唯一核心目标:将 reflowable EPUB 渲染/排版/分页改为参考 `Doc/WXRead/` 的微信读书(WXRead)原生渲染方式。 -- Fixed Layout EPUB 与交互式 EPUB 继续使用 `WKWebView`,不在本次范围内替换。 -- 除渲染替换所必需的最小改动外,其它能力暂不主动调整。 +- 项目范围已从“增强现有 reflowable renderer”升级为“**直接重构现有 reflowable EPUB 旧引擎**”。 +- `textReflowable` 将在旧引擎基础上演进为参考 WXRead 的原生渲染方案,不保留并行的第二套原生引擎。 +- `webFixedLayout` 与 `webInteractive` 继续使用 `WKWebView`,不在本次范围内替换。 +- 本次重构必须继续兼容:阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页。 + +## 当前风险焦点 + +- 分页正确性 +- 位置映射稳定性 +- 图片/块元素分页 +- 高亮与搜索链路回归 +- 主题和字号切换后的重排一致性 ## 现有代码库地图 @@ -24,7 +33,9 @@ - `.planning/codebase/STACK.md` - `.planning/codebase/STRUCTURE.md` - `.planning/codebase/CONCERNS.md` +- 方案文档: + - `Doc/FeatureSolution/ReflowableEPUB_WXReadRenderer_Design.md` ## 下一步 -- 运行:`$gsd-plan-phase 1`(为 Phase 1 生成可执行计划) +- 运行:`$gsd-plan-phase 1`(为“旧引擎直接重构”版本的 Phase 1 生成可执行计划)