docs: 建立项目文档体系（vision/requirements/tech-stack/architecture/coding-rules）

- docs/01-vision        核心目标、目标用户、产品原则、非目标
- docs/02-requirements  产品语言需求 + MVP 验收标准（无技术词）
- docs/03-tech-stack    go-app / 纯CSS / SQLite / Session Cookie / 单二进制部署
- docs/04-architecture  系统结构、前后端职责、真实 episodes.json 数据模型、技术难点
- docs/05-coding-rules  AI 写代码前必读的硬约束（防跑偏）
- CLAUDE.md             AI 入口：文档地图、真实数据 schema、强制必读编码规则

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/05-coding-rules.md

@@ -0,0 +1,88 @@
+# 编码规则（Coding Rules）
+
+> **每次写代码前先读完本文件。** 这是让 AI 不跑偏、代码质量稳定的"宪法"。
+> 与技术细节冲突时，以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 和 `CLAUDE.md` 的事实为准；与"该不该做"冲突时，以 [需求](02-requirements.md) 为准。
+
+## 0. 黄金法则（记住这 5 条就够稳）
+
+1. **不臆造**：数据字段、文件、接口、依赖，不确定就去查 / 去问，绝不凭印象编。
+2. **守范围**：只做被要求的事，MVP 只做 ep1–17 的 P0，不顺手加 V2/V3。
+3. **照架构**：用既定技术栈（go-app / net/http / SQLite），不擅自引入新框架或依赖。
+4. **小步改**：一次只解决一个问题，不夹带无关重构、不整文件重排版。
+5. **可验证**：改完必须能构建、过校验、对得上验收标准，再说"完成"。
+
+## 1. 动手前
+
+- 按链路确认：`vision`（方向）→ `requirements`（要什么 + 验收标准）→ `tech-stack` + `architecture` + `CLAUDE.md`（怎么做）。
+- 找到对应的**验收标准**（02-requirements 第五节），写之前就知道"怎么算做对"。
+- 需求含糊、或一个改动会偏离原则 / 架构时——**先问，不要猜着做**。
+- 动手前先找现有的函数 / 组件 / 工具能不能复用，**别重复造轮子**。
+
+## 2. 事实来源纪律（最容易踩的坑）
+
+- **内容数据只信 `family-album-usa/episodes.json` 的真实结构**：
+  - `line` 只有 `{ t, en }`——**没有 `zh`**，不要读、不要假设有行级中文。
+  - 三级是 `episode → act → line`，不是 `course/lesson`。
+  - `audio` 字段是**服务路径** `/family-album/audio/u{集}{幕}.mp3`，磁盘在 `family-album-usa/audio/`，**必须做映射**，不能当文件路径直接用。
+- **不要为 ep18–26 补造音频或假数据**——这 9 集真的没音频，MVP 不依赖它们。
+- **改了 `episodes.json` 或它的结构，必须**：① 跑 `python3 scripts/validate_episodes.py` 过校验；② 同步更新 [架构设计](04-architecture.md) 第三节 + `CLAUDE.md` 的 schema 段（防文档漂移）。
+- `notion_docs/` 和 `*.bak` 是只读存档，**不读作事实、不修改、不删除**。
+
+## 3. 范围纪律（防镀金 / 防跑题）
+
+- MVP 范围 = **ep1–17 + 6 个 P0 功能**（课程列表 / 播放 / 逐句同步 / 生词本 / 账号同步 / 离线）。其余一律不做。
+- 看到"顺便也能做 X"的冲动先停下：X 在 requirements 里是 P0 吗？不是就**不做**，最多记成 TODO。
+- 不做需求里明确的非目标：视频、行级中英对照、社交、AI 口语评分。
+- 不为"将来可能用到"提前抽象（多教材结构架构已预留，按现状写即可，别过度设计）。
+
+## 4. 架构纪律
+
+- **技术栈固定**：以 [技术栈](03-tech-stack.md) 为准（前端 go-app、后端 `net/http`、数据库 SQLite）。要加任何第三方依赖，**先说明理由并征求同意**。
+- **标"待定"的栈项不要擅自选定**（UI 样式 / 状态管理 / 鉴权方式 / 部署）——先在 tech-stack 文档定下来再用，别在代码里替项目拍板。
+- **内容数据 vs 用户数据分清**：教材内容（episodes.json）前端直接读、**不入库**；SQLite **只存**用户态（users / progress / vocab）。别把课程内容写进数据库。
+- 把浏览器互操作（`syscall/js`、Audio API）**封装成可复用组件**，不要散落在各处业务代码里。
+- 进度 / 生词本的字段以 [架构设计](04-architecture.md) 第 3.2 节为准（按 `episode_id + act` 定位，不是抽象 lesson_id）。
+
+## 5. Go / go-app 代码规范
+
+- 提交前过 `gofmt` 和 `go vet`；构建用 `GOOS=js GOARCH=wasm go build`（前端）/ 普通 `go build`（后端）。
+- **错误必须处理**：不忽略 `err`、不用 `_` 吞错；正常流程里不 `panic`（初始化致命错误除外）。
+- 包 / 文件按职责划分，对照 [架构设计](04-architecture.md) 第二节的前后端职责组织（列表 / 播放器 / 字幕同步 / 生词本 / API 封装）。
+- 控制 wasm 体积：不引重型库；公共逻辑抽函数，避免复制粘贴。
+- 不留 `TODO` 就当没事——要么实现，要么在 PR / 回复里**明确标注未完成项**。
+
+## 6. 字幕同步专项（核心功能，最易出 bug）
+
+- 定位当前句：用音频 `currentTime` 在该 act 的 `lines[].t` 上**二分查找**，不要线性扫每帧。
+- **时间戳可能非严格递增**（已知 ep18/ep25 有倒退）：定位逻辑要对乱序 / 相等 `t` 容错，不能假设严格单调。
+- 点句跳转：seek 到该句 `t`；高亮的句子必须和正在播放的一致（验收标准里有这条）。
+- `hasAudio=false` 的 act：没有音频可同步，UI 要**优雅降级**（只显示文本 / 标注无音频），不要崩。
+
+## 7. 命名与风格
+
+- 代码标识符用**英文**；UI 文案、注释、文档用**中文**（与项目现状一致）。
+- 写新代码前先看邻近代码的命名、缩进、注释密度，**与之保持一致**，不要自带一套风格。
+- 注释解释"为什么"，不复述"做了什么"。
+
+## 8. 改完之前（"完成"的定义）
+
+逐项过，全绿才算完成：
+
+- [ ] 能构建通过（前端 wasm / 后端 二进制）
+- [ ] 碰过内容数据就跑了 `validate_episodes.py`，0 ERROR
+- [ ] 对得上相关功能的**验收标准**
+- [ ] 没有夹带无关改动、没有整文件重排版
+- [ ] 涉及数据结构变化的，文档（tech-stack / architecture / CLAUDE.md）已同步
+- [ ] 如实汇报：跑了什么、结果如何；测试失败就说失败，别粉饰
+
+## 9. 绝不
+
+- 绝不把密钥 / token 写进代码或提交（用环境变量 / 配置）。
+- 绝不删除或覆盖 `notion_docs/`、`*.bak`、`episodes.json`（改它先靠 `fix_episodes.py` 备份）。
+- 绝不为了让测试 / 校验通过而改判据、删用例、注释掉检查。
+- 绝不引入版权存疑的素材或内容。
+- 绝不在没说明的情况下"顺手"重构、改公共接口、升级依赖。
+
+## 10. 拿不准就问
+
+宁可停下来问一句，也不要猜着写半天最后方向错了。问题要具体，给出你倾向的选项和理由。