ReadViewSDK/.planning/phases/04-reader-capabilities/04-PATTERNS.md

Phase 4: 接回现有 reader 能力链路 - Pattern Map

Goal

为 Phase 4 提供“先接哪里、怎么验证没把 reader 行为搞坏”的最短路径。重点不是继续改 paginator，而是把已经完成的 native text book/page model 稳定接回 reader 能力链路。

Planned Outputs

Planned file	Role	Primary evidence	Why this is the right analog
04-01-PLAN.md	native text backend 接回 reader 主流程	RDEPUBReaderController, RDEPUBTextBookBuilder, RDEPUBTextContentView, RDURLReaderController	这些文件定义当前 native text 打开、分页、展示和 page container 接口。
04-02-PLAN.md	位置映射 / 高亮 / 搜索兼容收敛	RDEPUBReadingSession, RDEPUBReaderController, RDEPUBTextSearchEngine, RDEPUBReadingModels	这些文件共同定义 reader state、search matches、selection normalization 与绝对 offset 持久化语义。
04-03-PLAN.md	主题 / 字号 / 行高 / viewport 变化后的重新分页与状态恢复验证	RDEPUBReaderController, RDEPUBReaderConfiguration, RDURLReaderController, ReadViewDemo	当前所有重新分页触发器和 demo 验证入口都在这里。

Code Evidence Map

Concern	Closest source of truth	Evidence to extract
native text page flow接入点	RDEPUBReaderController.paginatePublication, applyTextBook, pageContentView	现有 controller 已有 native/web 双路径，但需要收敛行为。
恢复位置与可见位置	restoreReadingLocation, currentVisibleLocation, finishPagination	这里决定 repagination 后回到哪里。
绝对 offset 高亮/选区兼容	RDEPUBTextContentView, normalizedTextSelection, RDEPUBTextOffsetRangeInfo	这些是 Phase 4 不能破坏的硬约束。
搜索跳转与页号解析	search, navigateToCurrentSearchMatch, pageNumber(for:), RDEPUBTextSearchEngine	需要保证 native text path 仍能定位正确页。
设置变更触发重排	configuration.didSet, requiresRepagination, refreshVisibleContentPreservingLocation, handleViewportChangeIfNeeded	字号/行高/主题/旋转都是 Phase 4 的状态恢复验证入口。

Writing Guidance

• 计划必须把“主流程接回、兼容能力收敛、重排恢复验证”拆成三个独立 plan，不要把所有 reader 能力挤进一个任务。
• 任何修复都要优先围绕 RDEPUBReaderController 和 RDEPUBReadingSession 的现有责任边界展开，不要借机重写 RDReaderView。
• 验证步骤要明确要求真实的 reader 行为检查，而不是只做 build pass。