2026-06-21 14:03:36 +08:00
|
|
|
|
# 编码规则（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）。要加任何第三方依赖，**先说明理由并征求同意**。
|
2026-06-21 19:30:14 +08:00
|
|
|
|
- **技术栈以 [技术栈](03-tech-stack.md) 为准**。若未来新增标"待定"的栈项，不要在代码里擅自选定；先在文档中决策，再实现。
|
2026-06-21 14:03:36 +08:00
|
|
|
|
- **内容数据 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 代码规范
|
|
|
|
|
|
|
2026-06-21 20:00:56 +08:00
|
|
|
|
- **写 go-app 代码前先扫** [架构设计](04-architecture.md) 第四节的「go-app 注意事项（避坑表）」；踩到新坑往那里补，别让同一个坑被踩第二次。
|
2026-06-21 14:03:36 +08:00
|
|
|
|
- 提交前过 `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）已同步
|
|
|
|
|
|
- [ ] 如实汇报：跑了什么、结果如何；测试失败就说失败，别粉饰
|
|
|
|
|
|
|
2026-06-21 19:30:14 +08:00
|
|
|
|
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 时必跑。
|
|
|
|
|
|
|
2026-06-21 14:03:36 +08:00
|
|
|
|
## 9. 绝不
|
|
|
|
|
|
|
|
|
|
|
|
- 绝不把密钥 / token 写进代码或提交（用环境变量 / 配置）。
|
|
|
|
|
|
- 绝不删除或覆盖 `notion_docs/`、`*.bak`、`episodes.json`（改它先靠 `fix_episodes.py` 备份）。
|
|
|
|
|
|
- 绝不为了让测试 / 校验通过而改判据、删用例、注释掉检查。
|
|
|
|
|
|
- 绝不引入版权存疑的素材或内容。
|
|
|
|
|
|
- 绝不在没说明的情况下"顺手"重构、改公共接口、升级依赖。
|
|
|
|
|
|
|
|
|
|
|
|
## 10. 拿不准就问
|
|
|
|
|
|
|
|
|
|
|
|
宁可停下来问一句，也不要猜着写半天最后方向错了。问题要具体，给出你倾向的选项和理由。
|
