Reorganize docs and update reader search flows

2026-06-10 08:22:07 +08:00
parent 0e7c0577e3
commit d15187b730
72 changed files with 517 additions and 5214 deletions
@@ -1,6 +1,6 @@
 # ReadViewSDK 系统架构文档

-> 最后更新：2026-06-04
+> 最后更新：2026-06-09

 ---

@@ -67,22 +67,27 @@ ReadViewSDK 是一个 iOS EPUB 阅读器 SDK，支持文本重排（Reflowable
 用户点击书籍
    │
    ▼
-RDEPUBReaderController.openBook(epubURL:)
+RDEPUBReaderController(epubURL:delegate:persistence:)  // 初始化，传入 epubURL
    │
-    ├─ RDEPUBParser.parse(epubURL:)           // 解压 ZIP → 解析 OPF → 构建 spine/TOC
-    │      └─ extractArchiveIfNeeded()        // ZIPFoundation 解压到 Caches
-    │      └─ parseContainerRootFile()        // SAX 解析 container.xml
-    │      └─ parseOPF()                      // SAX 解析 OPF (metadata/manifest/spine)
-    │      └─ parseTOC()                      // NCX 或 Navigation Document
+    ├─ viewDidLoad() → startInitialLoadIfNeeded()
+    │   │
+    │   ├─ RDEPUBReaderLoadCoordinator.startInitialLoadIfNeeded()
+    │   │   ├─ RDEPUBParser.parse(epubURL:)           // 解压 ZIP → 解析 OPF → 构建 spine/TOC
+    │   │   │      └─ extractArchiveIfNeeded()        // ZIPFoundation 解压到 Caches
+    │   │   │      └─ parseContainerRootFile()        // SAX 解析 container.xml
+    │   │   │      └─ parseOPF()                      // SAX 解析 OPF (metadata/manifest/spine)
+    │   │   │      └─ parseTOC()                      // NCX 或 Navigation Document
+    │   │   │
+    │   │   ├─ RDEPUBPublication(parser:)             // 创建门面对象
+    │   │   ├─ 恢复持久化数据（书签/高亮/位置）
+    │   │   └─ applyParsedPublication()
+    │   │
+    │   └─ 判断 readingProfile:
+    │       ├─ .textReflowable → 文本排版路径（本 SDK 核心路径）
+    │       ├─ .webInteractive → WebView 渲染路径
+    │       └─ .webFixedLayout → 固定布局路径
    │
