156 lines
5.3 KiB
Markdown
156 lines
5.3 KiB
Markdown
 
|
# 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) 第六节。
|