feat: 架构整改 — Context拆分、Runtime拆分、异步章节加载、UI测试覆盖
Phase 1: Context 拆分 - 新增 RDEPUBReaderState/RDEPUBReaderEnvironment/RDEPUBReaderServices - RDEPUBReaderContext 改为过渡门面，代理到 State/Environment/Services Phase 2: Runtime 拆分 - 新增 RDEPUBPresentationRuntime 处理分页状态管理 - 新增 RDEPUBChapterWarmupOrchestrator 处理章节预热与加载编排 - RDEPUBReaderRuntime 从 1277 行收缩，公共 API 转发到新 facade Phase 0.5: 性能优化 - prepareOnDemandChapter 支持异步模式（allowSynchronousLoad: false） - extendPartialBookPageMapIfNeeded 改为 DispatchGroup 并发加载 - RDEPUBChapterOffsetMap.cfiMap 加 NSLock 保护数据竞争 - CFI Map 构建延迟到后台队列（scheduleDeferredCFIMapBuildIfNeeded） - RDEPUBTextPageRenderView 引入静态位图缓存 - RDEPUBTextContentView 新增 loadingSpinner 占位页 Phase 3: 状态机 - 新增 RDEPUBNavigationStateMachine（含 DEBUG 合法转换校验） - 新增 RDEPUBPaginationState 记录分页来源 Review 修复 - makeSummary 重复方法合并 - ensureNavigationTargetAvailable 同步路径加注释标记 UI 测试 - 新增 AsyncChapterLoadingTests（20 个测试，覆盖全部架构整改场景） - 跨章节翻页、延迟 CFI、状态机、内存警告、预加载、位置恢复等
This commit is contained in:
shen
+70
-31
@@ -1,6 +1,6 @@
|
||||
# ReadViewSDK 系统架构文档
|
||||
|
||||
> 最后更新：2026-06-09
|
||||
> 最后更新：2026-06-22
|
||||
|
||||
---
|
||||
|
||||
@@ -201,43 +201,82 @@ struct RDEPUBChapterCacheKey: Hashable {
|
||||
|
||||
---
|
||||
|
||||
## 5. 章节按需加载架构
|
||||
## 5. ReaderController 组合架构
|
||||
|
||||
```
|
||||
RDEPUBReaderController
|
||||
│
|
||||
├─ RDEPUBReaderContext // 共享状态中心
|
||||
│ ├─ parser, publication, readingSession
|
||||
│ ├─ configuration, persistence
|
||||
│ └─ 便捷方法 (renderStyle, layoutConfig, cacheKey)
|
||||
├─ RDEPUBReaderContext（过渡门面）
|
||||
│ ├─ RDEPUBReaderState
|
||||
│ │ ├─ parser / publication / readingSession
|
||||
│ │ ├─ textBook / bookPageMap / pendingFullPageMap
|
||||
│ │ ├─ activeBookmarks / activeHighlights / searchState
|
||||
│ │ └─ currentSelection / paginationToken / snapshot
|
||||
│ │
|
||||
│ ├─ RDEPUBReaderEnvironment
|
||||
│ │ ├─ viewport / safeArea / traitCollection 抽象
|
||||
│ │ ├─ brightness / fallbackViewportSize
|
||||
│ │ └─ renderStyle / layoutConfig 推导
|
||||
│ │
|
||||
│ └─ RDEPUBReaderServices
|
||||
│ ├─ parser / paginator / builder factory
|
||||
│ ├─ renderer factory
|
||||
│ └─ chapter summary disk cache factory
|
||||
│
|
||||
├─ RDEPUBReaderRuntime // 运行时协调器集合（Facade 模式）
|
||||
│ ├─ chapterLoader // 章节加载器
|
||||
│ ├─ chapterRuntimeStore // 内存缓存
|
||||
│ ├─ summaryDiskCache // 磁盘摘要缓存
|
||||
│ ├─ pageResolver // 页码解析器
|
||||
│ ├─ loadCoordinator // 加载协调器
|
||||
│ ├─ paginationCoordinator // 分页协调器
|
||||
│ ├─ locationCoordinator // 位置协调器
|
||||
│ ├─ searchCoordinator // 搜索协调器
|
||||
│ ├─ chromeCoordinator // 工具栏协调器
|
||||
│ ├─ annotationCoordinator // 标注协调器
|
||||
│ └─ viewportMonitor // 视口变化监控
|
||||
│
|
||||
├─ RDEPUBReaderPaginationCoordinator // 分页协调器
|
||||
│ ├─ paginatePublication() // 入口
|
||||
│ ├─ paginateMetadataOnly() // 后台元数据解析
|
||||
│ └─ restoreBookPageMapIfPossible() // 缓存恢复
|
||||
│
|
||||
├─ RDEPUBChapterLoader // 章节加载器
|
||||
│ ├─ loadChapter() // 异步加载（Tier1→Tier2→全量构建）
|
||||
│ └─ loadChapterSynchronouslyForMigration() // 同步加载（快速打开用）
|
||||
│
|
||||
└─ RDEPUBBookPageMap // 轻量页码映射
|
||||
├─ ~100KB/1000章，不持有 NSAttributedString
|
||||
└─ 支持增量刷新 (Builder pattern)
|
||||
└─ RDEPUBReaderRuntime（兼容门面）
|
||||
├─ load / pagination / location / search / chrome / annotation coordinator
|
||||
├─ RDEPUBPresentationRuntime
|
||||
├─ RDEPUBChapterWarmupOrchestrator
|
||||
└─ 旧 API 转发
|
||||
```
|
||||
|
||||
当前 `RDEPUBReaderContext` 仍存在，但主要作用已经收缩为过渡门面：
|
||||
|
||||
- 对外维持兼容访问面
|
||||
- 对内把纯状态、环境推导、工厂依赖拆开
|
||||
- 避免新逻辑继续把 `Context` 当作全能对象扩散
|
||||
|
||||
---
|
||||
|
||||
## 6. 章节按需加载与分页窗口架构
|
||||
|
||||
```
|
||||
RDEPUBReaderController
|
||||
│
|
||||
├─ RDEPUBReaderPaginationCoordinator // 分页入口与后台元数据解析
|
||||
│ ├─ paginatePublication()
|
||||
│ ├─ paginateMetadataOnly()
|
||||
│ └─ restoreBookPageMapIfPossible()
|
||||
│
|
||||
├─ RDEPUBPresentationRuntime // 分页状态与窗口替换
|
||||
│ ├─ applyBookPageMap()
|
||||
│ ├─ refreshBookPageMapInPlace()
|
||||
│ ├─ applyPendingFullPageMapIfNeeded()
|
||||
│ └─ RDEPUBNavigationStateMachine
|
||||
│
|
||||
├─ RDEPUBChapterWarmupOrchestrator // 按需章节预热与边界预取
|
||||
│ ├─ prepareOnDemandChapter()
|
||||
│ ├─ extendPartialBookPageMapIfNeeded()
|
||||
│ ├─ prefetchForwardChaptersAfterInitialOpen()
|
||||
│ └─ ensureNavigationTargetAvailable()
|
||||
│
|
||||
├─ RDEPUBChapterLoader // 章节构建与缓存门面
|
||||
│ ├─ loadChapter() // 异步加载（主路径）
|
||||
│ └─ loadChapterSynchronouslyForMigration()
|
||||
│
|
||||
└─ RDEPUBBookPageMap / RDEPUBPaginationState
|
||||
├─ 当前激活窗口
|
||||
├─ 待接管完整 page map
|
||||
└─ 来源与切换状态
|
||||
```
|
||||
|
||||
这轮整改后，跨章节主路径的关键变化是：
|
||||
|
||||
- 普通翻页时不再要求 UI 主线程同步等待章节构建
|
||||
- 章节边界会前移预热相邻章节与 lookahead 章节
|
||||
- `bookPageMap` 的 partial extension 和 full replacement 统一经过 `RDEPUBPresentationRuntime`
|
||||
- `RDEPUBReaderRuntime` 不再内联维护整套预热/扩窗实现
|
||||
|
||||
---
|
||||
|
||||
## 6. WebView 渲染架构（Web 路径）
|
||||
|
||||
Reference in New Issue
Block a user