docs(01-01): complete current engine audit plan

2026-05-21 21:56:54 +08:00
parent 743988a78b
commit cc2573552c
4 changed files with 532 additions and 39 deletions
@@ -0,0 +1,84 @@
+---
+phase: 01-current-engine-boundaries
+plan: 01
+subsystem: testing
+tags: [epub, dtcoretext, coretext, reader, architecture]
+requires: []
+provides:
+  - "当前 `.textReflowable` 原生渲染链路审计"
+  - "Fixed / interactive WebView 边界说明"
+  - "`RDReaderView` 作为稳定翻页容器的约束结论"
+affects: [phase-02, phase-03, reflowable-engine, reader-integration]
+tech-stack:
+  added: []
+  patterns: ["source-first architecture audit", "reader branch-point preservation"]
+key-files:
+  created:
+    - .planning/phases/01-current-engine-boundaries/01-reflowable-audit.md
+  modified: []
+key-decisions:
+  - "将 `.textReflowable` 的主战场固定在 `EPUBTextRendering`，而不是转向新的 WebView 或并行原生引擎。"
+  - "将 `RDEPUBTextBook` / `RDEPUBTextPage` 视为 location/highlight/search 的兼容层，不作为 Phase 2/3 的随意破坏对象。"
+patterns-established:
+  - "先审计 `readingProfile` 分流与 reader branch point，再设计引擎重构触点。"
+  - "以 `RDReaderView` 为稳定外壳，内核升级只在 rendering/pagination 模块内部推进。"
+requirements-completed: [COMP-02]
+duration: 8min
+completed: 2026-05-21
+---
+
+# Phase 01 Plan 01: Current Engine Audit Summary
+
+**审计并固定了当前 reflowable EPUB 原生引擎的真实调用链、WebView 分流边界，以及 `RDReaderView` 不可改动的容器契约**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-05-21T13:48:00Z
+- **Completed:** 2026-05-21T13:56:09Z
+- **Tasks:** 2
+- **Files modified:** 1
+
+## Accomplishments
+- 写清了 `.epub` 从 `RDURLReaderController` 进入 `RDEPUBReaderController` 再进入 `readingProfile` 分流的真实入口路径
+- 固定了 native `.textReflowable` 的实际渲染链路：`RDEPUBDTCoreTextRenderer` -> `RDEPUBTextBookBuilder` -> `ss_pageRanges(size:)` -> `RDEPUBTextContentView`
+- 明确了 `webFixedLayout` / `webInteractive` 继续使用 `WKWebView`，并把 `RDReaderView` 记录为稳定外壳
+
+## Task Commits
+
+This plan was closed out with a documentation-only metadata commit after both tasks completed:
+
+1. **Task 1: 梳理原生 reflowable 调用链与数据模型** - included in final docs commit
+2. **Task 2: 写清 WebView 边界与容器不变约束** - included in final docs commit
+
+**Plan metadata:** pending commit hash at close-out
+
+## Files Created/Modified
+
+- `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md` - 基于源码证据的 current-engine 审计文档
+
+## Decisions Made
+
+- 以 `RDEPUBReaderController.paginatePublication()` 作为 native / web 分流的主证据点，而不是以历史文档描述为准
+- 把 `RDEPUBPaginator` 定义为 WebView 渲染/测量体系组成部分，而不是当前 native reflowable 的分页核心
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+- `gsd-sdk` 起初无法从中文 phase 名自动推导 phase 目录 slug，因此本阶段使用了稳定的英文目录名 `01-current-engine-boundaries`
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- Wave 1 事实基线已完成，Phase 1 的 strategy plan 可以直接基于该审计文档展开
+- 当前审计已足够支撑 Phase 2/3 避免把 WebView 路径和 native 路径混为一谈
+
+---
+*Phase: 01-current-engine-boundaries*
+*Completed: 2026-05-21*