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

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

Sources/RDReaderView/EPUBCore/RDEPUBReadingSession.swift

@@ -1,33 +1,56 @@
+// RDEPUBReadingSession.swift
+// EPUB 阅读会话（状态机）
+// 管理阅读器的运行时状态：导航状态（initializing/loading/idle/jumping/moving/repaginating）、
+// 活跃页面列表、待应用的分页快照、挂起的导航请求、当前视口和阅读上下文。
+// 提供分页快照生成、位置计算、导航队列、阅读上下文更新等核心业务方法。
+
 import Foundation
 
+/// EPUB 阅读会话，管理导航状态、页面列表和阅读进度
+/// 状态机：initializing → loading → idle ↔ jumping/moving/repaginating
 public final class RDEPUBReadingSession {
+    /// 分页快照类型别名（页面数组 + 章节信息数组）
     public typealias PaginationSnapshot = (pages: [EPUBPage], chapters: [EPUBChapterInfo])
 
+    /// 关联的出版物
     public let publication: RDEPUBPublication
 
+    /// 当前导航状态
     public private(set) var navigatorState: RDEPUBNavigatorState = .initializing
+    /// 当前生效的页面列表
     public private(set) var activePages: [EPUBPage] = []
+    /// 当前生效的章节信息列表
     public private(set) var activeChapters: [EPUBChapterInfo] = []
+    /// 暂存的待应用页面列表（分页计算完成后暂存，等状态允许时才生效）
     public private(set) var stagedPages: [EPUBPage]?
+    /// 暂存的待应用章节信息列表
     public private(set) var stagedChapters: [EPUBChapterInfo]?
+    /// 暂存快照对应的恢复位置
     public private(set) var stagedRestoreLocation: RDEPUBLocation?
+    /// 挂起的导航目标位置（用于 fragment 精确定位）
     public private(set) var pendingNavigationLocation: RDEPUBLocation?
+    /// 挂起的导航目标页码
     public private(set) var pendingNavigationPageNum: Int?
+    /// 当前视口信息
     public private(set) var currentViewport: RDEPUBViewport?
+    /// 当前阅读上下文（位置 + 视口 + 页码 + 章节）
     public private(set) var currentReadingContext: RDEPUBReadingContext?
 
     public init(publication: RDEPUBPublication) {
         self.publication = publication
     }
 
+    /// 资源解析器快捷访问
     public var resourceResolver: RDEPUBResourceResolver {
         publication.resourceResolver
     }
 
+    /// 状态机转换
     public func transition(to state: RDEPUBNavigatorState) {
         navigatorState = state
     }
 
+    /// 重置所有运行时状态（回到 initializing）
     public func resetRuntimeState() {
         navigatorState = .initializing
         activePages = []
@@ -38,17 +61,20 @@ public final class RDEPUBReadingSession {
         currentReadingContext = nil
     }
 
+    /// 设置当前生效的分页快照
     public func setActiveSnapshot(_ snapshot: PaginationSnapshot) {
         activePages = snapshot.pages
         activeChapters = snapshot.chapters
     }
 
+    /// 暂存分页快照（待状态允许时才生效）
     public func stageSnapshot(_ snapshot: PaginationSnapshot, restoreLocation: RDEPUBLocation?) {
         stagedPages = snapshot.pages
         stagedChapters = snapshot.chapters
         stagedRestoreLocation = restoreLocation
     }
 
+    /// 获取暂存的分页快照
     public func stagedSnapshot() -> PaginationSnapshot? {
         guard let stagedPages, let stagedChapters else {
             return nil
@@ -56,6 +82,7 @@ public final class RDEPUBReadingSession {
         return (stagedPages, stagedChapters)
     }
 
+    /// 如果状态稳定且有暂存快照，则消费并返回（原子操作）
     public func consumeStagedSnapshotIfAllowed() -> (snapshot: PaginationSnapshot, restoreLocation: RDEPUBLocation?)? {
         guard navigatorState.isStableForSnapshotApplication,
               let stagedPages,
@@ -67,17 +94,20 @@ public final class RDEPUBReadingSession {
         return ((stagedPages, stagedChapters), restoreLocation)
     }
 
+    /// 清除暂存快照
     public func clearStagedSnapshot() {
         stagedPages = nil
         stagedChapters = nil
         stagedRestoreLocation = nil
     }
 
+    /// 清除挂起的导航请求
     public func clearPendingNavigation() {
         pendingNavigationLocation = nil
         pendingNavigationPageNum = nil
     }
 
+    /// 检查指定页码和 spine 索引是否有挂起的导航位置
     public func pendingLocation(forPageNumber pageNumber: Int, spineIndex: Int?) -> RDEPUBLocation? {
         guard pendingNavigationPageNum == pageNumber,
               let pendingNavigationLocation else {
@@ -93,6 +123,7 @@ public final class RDEPUBReadingSession {
         return pendingNavigationLocation
     }
 
+    /// 判断指定页面是否包含给定的 spine 索引（固定版式需检查 spread 内所有资源）
     public func pageContains(spineIndex: Int, in page: EPUBPage) -> Bool {
         if let fixedSpread = page.fixedSpread {
             return fixedSpread.resources.contains(where: { $0.spineIndex == spineIndex })
@@ -100,6 +131,7 @@ public final class RDEPUBReadingSession {
         return page.spineIndex == spineIndex
     }
 
+    /// 根据页面信息生成回退位置（用于无精确位置时的兜底）
     public func fallbackLocation(for page: EPUBPage, bookIdentifier: String?) -> RDEPUBLocation? {
         if let fixedSpread = page.fixedSpread {
             return RDEPUBLocation(
@@ -129,6 +161,7 @@ public final class RDEPUBReadingSession {
         )
     }
 
+    /// 获取当前可见页面对应的位置
     public func currentVisibleLocation(currentPageNumber: Int, bookIdentifier: String?) -> RDEPUBLocation? {
         guard currentPageNumber > 0,
               activePages.indices.contains(currentPageNumber - 1) else {
@@ -137,6 +170,7 @@ public final class RDEPUBReadingSession {
         return fallbackLocation(for: activePages[currentPageNumber - 1], bookIdentifier: bookIdentifier)
     }
 
+    /// 根据位置获取初始 spine 索引
     public func initialSpineIndex(for location: RDEPUBLocation?) -> Int {
         guard let location,
               let normalizedHref = resourceResolver.normalizedHref(location.href),
@@ -146,6 +180,7 @@ public final class RDEPUBReadingSession {
         return spineIndex
     }
 
+    /// 根据位置计算对应的页面索引（支持固定版式和重排模式）
     public func pageIndex(for location: RDEPUBLocation, bookIdentifier: String?) -> Int? {
         guard location.bookIdentifier == nil || location.bookIdentifier == bookIdentifier else {
             return nil
@@ -186,6 +221,7 @@ public final class RDEPUBReadingSession {
         return candidates[localIndex].offset
     }
 
+    /// 排队导航到指定位置：规范化位置、查找页面索引、设置挂起导航、切换到 jumping 状态
     public func queueNavigation(
         to location: RDEPUBLocation,
         relativeToSpineIndex spineIndex: Int? = nil,
@@ -205,6 +241,7 @@ public final class RDEPUBReadingSession {
         return pageIndex + 1
     }
 
+    /// 更新阅读上下文：规范化位置、设置视口和阅读上下文、清除挂起导航、回到 idle 状态
     public func updateReadingContext(
         pageNumber: Int,
         location: RDEPUBLocation,
@@ -253,10 +290,13 @@ public final class RDEPUBReadingSession {
         }
     }
 
+    /// 获取当前阅读位置（优先从阅读上下文获取，回退到可见位置）
     public func currentReadingLocation(bookIdentifier: String?) -> RDEPUBLocation? {
         currentReadingContext?.location ?? currentVisibleLocation(currentPageNumber: currentViewport?.visiblePageNumber ?? 0, bookIdentifier: bookIdentifier)
     }
 
+    /// 根据分页计数和偏好设置生成分页快照
+    /// 固定版式按 spread 分页，重排模式按 spine 索引逐章分页
     public func makePaginationSnapshot(
         pageCounts: [Int],
         preferences: RDEPUBPreferences,