6a2632da70
将 Clover 从上层产品包旧仓库中独立出来,建立专属版本控制。 当前状态=纵切片端到端已打通(登录→选品→出文出图→审核→下载包), M1文案质量去套路化已验收。此提交作为后续按核销清单逐条修复的基线。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
43 lines
1.6 KiB
Markdown
43 lines
1.6 KiB
Markdown
---
|
||
paths:
|
||
- "src/api/**"
|
||
- "src/routers/**"
|
||
- "src/services/**"
|
||
---
|
||
|
||
# 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）
|
||
- 禁止出现品类/数量/角度任何枚举常量
|
||
- "看起来像枚举"的业务概念 → 做成数据不做成代码
|