lingo/docs/05-coding-rules.md

编码规则（Coding Rules）

每次写代码前先读完本文件。 这是让 AI 不跑偏、代码质量稳定的"宪法"。 与技术细节冲突时，以 技术栈 / 架构设计 和 CLAUDE.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 过校验；② 同步更新 架构设计 第三节 + CLAUDE.md 的 schema 段（防文档漂移）。
• notion_docs/ 和 *.bak 是只读存档，不读作事实、不修改、不删除。

3. 范围纪律（防镀金 / 防跑题）

• MVP 范围 = ep1–17 + 6 个 P0 功能（课程列表 / 播放 / 逐句同步 / 生词本 / 账号同步 / 离线）。其余一律不做。
• 看到"顺便也能做 X"的冲动先停下：X 在 requirements 里是 P0 吗？不是就不做，最多记成 TODO。
• 不做需求里明确的非目标：视频、行级中英对照、社交、AI 口语评分。
• 不为"将来可能用到"提前抽象（多教材结构架构已预留，按现状写即可，别过度设计）。

4. 架构纪律

• 技术栈固定：以 技术栈 为准（前端 go-app、后端 net/http、数据库 SQLite）。要加任何第三方依赖，先说明理由并征求同意。
• 技术栈以 技术栈 为准。若未来新增标"待定"的栈项，不要在代码里擅自选定；先在文档中决策，再实现。
• 内容数据 vs 用户数据分清：教材内容（episodes.json）前端直接读、不入库；SQLite 只存用户态（users / progress / vocab）。别把课程内容写进数据库。
• 把浏览器互操作（syscall/js、Audio API）封装成可复用组件，不要散落在各处业务代码里。
• 进度 / 生词本的字段以 架构设计 第 3.2 节为准（按 episode_id + act 定位，不是抽象 lesson_id）。

5. Go / go-app 代码规范

• 提交前过 gofmt 和 go vet；构建用 GOOS=js GOARCH=wasm go build（前端）/ 普通 go build（后端）。
• 错误必须处理：不忽略 err、不用 _ 吞错；正常流程里不 panic（初始化致命错误除外）。
• 包 / 文件按职责划分，对照 架构设计 第二节的前后端职责组织（列表 / 播放器 / 字幕同步 / 生词本 / 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 常用验证命令：

$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. 拿不准就问

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