liyanyu/video-compliance-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
video-compliance-ai/CONVENTIONS.md
Your Name 4b8809efe2 docs: 完善项目约定文档 
- 认证：双 Token JWT 方案，支持邮箱/手机号登录
- 组织：多对多关系（品牌方↔代理商↔达人）
- 文件：阿里云 OSS 直传，分片上传，最大 500MB
- AI：全部走中转服务商
- 审核：终审默认开启，代理商默认有强制通过权
- 技术：PostgreSQL + Redis + SSE

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-09 13:38:12 +08:00

5.1 KiB
Raw Blame History

项目约定与设计决策

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

AI 服务配置

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

  • 使用 OneAPI / OneInAll / OpenRouter 等中转服务商
  • 中转服务商统一了不同 AI 厂商（豆包、通义、DeepSeek 等）的接口
  • 只需配置中转服务商的 API Key 和 Base URL
  • 具体使用哪个底层模型，由中转服务商的模型名称决定
# 正确 ✓
AI_PROVIDER = "oneapi"
AI_API_BASE_URL = "https://api.oneinall.ai/v1"

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

用户认证

登录方式

支持两种登录方式（二选一）：

  • 邮箱 + 密码
  • 手机号 + 验证码

注册流程

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

JWT 双 Token 方案

后端设计：

// 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 等）

其他约定

（后续添加）