docs(phase-01): add planning artifacts

2026-05-21 22:00:41 +08:00
parent 0870996ed0
commit 6d196d64e5
5 changed files with 539 additions and 0 deletions
@@ -0,0 +1,102 @@
+---
+phase: 01-current-engine-boundaries
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - .planning/phases/01-current-engine-boundaries/01-reflowable-audit.md
+autonomous: true
+requirements:
+  - COMP-02
+user_setup: []
+must_haves:
+  truths:
+    - 审计文档准确描述 `RDURLReaderController -> RDEPUBReaderController -> readingProfile -> text/native or web` 的真实分流链路。
+    - 审计文档明确 `webFixedLayout` 与 `webInteractive` 继续走 `WKWebView`，不纳入原生重构。
+    - 审计文档明确 `RDReaderView` 是必须保持稳定的翻页容器。
+  artifacts:
+    - .planning/phases/01-current-engine-boundaries/01-reflowable-audit.md
+  key_links:
+    - `RDEPUBReaderController.paginatePublication()` 与 `RDEPUBParser.readingProfile()` 的关系被写清楚。
+    - `RDEPUBTextBookBuilder` / `RDEPUBDTCoreTextRenderer` / `RDEPUBTextContentView` 之间的数据流被写清楚。
+---
+
+<objective>
+产出一份基于当前代码的 `.textReflowable` 审计文档。
+
+Purpose: 为后续 Phase 2/3 提供“当前旧引擎真实是什么”的事实基线，避免围绕错误边界重构。
+Output: `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md`
+</objective>
+
+<execution_context>
+@$HOME/.codex/get-shit-done/workflows/execute-plan.md
+@$HOME/.codex/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/01-current-engine-boundaries/01-RESEARCH.md
+@.planning/phases/01-current-engine-boundaries/01-PATTERNS.md
+@Sources/RDReaderView/RDURLReaderController.swift
+@Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift
+@Sources/RDReaderView/EPUBCore/RDEPUBParser+ReadingProfile.swift
+@Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift
+@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift
+@Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift
+@Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift
+@Sources/RDReaderView/RDReaderView.swift
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: 梳理原生 reflowable 调用链与数据模型</name>
+  <files>.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md</files>
+  <read_first>Sources/RDReaderView/RDURLReaderController.swift, Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift, Sources/RDReaderView/EPUBCore/RDEPUBParser+ReadingProfile.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBDTCoreTextRenderer.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift</read_first>
+  <action>新建 `01-reflowable-audit.md`，写清楚 `RDURLReaderController` 如何把 `.epub` 交给 `RDEPUBReaderController`，`RDEPUBParser.readingProfile()` 如何把内容分为 `textReflowable` / `webFixedLayout` / `webInteractive`，以及 `RDEPUBReaderController.paginatePublication()` 在 `textReflowable` 分支内如何调用 `RDEPUBTextBookBuilder`、`RDEPUBDTCoreTextRenderer`、`ss_pageRanges(size:)`、`RDEPUBTextBook` / `RDEPUBTextPage`。必须包含关键类型名、关键方法名和每层输入输出，不能只写概念描述。</action>
+  <verify>rg -n "RDURLReaderController|RDEPUBReaderController|RDEPUBTextBookBuilder|RDEPUBDTCoreTextRenderer|ss_pageRanges|RDEPUBTextBook|RDEPUBTextPage" .planning/phases/01-current-engine-boundaries/01-reflowable-audit.md</verify>
+  <acceptance_criteria>
+    - `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md` 存在
+    - 文档包含 `RDURLReaderController`、`RDEPUBReaderController`、`RDEPUBTextBookBuilder`、`RDEPUBDTCoreTextRenderer`、`RDEPUBTextContentView`
+    - 文档明确 `ss_pageRanges(size:)` 仍是当前分页核心
+  </acceptance_criteria>
+  <done>审计文档把当前 native reflowable 路径的入口、渲染、分页、展示和位置数据模型全部串起来。</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: 写清 WebView 边界与容器不变约束</name>
+  <files>.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md</files>
+  <read_first>Sources/RDReaderView/EPUBCore/RDEPUBParser+ReadingProfile.swift, Sources/RDReaderView/EPUBCore/RDEPUBPaginator.swift, Sources/RDReaderView/EPUBCore/RDEPUBWebView+FixedLayout.swift, Sources/RDReaderView/EPUBCore/RDEPUBWebView+Reflowable.swift, Sources/RDReaderView/RDReaderView.swift</read_first>
+  <action>在同一份审计文档中追加“边界与排除项”章节，明确 `webFixedLayout` 与 `webInteractive` 为什么继续依赖 `WKWebView`，`RDEPUBPaginator` 在当前架构中的职责，以及 `RDReaderView` 的 page curl / scroll / dual-page / orientation 逻辑为什么必须保持不变。把这些结论落成可以直接供后续 phase 引用的约束条目。</action>
+  <verify>rg -n "WKWebView|webFixedLayout|webInteractive|RDEPUBPaginator|RDReaderView|不修改" .planning/phases/01-current-engine-boundaries/01-reflowable-audit.md</verify>
+  <acceptance_criteria>
+    - 文档包含 `WKWebView`、`webFixedLayout`、`webInteractive`、`RDEPUBPaginator`、`RDReaderView`
+    - 文档有单独的边界或排除项章节
+    - 文档明确写出“`RDReaderView` 不修改”或等价表述
+  </acceptance_criteria>
+  <done>审计文档既说明当前原生引擎，也说明哪些路径和容器不属于本次重构。</done>
+</task>
+
+</tasks>
+
+<verification>
+Before declaring plan complete:
+- [ ] `test -f .planning/phases/01-current-engine-boundaries/01-reflowable-audit.md`
+- [ ] `rg -n "textReflowable|webFixedLayout|webInteractive|RDReaderView" .planning/phases/01-current-engine-boundaries/01-reflowable-audit.md`
+- [ ] 文档内容可直接对应到当前源码文件，而不是只复述 roadmap 目标
+</verification>
+
+<success_criteria>
+
+- All tasks completed
+- All verification checks pass
+- No errors or warnings introduced
+- 审计文档能支撑后续 Phase 2/3 不再重新摸索当前引擎边界
+  </success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-current-engine-boundaries/01-01-SUMMARY.md`
+</output>