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、状态机、内存警告、预加载、位置恢复等
2026-06-23 08:17:08 +08:00
parent c65c190b71
commit 7de661eb54
29 changed files with 3297 additions and 658 deletions
@@ -0,0 +1,77 @@
+import Foundation
+
+enum RDEPUBNavigationState: Equatable {
+    case idle
+    case initialLoading
+    case restoringLocation
+    case preparingChapter(spineIndex: Int)
+    case presentingWindow
+    case reconcilingFullMap
+    case repaginating
+}
+
+final class RDEPUBNavigationStateMachine {
+
+    private let lock = NSLock()
+
+    private(set) var state: RDEPUBNavigationState = .idle
+
+    func transition(to newState: RDEPUBNavigationState) {
+        lock.lock()
+        let oldState = state
+        state = newState
+        lock.unlock()
+        #if DEBUG
+        validateTransition(from: oldState, to: newState)
+        #endif
+    }
+
+    #if DEBUG
+    private func validateTransition(from oldState: RDEPUBNavigationState, to newState: RDEPUBNavigationState) {
+        let isValid: Bool
+        switch (oldState, newState) {
+        case (.idle, .initialLoading),
+             (.idle, .preparingChapter),
+             (.idle, .restoringLocation),
+             (.idle, .idle):
+            isValid = true
+        case (.initialLoading, .preparingChapter),
+             (.initialLoading, .presentingWindow),
+             (.initialLoading, .idle),
+             (.initialLoading, .initialLoading):
+            isValid = true
+        case (.restoringLocation, .preparingChapter),
+             (.restoringLocation, .presentingWindow),
+             (.restoringLocation, .idle),
+             (.restoringLocation, .restoringLocation):
+            isValid = true
+        case (.preparingChapter, .presentingWindow),
+             (.preparingChapter, .preparingChapter),
+             (.preparingChapter, .idle):
+            isValid = true
+        case (.presentingWindow, .idle),
+             (.presentingWindow, .reconcilingFullMap),
+             (.presentingWindow, .preparingChapter),
+             (.presentingWindow, .presentingWindow),
+             (.presentingWindow, .repaginating):
+            isValid = true
+        case (.reconcilingFullMap, .presentingWindow),
+             (.reconcilingFullMap, .idle),
+             (.reconcilingFullMap, .reconcilingFullMap):
+            isValid = true
+        case (.repaginating, .presentingWindow),
+             (.repaginating, .idle),
+             (.repaginating, .repaginating):
+            isValid = true
+        default:
+            isValid = false
+        }
+        if !isValid {
+            RDEPUBBackgroundTrace.log(
+                "NavigationStateMachine",
+                "WARNING: unexpected transition \(oldState) → \(newState)"
+            )
+        }
+    }
+    #endif
+}