baseline: Clover 独立仓库首次基线提交

将 Clover 从上层产品包旧仓库中独立出来,建立专属版本控制。
当前状态=纵切片端到端已打通(登录→选品→出文出图→审核→下载包),
M1文案质量去套路化已验收。此提交作为后续按核销清单逐条修复的基线。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
yangqianqian
2026-06-16 11:30:22 +08:00
commit 6a2632da70
253 changed files with 27467 additions and 0 deletions

View File

@@ -0,0 +1,42 @@
---
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_idworker 内查库→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
- 禁止出现品类/数量/角度任何枚举常量
- "看起来像枚举"的业务概念 → 做成数据不做成代码