开发约定
基本原则
- 先读现有代码和文档，再修改。
- 不主动提交、推送或切分支，除非用户明确要求。
- 小任务一轮推进，完成后留下可追溯记录。
- 编写新功能或修改现有流程时，同步更新
docs/文档站。 - 影响计划、验收或状态时，同步更新
TODO.md。
前端
- 包管理器使用
pnpm。 - 基础 UI 优先使用 shadcn/ui。
- 表单使用 React Hook Form + Zod。
- 用户可见文本必须走 i18n。
- 列表优先使用统一列表组件。
- 状态展示使用语义化 Badge。
后端
- PostgreSQL，不使用 SQLite。
- Secret 和 Token 不明文落业务表。
- 外部平台能力由后端 provider/service/API 适配，前端不编排第三方平台 API。
- 长耗时任务进入 worker，不在 HTTP 请求中同步执行。
验证
小改动做针对性检查；跨多个业务域、认证权限、Secret、数据库迁移或运行时部署相关改动，需要完整验证并优先做浏览器验收。
文档体验
文档是为了减少用户负担。写文档时优先回答：
- 用户现在想完成什么。
- 最短路径是什么。
- 成功后应该看到什么。
- 失败时先看哪里。
内部架构和边界可以放在开发文档里，不要挡在用户开始使用之前。