功能系统

本文档概述了 MagicWord 中的主要功能实现，这些功能跨越多个组件和层。这些功能代表了应用程序的核心价值主张，涉及 UI、业务逻辑、数据持久化和外部服务之间的复杂交互。

三个主要的功能系统是：

1. AI 集成: 单词定义获取、批量文本提取和助记符生成。
2. 间隔重复系统 (SM-2): 科学的复习调度和记忆优化。
3. 更新系统: APK 分发的自更新机制。

有关每个系统的详细实现，请参阅：

• AI 集成
• 间隔重复系统 (SM-2)
• 更新系统

功能系统架构概览

这三个主要功能系统主要通过 LibraryViewModel 进行编排，该 ViewModel 充当中央协调器。每个系统都有独特的数据流和依赖关系，但共享通用的基础设施。

AI 集成系统

AI 集成系统提供三个主要功能：自动导入的单个单词查找、带并行处理的批量文本提取，以及通过 AI 生成的助记符和例句进行的增强学习。

关键组件:

• handleGlobalSearch: 编排单词查找和导入。
• importSingleWord: AI 驱动的单个单词导入。
• bulkImport: 从文本中提取和导入单词。
• processChunk: 带重试的单词批处理。
• RetrofitClient: AI API 客户端。
• AppConfig: AI 模型配置。

批量导入处理流程:

1. AI 请求配置: 使用 AppConfig 获取模型、温度和用户角色。
2. 并行处理策略:
   • 分块: 3 个单词一组。
   • 批处理: 并行处理最多 3 个块。
   • 重试队列: 失败的块重新排队（最多 3 次）。
   • 同步: 线程安全的导入跟踪。

间隔重复系统 (SM-2)

SM-2 算法实现提供了基于用户表现的科学优化复习调度。系统跟踪每个单词的重复次数、间隔和难度因子。

核心逻辑: processReview 函数遵循 SuperMemo-2 规范，对忘记的单词有特定的处理。

SM-2 数据模型:

• repetitions: 连续正确复习次数。
• interval: 距离下次复习的天数。
• easinessFactor: 难度乘数 (默认 2.5)。
• nextReviewTime: 下次复习时间戳。

到期单词查询: 系统使用 Kotlin Flow 算子 (combine, flatMapLatest) 根据选定的词库反应式地计算到期单词。

更新系统

更新系统启用自更新 APK 分发，对于无法访问标准应用商店的用户至关重要。系统通过 Cloudflare 代理检查 GitHub Releases。

更新检查流程:

1. 触发: MainScreen 启动时。
2. API 调用: 请求 Cloudflare 代理端点。
3. 版本比较: 解析 Release tag_name。
4. 用户提示: 显示带有发布说明的对话框。
5. 下载: 流式传输 APK 到缓存。
6. 安装: 使用 FileProvider 启动安装 Intent。

跳过版本机制: 用户可以忽略更新，将版本号持久化到 skip_update_version 以防止重复提示。

共享基础设施

所有三个系统都依赖于通用的基础设施组件：

• LibraryViewModel: 状态管理和编排。
• WordDao: 数据库 CRUD 操作。
• SharedPreferences: 轻量级持久化。
• OkHttpClient: 网络通信。
• viewModelScope: 协程生命周期管理。
• LogUtil: 错误跟踪。

错误处理模式

• AI 集成: 指数退避重试，基于队列的故障恢复，用户可见日志。
• SM-2 系统: 初始化验证，静默故障处理。
• 更新系统: 网络超时处理，回退到直接 GitHub API。