---
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）
- 禁止出现品类/数量/角度任何枚举常量
- "看起来像枚举"的业务概念 → 做成数据不做成代码