docs: 补充注释、修正过时文档、清理重复内容

源码注释：
- 为 ~60 个 Swift 文件补充缺失的 doc comment（file header、类型、属性、方法）
- 修正 4 处错误注释：翻页模式数量、搜索行为描述、手势识别器描述、悬空文档块

文档维护：
- 删除重复文档：WXRead/读书EPUB阅读器实现架构.md（与微信读书版完全一致）
- 合并重叠文档：阅读器规划.md → 阅读器功能开发计划.md（单一真值）
- 修正过时内容：所有文档中"四种翻页模式"→"三种"，移除 horizontalCoverScroll
- 更新架构图：补齐 EPUBUI/ReaderController、Paging/、Typesetter/ 等子目录
- 更新 index.md 索引：新增开发计划和架构对比文档引用

Sources/RDReaderView/ReaderView/Paging/RDReaderPreloadController.swift

@@ -1,6 +1,17 @@
+//
+//  RDReaderPreloadController.swift
+//  ReadViewSDK
+//
+//  文件职责：页面预加载控制器，负责提前渲染即将显示的页面视图以减少翻页卡顿。
+//
+
 import UIKit
 
+/// 页面预加载控制器
+/// 负责管理页面视图的预加载和缓存，在当前页面基础上提前渲染前后若干页，
+/// 以减少翻页时的等待时间。支持仿真翻页和滚动模式下的不同复用策略。
 final class RDReaderPreloadController {
+    /// 预加载半径，表示在当前页前后各预加载的页数，默认为 1
     var radius: Int = 1
 
     private let preloadHostView = UIView()
@@ -8,6 +19,7 @@ final class RDReaderPreloadController {
     private var pageCurlCachedViews: [Int: UIView] = [:]
     private var cacheSignature: CacheSignature?
 
+    /// 预加载环境参数，封装翻页模式、屏幕方向、页面尺寸等上下文信息
     struct Environment {
         let displayType: RDReaderView.DisplayType
         let isLandscape: Bool
@@ -26,10 +38,12 @@ final class RDReaderPreloadController {
         let boundsSize: CGSize
     }
 
+    /// 设置预加载宿主视图的 frame
     func setHostFrame(_ frame: CGRect) {
         preloadHostView.frame = frame
     }
 
+    /// 将预加载宿主视图添加到父视图中（如果尚未添加），置于最底层且不可见
     func ensureHostView(in parentView: UIView) {
         guard preloadHostView.superview == nil else { return }
         preloadHostView.isHidden = true
@@ -40,10 +54,12 @@ final class RDReaderPreloadController {
         parentView.insertSubview(preloadHostView, at: 0)
     }
 
+    /// 根据当前环境初始化缓存签名，用于后续检测环境是否发生变化
     func initializeSignature(_ environment: Environment) {
         cacheSignature = currentCacheSignature(environment)
     }
 
+    /// 清除所有已缓存的页面视图并更新缓存签名
     func invalidate(environment: Environment) {
         pageCurlCachedViews.values.forEach { $0.removeFromSuperview() }
         preloadedPageViews.values.forEach { $0.removeFromSuperview() }
@@ -52,6 +68,7 @@ final class RDReaderPreloadController {
         cacheSignature = currentCacheSignature(environment)
     }
 
+    /// 获取指定页码的页面视图用于显示，优先复用已缓存的视图
     func pageViewForDisplay(
         pageNum: Int,
         environment: Environment,
@@ -63,12 +80,14 @@ final class RDReaderPreloadController {
         return view
     }
 
+    /// 取出指定页码的预加载视图并从缓存中移除，供外部复用
     func takePreloadedView(for pageNum: Int) -> UIView? {
         let preloaded = preloadedPageViews.removeValue(forKey: pageNum)
         preloaded?.removeFromSuperview()
         return preloaded
     }
 
+    /// 预加载当前页周围指定半径内的页面，清除不再需要的缓存视图
     func prime(
         around pageNum: Int,
         preferredForward: Bool? = nil,

Sources/RDReaderView/ReaderView/Paging/RDReaderSpreadResolver.swift

@@ -1,6 +1,17 @@
+//
+//  RDReaderSpreadResolver.swift
+//  ReadViewSDK
+//
+//  文件职责：页面展开（spread）解析器，负责计算双页模式下的页面配对和翻页目标。
+//
+
 import Foundation
 
+/// 页面展开解析器
+/// 处理横屏双页模式下的页码配对逻辑，包括封面页独占、双页对齐、
+/// 以及相邻页面跳转等计算。
 struct RDReaderSpreadResolver {
+    /// 判断指定页码是否为全屏独占页面（如封面页在双页模式下独占一屏）
     func isFullScreenPage(
         _ pageNum: Int,
         landscapeDualPageEnabled: Bool,
@@ -11,6 +22,8 @@ struct RDReaderSpreadResolver {
         return pageNum == coverIndex
     }
 
+    /// 计算指定页码在双页模式下的左右页配对，返回 (左页, 右页?)。
+    /// 封面页独占时单独处理，后续页面按两页一组配对。
     func dualPagePair(
         for pageNum: Int,
         totalPages: Int,
@@ -32,6 +45,7 @@ struct RDReaderSpreadResolver {
         return (left, right)
     }
 
+    /// 计算从指定页码出发的下一个（或上一个）双页展开的起始页码
     func adjacentDualPage(
         from pageNum: Int,
         totalPages: Int,
@@ -49,6 +63,7 @@ struct RDReaderSpreadResolver {
         return dualPagePair(for: prevEnd, totalPages: totalPages, coverPageIndex: coverPageIndex).left
     }
 
+    /// 计算下一页（或上一页）的页码，自动根据单页/双页模式选择合适的算法
     func nextPage(
         from currentPage: Int,
         totalPages: Int,

Sources/RDReaderView/ReaderView/Paging/RDReaderTapRegionHandler.swift

@@ -1,6 +1,20 @@
+//
+//  RDReaderTapRegionHandler.swift
+//  ReadViewSDK
+//
+//  文件职责：点击区域判定处理器，将屏幕点击坐标映射为翻页或工具栏操作事件。
+//
+
 import CoreGraphics
 
+/// 点击区域判定处理器
+/// 将屏幕三等分为左、中、右三个区域，根据点击位置和工具栏可见状态
+/// 决定触发上一页、下一页还是切换工具栏。
 struct RDReaderTapRegionHandler {
+    /// 根据点击坐标和视图尺寸，解析点击事件类型
+    /// - 左1/3区域：上一页（工具栏可见时转为 center）
+    /// - 中1/3区域：切换工具栏
+    /// - 右1/3区域：下一页（工具栏可见时转为 center）
     func resolveTapEvent(
         point: CGPoint,
         viewFrame: CGRect,