feat: EPUB 阅读器搜索、选中注释、书签 chrome 状态及大量重构优化

- 新增 RDEPUBReaderSearchCoordinator 与 RDEPUBSelectionState 管理搜索和选中状态
- 新增 BookmarkChromeStateTests、NavigationBackwardTests、SelectionAnnotateTests 等 UI 测试
- 新增多个边界测试 epub 样本（损坏结构、空归档、缺失文件、流式外链验证）
- 重构阅读器 chrome 状态管理，统一 tool bar 与 search bar 交互
- 优化大书分页缓存策略（RDEPUBChapterSummaryDiskCache、RDEPUBPageCountCache）
- 移除废弃的 RDEPUBLocationConverter 和 RDEPUBPageBreakPolicy
- 更新 epub-bridge.js 与 JS bridge 通信协议
- 全面更新现有 UI 测试以适配新的 helper 和状态管理

Sources/RDReaderView/EPUBUI/ReaderController/ChapterRuntime/RDEPUBChapterSummaryDiskCache.swift

@@ -34,8 +34,28 @@ final class RDEPUBChapterSummaryDiskCache {
 
     func read(for key: RDEPUBChapterCacheKey) -> RDEPUBChapterSummary? {
         let fileURL = self.fileURL(for: key)
-        guard let data = try? Data(contentsOf: fileURL) else { return nil }
-        return try? JSONDecoder().decode(RDEPUBChapterSummary.self, from: data)
+        let data: Data
+        do {
+            data = try Data(contentsOf: fileURL)
+        } catch {
+            let nsError = error as NSError
+            if nsError.domain == NSCocoaErrorDomain && nsError.code == NSFileReadNoSuchFileError {
+                // 文件不存在属于正常缓存未命中，不报错
+            } else {
+                #if DEBUG
+                print("[RDEPUBChapterSummaryDiskCache] ⚠️ read IO error for \(fileURL.lastPathComponent): \(error.localizedDescription)")
+                #endif
+            }
+            return nil
+        }
+        do {
+            return try JSONDecoder().decode(RDEPUBChapterSummary.self, from: data)
+        } catch {
+            #if DEBUG
+            print("[RDEPUBChapterSummaryDiskCache] ⚠️ decode error for \(fileURL.lastPathComponent): \(error.localizedDescription)")
+            #endif
+            return nil
+        }
     }
 
     // MARK: - 批量读取：二次打开时直接从磁盘构建 BookPageMap
@@ -75,32 +95,78 @@ final class RDEPUBChapterSummaryDiskCache {
         return true
     }
 
-    /// 语义化别名：用于判断当前 renderSignature 下是否具备完整章节摘要集合。
-    func containsCompleteSet(keys: [RDEPUBChapterCacheKey]) -> Bool {
-        isCacheComplete(keys: keys)
-    }
-
     /// 清空所有缓存文件
     func removeAll() {
-        guard let files = try? fileManager.contentsOfDirectory(at: cacheDirectory, includingPropertiesForKeys: nil) else { return }
-        for fileURL in files where fileURL.pathExtension == "json" {
-            try? fileManager.removeItem(at: fileURL)
+        removeFiles(matching: { _ in true })
+    }
+
+    /// 清空指定书籍的所有缓存文件
+    func removeAll(forBookID bookID: String) {
+        let bookPrefix = Self.cacheNamespacePrefix(for: bookID)
+        removeFiles { $0.hasPrefix(bookPrefix + "__") }
+    }
+
+    /// 清空指定渲染签名下的所有缓存文件
+    func removeAll(forRenderSignature renderSignature: String) {
+        let renderPrefix = "__" + Self.cacheNamespacePrefix(for: renderSignature) + "__"
+        removeFiles { $0.contains(renderPrefix) }
+    }
+
+    /// 缓存统计信息
+    var cacheStatistics: (fileCount: Int, totalBytes: Int64) {
+        guard let files = try? fileManager.contentsOfDirectory(at: cacheDirectory, includingPropertiesForKeys: [.fileSizeKey]) else {
+            return (0, 0)
         }
+        var count = 0
+        var totalBytes: Int64 = 0
+        for fileURL in files where fileURL.pathExtension == "json" {
+            count += 1
+            if let size = try? fileURL.resourceValues(forKeys: [.fileSizeKey]).fileSize {
+                totalBytes += Int64(size)
+            }
+        }
+        return (count, totalBytes)
     }
 
     // MARK: - key -> 文件路径
 
     /// 使用确定性字符串拼接生成文件名，不依赖 Hashable.hashValue
     private func fileURL(for key: RDEPUBChapterCacheKey) -> URL {
+        let bookPrefix = Self.cacheNamespacePrefix(for: key.bookID)
+        let renderPrefix = Self.cacheNamespacePrefix(for: key.renderSignature)
         let rawKey = "\(key.bookID)_\(key.spineIndex)_\(key.renderSignature)_\(key.chapterContentHash)"
         let digest = rawKey.sha256Hex
-        return cacheDirectory.appendingPathComponent("\(digest).json")
+        return cacheDirectory.appendingPathComponent("\(bookPrefix)__\(renderPrefix)__\(digest).json")
     }
 
     private func writeImmediately(summary: RDEPUBChapterSummary, for key: RDEPUBChapterCacheKey) {
         let fileURL = self.fileURL(for: key)
-        let data = try? JSONEncoder().encode(summary)
-        try? data?.write(to: fileURL)
+        let tmpURL = fileURL.appendingPathExtension("tmp")
+        do {
+            let data = try JSONEncoder().encode(summary)
+            try data.write(to: tmpURL)
+            if fileManager.fileExists(atPath: fileURL.path) {
+                _ = try fileManager.replaceItemAt(fileURL, withItemAt: tmpURL)
+            } else {
+                try fileManager.moveItem(at: tmpURL, to: fileURL)
+            }
+        } catch {
+            #if DEBUG
+            print("[RDEPUBChapterSummaryDiskCache] ⚠️ write error for \(fileURL.lastPathComponent): \(error.localizedDescription)")
+            #endif
+            try? fileManager.removeItem(at: tmpURL)
+        }
+    }
+
+    private func removeFiles(matching predicate: (String) -> Bool) {
+        guard let files = try? fileManager.contentsOfDirectory(at: cacheDirectory, includingPropertiesForKeys: nil) else { return }
+        for fileURL in files where fileURL.pathExtension == "json" && predicate(fileURL.lastPathComponent) {
+            try? fileManager.removeItem(at: fileURL)
+        }
+    }
+
+    private static func cacheNamespacePrefix(for rawValue: String) -> String {
+        rawValue.sha256Hex.prefix(12).lowercased()
     }
 }