docs(06): create phase plan

2026-05-22 14:20:33 +08:00
parent 7b5c77cedd
commit 46fa9fceff
7 changed files with 399 additions and 5 deletions
@@ -0,0 +1,39 @@
+# Phase 6: 页面几何与交互命中层 - Patterns
+
+## Reusable Patterns
+
+### Offset continuity is already the compatibility contract
+
+- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift` and `Sources/RDReaderView/LegacyRDReaderController/RDEPUBTextPaging.swift` both preserve `pageStartOffset`, `pageEndOffset`, and `fragmentOffsets`.
+- `Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift` keeps `RDEPUBTextOffsetRangeInfo` as the absolute-offset payload used by selection and highlight consumers.
+- Phase 6 should keep that contract intact even after a geometry overlay is introduced.
+
+### The layouter already knows more than the view layer
+
+- `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextLayouter.swift` already determines `blockRange`, `attachmentRanges`, `attachmentKinds`, `breakReason`, and `trailingFragmentID`.
+- That makes the layouter the right place to enrich `RDEPUBTextLayoutFrame` with queryable page geometry instead of re-deriving page rules inside `RDEPUBTextContentView`.
+
+### Reader coordination already belongs to the controller
+
+- `Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift` already owns selection persistence, current-location updates, highlight creation, search state, and repagination.
+- Any new geometry-backed selection flow should plug into the controller rather than creating a second reader state owner.
+
+### Content view should become a thin host
+
+- `Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift` currently mixes display, selection, highlight painting, and offset conversion.
+- For this phase, the safest direction is to let the view host text plus an overlay and keep the selection model conversion in one place.
+
+## Closest Existing Analogs
+
+- `RDEPUBTextLayoutFrame` is the natural home for page geometry metadata.
+- `RDEPUBTextBookBuilder` is the natural place to lift geometry results into page-level book state.
+- `RDEPUBReaderController` is the natural adapter layer for user interactions and persistence.
+- `RDEPUBTextContentView` is the natural host for an overlay layer because it already owns the page view composition.
+
+## Design Guardrails
+
+- Do not move fixed/interactive EPUB off `WKWebView`.
+- Do not change `RDReaderView`.
+- Do not break the existing offset-based consumers while introducing geometry queries.
+- Do not let search/highlight/tap-locate become separate geometry implementations; they should reuse the same page geometry API later.
+