4b8809efe2
- 认证：双 Token JWT 方案，支持邮箱/手机号登录 - 组织：多对多关系（品牌方↔代理商↔达人） - 文件：阿里云 OSS 直传，分片上传，最大 500MB - AI：全部走中转服务商 - 审核：终审默认开启，代理商默认有强制通过权 - 技术：PostgreSQL + Redis + SSE Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
233 lines
5.1 KiB
Markdown
233 lines
5.1 KiB
Markdown
# 项目约定与设计决策
|
||
|
||
本文档记录容易被误解的设计决策，确保开发一致性。
|
||
|
||
---
|
||
|
||
## 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 等） |
|
||
|
||
---
|
||
|
||
## 其他约定
|
||
|
||
（后续添加）
|