# {{project_name}} 开发规范

| 状态 | 生效 |
| 最后更新 | {{today}} |
| 关联 | PRD.md · ARCHITECTURE.md · DECISIONS.md |

> 本文档定义**本项目必须遵守**的工程规范。凡是「应该/不应该」的规定写在这里，具体代码写法见 `quick-ref.md`。

---

## 1. 总体架构

| 层次 | 职责 | 技术 |
| ---- | ---- | ---- |
| 前端 | {{frontend_desc}} | {{frontend_tech}} |
| 后端 | {{backend_desc}} | {{backend_tech}} |
| 数据库 | {{db_desc}} | {{db_tech}} |
| 缓存 | {{cache_desc}} | {{cache_tech}} |
| 部署 | {{deploy_desc}} | {{deploy_tech}} |

> 架构细节见 [ARCHITECTURE.md](docs/ARCHITECTURE.md)

---

## 2. 设计原则

### 2.1 本地 AI 优先

多种实现方案并存时，**禁止**引入非必要的服务端 LLM 调用。若确需，须写 ADR 说明理由与成本。

### 2.2 拉取优于推送

**禁止**非必要 Web Push / WebSocket / SSE / 邮件推送。确需须先讨论并文档化。

### 2.3 最小正确改动

- 能 5 行解决的不写 50 行
- 新代码像原作者写的——匹配现有风格
- 禁止顺手重构、无关格式化、扩大 scope

### 2.4 功能模块收尾清理

可独立验收的模块完成时：
- [ ] 无 `console.log` / `dbg!()` / 注释掉的旧实现
- [ ] STATUS 已更新
- [ ] 关键路径测试通过
- [ ] 新踩坑 → PITFALLS.md

---

## 3. 代码风格

| 项 | 要求 |
| -- | ---- |
| 命名 | 见 `quick-ref.md` 对应语言规范 |
| 注释 | 只写非显而易见的业务/技术点；不写「i++ // 自增」这类废话 |
| 文件大小 | 单文件 ≤ 300 行；接近上限时考虑拆分 |
| 导入 | 按标准库 → 第三方 → 内部模块分组，组间空行 |
| 错误处理 | 不吞异常；上游决定如何处理（不提前 catch + log + return null） |

---

## 4. Git 与版本控制

| 项 | 说明 |
| -- | ---- |
| 主分支 | `main`（或 `master`），受保护 |
| 功能分支 | `feature/<name>` / `fix/<name>` |
| 提交信息 | `<type>(<scope>): <简述>` — `feat` / `fix` / `docs` / `refactor` / `chore` / `test` |
| 禁止提交 | `.env` / 密钥 / `node_modules` / 构建产物 |

### 提交信息规范

```
feat(auth): 新增邮箱验证码登录
fix(api): 修复分页参数越界导致 500
docs(readme): 更新本地开发步骤
refactor(db): 抽取公共查询条件
chore(deps): 升级依赖版本
test(e2e): 新增注册流程 E2E
```

---

## 5. 测试

| 层级 | 工具 | 重点 | 覆盖率期望 |
|------|------|------|-----------|
| 单元测试 | {{unit_test_tool}} | 核心逻辑、边界条件 | ≥ 60% |
| 集成测试 | {{integration_test_tool}} | API 端点、数据库交互 | 关键路径全覆盖 |
| E2E | {{e2e_test_tool}} | 用户主流程（注册/登录/核心功能） | 主流程 3～5 条 |

必测安全用例：
- [ ] 用户 A 无法访问用户 B 的数据
- [ ] 无效/过期 Token → 401
- [ ] 输入校验（XSS、SQL 注入、路径穿越）
- [ ] 越权操作（普通用户不能执行管理员操作）

---

## 6. 安全

| 项 | 要求 |
| -- | ---- |
| HTTPS | 生产强制；开发期可选 |
| CSRF | Web POST/PUT/DELETE 须 CSRF Token |
| 鉴权 | Bearer Token 或 Session Cookie；密码 bcrypt/argon2 哈希 |
| 密钥 | `.env` 不入库；`.env.example` 仅含空占位符 |
| 日志 | 不记录密码、Token、身份证号等敏感信息 |
| 依赖 | 定期 `npm audit` / `cargo audit`；高危漏洞 48h 内修复 |

---

## 7. API 设计

| 项 | 规范 |
| -- | ---- |
| 风格 | RESTful |
| 版本 | URL 路径版本 `/api/v1/` |
| 命名 | 复数名词：`/users`、`/prompts`；kebab-case 多词：`/task-suites` |
| 分页 | `?page=1&limit=15`；响应含 `meta: { total, page, last_page }` |
| 错误 | 统一格式 `{ "error": { "code": "...", "message": "..." } }` |
| 成功 | 单条返回对象；列表返回 `{ "data": [...], "meta": {...} }` |

---

## 8. 数据库

| 项 | 规范 |
| -- | ---- |
| 迁移 | 所有 schema 变更通过 migration 文件，不手动改库 |
| 命名 | 表名复数 snake_case：`users`、`task_suites`；字段 snake_case：`created_at` |
| 时间 | 统一 UTC 存储，展示层转换为用户时区 |
| 软删除 | 使用 `deleted_at` + `status = 'deleted'`，不物理删除用户数据 |
| 索引 | 外键、高频查询字段（`user_id`、`slug`、`status`）须建索引 |

---

## 9. 新增功能检查清单

开发新功能时，确认以下各项：

- [ ] PRD / 需求已明确（附 AC 验收标准）
- [ ] 涉及新决策 → DECISIONS.md 新 ADR
- [ ] 涉及新路由/页面 → 确认路由注册、权限检查、CSRF 保护
- [ ] API 变更 → 更新 API 文档；不影响已有调用方
- [ ] 数据库变更 → migration 文件 + 回滚方案
- [ ] 错误处理 → 用户可见的友好提示；不暴露内部错误信息
- [ ] STATUS.md 更新