3.4 KiB
3.4 KiB
Phase 3: 重构属性体系与复杂分页器 - Pattern Map
Goal
为 Phase 3 执行提供“先看哪里、怎么保持兼容”的最短路径。这个阶段的关键不是改 reader UI，而是扩展 page metadata 并把 paginator 从纯 range slicing 升级为可表达页面语义的内部 layouter。
Planned Outputs
| Planned file | Role | Primary evidence | Why this is the right analog |
|---|---|---|---|
.planning/phases/03-page-metadata-pagination/03-01-PLAN.md |
页面级 attributed string 元数据与属性键实现计划 | Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift, Sources/RDReaderView/EPUBTextRendering/RDEPUBTextRenderer.swift |
这些文件共同定义 page/chapter contract、range info、fragment offsets 与 renderer output。 |
.planning/phases/03-page-metadata-pagination/03-02-PLAN.md |
复杂分页器与 layouter/frame 重构计划 | Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift, RDEPUBTextBookBuilder.swift |
当前所有分页都在这里；Phase 3 必须从这条路径升级，而不是另起 reader shell。 |
.planning/phases/03-page-metadata-pagination/03-03-PLAN.md |
复杂块元素/图片分页验证计划 | ReadViewDemo/ReadViewDemo/book/*.epub, ReadViewDemo/ReadViewDemo/ViewController.swift, RDEPUBTextContentView.swift |
需要真实样本和现有 demo 入口来证明分页语义变强但 offset compatibility 没坏。 |
Code Evidence Map
| Concern | Closest source of truth | Evidence to extract |
|---|---|---|
| 当前 page model 的边界 | Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift |
RDEPUBTextPage / RDEPUBTextChapter 当前只有 offsets、ranges、fragmentOffsets。 |
| 当前 paginator 的真实实现 | Sources/RDReaderView/EPUBTextRendering/RDEPUBTextPaginationSupport.swift |
CTFramesetterCreateFrame + CTFrameGetVisibleStringRange 的纯 slicing 逻辑。 |
| 位置/导航如何依赖 offsets | Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift |
pageIndex(for:)、pending navigation、href/progression 到 page 的映射。 |
| 高亮/选区如何依赖 offsets | Sources/RDReaderView/EPUBUI/RDEPUBTextContentView.swift, Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift |
RDEPUBTextOffsetRangeInfo 与 pageStartOffset/pageEndOffset 的 overlap 计算。 |
| 搜索如何依赖 chapter text continuity | Sources/RDReaderView/EPUBTextRendering/RDEPUBTextSearchEngine.swift |
chapter-level attributed string 搜索 + rangeLocation/rangeLength。 |
| 复杂块元素/图片验证入口 | ReadViewDemo/ReadViewDemo/book/, ReadViewDemo/ReadViewDemo/ViewController.swift |
现有 demo 与样本 corpus 已经是可运行回归入口。 |
Writing Guidance
- 计划必须把 “metadata first, paginator second, validation third” 的顺序写清楚，避免把所有变更压进一个 plan。
- 任何新分页语义都要同时写出 “增强点” 和 “必须保留的 offset invariant”。
- 如果引入内部 layouter / layout-frame 类型，职责要落在
EPUBTextRendering内部，不要扩散到RDEPUBReaderController。 - 验证计划除了 demo/run，还要有源代码断言，确保 metadata 与 page-edge reason 真正落盘到模型里。