CruEnglish - 考研英语无痛阅读APP

项目简介

CruEnglish（考研英语无痛阅读器）是一款专为考研英语学习设计的智能阅读应用，通过上下文精准释义技术，消除一词多义干扰，支持单句翻译和句式结构分析，实现沉浸式无痛英语学习体验。

产品特色

• 🔒 完全离线运行 - 保护用户隐私，无需网络连接
• 🎯 精准上下文释义 - 基于语境的智能词义匹配
• 📚 智能个人词汇管理 - 自动收集与复习提醒
• 📖 多格式文档支持 - 支持文本和PDF文档阅读
• 🎨 个性化阅读体验 - 自定义主题、字体和布局

核心功能模块

📖 智能阅读引擎

• 多格式支持: 支持文本文章和PDF文档阅读
• 文本渲染: 支持多种字体、字号、行距的个性化阅读体验
• 点击取词: 一键获取上下文相关释义，支持词组和短语识别
• 单句翻译: 点击句子或段落显示翻译，AI智能分析句式结构
• 语境分析: 基于NLP技术的词义消歧算法
• 阅读辅助: 划线标记、笔记功能、阅读进度自动保存

📚 个人词汇宝典系统

• 智能收集: 根据点击行为自动收录生词到个人词典
• 上下文记录: 保存单词出现的原文语境和释义
• 掌握度管理: 三级标记系统（生疏/熟悉/掌握）

数据迁移说明（2025-11-06）

• 为兼容历史数据中使用的掌握程度中文别名（“已掌握”“不熟悉”）及英文值（mastered/familiar/unfamiliar），新增一次性迁移：
  • 启动重测服务时，自动将 TestedWord.masteryLevel 统一写回枚举原始值（掌握/熟悉/生疏）。
  • 迁移过程仅在首次运行执行一次，更新完成后保存至数据库，确保统计与筛选准确。
  • 同步扩展解析逻辑，避免旧值导致判定为“生疏”。

验证步骤：

• 打开重测模式，选择“考研英语词汇”，在“选择掌握程度”面板应显示已掌握/熟悉/生疏的真实数量分布，不再全部为“生疏”。
• 复习算法: 基于艾宾浩斯遗忘曲线的智能复习提醒
• 词频统计: 个人查词频率分析和重点词汇突出
• 词汇量测试: 智能词汇量评估系统，支持多词典测试和历史记录

📖 真题文章库

• 内容覆盖: 考研英语近20年阅读理解真题（98-09，10-22年）
• 智能分类: 按年份、主题、难度、词汇量多维度分类
• 进度管理: 阅读历史记录和完成度统计
• 扩展支持: 支持用户导入自定义文章（TXT/PDF格式）

📊 学习分析中心

• 数据统计: 阅读量、词汇量、学习时长等多维度统计
• 进步可视化: 词汇掌握曲线、学习成果图表展示
• 弱项识别: 高频查询词汇分析，提供针对性学习建议
• 成就系统: 学习里程碑和激励机制

技术架构

开发环境

• 平台: iOS 17.0+
• 语言: Swift 5.9
• 框架: SwiftUI + SwiftData
• 架构: MVVM
• 文档处理: PDFKit + 自定义PDF渲染引擎

核心技术特性

• 颜色系统优化: 安全的十六进制颜色解析，支持动态主题切换
• PDF文档支持: 原生PDF渲染和文本提取
• 性能监控: 实时性能指标追踪和优化
• 内存管理: 智能缓存和资源释放机制

项目结构

en01/
├── Models/                    # 数据模型层
│   ├── Article.swift         # 文章数据模型
│   ├── Word.swift            # 词汇数据模型
│   ├── UserProgress.swift    # 用户进度模型
│   ├── Settings.swift        # 应用设置模型
│   ├── PDFDocument.swift     # PDF文档模型
│   ├── TestWord.swift        # 词汇测试数据模型
│   └── VocabularyTest.swift  # 词汇量测试模型
├── Views/                     # 视图层
│   ├── HomeView.swift        # 主页视图
│   ├── ReadingView.swift     # 阅读页面
│   ├── ArticleReaderView.swift # 文章阅读器
│   ├── PDFReaderView.swift   # PDF阅读器
│   ├── VocabularyView.swift  # 词汇管理视图
│   ├── VocabularyTestView.swift # 词汇量测试视图
│   ├── WordTestCard.swift    # 单词测试卡片
│   ├── TestResultView.swift  # 测试结果视图
│   ├── TestHistoryListView.swift # 测试历史列表
│   ├── ProgressView.swift    # 进度统计视图
│   └── SettingsView.swift    # 设置页面
├── ViewModels/                # 视图模型层
│   ├── AppViewModel.swift    # 主应用视图模型
│   ├── ReadingViewModel.swift # 阅读视图模型
│   ├── PDFViewModel.swift    # PDF视图模型
│   └── VocabularyTestViewModel.swift # 词汇量测试视图模型
├── Services/                  # 服务层
│   ├── ArticleService.swift  # 文章服务
│   ├── PDFService.swift      # PDF处理服务
│   ├── DictionaryService.swift # 词典服务
│   ├── UserProgressService.swift # 进度服务
│   ├── VocabularyTestService.swift # 词汇量测试服务
│   └── PerformanceService.swift # 性能监控服务
└── Utils/                     # 工具类
    ├── TextProcessor.swift   # 文本处理工具
    ├── ColorExtensions.swift # 颜色扩展工具
    └── PDFExtractor.swift   # PDF文本提取工具

