language4english/CLAUDE.md

CLAUDE.md

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

项目概述

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

常用命令

# 编译（项目在 LearnEnglish/ 子目录，非仓库根目录）
xcodebuild -project LearnEnglish/LearnEnglish.xcodeproj -scheme LearnEnglish \
  -destination 'platform=iOS Simulator,id=<UDID>' -configuration Debug build

# 查看可用模拟器及运行时
xcrun simctl list devices available
xcrun simctl list runtimes

# 安装 / 启动 / 截图验证 UI
xcrun simctl install <UDID> <路径>/Debug-iphonesimulator/LearnEnglish.app
xcrun simctl launch <UDID> com.fishestlife.english
xcrun simctl io <UDID> screenshot /tmp/shot.png

注意：

• 改完代码只允许编译验证：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 关闭大标题。