refactor: 添加中文注释 + 优化模块结构

- 给全部 78 个 Swift 源文件添加详细的中文注释（文件级、类级、方法级）
- 删除 LegacyRDReaderController/ 死代码目录（16 文件 4592 行）
- 根目录翻页容器文件移入 ReaderView/ 目录
- Resources/ 移入 EPUBCore/Resources/（与使用者归属一致）
- RDEPUBTextIndexTable.swift 移入 EPUBTextRendering/（消除反向依赖）
- RDURLReaderController.swift 移入 EPUBUI/（入口控制器归入 UI 层）
- 更新 podspec 资源路径

Sources/RDReaderView/EPUBCore/RDEPUBPaginator.swift

@@ -1,25 +1,45 @@
+// RDEPUBPaginator.swift
+// EPUB 离屏分页计算器
+// 使用隐藏的 WKWebView 加载每个 spine 项，通过 JS 测量 scrollWidth
+// 计算每章的页数。采用多轮延迟测量（0ms/80ms/180ms）确保布局稳定。
+// 固定版式（Fixed Layout）直接返回 1 页。
+
 import UIKit
 import WebKit
 
+/// EPUB 分页计算器，通过离屏 WebView 测量每个 spine 项的分页数
 public final class RDEPUBPaginator: NSObject {
+    /// 当前解析器引用
     private var parser: RDEPUBParser?
+    /// 承载 WebView 的父视图（弱引用）
     private weak var hostingView: UIView?
+    /// 当前展示样式（视口尺寸、内边距、字号、行高）
     private var presentation = RDEPUBPresentationStyle(
         viewportSize: .zero,
         contentInsets: .zero,
         fontSize: 16,
         lineHeightMultiple: 1.5
     )
+    /// 全量分页完成回调（返回每个 spine 项的页数数组）
     private var completion: (([Int]) -> Void)?
+    /// 单个 spine 项分页完成回调
     private var singlePageCountCompletion: ((Int) -> Void)?
+    /// 各 spine 项的页数结果
     private var pageCounts: [Int] = []
+    /// 待测量的 spine 项索引列表
     private var measurementIndices: [Int] = []
+    /// 当前测量偏移量（在 measurementIndices 中的位置）
     private var currentMeasurementOffset = 0
+    /// 当前 spine 项的待定页数（多轮测量取最大值）
     private var pendingMeasurementValue = 1
+    /// 当前测量轮次（0/1/2 对应延迟 0ms/80ms/180ms）
     private var measurementPass = 0
+    /// 当前测量会话 ID，用于防并发和取消过期任务
     private var activeSessionID = UUID()
+    /// 调试日志作用域标识
     private let debugScope = "PaginatorWebView"
 
+    /// 用于分页测量的隐藏 WebView（非持久化数据存储，禁止用户交互）
     private lazy var webView: WKWebView = {
         let configuration = WKWebViewConfiguration()
         configuration.websiteDataStore = .nonPersistent()
@@ -52,6 +72,12 @@ public final class RDEPUBPaginator: NSObject {
         webView.removeFromSuperview()
     }
 
+    /// 计算所有 spine 项的分页数
+    /// - Parameters:
+    ///   - parser: EPUB 解析器
+    ///   - hostingView: 承载 WebView 的父视图
+    ///   - presentation: 展示样式（视口、内边距、字号、行高）
+    ///   - completion: 完成回调，返回每个 spine 项的页数数组
     public func calculate(
         parser: RDEPUBParser,
         hostingView: UIView,
@@ -82,6 +108,7 @@ public final class RDEPUBPaginator: NSObject {
         measureNextSpineItem()
     }
 
+    /// 便捷方法：使用独立参数计算所有 spine 项的分页数
     public func calculate(
         parser: RDEPUBParser,
         hostingView: UIView,
@@ -104,6 +131,13 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
+    /// 仅计算单个 spine 项的分页数
+    /// - Parameters:
+    ///   - parser: EPUB 解析器
+    ///   - spineIndex: 要测量的 spine 项索引
+    ///   - hostingView: 承载 WebView 的父视图
+    ///   - presentation: 展示样式
+    ///   - completion: 完成回调，返回该 spine 项的页数
     public func calculateSingleSpinePageCount(
         parser: RDEPUBParser,
         spineIndex: Int,
@@ -135,6 +169,7 @@ public final class RDEPUBPaginator: NSObject {
         measureNextSpineItem()
     }
 
+    /// 便捷方法：使用独立参数计算单个 spine 项的分页数
     public func calculateSingleSpinePageCount(
         parser: RDEPUBParser,
         spineIndex: Int,
@@ -159,6 +194,7 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
+    /// 静态方法：将分页 CSS 注入到 HTML 字符串中（用于预渲染场景）
     public static func injectPaginationCSS(
         into html: String,
         viewportSize: CGSize,
@@ -181,6 +217,7 @@ public final class RDEPUBPaginator: NSObject {
         )
     }
 
+    /// 测量下一个 spine 项：加载文件到 WebView，跳过不可渲染或文件缺失的项
     private func measureNextSpineItem() {
         guard let parser else {
             finishIfNeeded()
@@ -218,10 +255,12 @@ public final class RDEPUBPaginator: NSObject {
         webView.loadFileURL(fileURL, allowingReadAccessTo: readAccessURL)
     }
 
+    /// 获取当前正在测量的 spine 项索引
     private func currentSpineIndexForMeasurement() -> Int? {
         measurementIndices[safe: currentMeasurementOffset]
     }
 
+    /// 检查是否所有 spine 项都已测量完毕，触发对应的完成回调
     private func finishIfNeeded() {
         if let singlePageCountCompletion {
             let measuredSpineIndex = measurementIndices.first ?? 0
@@ -236,6 +275,7 @@ public final class RDEPUBPaginator: NSObject {
         cleanupMeasurementState()
     }
 
+    /// 清理测量状态，释放 WebView 和所有引用
     private func cleanupMeasurementState() {
         parser = nil
         hostingView = nil
@@ -251,11 +291,13 @@ public final class RDEPUBPaginator: NSObject {
         webView.removeFromSuperview()
     }
 
+    /// 判断 spine 项是否可渲染（仅 HTML/XHTML/XML 类型可分页）
     private func isRenderablePage(item: RDEPUBSpineItem) -> Bool {
         let mediaType = item.mediaType.lowercased()
         return mediaType.contains("html") || mediaType.contains("xhtml") || mediaType.contains("xml")
     }
 
+    /// 调度多轮测量：0ms/80ms/180ms 三轮延迟，取最大值以应对布局抖动
     private func scheduleMeasurementPass() {
         let sessionID = activeSessionID
         let delays: [TimeInterval] = [0.0, 0.08, 0.18]
@@ -278,6 +320,7 @@ public final class RDEPUBPaginator: NSObject {
         }
     }
 
+    /// 执行当前文档的测量：通过 JS 获取 scrollWidth 并计算页数
     private func measureCurrentDocument(sessionID: UUID) {
         let script = RDEPUBStyleSheetBuilder.measurementScript(for: presentation)
         RDEPUBWebViewDebug.logJavaScript(debugScope, webView: webView, action: "measure", details: "session=\(sessionID) pass=\(measurementPass)")
@@ -332,6 +375,7 @@ extension RDEPUBPaginator: WKNavigationDelegate {
     }
 }
 
+/// Array 安全下标扩展，越界时返回 nil 而非崩溃
 private extension Array {
     subscript(safe index: Int) -> Element? {
         indices.contains(index) ? self[index] : nil