# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

iOS 背单词应用（UIKit，纯代码 UI，无 Storyboard 布局），面向中文用户学习英语词汇。词库覆盖颜色、动物、水果、数字、家庭等分类，支持浏览、发音和四种测验模式。

## 常用命令

```bash
# 编译（项目在 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` 关闭大标题。