# 编码规则（Coding Rules）

> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。

## 0. 黄金法则

1. 不臆造：钉钉字段、接口、依赖、文件，不确定就查证或询问。
2. 守范围：只做当前任务要求的事，不顺手加 V2 功能。
3. 照架构：使用 Go + Gin + SQLite + 原生前端，不擅自换栈。
4. 小步改：一次只解决一个任务，不夹带无关重构。
5. 可验证：改完必须能构建、能测试、对得上验收标准。

## 1. 动手前

- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
- 找到本任务对应的验收标准，写之前就知道怎么算做对。
- 先找现有函数、包、SQL、页面和测试，复用优先。
- 如果需求含糊，或改动会偏离 Go + Gin / 原生前端约束，先问。

## 2. 事实来源纪律

- 钉钉接口以 `docs/api.md`、`docs/04-architecture.md` 和实际 OpenAPI 响应为准。
- 新项目技术事实以 `docs/03-tech-stack.md` 为准。
- API 形状以 `docs/api.md` 为准。
- 数据结构变化必须同步更新 `docs/04-architecture.md`、`docs/api.md` 和相关任务。
- 不从旧 JSON 文件中推断未确认的字段含义。

## 3. 范围纪律

- MVP 只做 `02-requirements.md` 中列为 P0 的功能。
- V2 / V3 功能只记录，不实现。
- 不实现登录、权限、定时同步、变更历史，除非任务明确要求。
- 不为将来可能用到提前抽象。

## 4. 架构纪律

- 后端必须用 Gin。
- 前端必须是原生 HTML/CSS/JavaScript。
- Gin 负责托管前端文件和 `/api/*`。
- 不引入 Vue、React、Element Plus、Vite、Webpack。
- 不让浏览器直接调用钉钉 OpenAPI。
- 不把 SQL、钉钉调用和 HTTP 处理混在同一个函数里。

## 5. 代码规范

- Go 标识符使用英文，包名短小清晰。
- UI 文案和文档默认中文。
- 错误必须处理，不吞错。
- HTTP 错误统一返回 `{"error":{"code":"...","message":"..."}}`。
- 注释解释为什么，不复述做了什么。
- Go 代码提交前运行 `gofmt`。

## 6. 测试与验证

完成前至少检查：

- [ ] 构建通过。
- [ ] 相关测试通过。
- [ ] 对得上需求验收标准。
- [ ] 没有夹带无关改动。
- [ ] 涉及文档事实变化时，文档已同步。
- [ ] 回复里如实说明跑了什么命令、结果如何。

目标命令：

```powershell
go test ./...
go build ./...
```

## 7. 绝不

- 绝不把真实 app_key、app_secret、access_token、手机号样本写进代码或文档。
- 绝不为了让测试通过而删除断言、降低验收标准。
- 绝不擅自删除用户已有文件或重置工作区。
- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。

## 8. 拿不准就问

问题要具体，说明卡在哪里、有哪些选项、倾向哪个选项以及原因。