# 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 段，避免文档与数据漂移。