103 lines
5.4 KiB
Markdown
103 lines
5.4 KiB
Markdown
 
|
# CLAUDE.md — 走遍美国 · 英语学习 PWA
|
|||
|
|
|
|||
|
|
> 给 AI 编程助手的项目上下文。先读本文件，再按需查 `docs/`。
|
|||
|
|
>
|
|||
|
|
> ⚠️ **写任何代码前，必须先读完 [`docs/05-coding-rules.md`](docs/05-coding-rules.md)（编码规则）。** 这是保证代码不跑偏、质量稳定的硬约束。
|
|||
|
|
|
|||
|
|
## 一句话
|
|||
|
|
|
|||
|
|
用 **go-app (Go → WebAssembly)** 构建的 PWA，基于「走遍美国 (Family Album, U.S.A.)」音频素材，做**音频 + 逐句同步字幕**的英语精听学习工具。大屏手机 / 平板优先，可安装、可离线，账号化同步进度与生词本。
|
|||
|
|
|
|||
|
|
## 文档地图（`docs/`）
|
|||
|
|
|
|||
|
|
三份文档职责分层，按需读对应那份；**不要把技术细节往 vision/requirements 里塞**：
|
|||
|
|
|
|||
|
|
| 文档 | 职责（回答什么） | 该查它当… |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| [`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/05-coding-rules.md`](docs/05-coding-rules.md) | **编码规则**：写代码的硬约束与"完成"的定义 | ⚠️ 动手写代码**之前**必读 |
|
|||
|
|
|
|||
|
|
> 写代码前的判断链路：`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/
|
|||
|
|
├── CLAUDE.md # 本文件
|
|||
|
|
├── docs/ # 规范化项目文档（事实来源）
|
|||
|
|
├── notion_docs/ # Notion 原始导出（只读存档）
|
|||
|
|
└── family-album-usa/ # 内容素材
|
|||
|
|
├── 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": 50 },
|
|||
|
|
"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. 后端账号体系 + 鉴权（JWT 或 session）
|
|||
|
|
4. 生词本（前端 UI + 后端 API）
|
|||
|
|
5. 进度同步
|
|||
|
|
6. PWA manifest + Service Worker 离线化
|
|||
|
|
7. （V2）复读 / 测验 / 打卡
|
|||
|
|
|
|||
|
|
## 约定
|
|||
|
|
|
|||
|
|
- 文档与 UI 文案用**中文**；代码标识符用英文。
|
|||
|
|
- 改动内容数据结构时，**同步更新** `docs/04-architecture.md` 与本文件的 schema 段，避免文档与数据漂移。
|