开发迭代规划

Phase 1: MVP版本 (v0.1.0 - 当前阶段)

核心目标: 验证产品核心价值

已完成功能:

• ✅ 基础阅读界面和文本渲染
• ✅ 简单点击取词功能
• ✅ 基础个人词典管理
• ✅ 词汇量测试系统（智能测试、历史记录、结果分析）
• ✅ 颜色系统优化和安全解析
• ✅ PDF文档阅读支持
• ✅ 基本的用户设置和主题切换
• ✅ 智能排序系统（文章匹配度算法、批量学习功能）
• ✅ 学习进度跟踪系统（批量操作、撤销功能）

技术重点:

• ✅ 建立基础MVVM架构
• ✅ 实现核心阅读引擎
• ✅ 完成基础UI/UX设计
• ✅ 颜色解析和主题系统优化
• ✅ PDF文档处理集成
• ✅ 智能排序算法优化和调试日志系统

Phase 2: V1.0正式版 (计划中)

核心目标: 完整产品功能实现

计划功能:

• 🔄 完整的上下文词义匹配系统
• 🔄 智能个人词汇宝典
• 🔄 完整真题库（近10年）
• 🔄 基础学习统计和分析
• 🔄 数据备份/恢复功能
• 🔄 性能优化和稳定性提升

词汇管理系统重构规划:

• 🎯 高优先级: 学习进度系统架构优化
  • 统一学习记录数据模型
  • 优化批量操作性能
  • 完善撤销机制的数据一致性
  • 实现学习会话管理
• 🎯 中优先级: 智能推荐算法增强
  • 基于用户学习行为的个性化推荐
  • 多维度文章匹配算法优化
  • 学习效果反馈循环机制
• 🎯 低优先级: 高级分析功能
  • 学习数据可视化增强
  • 学习报告生成系统
  • 跨设备数据同步准备

安装与运行

1. 克隆项目

git clone [repository-url]
cd en01

2. 使用 Xcode 打开项目

open en01.xcodeproj

3. 选择目标设备并运行

质量标准

性能指标

• 响应速度: 点击取词<100ms响应
• 内存占用: 运行时内存<200MB
• 启动时间: 应用启动<3秒
• 稳定性: 连续使用2小时无崩溃
• 准确性: 词义匹配准确率>95%

用户体验标准

• 界面响应: 99%的操作响应时间<1秒
• 崩溃率: <0.1%
• 资源占用: 内存占用<系统可用内存的10%
• 电池优化: 1小时阅读耗电<10%

数据存储架构

本地存储

• 用户数据: SwiftData本地数据库
• 词汇库: 预置JSON/SwiftData混合存储
• 文章库: 结构化JSON格式
• PDF文档: 本地文件系统缓存
• 配置文件: UserDefaults本地存储

核心算法

• 词义消歧: TF-IDF + 词向量相似度计算
• 上下文分析: 基于轻量化模型的语义理解
• 学习曲线: 改进的艾宾浩斯遗忘曲线算法
• 颜色解析: 安全的十六进制颜色字符串处理

开发指南

代码规范

• 遵循 Swift 官方编码规范
• 使用 SwiftUI 声明式编程
• 采用 MVVM 架构模式
• 注重代码可读性和可维护性
• 实施安全的颜色和资源处理

数据管理

• 使用 SwiftData 进行本地数据持久化
• 支持数据导入导出功能
• 实现数据备份与恢复
• PDF文档的高效处理和缓存

性能优化

1. 内存管理: 智能缓存和资源释放机制
2. UI优化: 异步加载和懒加载策略
3. 文档处理: PDF渲染优化和文本提取
4. 颜色系统: 安全的颜色解析避免应用崩溃

词典加载幂等性（新增）

• 配置管理器实现词典加载的幂等与并发保护：
  • 使用 hasLoadedDictionaries 与 isLoadingDictionaries 旗标，避免重复或并发触发。
  • 移除初始化阶段的自动加载；由视图模型在初始化工作流中按需触发加载。
• 视图模型在 setupInitialData() 与 loadAvailableDictionaries() 中增加空数据判定，已加载则跳过，并保持 isLoading 与 UI 同步。
• 词汇量测试视图移除了 onAppear 的重复加载，仅保留测试历史加载，避免首页出现“加载词典中…”长时间转圈。

