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

docs: add no-page-turning-change constraint

Browse Source
This commit is contained in:
shen 2026-05-21 21:13:13 +08:00
parent 43c3381e9b
commit 743988a78b
4 changed files with 16 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.planning/PROJECT.md
View File

@ -28,6 +28,7 @@
- Fixed Layout EPUB：继续使用 `WKWebView`，不切换到 WXRead 渲染方式 - Fixed Layout EPUB：继续使用 `WKWebView`，不切换到 WXRead 渲染方式
- 交互式 EPUB（含 JS / 音视频 / 表单 / iframe / 外链 / 脚本桥接等）：继续使用 `WKWebView`，不切换到 WXRead 渲染方式 - 交互式 EPUB（含 JS / 音视频 / 表单 / iframe / 外链 / 脚本桥接等）：继续使用 `WKWebView`，不切换到 WXRead 渲染方式
- 当前翻页代码（包括 `RDReaderView` 及其现有翻页模式/翻页交互逻辑）：不做修改
- 直接拷贝使用微信读书私有 JS/CSS/私有实现代码：不做 - 直接拷贝使用微信读书私有 JS/CSS/私有实现代码：不做
- 同时保留两套 reflowable 原生引擎：不做 - 同时保留两套 reflowable 原生引擎：不做
@ -45,6 +46,7 @@
- **依赖管理**：CocoaPods 为主（`RDReaderView.podspec`、`Podfile`、`ReadViewDemo/Podfile`）— 现状约束 - **依赖管理**：CocoaPods 为主（`RDReaderView.podspec`、`Podfile`、`ReadViewDemo/Podfile`）— 现状约束
- **引擎策略**：必须基于现有旧引擎直接演进，不新增并行原生引擎 — 本次关键约束 - **引擎策略**：必须基于现有旧引擎直接演进，不新增并行原生引擎 — 本次关键约束
- **范围控制**：仅重构 reflowable EPUB 原生渲染内核；Fixed Layout 与交互式内容保持 `WKWebView` — 本次目标边界 - **范围控制**：仅重构 reflowable EPUB 原生渲染内核；Fixed Layout 与交互式内容保持 `WKWebView` — 本次目标边界
- **翻页边界**：不修改当前翻页代码（`RDReaderView` 及现有 page curl / scroll 交互逻辑）— 新内核必须适配现有翻页容器
- **兼容性**：阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页必须继续可用 — 核心功能约束 - **兼容性**：阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页必须继续可用 — 核心功能约束
- **稳定性优先**：任何改造需以“可回归验证、不破坏现有打开/阅读主流程”为前提 — 核心价值驱动 - **稳定性优先**：任何改造需以“可回归验证、不破坏现有打开/阅读主流程”为前提 — 核心价值驱动
@ -55,6 +57,7 @@
| reflowable EPUB 旧引擎直接重构为 WXRead 风格原生渲染 | 需要页面级排版能力，而不是继续在轻量 renderer 外壳上打补丁 | — Pending | | reflowable EPUB 旧引擎直接重构为 WXRead 风格原生渲染 | 需要页面级排版能力，而不是继续在轻量 renderer 外壳上打补丁 | — Pending |
| Fixed Layout 与交互式 EPUB 继续使用 `WKWebView` | 降低风险与范围，避免破坏既有能力 | — Pending | | Fixed Layout 与交互式 EPUB 继续使用 `WKWebView` | 降低风险与范围，避免破坏既有能力 | — Pending |
| 不保留并行 reflowable 原生引擎 | 避免双引擎长期维护成本，把演进压力集中在现有主路径上 | — Pending | | 不保留并行 reflowable 原生引擎 | 避免双引擎长期维护成本，把演进压力集中在现有主路径上 | — Pending |
| 不修改当前翻页代码 | 控制改动半径，避免把阅读容器与翻页交互回归风险卷入本次内核重构 | — Pending |
## 演进 ## 演进

7
.planning/REQUIREMENTS.md
View File

