docs(01-02): complete refactor entry strategy plan

2026-05-21 21:58:52 +08:00
parent cc2573552c
commit 6d7f02debd
3 changed files with 358 additions and 3 deletions
@@ -0,0 +1,87 @@
+---
+phase: 01-current-engine-boundaries
+plan: 02
+subsystem: testing
+tags: [epub, wxread, refactor, pagination, strategy]
+requires:
+  - phase: 01-current-engine-boundaries
+    provides: "当前 reflowable 引擎与 WebView 边界审计"
+provides:
+  - "旧引擎直接演进的实施顺序"
+  - "WXRead 能力到当前源码触点的映射"
+  - "后续 phase 的非目标与硬边界"
+affects: [phase-02, phase-03, phase-04, refactor-sequencing]
+tech-stack:
+  added: []
+  patterns: ["typesetter-first refactor", "page-model-preserving pagination upgrade"]
+key-files:
+  created:
+    - .planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md
+  modified: []
+key-decisions:
+  - "Phase 2 只升级 renderer/typesetter 与 CSS 分层，不把分页器和 reader 回接一并混入。"
+  - "Phase 3 再升级 `RDEPUBTextPaginationSupport`、`RDEPUBTextPage` 与 `RDEPUBTextChapter` 的页面语义。"
+  - "Phase 4 才处理位置、高亮、搜索、主题切换后的重分页兼容回接。"
+patterns-established:
+  - "先提升 HTML/CSS 输入质量，再定位分页语义问题。"
+  - "扩展现有 `RDEPUBTextBook` 契约，而不是引入第二套 page model。"
+requirements-completed: [COMP-02]
+duration: 2min
+completed: 2026-05-21
+---
+
+# Phase 01 Plan 02: Refactor Entry Strategy Summary
+
+**把 WXRead 风格能力拆解成当前旧引擎可直接落地的文件触点与实施顺序，并固定了 `WKWebView` 与 `RDReaderView` 的非目标边界**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-05-21T13:56:10Z
+- **Completed:** 2026-05-21T13:58:09Z
+- **Tasks:** 2
+- **Files modified:** 1
+
+## Accomplishments
+- 建立了 `WXRead capability -> current file touchpoint -> target phase` 的执行映射
+- 固定了 Phase 2 先做 typesetter / CSS 分层，Phase 3 再做 page model / pagination semantics，Phase 4 再做 reader compatibility 回接的实施顺序
+- 把 `WKWebView` retention boundary、`RDReaderView` 不修改、位置/高亮/搜索/重分页兼容性列成后续 phase 的硬约束
+
+## Task Commits
+
+This plan was closed out with a documentation-only metadata commit after both tasks completed:
+
+1. **Task 1: 提炼 WXRead 目标能力到当前引擎触点** - included in final docs commit
+2. **Task 2: 固化范围边界和兼容性保留链路** - included in final docs commit
+
+**Plan metadata:** pending commit hash at close-out
+
+## Files Created/Modified
+
+- `.planning/phases/01-current-engine-boundaries/01-refactor-entry-strategy.md` - 旧引擎直接演进的切入策略文档
+
+## Decisions Made
+
+- 选择“typesetter first”而不是“pagination first”，避免把输入质量问题和布局语义问题混在一起排查
+- 把 `RDEPUBReaderController` 定义为 reader capability 编排点，而不是新的排版实现承载层
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- Phase 1 的审计与策略文档都已齐备，已能直接支撑 Phase 2 开始 renderer/typesetter 升级工作
+- 后续 phase 可以把 `.planning/phases/01-current-engine-boundaries/01-reflowable-audit.md` 和 `01-refactor-entry-strategy.md` 作为固定输入
+
+---
+*Phase: 01-current-engine-boundaries*
+*Completed: 2026-05-21*