版本历史

v0.1.0 (当前版本)

• ✅ 项目初始化和基础架构搭建
• ✅ 基础阅读界面和文本渲染
• ✅ 简单点击取词功能
• ✅ 基础个人词典管理
• ✅ 词汇量测试系统完整实现
  • ✅ 智能词典选择和自适应测试
  • ✅ 单词测试卡片和掌握程度选择
  • ✅ 测试结果统计和可视化展示
  • ✅ 测试历史记录和详情查看
  • ✅ 暂停恢复和进度跟踪功能
  • ✅ TestWord类型冲突解决和数据模型优化
• ✅ 颜色系统优化和安全解析
• ✅ PDF文档阅读支持
• ✅ 基本用户设置和主题切换

v0.2.0 (计划中)

• 🔄 完整的上下文词义匹配系统
• 🔄 智能个人词汇宝典
• 🔄 真题文章库扩展
• 🔄 学习统计和分析功能

v1.0.0 (计划中)

• 🔄 完整产品功能实现
• 🔄 性能优化和稳定性提升
• 🔄 数据备份/恢复功能
• 🔄 应用商店发布

贡献指南

欢迎提交 Issue 和 Pull Request 来改进项目！

开发流程

1. Fork 项目到个人仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

测试清理与数据导入验证（干净环境）

为确保导入验证数据环境干净，项目已移除所有测试内容：

• 删除 en01Tests/ 与 en01UITests/ 目录下的所有测试文件
• 删除根目录下所有以 test_ 前缀命名的测试/验证文件，以及相关报告文件

此清理不影响应用的正常运行与构建，仅移除测试目标与脚本，避免测试数据或 Mock 影响导入验证。

导入验证步骤

• 使用 Xcode 15+ 打开项目并运行到 iPhone 16 Pro 模拟器
• 在应用中进入“个人词典”->“导入词典”，选择需要导入的词典
• 导入完成后，切换到“词汇”页的“我的单词”标签
• 预期：列表与统计一致显示，筛选/搜索/排序均能即时更新
• 进行一次“词汇量测试”或“重测模式”，以便生成“测试历史”记录（导入本身不会产生历史）

常见核验点

• “总词汇量”显示来自 viewModel.vocabulary.count
• 列表数据源统一绑定 viewModel.filteredVocabulary（不再使用视图层本地副本）
• 若统计与列表不一致，可在 VocabularyViewModel.filterVocabulary 增加日志比对过滤前后数量与条件

联系方式

如有问题或建议，请通过以下方式联系我们：

• GitHub Issues: [项目Issues页面]
• 邮箱: [307105024@qq.com]

---

让英语学习变得更加高效和愉快！ 🚀

CruEnglish - 您的考研英语学习伙伴

稳定性修复说明（并发安全）

为解决一次因缓存大小读取引发的崩溃（doesNotRecognizeSelector，发生在 TextProcessor.getSafeCacheSize），已将缓存大小的读取方式从“传入字典并在队列中读取”调整为“在对应队列内执行读取闭包”，示例：

// 旧：queue.sync { cache.count }（可能在调用处捕获到字典副本）
// 新：getSafeCacheSize(queue: stemCacheQueue) { self.stemCache.count }

该改动避免了在调用点捕获字典副本导致的并发数据竞态，提升缓存访问的线程安全性与稳定性。

更新日志（近期）

• 2025-11-05
  • 修复 Retest 模式词典“已测试”计数 UI 不刷新的问题：将 RetestModeViewModel.dictionaryWordCounts 改为 @Published private(set) 并保证在主线程更新。
  • 修复重测词获取的匹配逻辑：RetestModeService.getRetestWords(for:) 改为按 dictionary.fileName 匹配 TestedWord.dictionaryFileName，避免 UUID 与文件名不一致导致的记录缺失。
  • 已通过 iPhone 16 Pro 模拟器构建验证（Debug, iphonesimulator），编译成功。

更新日志（2025-11-06）

• 修复测试采样大小在“全部”模式下的语义：TestSize.all 映射为负数（-1）时，服务层统一解释为“选取全部筛选后的单词”，避免返回空集合。
• 常规测试采样：当采样大小为负数时返回全部单词；采样为 0 仍返回空，保持明确语义。
• 重测模式 UI：在触发重测进入测试视图之前，先关闭重测选择弹窗，避免测试视图与弹窗同时显示造成叠层。

后续优化建议

• 统一 VocabularyTestViewModel.loadRetestWords(...) 的硬编码采样（当前为 100）为配置驱动，与 TestConfigurationManager.testSize 保持一致。
• 对于超大词典的“全部”采样，可选引入软上限与分页加载，保持首屏响应与内存占用稳定。