81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
# 编码规则（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. 拿不准就问
|
||
|
||
问题要具体，说明卡在哪里、有哪些选项、倾向哪个选项以及原因。
|