lingo/docs/00-ai-start-here.md

AI 开发入口

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

一句话定位

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

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

必读顺序

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

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

如果根目录有 ../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 领取任务时：

• 只领取第一个状态为 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 为准：

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

Windows 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 合约草案（写后端/前端 client 前看）。
• routes.md：go-app 页面路由与组件归属（写页面/导航前看）。
• current-state.md：当前实现状态、入口文件、可运行命令、下一步可做任务。
• 项目包布局见 04-architecture.md 第六节。