# 项目约定与设计决策

本文档记录容易被误解的设计决策，确保开发一致性。

---

## AI 服务配置

**重要：系统使用 AI 中转服务商，不直连 AI 厂商！**

- 使用 OneAPI / OneInAll / OpenRouter 等中转服务商
- 中转服务商统一了不同 AI 厂商（豆包、通义、DeepSeek 等）的接口
- 只需配置中转服务商的 API Key 和 Base URL
- 具体使用哪个底层模型，由中转服务商的模型名称决定

```python
# 正确 ✓
AI_PROVIDER = "oneapi"
AI_API_BASE_URL = "https://api.oneinall.ai/v1"

# 错误 ✗ - 不直接配置 AI 厂商
AI_PROVIDER = "doubao"
```

---

## 用户认证

### 登录方式

支持两种登录方式（二选一）：
- **邮箱 + 密码**
- **手机号 + 验证码**

### 注册流程

- 自助注册，支持邮箱注册或手机号注册
- 邮箱注册后，可在设置中绑定手机号，之后可用手机号登录
- 手机号注册后，可在设置中绑定邮箱，之后可用邮箱登录
- 两种登录方式关联同一账号

### JWT 双 Token 方案

**后端设计：**
```json
// POST /api/v1/auth/login 返回
{
  "accessToken": "xxx",   // 有效期 15 分钟
  "refreshToken": "xxx",  // 有效期 7 天
  "user": {
    "id": "user-001",
    "name": "张三",
    "email": "zhang@example.com",
    "phone": "138****8888",
    "role": "agency",
    "tenantId": "tenant-001",
    "tenantName": "美妆品牌A"
  }
}

// POST /api/v1/auth/refresh 刷新 Token
// 请求：{ "refreshToken": "xxx" }
// 返回：{ "accessToken": "新的 accessToken" }
```

**前端设计（Axios 拦截器）：**
1. Token 存入 localStorage
2. 请求拦截器：自动添加 `Authorization: Bearer {accessToken}`
3. 响应拦截器：
   - 监听 401 错误
   - 触发后暂停后续请求
   - 调用 `/refresh` 接口换新 Token
   - 更新本地存储
   - 自动重发失败的原请求
   - 若刷新也失败，清空存储并跳转登录页

---

## 多租户与组织关系

### 租户定义

- **租户 = 品牌方**
- 数据隔离按品牌方划分（品牌方 A 看不到品牌方 B 的数据）

### 组织关系（多对多）

```
品牌方 ←→ 代理商（多对多）
代理商 ←→ 达人（多对多）
```

- 一个品牌方可以有多个代理商
- 一个代理商可以服务多个品牌方
- 一个代理商可以有多个达人
- 一个达人可以服务多个代理商

### 注册与邀请流程

1. **品牌方**：自助注册
2. **代理商**：自助注册 → 被品牌方邀请加入
3. **达人**：自助注册 → 被代理商邀请加入

### 任务分配流程

```
品牌方发布项目
    ↓
分配给多个代理商
    ↓
代理商选择达人并分配任务（可多次选同一达人）
    ↓
达人收到任务：宣传任务(1)、宣传任务(2)...
    ↓
达人只能接受/完成任务，不能自己创建任务
```

### 语义化 ID

- 代理商 ID：`AG` + 6位数字，如 `AG123456`
- 达人 ID：`CR` + 6位数字，如 `CR123456`
- 品牌方 ID：`BR` + 6位数字，如 `BR123456`

---

## 文件存储

### 存储服务

- **阿里云 OSS**
- 公开访问（无需签名 URL）

### 上传方式

- **前端直传 OSS**
- 后端提供 STS 临时凭证或签名
- 前端使用阿里云 OSS SDK 直传

### 文件大小限制

- 最大 **500MB**
- 采用**分片上传（Multipart Upload）**
- 适应达人上传高清原片的需求

### 支持的文件类型

| 类型 | 格式 |
|------|------|
| 脚本 | .docx, .pdf, .xlsx, .txt, .pptx |
| 视频 | .mp4, .mov, .webm |
| 图片 | .jpg, .png, .gif |

---

## AI 审核能力

### 统一走中转

所有 AI 能力都通过中转服务商调用，不单独接入其他服务：

| 能力 | 实现方式 |
|------|----------|
| 文本分析 | 中转 LLM |
| 语音转文字 (ASR) | 中转（如 Whisper） |
| 字幕识别 (OCR) | 中转视觉模型 |
| Logo/画面检测 | 中转视觉模型 + Brief/规则 |

### 模型列表

- 从后端动态获取（后端可从中转商 API 拉取可用模型）
- 前端不硬编码模型列表

### Logo 检测逻辑

- 将 Brief 中的竞品信息 + 平台规则传给 AI
- AI 分析视频画面，识别是否出现竞品 Logo
- 不需要自训练模型，依赖多模态 AI 的理解能力

---

## 审核流程

### 品牌方终审

- **默认开启**
- 品牌方可在设置中关闭

### 强制通过权

- **代理商默认拥有**
- 品牌方可按代理商关闭此权限

### 申诉机制

- 每个任务初始 **1 次** 申诉机会
- 用完后可向代理商申请增加
- 代理商可同意/拒绝申请

---

## Brief 与规则

### 平台规则库

- 抖音/小红书/B站等平台规则
- **手动录入**，后台管理
- 规则更新需人工维护

### Brief 解析

- AI 自动解析 Brief 文档
- 提取：卖点、违禁词、品牌调性要求
- 支持格式：PDF/Word/Excel/PPT/图片

---

## 技术选型

| 项目 | 选择 |
|------|------|
| 数据库 | PostgreSQL |
| 缓存 | Redis |
| 消息推送 | **SSE**（Server-Sent Events） |
| 邮件/短信 | 暂不实现 |
| 文件存储 | 阿里云 OSS |
| AI 服务 | 中转服务商（OneAPI 等） |

---

## 其他约定

（后续添加）