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>
114 lines
6.7 KiB
Markdown
114 lines
6.7 KiB
Markdown
# CLAUDE.md — 走遍美国 · 英语学习 PWA
|
||
|
||
> 给 AI 编程助手的项目上下文。先读本文件，再按需查 `docs/`。
|
||
>
|
||
> ⚠️ **写任何代码前，必须先读完 [`docs/05-coding-rules.md`](docs/05-coding-rules.md)（编码规则）。** 这是保证代码不跑偏、质量稳定的硬约束。
|
||
>
|
||
> 🧭 **按 [`docs/06-tasks.md`](docs/06-tasks.md) 任务看板开发：每轮只领取并完成一个任务（依赖已 DONE 的最靠前 TODO），做完即停、汇报、等指令——不要一次生成整个项目。**
|
||
|
||
## 一句话
|
||
|
||
用 **go-app (Go → WebAssembly)** 构建的 PWA，基于「走遍美国 (Family Album, U.S.A.)」音频素材，做**音频 + 逐句同步字幕**的英语精听学习工具。大屏手机 / 平板优先，可安装、可离线，账号化同步进度与生词本。
|
||
|
||
## 文档地图（`docs/`）
|
||
|
||
文档职责分层，按需读对应那份；**不要把技术细节往 vision/requirements 里塞**：
|
||
|
||
| 文档 | 职责（回答什么） | 该查它当… |
|
||
| --- | --- | --- |
|
||
| [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) | **AI 开发入口**：阅读顺序、任务领取、验证命令 | AI coding agent 进入项目的第一站 |
|
||
| [`docs/README.md`](docs/README.md) | 项目概览与导航 | 想先有个整体印象 |
|
||
| [`docs/01-vision.md`](docs/01-vision.md) | **为什么 / 为谁 / 产品原则 / 不做什么** | 拿不准取舍方向、判断某需求该不该做 |
|
||
| [`docs/02-requirements.md`](docs/02-requirements.md) | **要什么 + 怎么算达成**（产品语言，无技术词、含验收标准） | 确认功能范围、优先级、验收判据 |
|
||
| [`docs/03-tech-stack.md`](docs/03-tech-stack.md) | **用什么**：框架 / 数据库 / UI / 状态管理 / 部署（速查） | 想知道某层用哪个技术 |
|
||
| [`docs/04-architecture.md`](docs/04-architecture.md) | **怎么搭**：系统结构、职责划分、**数据模型**、技术难点 | 实际写代码、查数据结构与字段 |
|
||
| [`docs/api.md`](docs/api.md) | **API 合约草案**：账号 / 生词本 / 进度接口 | 写后端 API 或前端 API client 前 |
|
||
| [`docs/routes.md`](docs/routes.md) | **路由与页面结构**：页面路由、职责、组件归属 | 写 go-app 页面与导航前 |
|
||
| [`docs/current-state.md`](docs/current-state.md) | **当前实现状态**：仓库现实、当前可做任务 | 判断代码现状和下一步任务 |
|
||
| [`docs/05-coding-rules.md`](docs/05-coding-rules.md) | **编码规则**：写代码的硬约束与"完成"的定义 | ⚠️ 动手写代码**之前**必读 |
|
||
| [`docs/06-tasks.md`](docs/06-tasks.md) | **任务看板**（AI 的 Jira）：MVP 拆解、依赖、状态 | 决定"这次做什么"时 |
|
||
|
||
> 写代码前的判断链路：`vision`（方向对不对）→ `requirements`（要做成什么样、怎么算对）→ `tech-stack`（用什么）→ `architecture` + 本文件（怎么搭、查字段）→ `coding-rules`（怎么写）。
|
||
>
|
||
> `notion_docs/` 是 Notion 原始导出，**只读存档，勿改、勿作为事实来源**。一切以 `docs/` 与真实代码/数据为准。
|
||
|
||
## 技术栈
|
||
|
||
完整选型与理由见 [`docs/03-tech-stack.md`](docs/03-tech-stack.md)；速览：
|
||
|
||
| 层 | 选型 |
|
||
| --- | --- |
|
||
| 前端 | go-app（Go → WebAssembly），PWA 可安装 / 离线 |
|
||
| UI 样式 | 纯 CSS 文件（移动优先），经 `Handler.Styles` 引入 |
|
||
| 状态管理 | go-app 原生（局部状态 + `ctx` 全局观察者），不引第三方 |
|
||
| 后端 | Go `net/http` 标准库 |
|
||
| 数据库 | SQLite（仅存用户态：账号 / 进度 / 生词本） |
|
||
| 鉴权 | httpOnly Session Cookie |
|
||
| 音频控制 | 浏览器 Audio API（经 `syscall/js` 互操作） |
|
||
| 部署 | 单 Go 二进制自托管（wasm + 静态 + 音频 + API） |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
lingo/
|
||
├── AGENTS.md # 仓库级 AI 强约束入口（英文）
|
||
├── CLAUDE.md # 本文件
|
||
├── docs/ # 规范化项目文档（事实来源）
|
||
├── scripts/ # episodes.json 校验/修正脚本
|
||
├── design_mockups/ # UI 效果稿（HTML/CSS，可迁移参考）
|
||
├── notion_docs/ # Notion 原始导出（只读存档，git 忽略）
|
||
├── design_images/ # 第三方设计参考图（git 忽略）
|
||
└── family-album-usa/ # 内容素材（git 忽略，含大音频）
|
||
├── episodes.json # 全部课程内容（约 700KB）
|
||
└── audio/ # 50 个 mp3，命名 u{集}{幕}.mp3，如 u0101.mp3
|
||
```
|
||
|
||
> 当前**尚无 Go 代码**（无 `go.mod`）。开始编码时在仓库根初始化 go-app 项目结构。
|
||
|
||
## 内容数据：`family-album-usa/episodes.json`（关键，勿臆测）
|
||
|
||
结构 **episode（集）→ act（幕）→ line（句）**：
|
||
|
||
```json
|
||
{
|
||
"meta": { "totalEpisodes": 26, "totalActs": 78, "audioActs": 49 },
|
||
"episodes": [
|
||
{ "id": 1, "title": "46 Linden Street", "titleCn": "林登大街46号",
|
||
"acts": [
|
||
{ "act": 1, "label": "Act I", "audio": "/family-album/audio/u0101.mp3",
|
||
"hasAudio": true, "lineCount": 86,
|
||
"lines": [ { "t": 34.18, "en": "Excuse me. My name is Richard Stewart." } ] }
|
||
] }
|
||
]
|
||
}
|
||
```
|
||
|
||
必须记住的事实：
|
||
|
||
- **line 只有 `{ t, en }`**——`t` 是音频时间戳（秒），`en` 是英文句。**没有 `zh`（行级中文翻译）字段**，别去读它。
|
||
- episode 有 `titleCn`（集标题中文，26 集全有）；行级中文目前不存在。
|
||
- 规模：26 集 / 78 个 act 条目，其中 49 个 `hasAudio=true`；`audio/` 共 50 个 mp3 / 合计 6335 句。
|
||
- **路径映射**：JSON 中的 `/family-album/audio/...` 是服务路径，磁盘实际在 `family-album-usa/audio/`，后端路由需映射。
|
||
- `audio/episode12_act2.mp3` 命名不符 `u####.mp3` 且未被 JSON 引用，属游离文件，勿默认它有效。
|
||
|
||
详见 `docs/04-architecture.md` 第三节（含 SQLite 用户表设计）。
|
||
|
||
## 字幕同步（核心功能，最难）
|
||
|
||
播放时用音频 `currentTime` 匹配 line 的 `t` 字段定位当前句 → 逐句高亮；点击某句 → seek 到该句 `t`。比解析 .srt 更直接。go-app 下需经 `syscall/js` 调浏览器 Audio API，建议封装成可复用组件。
|
||
|
||
## 推荐开发顺序（先验证最难的）
|
||
|
||
1. **「音频 + 时间戳字幕同步」最小原型**（最难一环，先跑通）
|
||
2. 课程列表 + 播放页骨架（读 `episodes.json` 渲染）
|
||
3. 后端账号体系 + 鉴权（httpOnly Session Cookie）
|
||
4. 生词本（前端 UI + 后端 API）
|
||
5. 进度同步
|
||
6. PWA manifest + Service Worker 离线化
|
||
7. （V2）复读 / 测验 / 打卡
|
||
|
||
## 约定
|
||
|
||
- 文档与 UI 文案用**中文**；代码标识符用英文。
|
||
- 改动内容数据结构时，**同步更新** `docs/04-architecture.md` 与本文件的 schema 段，避免文档与数据漂移。
|