85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
# 编码规则（Coding Rules）
|
||
|
||
> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
|
||
|
||
## 0. 黄金法则
|
||
|
||
1. **不臆造**：数据字段、文件、接口、依赖，不确定就查证或询问。
|
||
2. **守范围**：只做当前任务要求的事，不顺手加后续功能。
|
||
3. **照架构**：使用 Wagtail / Django / Python 3.12 / SQLite 的既定方案，不擅自换栈。
|
||
4. **小步改**：一次只解决一个任务，不夹带无关重构。
|
||
5. **可验证**：改完必须能构建、能测试、对得上验收标准。
|
||
|
||
## 1. 动手前
|
||
|
||
- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
|
||
- 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
|
||
- 先找现有 Wagtail/Django 结构、模型、模板和测试，复用优先。
|
||
- 如果需求含糊，或改动会偏离原则 / 架构，先问。
|
||
|
||
## 2. 事实来源纪律
|
||
|
||
- 只相信文档指定的权威需求、模型、路由、API 边界和当前代码。
|
||
- 不从聊天记录、备份、草稿、旧导出文件里推断当前事实。
|
||
- 不虚构字段、接口、状态码、配置项。
|
||
- 数据结构变化必须同步更新 `04-architecture.md`、`api.md`、`routes.md` 和相关任务。
|
||
|
||
## 3. 范围纪律
|
||
|
||
- MVP 只做 `02-requirements.md` 中列为 P0 的功能。
|
||
- V2 / V3 功能只记录，不实现。
|
||
- 需求明确排除的非目标不得实现。
|
||
- 不为“将来可能用到”提前抽象。
|
||
|
||
## 4. 架构纪律
|
||
|
||
- 技术栈以 `03-tech-stack.md` 为准。
|
||
- 新增依赖前先说明理由；未经确认不要引入重量级依赖。
|
||
- Page / Snippet / Template / Settings 的职责以 `04-architecture.md` 为准。
|
||
- 公开路由以 `routes.md` 为准。
|
||
- MVP 不提供公开 REST API；不要擅自新增 API 层。
|
||
|
||
## 5. Wagtail / Django 规则
|
||
|
||
- 模型字段必须有清晰业务含义，不能只为页面展示临时堆字段。
|
||
- 迁移文件必须随模型变化提交。
|
||
- Wagtail 后台字段分组要服务编辑体验。
|
||
- 前台模板不要写复杂业务查询；复杂查询放到模型方法、QuerySet 或 view/helper。
|
||
- URL slug 要稳定，避免上线后频繁修改。
|
||
- 上传媒体走 Wagtail / Django media 机制，不硬编码本地绝对路径。
|
||
|
||
## 6. SQLite 规则
|
||
|
||
- 不写 SQLite 专属 SQL，保持未来迁移 PostgreSQL 的可能性。
|
||
- 不做高频写入功能。
|
||
- 上线前启用 WAL 并记录备份策略。
|
||
- 如果出现 `database is locked`，先记录到 `current-state.md`，再规划 PostgreSQL 迁移任务。
|
||
|
||
## 7. 测试与验证
|
||
|
||
生产代码尚未初始化。完成 T-001 后，把真实命令填入这里，并同步 `init.ps1` / `init.sh`：
|
||
|
||
```powershell
|
||
# 目标形态
|
||
.\.venv\Scripts\python manage.py check
|
||
.\.venv\Scripts\python manage.py test
|
||
```
|
||
|
||
完成前至少检查：
|
||
|
||
- [ ] Django system check 通过。
|
||
- [ ] 相关测试通过。
|
||
- [ ] 对得上需求验收标准。
|
||
- [ ] 没有夹带无关改动。
|
||
- [ ] 涉及文档事实变化时，文档已同步。
|
||
- [ ] 已在 `../progress.md` 记录跑过的命令和结果作为证据。
|
||
- [ ] 回复里如实说明跑了什么命令、结果如何。
|
||
|
||
## 8. 绝不
|
||
|
||
- 绝不把密钥、token、密码写进代码或文档样例的真实值里。
|
||
- 绝不为了让测试通过而删除断言、降低验收标准。
|
||
- 绝不擅自删除用户已有文件或重置工作区。
|
||
- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
|
||
- 绝不把赞助项目伪装成编辑推荐。
|