@ -17,6 +17,7 @@
- [ ] **COMP-01**：`RDURLReaderController` / `RDEPUBReaderController` 作为公开入口继续可用，`.epub` / `.txt` 打开主流程不回归 - [ ] **COMP-01**：`RDURLReaderController` / `RDEPUBReaderController` 作为公开入口继续可用，`.epub` / `.txt` 打开主流程不回归
- [ ] **COMP-02**：Fixed Layout EPUB 与交互式 EPUB 继续使用 `WKWebView`，行为不因本次改造产生回归 - [ ] **COMP-02**：Fixed Layout EPUB 与交互式 EPUB 继续使用 `WKWebView`，行为不因本次改造产生回归
- [ ] **COMP-03**：reflowable EPUB 的阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页在新内核下继续可用 - [ ] **COMP-03**：reflowable EPUB 的阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页在新内核下继续可用
- [ ] **COMP-04**：当前翻页代码（`RDReaderView` 及现有 page curl / horizontal scroll / vertical scroll 交互逻辑）不做修改，新内核必须适配既有翻页容器
### 稳定性与验证 ### 稳定性与验证
@ -36,6 +37,7 @@
|---|---| |---|---|
| Fixed Layout EPUB 改为原生渲染 | 本次明确保留 `WKWebView` 路径以控制风险 | | Fixed Layout EPUB 改为原生渲染 | 本次明确保留 `WKWebView` 路径以控制风险 |
| 交互式 EPUB 改为原生渲染 | 交互能力（JS/音视频/表单/iframe/外链/bridge）更适配 `WKWebView`，本次不改 | | 交互式 EPUB 改为原生渲染 | 交互能力（JS/音视频/表单/iframe/外链/bridge）更适配 `WKWebView`，本次不改 |
| 修改当前翻页代码（`RDReaderView` / 现有翻页模式与交互逻辑） | 本次只重构 reflowable 渲染内核，不把翻页容器一起纳入改造 |
| 直接拷贝使用微信读书私有 JS/CSS/私有实现代码 | 只能参考设计与行为，不直接搬运私有实现 | | 直接拷贝使用微信读书私有 JS/CSS/私有实现代码 | 只能参考设计与行为，不直接搬运私有实现 |
| 同时保留两套 reflowable 原生引擎 | 本次要求直接演进旧引擎，不维护双轨 | | 同时保留两套 reflowable 原生引擎 | 本次要求直接演进旧引擎，不维护双轨 |
@ -50,12 +52,13 @@
| COMP-01 | Phase 4 | Pending | | COMP-01 | Phase 4 | Pending |
| COMP-02 | Phase 1 | Pending | | COMP-02 | Phase 1 | Pending |
| COMP-03 | Phase 4 | Pending | | COMP-03 | Phase 4 | Pending |
| COMP-04 | Phase 4 | Pending |
| STAB-01 | Phase 5 | Pending | | STAB-01 | Phase 5 | Pending |
| STAB-02 | Phase 5 | Pending | | STAB-02 | Phase 5 | Pending |
**覆盖统计：** **覆盖统计：**
- v1 需求总数：9 - v1 需求总数：10
- 已映射到 phases：9 - 已映射到 phases：10
- 未映射：0 ✓ - 未映射：0 ✓
--- ---

12
.planning/ROADMAP.md
View File

