4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5698aeaead
ReadViewSDK/.planning/ROADMAP.md

7.5 KiB
Raw Blame History

路线图：ReadViewSDK

概述

本次路线图围绕“直接重构现有 reflowable EPUB 旧引擎”展开，而不是继续在轻量 renderer 外壳上做增量增强，也不是维护并行的第二套原生引擎。Fixed Layout 与交互式 EPUB 保持 WKWebView 路径不变；reflowable EPUB 则在现有 .textReflowable 主路径上逐步引入 WXRead 风格的 CSS 分层、自定义 DTCoreText 属性体系、页面级元数据与复杂分页能力，最终完成对旧内核的直接演进。当前翻页代码（RDReaderView 及现有翻页模式/交互逻辑）不在本次改动范围内，新内核必须适配现有翻页容器。

Phases

  • Phase 1: 对齐现状、边界与重构切入点 - 明确当前旧引擎的真实调用链、分流边界与必须保留的兼容能力 (completed 2026-05-21)
  • Phase 2: 重构 typesetter 与 CSS 分层 - 在旧引擎基础上引入 WXRead 风格样式组织与章节级 HTML → attributed string 转换增强 (completed 2026-05-22)
  • Phase 3: 重构属性体系与复杂分页器 - 引入页面级 attributed string 元数据与更强的分页/布局能力 (completed 2026-05-22)
  • Phase 4: 接回现有 reader 能力链路 - 让新内核与阅读位置、高亮、搜索、主题切换等现有功能继续协作 (completed 2026-05-22)
  • Phase 5: 回归验证与稳定性收敛 - 以样本书和主流程为核心完成回归、修复与验收 (completed 2026-05-22)

Phase Details

Phase 1: 对齐现状、边界与重构切入点

Goal: 把“当前旧引擎是什么、哪些能力必须保留、哪些路径绝对不能动”说清楚，形成直接重构旧引擎的实施基线。
Depends on: Nothing (first phase)
Requirements: COMP-02
Success Criteria (必须为 TRUE):

  1. 能准确描述当前 .textReflowable 的真实调用链与数据流
  2. Fixed Layout / 交互式 EPUB 的 WKWebView 边界不含糊，且不被纳入本次重构
  3. 当前翻页代码（RDReaderView）被明确排除在本次改造范围外
  4. 输出一份针对“旧引擎直接演进”的重构切入策略，而不是双引擎方案 Plans: 2 plans

Plans:

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

Phase 2: 重构 typesetter 与 CSS 分层

Goal: 在现有旧引擎基础上引入 WXRead 风格的 CSS 分层与章节级 HTML → attributed string 增强，让 renderer 输入具备更完整的排版语义。
Depends on: Phase 1
Requirements: REND-01, REND-02
Success Criteria (必须为 TRUE):

  1. reflowable EPUB 的章节渲染输入不再只是“简单 DTCoreText 默认 builder + 少量 options”
  2. CSS 五层策略（default / replace / dark / epub / user）能够在旧引擎路径中落地
  3. 章节级 baseURL、资源解析与样式注入策略清晰、可验证 Plans: 3 plans

Plans:

  • 02-01：设计并实现旧引擎中的 WXRead 风格 stylesheet builder / HTML 预处理增强
  • 02-02：改造 RDEPUBDTCoreTextRenderer 与相邻渲染链路，使其承接新的样式分层与章节上下文
  • 02-03：验证章节级图片/CSS/基础资源在新渲染输入下可正常解析

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: Wave 1

  • 03-01：定义并实现页面级 attributed string 元数据与自定义属性键

Wave 2 (blocked on Wave 1 completion)

  • 03-02：在旧引擎基础上重构分页器，使其具备接近 WRCoreTextLayouter / WRCoreTextLayoutFrame 的核心能力

Wave 3 (blocked on Wave 2 completion)

  • 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作

Cross-cutting constraints:

  • pageStartOffset、pageEndOffset、chapter text continuity、fragmentOffsets 必须保持为稳定兼容字段
  • 不修改 RDReaderView，不碰 fixed / interactive WKWebView 路径

Phase 4: 接回现有 reader 能力链路

Goal: 让新内核在不新增并行原生引擎、且不修改当前翻页代码的前提下，继续服务现有 reader UI、阅读位置、高亮、搜索与主题切换能力。
Depends on: Phase 3
Requirements: COMP-01, COMP-03, COMP-04
Success Criteria (必须为 TRUE):

  1. RDURLReaderController / RDEPUBReaderController 主流程在新内核下继续可用
  2. 阅读位置映射、高亮/选区、搜索结果定位可继续工作
  3. 字号/行高/主题切换可驱动正确的重新分页，而不是破坏状态链路
  4. RDReaderView 及现有翻页模式/交互逻辑无需修改即可承接新内核输出 Plans: 3 plans

Plans:

  • 04-01：将新内核接回 RDEPUBTextBookBuilder / RDEPUBTextContentView / RDEPUBReaderController，不修改 RDReaderView
  • 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力
  • 04-03：验证字体、行高、主题切换后的重新分页与状态恢复

Cross-cutting constraints:

  • RDReaderView 继续只作为现有翻页容器使用，不承接新的 native page metadata 责任
  • native text 兼容能力必须继续围绕 RDEPUBLocation、pageStartOffset / pageEndOffset、RDEPUBTextOffsetRangeInfo 工作
  • 主题 / 字号 / 行高 / viewport 变化后的恢复应以 semantic location 为主，而不是 page number

Phase 5: 回归验证与稳定性收敛

Goal: 围绕样本书和主流程做回归，收敛分页正确性、位置映射稳定性与关键阅读交互问题。
Depends on: Phase 4
Requirements: STAB-01, STAB-02
Success Criteria (必须为 TRUE):

  1. 至少 3 类样本书验证通过：纯文本/小说类、含图片与复杂段落样式、含外链与多个 CSS 文件引用
  2. .epub / .txt 打开主流程、Fixed Layout、交互式 EPUB 不回归
  3. 新内核下不出现崩溃、白屏、无限加载、严重错页或关键交互链路失效 Plans: 2 plans

Plans:

  • 05-01：构建样本书验证矩阵与诊断手段（日志/断言/复现清单）
  • 05-02：收敛分页、位置映射、图片/块元素分页与主题切换后的稳定性问题

Cross-cutting constraints:

  • Phase 5 以验证和收敛修复为主，不重新打开更大范围的架构改造
  • 样本矩阵必须覆盖 native reflowable、fixed/interactive WebKit 路径，以及 TXT 兼容路径
  • 每项回归结论都应尽量附着到可重复证据：runtime summary、日志、断言或清单

Progress

Phase Plans Complete Status Completed
1. 对齐现状、边界与重构切入点 2/2 Complete 2026-05-21
2. 重构 typesetter 与 CSS 分层 3/3 Complete 2026-05-22
3. 重构属性体系与复杂分页器 3/3 Complete 2026-05-22
4. 接回现有 reader 能力链路 3/3 Complete 2026-05-22
5. 回归验证与稳定性收敛 2/2 Complete 2026-05-22