ilaandClaude Opus 4.8
b9bcbf7e6b
新增（Codex 起草，本次纳入并校对）： - AGENTS.md：仓库级 AI 强约束入口 - docs/00-ai-start-here.md：AI 开发入口与导航 - docs/api.md：账号/生词本/进度 API 合约草案 - docs/routes.md：go-app 页面路由与组件归属 - docs/current-state.md：当前实现状态 补充与对齐： - 验证命令补 bash（WSL/Linux 为主，PowerShell 为备）：00-ai-start-here、AGENTS - 04-architecture：新增第六节"项目结构（包布局）"+ 3.2 建表 SQL 草案 - docs/README 导航补 06-tasks；CLAUDE 目录树补 AGENTS/scripts/design_mockups - 00-ai-start-here 去除已过时的"需要补齐"段 - 06-tasks：Phase 2/3/4/5 交叉引用 api.md / routes.md / 包布局 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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) 第六节。
|