3.1 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
项目概述
iOS 背单词应用（UIKit，纯代码 UI，无 Storyboard 布局），面向中文用户学习英语词汇。词库覆盖颜色、动物、水果、数字、家庭等分类，支持浏览、发音和四种测验模式。
常用命令
# 编译（项目在 LearnEnglish/ 子目录，非仓库根目录）
# 固定使用 iPhone 17 Pro 模拟器作为编译目标
xcodebuild -project LearnEnglish/LearnEnglish.xcodeproj -scheme LearnEnglish \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' -configuration Debug build
注意：
- 改完代码只允许编译验证：
xcodebuild build通过即完成，禁止启动模拟器、安装 App 或截图确认（用户明确规则，UI 改动同样适用）。 - 部署目标为 iOS 26，模拟器必须是 iOS 26.x 运行时，否则安装时报系统版本过低。
- 无测试 target、无 lint 配置，验证方式 = 编译。
- Xcode 工程使用同步文件夹（objectVersion 77），在
LearnEnglish/LearnEnglish/下新建 .swift 文件会自动加入 target，无需改 pbxproj。
架构
数据流：Resources/words.json → WordStore.load()（SceneDelegate 启动时加载一次）→ 通过初始化器逐层注入（CategoryListViewController(store:) → WordListViewController(category:) → 详情/测验）。词库模型 WordBank/WordCategory/Word 均为 Codable，见 Models/Word.swift。
words.json 格式：每个单词单行 JSON 对象，字段为 word/phonetic/meaning/example/exampleMeaning，追加新词时保持该格式。编辑时注意同名单词可能出现在多个分类（如 orange 既是颜色也是水果），替换要限定在目标分类区块内。
页面流：分类列表 → 单词列表（WordCardCell）→ 单词详情；单词列表底部"开始测验" → QuizSetupViewController（选模式、题量）→ QuizViewController → QuizResultView。
测验：四种模式（英选汉/汉选英/拼写/默写，QuizMode）由同一个 QuizViewController 承载；题目由 QuizGenerator.makeQuestions 生成（选择题自动取 3 个干扰项，拼写题按 40% 比例挖空）。拼写/默写分别用 SpellingInputView/DictationInputView 自定义输入组件。新增测验相关结构放 Models/Quiz.swift。
发音：SpeechService.shared 单例封装 AVSpeechSynthesizer（en-US），播放状态通过 speakingDidChangeNotification 广播，各页面监听后刷新喇叭按钮图标与可用状态。
设计系统：Utilities/Theme.swift 集中管理色板（Theme.Color，含分类调色板 category(at:)）、圆角（Theme.Metrics）、字体（Theme.Font）；UIView.setPressed/animateEntry 为通用按压/入场动画。新 UI 元素应复用这些 token 而不是硬编码数值。HairlineView 是适配屏幕缩放的分隔线组件。
导航：SceneDelegate 直接构建 UINavigationController 根控制器并设置 window.tintColor；各页面用 navigationItem.largeTitleDisplayMode = .never 关闭大标题。