# 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 工具访问