-    ├─ RDEPUBPublication(parser:)             // 创建门面对象
-    │
-    ├─ 判断 readingProfile:
-    │   ├─ .textReflowable → 文本排版路径（本 SDK 核心路径）
-    │   ├─ .webInteractive → WebView 渲染路径
-    │   └─ .webFixedLayout → 固定布局路径
-    │
-    └─ paginateTextPublication()              // 进入分页流程
+    └─ runtime.paginatePublication()                  // 进入分页流程
 ```

 ### 3.2 文本重排分页流程（大书优化路径）
@@ -206,10 +211,17 @@ RDEPUBReaderController
    │   ├─ configuration, persistence
    │   └─ 便捷方法 (renderStyle, layoutConfig, cacheKey)
    │
-    ├─ RDEPUBReaderRuntime                  // 运行时协调器集合
+    ├─ RDEPUBReaderRuntime                  // 运行时协调器集合（Facade 模式）
    │   ├─ chapterLoader                    // 章节加载器
    │   ├─ chapterRuntimeStore              // 内存缓存
    │   ├─ summaryDiskCache                 // 磁盘摘要缓存
+    │   ├─ pageResolver                     // 页码解析器
+    │   ├─ loadCoordinator                  // 加载协调器
+    │   ├─ paginationCoordinator            // 分页协调器
+    │   ├─ locationCoordinator              // 位置协调器
+    │   ├─ searchCoordinator                // 搜索协调器
+    │   ├─ chromeCoordinator                // 工具栏协调器
+    │   ├─ annotationCoordinator            // 标注协调器
    │   └─ viewportMonitor                  // 视口变化监控
    │
    ├─ RDEPUBReaderPaginationCoordinator    // 分页协调器
@@ -335,7 +347,7 @@ Sources/RDReaderView/
 │   │   ├── cssInjector.js
 │   │   ├── WeReadApi.js
 │   │   ├── rangy-core.js / rangy-serializer.js
-│   │   ├── wxread-default.css / wxread-dark.css / wxread-replace.css
+│   │   ├── wxread-default.css / wxread-dark.css / wxread-replace-latin.css
 │   │   └── epub-fixed-layout.html
 │   ├── RDEPUBParser.swift             # 核心解析器
 │   ├── RDEPUBParser+Archive.swift     # ZIP 解压
@@ -398,27 +410,38 @@ Sources/RDReaderView/
    │   │   ├── RDEPUBChapterLoader.swift
    │   │   ├── RDEPUBChapterRuntimeStore.swift
    │   │   ├── RDEPUBChapterSummaryDiskCache.swift
-    │   │   ├── RDEPUBChapterCacheKey.swift
    │   │   ├── RDEPUBBookPageMap.swift
-    │   │   ├── RDEPUBChapterSummary.swift
+    │   │   ├── RDEPUBPageResolver.swift
    │   │   └── ...
    │   ├── RDEPUBReaderContext.swift           // 共享状态中心
-    │   ├── RDEPUBReaderRuntime.swift           // 运行时协调器
+    │   ├── RDEPUBReaderRuntime.swift           // 运行时协调器（Facade）
+    │   ├── RDEPUBReaderDependencies.swift     // 依赖注入
+    │   ├── RDEPUBReaderLoadCoordinator.swift  // 加载协调器
    │   ├── RDEPUBReaderPaginationCoordinator.swift  // 分页协调器
-    │   ├── RDEPUBReaderAnnotationCoordinator.swift  // 标注协调器
+    │   ├── RDEPUBReaderLocationCoordinator.swift    // 位置协调器
    │   ├── RDEPUBReaderSearchCoordinator.swift      // 搜索协调器
-    │   ├── RDEPUBReaderNavigationCoordinator.swift  // 导航协调器
+    │   ├── RDEPUBReaderChromeCoordinator.swift      // 工具栏协调器
+    │   ├── RDEPUBReaderAnnotationCoordinator.swift  // 标注协调器
+    │   ├── RDEPUBReaderAssemblyCoordinator.swift    // 组装协调器
+    │   ├── RDEPUBReaderViewportMonitor.swift        // 视口监控
    │   └── ...
    ├── Settings/                      # 设置面板
-    │   ├── RDEPUBReaderSettingsViewController.swift
-    │   ├── RDEPUBReaderThemeSelector.swift
+    │   ├── RDEPUBReaderConfiguration.swift    # 配置模型
+    │   ├── RDEPUBReaderSettings.swift         # 持久化设置
+    │   ├── RDEPUBReaderSettingsViewController.swift  # 设置面板 VC
+    │   ├── RDEPUBReaderTheme.swift            # 主题定义
    │   └── ...
    ├── TextPage/                      # 文本页面渲染
-    │   ├── RDEPUBTextContentView.swift
-    │   ├── RDEPUBTextPageViewController.swift
+    │   ├── RDEPUBTextContentView.swift        # 文本内容视图（CoreText）
+    │   ├── RDEPUBTextSelectionController.swift # 文本选择控制器
+    │   ├── RDEPUBPageInteractionController.swift # 点击交互控制器
+    │   ├── RDEPUBSelectionOverlayView.swift   # 选区覆盖层
+    │   ├── RDEPUBTextAnnotationOverlay.swift  # 标注覆盖层
+    │   ├── RDEPUBTextPageRenderView.swift     # CoreText 绘制视图
    │   └── ...
-    ├── RDEPUBReaderController.swift   # 主控制器
-    ├── RDEPUBReaderConfiguration.swift # 配置模型
+    ├── RDEPUBReaderController.swift   # 主控制器（+ContentDelegates/DataSource/PublicAPI 等扩展）
+    ├── RDEPUBReaderDelegate.swift     # 公开委托协议
+    ├── RDEPUBReaderPersistence.swift  # 持久化协议
    └── ...
 ```

@@ -432,7 +455,7 @@ Sources/RDReaderView/
 | **Facade** | `RDEPUBPublication` 封装 `RDEPUBParser`，`RDEPUBChapterData` 封装章节查询 |
 | **Builder** | `RDEPUBBookPageMap.Builder` 增量构建页码映射 |
 | **Strategy** | `RDEPUBTextRenderer` 协议，可替换渲染器实现 |
-| **Pipeline** | `RDEPUBTextTypesetterPipeline` 8 阶段排版管线 |
+| **Pipeline** | `RDEPUBTextTypesetterPipeline` 排版管线（8 个逻辑阶段，封装为 5-6 个顶层调用） |
 | **State Machine** | `RDEPUBNavigatorState` 管理阅读器状态转换 |
 | **Adapter** | `RDReaderLegacyDataSourceAdapter` 适配旧数据源协议 |
 | **三级缓存** | 内存 → 磁盘摘要 → 全书分页，逐级降级 |