修复阅读器资源、朗读与持久化稳定性

阅读器在多会话朗读、加密 EPUB 资源、并发打开同一本书和多 UserDefaults 容器等场景下，存在旧异步结果覆盖新状态、锁屏控制串会话、大型明文资源被误拒绝、解压半成品被复用及标注跨容器混用的风险；同时高亮、书签、搜索和设置面板的空状态与自动化可访问性入口不完整。\n\n本次为朗读会话引入代次和当前 utterance 校验，远程控制改为仅响应当前会话并按自身 token 清理；加密资源 provider 先判定是否实际返回解密数据，明文大资源继续流式读取；解压缓存串行化以避免并发复用未完成目录。书签与高亮迁移至受保护文件，按 UserDefaults 容器隔离命名空间，保留标准容器旧文件兼容并确保新副本成功落盘后才删除历史数据。\n\n同步调整缓存淘汰、FoundationModels 弱链接、搜索/标注/设置面板交互与 UI 测试，并更新 Pod 生成配置及 API、风险文档。已执行 git diff --check 和 ReadViewDemo Debug Simulator 构建，结果为 BUILD SUCCEEDED。
2026-07-30 20:52:21 +09:00
parent e01cbc169d
commit 3e60bf1869
40 changed files with 3210 additions and 2691 deletions
@@ -169,4 +169,74 @@ extension XCUIApplication {
    private func readerChromeIsVisible(requiredButtonIDs: [String]) -> Bool {
        requiredButtonIDs.allSatisfy { buttons[$0].exists }
    }
+
+    // MARK: - 设置面板
+
+    /// 等 EPUB 设置面板出现。面板已改成固定高度布局，所有控件一屏可见，
+    /// 既没有 scrollView 也不需要滚动才能触达。
+    @discardableResult
+    func waitForSettingsPanel(timeout: TimeInterval = 5) -> Bool {
+        if otherElements[IDs.settingsPanel].waitForExistence(timeout: timeout) {
+            return true
+        }
+        // 面板根视图偶尔不作为 otherElement 暴露，退回用「完成」按钮判定
+        return buttons[IDs.settingsDone].waitForExistence(timeout: 1)
+    }
+
+    /// 设置面板的字体/行距/翻页方式都是 pill 按钮 + action sheet，不是
+    /// segmentedControl：点开 pill 后再点选项标题。
+    @discardableResult
+    func selectSettingsPillOption(
+        pillIdentifier: String,
+        optionTitle: String,
+        timeout: TimeInterval = 5
+    ) -> Bool {
+        let pill = buttons[pillIdentifier]
+        guard pill.waitForExistence(timeout: timeout) else { return false }
+        pill.tap()
+
+        // action sheet 的选项在 iOS 上是 button，取消项同名风险由标题唯一性保证
+        let option = sheets.buttons[optionTitle].exists
+            ? sheets.buttons[optionTitle]
+            : buttons[optionTitle]
+        guard option.waitForExistence(timeout: timeout) else {
+            // 收起 sheet，避免污染后续断言
+            if sheets.buttons["取消"].exists {
+                sheets.buttons["取消"].tap()
+            }
+            return false
+        }
+        option.tap()
+        return true
+    }
+
+    /// 字号是 slider（`epub.reader.settings.font.size`），没有增大/减小按钮。
+    /// 把滑块推到指定归一化位置以触发重排；返回是否成功。
+    @discardableResult
+    func adjustSettingsFontSize(toNormalizedPosition position: CGFloat, timeout: TimeInterval = 5) -> Bool {
+        let slider = sliders[IDs.settingsFontSize]
+        guard slider.waitForExistence(timeout: timeout) else { return false }
+        slider.adjust(toNormalizedSliderPosition: position)
+        return true
+    }
+
+    /// 在当前值基础上增减字号，替代早已不存在的 font.increase / font.decrease 按钮。
+    @discardableResult
+    func nudgeSettingsFontSize(by delta: CGFloat, timeout: TimeInterval = 5) -> Bool {
+        let slider = sliders[IDs.settingsFontSize]
+        guard slider.waitForExistence(timeout: timeout) else { return false }
+        let target = min(max(slider.normalizedSliderPosition + delta, 0), 1)
+        slider.adjust(toNormalizedSliderPosition: target)
+        return true
+    }
+
+    @discardableResult
+    func increaseSettingsFontSize(timeout: TimeInterval = 5) -> Bool {
+        nudgeSettingsFontSize(by: 0.25, timeout: timeout)
+    }
+
+    @discardableResult
+    func decreaseSettingsFontSize(timeout: TimeInterval = 5) -> Bool {
+        nudgeSettingsFontSize(by: -0.25, timeout: timeout)
+    }
 }