6a2632da70
将 Clover 从上层产品包旧仓库中独立出来,建立专属版本控制。 当前状态=纵切片端到端已打通(登录→选品→出文出图→审核→下载包), M1文案质量去套路化已验收。此提交作为后续按核销清单逐条修复的基线。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1.6 KiB
1.6 KiB
paths
| paths | |||
|---|---|---|---|
|
API 层开发规则（Clover 后端）
承接架构方案v0.3 基石 + API契约.md，冲突以架构方案为准。
路由规范
- RESTful 命名：资源用名词复数（/tasks, /products, /api-keys）
- 版本前缀：/api/v1/
- 控制器只做：参数校验 → 调 service → 格式化响应，不含业务逻辑
响应格式（统一包络）
- 成功：
{ "code": 0, "data": {...} } - 失败：
{ "code": <错误码>, "message": "用户可读信息" } - HTTP 状态码与业务 code 分离（见契约§0七类错误码）
安全（基石B/C）
- 所有用户输入必须校验（类型、长度、范围）
- SQL 查询使用参数化，禁止字符串拼接
- API Key 绝不进 Celery 参数，只传 task_id；worker 内查库→Fernet解密→局部变量
- FERNET_KEY 走环境变量，绝不进代码库；解密不落盘、不打日志
- 敏感操作记审计日志（ai_call_logs）
多租户隔离（红线）
- 所有查询强制带 workspace_id 条件
- 写操作 + 切 workspace 必须查 workspace_members 校验权限
- workspace_id / product_id 从 JWT + 上下文自动带，前端不传（防越权）
- 所有 workspace 相关 Repo 继承 base_workspace_repo
错误处理（官网V1坑3）
- service 错误不许静默吞，至少打 error log
- AI/token站调用失败归因到个人 key（错误码50002）
- DB 枚举约束要有对应代码侧常量文件
业务参数不写死（基石A）
- 禁止出现品类/数量/角度任何枚举常量
- "看起来像枚举"的业务概念 → 做成数据不做成代码