Dev backend

后端先行

按契约实现后端。核心纪律：契约是合同——实现过程中发现契约不合理，先改 03-api-contract.md 再改代码，绝不让代码悄悄偏离文档。

前置检查

1. 读取 docs/dev/02-architecture.md 和 docs/dev/03-api-contract.md。缺失则建议先跑 /dev-architecture；用户坚持直接写时，先花几分钟现场补一份最小契约（全局约定 + 接口清单）再动手。
2. 确认本地环境：数据库能连上、依赖能装、端口不冲突。环境起不来就先解决环境，不要盲写代码。

开工前对齐（必须）

前置检查完成后，先向用户列出本次实现计划：要实现的接口清单、实现顺序、涉及的表和文件。用户明确同意后才开始写代码；用户要砍范围或调顺序，先改计划再动手。

商量必须自带默认推荐：计划本身就是你的推荐方案，直接说"建议按此执行，确认即开工"；有多个可选路线时标注「推荐」项+一句理由，不许只抛开放式问题。

实现顺序

严格按依赖方向从下往上，每层可验证后再进入下一层：

1. 数据层

• 按架构文档的 ER 图写建表迁移（用项目技术栈自带的 migration 机制；没有就用带序号的 SQL 文件 migrations/001_xxx.sql）。
• 写种子数据脚本：至少 1 个测试账号 + 每张核心表 3-5 条真实形状的数据（不要 "test1/test2" 式敷衍数据，前端要拿它做展示开发）。
• 验证：迁移能在空库上从零执行成功。

2. 服务层（业务逻辑）

• 按模块实现业务逻辑，与 HTTP 层解耦（service 不 import web 框架）。
• 校验规则、权限判断、事务边界都在这一层，不散落在 controller 里。

3. 接口层

• 严格按契约实现：路径、方法、参数名、响应结构、错误码逐项对齐。
• 统一响应包装和全局异常处理先做——保证任何错误都返回契约约定的结构，而不是框架默认的 500 堆栈。
• 认证中间件就位后，逐个接口标注需要/不需要登录。

4. 自测验证

每完成一个接口立即验证，不攒到最后：

• 用 curl（或项目已有的测试框架）跑通：正常路径、参数缺失、参数非法、未登录、无权限。
• 响应 JSON 与契约中的示例逐字段比对——字段名大小写、类型、null 处理都算。
• 关键业务逻辑写单元测试；接口层至少每个端点一条 happy-path 测试。

完成标准（全部满足才算交付）

• docs/dev/03-api-contract.md 中所有 P0 接口状态更新为 ✅ 后端已实现
• 空库 → 迁移 → 种子数据 → 启动服务，一套命令能从零跑起来（把命令写进契约文档"本地启动"一节）
• 每个接口的 curl 验证命令记录在契约文档对应接口下（前端联调直接可用）
• 测试全绿；实现与契约有出入的地方已回写契约并标注变更原因

交接

向用户汇报：实现了哪些接口、启动命令、测试账号密码、遗留问题。 提示：下一步运行 /dev-frontend 开始前端实现。

原则

• 一次只做一个模块，做完自测再做下一个；不要铺开写完所有 controller 再回头调。
• 发现需求或契约有歧义，停下来问用户，不要按自己的猜测实现后让联调买单。
• 日志：每个请求可追踪（方法/路径/耗时/错误），但不打印密码和 token。
• 密钥、数据库密码走 env 文件，提供 .env.example，真实 .env 进 .gitignore。