@ -2,7 +2,7 @@
## 概述 ## 概述
本次路线图围绕“**直接重构现有 reflowable EPUB 旧引擎**”展开，而不是继续在轻量 renderer 外壳上做增量增强，也不是维护并行的第二套原生引擎。Fixed Layout 与交互式 EPUB 保持 `WKWebView` 路径不变；reflowable EPUB 则在现有 `.textReflowable` 主路径上逐步引入 WXRead 风格的 CSS 分层、自定义 DTCoreText 属性体系、页面级元数据与复杂分页能力，最终完成对旧内核的直接演进。 本次路线图围绕“**直接重构现有 reflowable EPUB 旧引擎**”展开，而不是继续在轻量 renderer 外壳上做增量增强，也不是维护并行的第二套原生引擎。Fixed Layout 与交互式 EPUB 保持 `WKWebView` 路径不变；reflowable EPUB 则在现有 `.textReflowable` 主路径上逐步引入 WXRead 风格的 CSS 分层、自定义 DTCoreText 属性体系、页面级元数据与复杂分页能力，最终完成对旧内核的直接演进。**当前翻页代码（`RDReaderView` 及现有翻页模式/交互逻辑）不在本次改动范围内，新内核必须适配现有翻页容器。**
## Phases ## Phases
@ -21,7 +21,8 @@
**Success Criteria**（必须为 TRUE）： **Success Criteria**（必须为 TRUE）：
1. 能准确描述当前 `.textReflowable` 的真实调用链与数据流 1. 能准确描述当前 `.textReflowable` 的真实调用链与数据流
2. Fixed Layout / 交互式 EPUB 的 `WKWebView` 边界不含糊，且不被纳入本次重构 2. Fixed Layout / 交互式 EPUB 的 `WKWebView` 边界不含糊，且不被纳入本次重构
3. 输出一份针对“旧引擎直接演进”的重构切入策略，而不是双引擎方案 3. 当前翻页代码（`RDReaderView`）被明确排除在本次改造范围外
4. 输出一份针对“旧引擎直接演进”的重构切入策略，而不是双引擎方案
**Plans**：2 plans **Plans**：2 plans
Plans: Plans:
@ -59,17 +60,18 @@ Plans:
- [ ] 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作 - [ ] 03-03：验证复杂块元素、图片与分页边界控制在新分页器下可工作
### Phase 4：接回现有 reader 能力链路 ### Phase 4：接回现有 reader 能力链路
**Goal**：让新内核在不新增并行原生引擎的前提下，继续服务现有 reader UI、阅读位置、高亮、搜索与主题切换能力。 **Goal**：让新内核在不新增并行原生引擎、且不修改当前翻页代码的前提下，继续服务现有 reader UI、阅读位置、高亮、搜索与主题切换能力。
**Depends on**：Phase 3 **Depends on**：Phase 3
**Requirements**：COMP-01, COMP-03 **Requirements**：COMP-01, COMP-03, COMP-04
**Success Criteria**（必须为 TRUE）： **Success Criteria**（必须为 TRUE）：
1. `RDURLReaderController` / `RDEPUBReaderController` 主流程在新内核下继续可用 1. `RDURLReaderController` / `RDEPUBReaderController` 主流程在新内核下继续可用
2. 阅读位置映射、高亮/选区、搜索结果定位可继续工作 2. 阅读位置映射、高亮/选区、搜索结果定位可继续工作
3. 字号/行高/主题切换可驱动正确的重新分页，而不是破坏状态链路 3. 字号/行高/主题切换可驱动正确的重新分页，而不是破坏状态链路
4. `RDReaderView` 及现有翻页模式/交互逻辑无需修改即可承接新内核输出
**Plans**：3 plans **Plans**：3 plans
Plans: Plans:
- [ ] 04-01：将新内核接回 `RDEPUBTextBookBuilder` / `RDEPUBTextContentView` / `RDEPUBReaderController` - [ ] 04-01：将新内核接回 `RDEPUBTextBookBuilder` / `RDEPUBTextContentView` / `RDEPUBReaderController`，不修改 `RDReaderView`
- [ ] 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力 - [ ] 04-02：修复并验证阅读位置映射、高亮、搜索等兼容能力
- [ ] 04-03：验证字体、行高、主题切换后的重新分页与状态恢复 - [ ] 04-03：验证字体、行高、主题切换后的重新分页与状态恢复

1
.planning/STATE.md
View File

@ -15,6 +15,7 @@
- 项目范围已从“增强现有 reflowable renderer”升级为“**直接重构现有 reflowable EPUB 旧引擎**”。 - 项目范围已从“增强现有 reflowable renderer”升级为“**直接重构现有 reflowable EPUB 旧引擎**”。
- `textReflowable` 将在旧引擎基础上演进为参考 WXRead 的原生渲染方案，不保留并行的第二套原生引擎。 - `textReflowable` 将在旧引擎基础上演进为参考 WXRead 的原生渲染方案，不保留并行的第二套原生引擎。
- `webFixedLayout` 与 `webInteractive` 继续使用 `WKWebView`，不在本次范围内替换。 - `webFixedLayout` 与 `webInteractive` 继续使用 `WKWebView`，不在本次范围内替换。
- 当前翻页代码（`RDReaderView` 及现有翻页模式/交互逻辑）明确不修改，新内核必须适配现有翻页容器。
- 本次重构必须继续兼容：阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页。 - 本次重构必须继续兼容：阅读位置映射、高亮/选区、搜索结果定位、字号/行高/主题切换后的重新分页。
## 当前风险焦点 ## 当前风险焦点