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

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

Sources/RDReaderView/EPUBCore/RDEPUBSearchEngine.swift

@@ -1,12 +1,22 @@
+// RDEPUBSearchEngine.swift
+// EPUB 全文搜索引擎
+// 遍历 spine 中的线性 HTML/XHTML 资源，提取纯文本后执行大小写不敏感的关键词搜索，
+// 返回匹配项列表（含 href、progression、previewText 等）。
+
 import Foundation
 import UIKit
 
+/// 搜索引擎协议，定义全文搜索接口
 protocol RDEPUBSearchEngine {
     func search(keyword: String) -> [RDEPUBSearchMatch]
 }
 
+/// HTML 全文搜索引擎实现
+/// 通过解析 HTML 为纯文本，逐章执行关键词匹配
 final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
+    /// EPUB 解析器（用于读取 HTML 内容）
     private let parser: RDEPUBParser
+    /// EPUB 出版物（用于遍历 spine 和规范化 href）
     private let publication: RDEPUBPublication
 
     init(parser: RDEPUBParser, publication: RDEPUBPublication) {
@@ -14,6 +24,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
         self.publication = publication
     }
 
+    /// 执行全文搜索：遍历所有线性 spine 项，提取纯文本后匹配关键词
     func search(keyword: String) -> [RDEPUBSearchMatch] {
         let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !normalizedKeyword.isEmpty else {
@@ -35,6 +46,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
         return searchMatches
     }
 
+    /// 将 HTML 转换为纯文本（优先使用 NSAttributedString，失败时用正则兜底）
     private func plainText(fromHTML html: String, baseURL: URL?) -> String {
         guard let data = html.data(using: .utf8) else {
             return fallbackPlainText(fromHTML: html)
@@ -54,6 +66,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
         return fallbackPlainText(fromHTML: html)
     }
 
+    /// 兜底方案：用正则去除 HTML 标签并解码 HTML 实体
     private func fallbackPlainText(fromHTML html: String) -> String {
         let stripped = html.replacingOccurrences(of: "<[^>]+>", with: " ", options: .regularExpression)
         return stripped
@@ -65,6 +78,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
             .replacingOccurrences(of: "&quot;", with: "\"")
     }
 
+    /// 在纯文本中查找所有关键词匹配项（大小写不敏感）
     private func matches(in text: String, href: String, keyword: String) -> [RDEPUBSearchMatch] {
         let source = text as NSString
         let fullLength = source.length
@@ -106,6 +120,7 @@ final class RDEPUBHTMLSearchEngine: RDEPUBSearchEngine {
         return results
     }
 
+    /// 截取匹配位置前后的文本作为预览（前后各 12 个字符）
     private func previewText(in text: NSString, matchRange: NSRange) -> String {
         let previewRadius = 12
         let start = max(matchRange.location - previewRadius, 0)