3a444864ac
签名算法从 COS HMAC-SHA1 改为 TOS V4 HMAC-SHA256， 更新前后端上传凭证字段、配置项、备份脚本和文档。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
139 lines
5.3 KiB
Markdown
139 lines
5.3 KiB
Markdown
# CLAUDE.md — 秒思智能审核平台
|
||
|
||
## 常用命令
|
||
|
||
### 前端 (frontend/)
|
||
```bash
|
||
cd frontend && npm run dev # 开发服务器 http://localhost:3000
|
||
cd frontend && npm run build # 生产构建（含类型检查）
|
||
cd frontend && npm run lint # ESLint 检查
|
||
cd frontend && npm test # Vitest 测试
|
||
cd frontend && npm run test:coverage # 覆盖率报告
|
||
```
|
||
|
||
### 后端 (backend/)
|
||
```bash
|
||
cd backend && uvicorn app.main:app --reload # 开发服务器 http://localhost:8000
|
||
cd backend && pytest # 运行测试
|
||
cd backend && pytest --cov # 带覆盖率
|
||
cd backend && pytest -m "not slow" # 跳过慢测试
|
||
cd backend && alembic upgrade head # 执行数据库迁移
|
||
cd backend && alembic revision --autogenerate -m "msg" # 生成迁移
|
||
```
|
||
|
||
### Docker
|
||
```bash
|
||
cd backend && docker-compose up # 启动 PostgreSQL + Redis + API + Celery
|
||
```
|
||
|
||
## 项目架构
|
||
|
||
**秒思智能审核平台** — AI 营销内容合规审核系统，支持品牌方/代理商/达人三端。
|
||
|
||
```
|
||
video-compliance-ai/
|
||
├── frontend/ Next.js 14 + TypeScript + TailwindCSS (App Router)
|
||
├── backend/ FastAPI + SQLAlchemy 2.0 (async) + PostgreSQL
|
||
├── documents/ 产品文档 (PRD, 设计稿, 约定等)
|
||
└── scripts/ 工具脚本
|
||
```
|
||
|
||
### 前端结构
|
||
```
|
||
frontend/
|
||
├── app/
|
||
│ ├── login/, register/ 认证页面
|
||
│ ├── creator/ 达人端（任务/上传/申诉）
|
||
│ ├── agency/ 代理商端（审核/管理/报表）
|
||
│ └── brand/ 品牌方端（项目/规则/AI配置）
|
||
├── components/ui/ 通用 UI 组件
|
||
├── lib/api.ts Axios API 客户端（所有后端接口已封装）
|
||
├── lib/taskStageMapper.ts 任务阶段 → UI 状态映射
|
||
├── hooks/ 自定义 Hooks（useOSSUpload 等）
|
||
├── contexts/ AuthContext, SSEContext
|
||
└── types/ TypeScript 类型定义（与后端 schema 对齐）
|
||
```
|
||
|
||
### 后端结构
|
||
```
|
||
backend/app/
|
||
├── main.py FastAPI 应用入口，API 前缀 /api/v1
|
||
├── config.py Pydantic Settings 配置
|
||
├── database.py SQLAlchemy async session
|
||
├── celery_app.py Celery 配置
|
||
├── api/ 路由（auth, tasks, projects, briefs, organizations, dashboard, sse, upload, scripts, videos, rules, ai_config）
|
||
├── models/ SQLAlchemy ORM 模型
|
||
├── schemas/ Pydantic 请求/响应 schema
|
||
├── services/ 业务逻辑层
|
||
├── tasks/ Celery 异步任务
|
||
└── utils/ 工具函数
|
||
```
|
||
|
||
## 关键约定
|
||
|
||
### 认证与多租户
|
||
- JWT 双 Token：access 15min + refresh 7天
|
||
- localStorage keys：`miaosi_access_token`, `miaosi_refresh_token`, `miaosi_user`
|
||
- 品牌方 = 租户，数据按品牌方隔离
|
||
- 组织关系多对多：品牌方 ↔ 代理商 ↔ 达人
|
||
|
||
### ID 规范
|
||
- 语义化前缀 + 6位数字：`BR`(品牌方), `AG`(代理商), `CR`(达人), `PJ`(项目), `TK`(任务), `BF`(Brief)
|
||
|
||
### Mock 模式
|
||
- `USE_MOCK` 标志从 `contexts/AuthContext.tsx` 导出
|
||
- 开发环境或 `NEXT_PUBLIC_USE_MOCK=true` 时为 true
|
||
- 每个页面在 `loadData()` 中先检查 `USE_MOCK`，为 true 则使用本地 mock 数据
|
||
|
||
### 前端数据加载模式
|
||
```typescript
|
||
const loadData = useCallback(async () => {
|
||
if (USE_MOCK) { setData(mockData); setLoading(false); return }
|
||
try {
|
||
const res = await api.someMethod()
|
||
setData(res)
|
||
} catch (err) {
|
||
toast.error('加载失败')
|
||
} finally {
|
||
setLoading(false)
|
||
}
|
||
}, [toast])
|
||
useEffect(() => { loadData() }, [loadData])
|
||
```
|
||
|
||
### AI 服务
|
||
- 通过中转服务商（OneAPI/OneInAll）调用，不直连 AI 厂商
|
||
- 配置项：`AI_PROVIDER`, `AI_API_KEY`, `AI_API_BASE_URL`
|
||
|
||
### 文件上传
|
||
- 火山引擎 TOS 直传，前端通过 `useOSSUpload` hook 处理
|
||
- 流程：`api.getUploadPolicy()` → POST 到 TOS → `api.fileUploaded()` 回调
|
||
- TOS V4 签名：HMAC-SHA256，字段包括 `x-tos-algorithm`、`x-tos-credential`、`x-tos-date`、`x-tos-signature`、`policy`
|
||
|
||
### 实时推送
|
||
- SSE (Server-Sent Events)，端点 `/api/v1/sse/events`
|
||
- 前端通过 `SSEContext` 提供 `subscribe(eventType, handler)` API
|
||
|
||
## 设计系统
|
||
|
||
### 暗色主题配色
|
||
- 背景：`bg-page`(#0B0B0E), `bg-card`(#16161A), `bg-elevated`(#1A1A1E)
|
||
- 文字：`text-primary`(#FAFAF9), `text-secondary`(#6B6B70), `text-tertiary`(#4A4A50)
|
||
- 强调色：`accent-indigo`(#6366F1), `accent-green`(#32D583), `accent-coral`(#E85A4F), `accent-amber`(#FFB547)
|
||
- 边框：`border-subtle`(#2A2A2E), `border-strong`(#3A3A40)
|
||
|
||
### 字体
|
||
- 正文：DM Sans
|
||
- 展示：Fraunces
|
||
|
||
## 任务审核流程
|
||
```
|
||
脚本上传 → AI审核 → 代理商审核 → 品牌终审 → 视频上传 → AI审核 → 代理商审核 → 品牌终审 → 完成
|
||
```
|
||
对应 `TaskStage`：`script_upload` → `script_ai_review` → `script_agency_review` → `script_brand_review` → `video_upload` → ... → `completed`
|
||
|
||
## 注意事项
|
||
- 后端 Celery 异步任务（视频审核处理）尚未完整实现
|
||
- 数据库已有 3 个 Alembic 迁移版本
|
||
- `.pen` 文件是加密设计文件，只能通过 Pencil MCP 工具访问
|