# 编码规则（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）。要加任何第三方依赖，**先说明理由并征求同意**。
- **技术栈以 [技术栈](03-tech-stack.md) 为准**。若未来新增标"待定"的栈项，不要在代码里擅自选定；先在文档中决策，再实现。
- **内容数据 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）已同步
- [ ] 如实汇报：跑了什么、结果如何；测试失败就说失败，别粉饰

Windows PowerShell 常用验证命令：

```powershell
$env:GOOS='js'; $env:GOARCH='wasm'; go build -o app.wasm
go build
go vet ./...
python scripts/validate_episodes.py
```

`validate_episodes.py` 仅在改动内容数据或 schema 时必跑。

## 9. 绝不

- 绝不把密钥 / token 写进代码或提交（用环境变量 / 配置）。
- 绝不删除或覆盖 `notion_docs/`、`*.bak`、`episodes.json`（改它先靠 `fix_episodes.py` 备份）。
- 绝不为了让测试 / 校验通过而改判据、删用例、注释掉检查。
- 绝不引入版权存疑的素材或内容。
- 绝不在没说明的情况下"顺手"重构、改公共接口、升级依赖。

## 10. 拿不准就问

宁可停下来问一句，也不要猜着写半天最后方向错了。问题要具体，给出你倾向的选项和理由。