lingo/CLAUDE.md

CLAUDE.md — 走遍美国 · 英语学习 PWA

给 AI 编程助手的项目上下文。先读本文件，再按需查 docs/。

⚠️ 写任何代码前，必须先读完 docs/05-coding-rules.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	AI 开发入口：阅读顺序、任务领取、验证命令	AI coding agent 进入项目的第一站
docs/README.md	项目概览与导航	想先有个整体印象
docs/01-vision.md	为什么 / 为谁 / 产品原则 / 不做什么	拿不准取舍方向、判断某需求该不该做
docs/02-requirements.md	要什么 + 怎么算达成（产品语言，无技术词、含验收标准）	确认功能范围、优先级、验收判据
docs/03-tech-stack.md	用什么：框架 / 数据库 / UI / 状态管理 / 部署（速查）	想知道某层用哪个技术
docs/04-architecture.md	怎么搭：系统结构、职责划分、数据模型、技术难点	实际写代码、查数据结构与字段
docs/api.md	API 合约草案：账号 / 生词本 / 进度接口	写后端 API 或前端 API client 前
docs/routes.md	路由与页面结构：页面路由、职责、组件归属	写 go-app 页面与导航前
docs/current-state.md	当前实现状态：仓库现实、当前可做任务	判断代码现状和下一步任务
docs/05-coding-rules.md	编码规则：写代码的硬约束与"完成"的定义	⚠️ 动手写代码之前必读
docs/06-tasks.md	任务看板（AI 的 Jira）：MVP 拆解、依赖、状态	决定"这次做什么"时

写代码前的判断链路：vision（方向对不对）→ requirements（要做成什么样、怎么算对）→ tech-stack（用什么）→ architecture + 本文件（怎么搭、查字段）→ coding-rules（怎么写）。

notion_docs/ 是 Notion 原始导出，只读存档，勿改、勿作为事实来源。一切以 docs/ 与真实代码/数据为准。

技术栈

完整选型与理由见 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（句）：

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