# AI 开发入口

> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。

## 一句话定位

这是一个大屏手机 / 平板优先的英语精听 PWA：基于「走遍美国 (Family Album, U.S.A.)」音频和逐句英文字幕，提供课程列表、音频播放、逐句同步、生词积累、账号同步和离线学习。

MVP 先做「走遍美国」ep1-17。ep18-26 暂缺音频，不进入 MVP 精听闭环。

## 必读顺序

每次开始写代码前，按这个顺序建立上下文：

1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。
2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。
3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。
4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。
5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
7. [`../CLAUDE.md`](../CLAUDE.md)：仓库根部的 AI 上下文和关键数据事实。

如果根目录有 [`../AGENTS.md`](../AGENTS.md)，也必须先读。它是仓库级强约束入口。

## 当前阶段

当前项目处于 MVP 起步阶段。任务看板的优先路径是：

1. Phase 0：最小可运行地基。
2. Phase 1：先验证字幕同步原型，这是最高风险。
3. Phase 2：课程列表和播放页。
4. Phase 3-5：账号、生词本、进度同步。
5. Phase 6：PWA 安装和离线。

设计 spike `T-200` 已完成，后续课程列表和播放页实现时参考：

- `design_mockups/list.html`
- `design_mockups/play.html`

这些是视觉参考和可迁移 CSS 来源，不是生产代码本身。

## 领取任务规则

从 [`06-tasks.md`](06-tasks.md) 领取任务时：

- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。
- 开始前把该任务状态改为 `DOING`。
- 本轮只完成这一个任务。
- 验收通过后把状态改为 `DONE`。
- 做完即停，汇报验证结果，等待下一步指令。

如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。

## MVP 边界

MVP 只做：

- 课程列表
- 音频播放
- 逐句同步和点句跳转
- 生词本
- 账号与跨设备同步
- PWA 安装和已缓存课程离线可用

MVP 不做：

- 视频播放
- 行级中英对照
- 社区、分享、社交
- AI 口语评分
- 生词 SRS
- 测验、打卡、激励模块
- 真正的多教材接入逻辑

`course_id` 可以按架构作为用户数据预留列存在，但 MVP 不实现多教材筛选、课程管理或多教材 UI。

## 事实来源

内容数据只信：

- `family-album-usa/episodes.json`
- `family-album-usa/audio/`
- `scripts/` 中的数据校验脚本

关键事实：

- 数据结构是 `episode -> act -> line`。
- `line` 只有 `t` 和 `en`，没有 `zh`。
- JSON 中 `/family-album/audio/...` 是服务路径，不是磁盘路径。
- 磁盘音频目录是 `family-album-usa/audio/`。
- ep18-26 暂缺音频，不要补造假数据。
- `notion_docs/` 和 `*.bak` 是只读存档，不作为事实来源。

## 常见任务该看哪里

做课程列表：

- 先看 `02-requirements.md` 的课程列表验收。
- 再看 `04-architecture.md` 的内容数据结构。
- 视觉参考 `design_mockups/list.html`。

做播放页或字幕同步：

- 先看 `02-requirements.md` 的音频播放和逐句同步验收。
- 再看 `04-architecture.md` 的关键技术难点。
- 必须遵守 `05-coding-rules.md` 的字幕同步专项：定位当前句用二分查找，对乱序 / 相等时间戳容错。
- 视觉参考 `design_mockups/play.html`。

做账号、生词本、进度：

- 先看 `02-requirements.md` 的 P0 用户故事和验收。
- 再看 `04-architecture.md` 的 SQLite 用户数据模型。
- API 形状如果尚未写入文档，先提出并补充合约，不要在多个任务里各自发明。

做 PWA / 离线：

- 先看 `02-requirements.md` 的离线验收。
- 再看 `03-tech-stack.md` 的 PWA / Service Worker 选型。
- 只要求已缓存课程离线可用，不要求首次离线访问全部音频。

## 验证命令

本项目主要在 **WSL / Linux（bash）** 下开发，命令以 bash 为准：

```bash
GOOS=js GOARCH=wasm go build -o app.wasm   # 前端 wasm
go build                                    # 后端
go vet ./...
python3 scripts/validate_episodes.py
```

Windows PowerShell 等价命令：

```powershell
$env:GOOS='js'; $env:GOARCH='wasm'; go build -o app.wasm
go build
go vet ./...
python scripts/validate_episodes.py
```

说明：

- 前端 wasm 改动后跑 wasm 构建。
- 后端 Go 改动后跑 `go build` 和 `go vet ./...`。
- 改动 `episodes.json` 或内容 schema 后跑 `python scripts/validate_episodes.py`。
- 没有触碰内容数据时，不需要跑内容校验。

## 相关补充文档（已具备）

以下文档已建好，开发到对应阶段时优先参考：

- [`api.md`](api.md)：账号、生词本、进度 API 合约草案（写后端/前端 client 前看）。
- [`routes.md`](routes.md)：go-app 页面路由与组件归属（写页面/导航前看）。
- [`current-state.md`](current-state.md)：当前实现状态、入口文件、可运行命令、下一步可做任务。
- 项目包布局见 [`04-architecture.md`](04-architecture.md) 第六节。