video-shuoshan/CLAUDE.md

# Jimeng Clone — AI Video Generation Platform

> This file is the single source of truth for AI-assisted development on this project.
> AI agents (including Claude Code) should read this file first before making any changes.

## Quick Start

### Development Environment
- **Backend**: Python 3.12 + Django 4.2 + DRF + SimpleJWT
- **Frontend**: React 18 + Vite 6 + TypeScript 5 + Zustand
- **Database**: SQLite (dev) / Aliyun RDS MySQL (prod)
- **UI Library**: Arco Design (`@arco-design/web-react`)
- **Charts**: ECharts 6 + echarts-for-react

### Setup Commands
```bash
# Backend
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver 8000

# Frontend
cd web
npm install
npm run dev          # Dev server at localhost:5173
npm run build        # Production build: tsc -b && vite build
```

### Test Commands
```bash
# Frontend unit tests
cd web && npx vitest run

# Backend checks
cd backend && python manage.py check
```

### Admin Credentials (Dev)
- Username: `admin` / Password: `admin123`

## Project Architecture

### Directory Structure
```
jimeng-clone/
├── backend/                 # Django REST Framework backend
│   ├── config/              # Django settings, urls, wsgi
│   │   ├── settings.py      # Main config (DB, CORS, JWT, apps)
│   │   └── urls.py          # Root URL routing
│   ├── apps/
│   │   ├── accounts/        # User auth: models, views, serializers, urls
│   │   └── generation/      # Video generation: models, views, serializers, urls
│   ├── requirements.txt     # Python dependencies
│   └── Dockerfile           # Python 3.12 + gunicorn
├── web/                     # React 18 + Vite frontend
│   ├── src/
│   │   ├── App.tsx          # Root router (all routes defined here)
│   │   ├── main.tsx         # Entry point
│   │   ├── pages/           # Page-level components (one per route)
│   │   ├── components/      # Reusable UI components
│   │   ├── store/           # Zustand state stores
│   │   ├── lib/             # Utilities (API client, log center)
│   │   └── types/           # TypeScript type definitions
│   ├── nginx.conf           # Production nginx config
│   └── Dockerfile           # Node 18 + nginx
├── k8s/                     # Kubernetes deployment configs
├── docs/                    # PRD, design review documents
├── .gitea/workflows/        # CI/CD pipeline
└── .autonomous/             # Autonomous skill task tracking
```

### Key Files (Most Commonly Modified)
- `web/src/App.tsx` — Route definitions. Modify when adding new pages.
- `web/src/store/auth.ts` — Auth state (login/logout/JWT refresh)
- `web/src/store/generation.ts` — Video generation state & API calls
- `web/src/store/inputBar.ts` — Input bar state (mode, files, prompt)
- `web/src/lib/api.ts` — Axios client with JWT interceptor. API base URL configured here.
- `web/src/types/index.ts` — All TypeScript interfaces
- `backend/config/settings.py` — Django settings (DB, CORS, JWT, installed apps)
- `backend/config/urls.py` — Root URL routing
- `backend/apps/accounts/models.py` — User model (extends AbstractUser)
- `backend/apps/generation/models.py` — GenerationRecord + QuotaConfig models
- `backend/apps/generation/views.py` — All API endpoints (video, admin, profile)
- `backend/apps/generation/urls.py` — API URL patterns

## Development Conventions

### Code Style
- **Frontend**: TypeScript strict mode, functional components, named exports
- **Backend**: PEP 8, function-based views with `@api_view` decorator
- **CSS**: Inline styles + Arco Design component props (no separate CSS modules)

### Naming Conventions
- **React Components**: PascalCase files (e.g., `LoginPage.tsx`, `InputBar.tsx`)
- **Stores**: camelCase files (e.g., `auth.ts`, `generation.ts`)
- **Django Apps**: lowercase (e.g., `accounts`, `generation`)
- **API URLs**: `/api/v1/` prefix, no trailing slashes in URL patterns
- **Database**: snake_case (Django default)

### State Management Pattern
- Zustand stores in `web/src/store/`, one store per domain
- Each store exports a `use[Name]Store` hook
- API calls are defined inside stores (not in components)
- Pattern: `const doSomething = useAuthStore((s) => s.doSomething)`

### Component Pattern
- Pages in `web/src/pages/` — full-page components mounted by router
- Reusable components in `web/src/components/`
- Protected routes use `<ProtectedRoute>` wrapper, admin routes add `requireAdmin` prop

### Backend Pattern
- Function-based views with `@api_view(['GET', 'POST'])` decorator
- Auth via `@permission_classes([IsAuthenticated])`
- Admin endpoints check `request.user.is_staff`
- Singleton pattern for QuotaConfig (pk always = 1)

## API Endpoints

### Auth (`/api/v1/auth/`)
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/auth/register` | User registration |
| POST | `/api/v1/auth/login` | JWT login (returns access + refresh tokens) |
| POST | `/api/v1/auth/token/refresh` | Refresh JWT access token |
| GET | `/api/v1/auth/me` | Get current user info |

### Video Generation (`/api/v1/`)
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/media/upload` | Upload reference media files |
| POST | `/api/v1/video/generate` | Submit video generation task |
| GET | `/api/v1/video/tasks` | List user's generation tasks |
| GET | `/api/v1/video/tasks/<uuid>` | Get task status & result |

### Admin (`/api/v1/admin/`)
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/admin/stats` | Dashboard statistics & charts data |
| GET | `/api/v1/admin/users` | List all users (search, filter, paginate) |
| POST | `/api/v1/admin/users/create` | Create new user |
| GET/PUT | `/api/v1/admin/users/<id>` | Get/update user details |
| PUT | `/api/v1/admin/users/<id>/quota` | Update user quota limits |
| PUT | `/api/v1/admin/users/<id>/status` | Toggle user active status |
| GET | `/api/v1/admin/records` | List all generation records |
| GET/PUT | `/api/v1/admin/settings` | Get/update global settings (QuotaConfig) |

### Profile (`/api/v1/profile/`)
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/profile/overview` | User consumption summary |
| GET | `/api/v1/profile/records` | User's own generation records |

## Database Models

### User (extends AbstractUser)
- `email` (unique), `daily_seconds_limit` (default: 600), `monthly_seconds_limit` (default: 6000)
- `created_at`, `updated_at`

### GenerationRecord
- `user` (FK), `task_id` (UUID), `ark_task_id`, `prompt`, `mode` (universal|keyframe)
- `model` (seedance_2.0|seedance_2.0_fast), `aspect_ratio`, `duration`, `seconds_consumed`
- `status` (queued|processing|completed|failed), `result_url`, `error_message`, `reference_urls` (JSON)
- Index: (user, created_at)

### QuotaConfig (Singleton, pk=1)
- `default_daily_seconds_limit`, `default_monthly_seconds_limit`
- `announcement`, `announcement_enabled`, `updated_at`

## Frontend Routes

| Path | Component | Auth | Description |
|------|-----------|------|-------------|
| `/login` | LoginPage | No | Login page |
| `/` | VideoGenerationPage | Yes | Main video generation UI |
| `/profile` | ProfilePage | Yes | User consumption overview |
| `/admin/dashboard` | DashboardPage | Admin | Stats & charts |
| `/admin/users` | UsersPage | Admin | User management |
| `/admin/records` | RecordsPage | Admin | Generation records |
| `/admin/settings` | SettingsPage | Admin | Global quota & announcement |

## Incremental Development Guide

### How to Add Features to This Project

This project was generated and maintained using **agent-auto**（多 Agent 协作自动开发系统）。
项目路径：`/Users/maidong/Desktop/zyc/研究openclaw/agent-auto/`

增量开发有两种方式：

#### 方式 1：Direct AI Development（小改动）
Bug 修复、UI 微调、单个接口等小改动，直接在 Claude Code 中描述需求即可。
Claude Code 会读取本文件（CLAUDE.md）理解项目上下文。

示例：
- "Add a logout button to the navbar"
- "Fix the date format in the records table"
- "修改轮询间隔为 3 分钟"
- "Change the default daily quota from 600 to 1200 seconds"

**IMPORTANT — 每次改动后必须更新文档：**

1. **更新 `CLAUDE.md`**（本文件）：
   - 新 API 端点 → 加到 API Endpoints 表
   - 新页面/路由 → 加到 Frontend Routes 表
   - 新 model/字段 → 加到 Database Models 区
   - 配置变更 → 更新对应区
   - 始终在底部 **Change History** 表加一行

2. **更新 Claude Code memory**（如有）：
   - 更新 `~/.claude/projects/` 下的 memory 文件
   - 确保跨会话的 AI 也能了解变更

3. **非架构性改动也要记录**：
   - Bug fix / UI 微调 / 依赖更新 / 配置值变更 → 都加到 Change History

未更新文档会导致后续 AI 会话使用过期上下文，引发冲突或重复工作。

#### 方式 2：agent-auto（大功能 / 全栈新模块）
涉及 3+ 文件、新模块、跨模块重构等复杂需求，使用 agent-auto 自动完成全流程：

```
需求 → PRD → HTML 原型 → 设计评审 → 全栈代码 → 测试 → Bug 修复循环 → 完成
```

**运行命令：**
```bash
cd /Users/maidong/Desktop/zyc/研究openclaw/agent-auto

# 增量需求（在已有项目上加功能）
npx tsx src/index.ts --resume /Users/maidong/Desktop/zyc/研究openclaw/视频生成平台/jimeng-clone "你的增量需求描述"

# 崩溃恢复 / 继续执行
npx tsx src/index.ts --resume /Users/maidong/Desktop/zyc/研究openclaw/视频生成平台/jimeng-clone
```

**agent-auto 会自动：**
1. 读取 `.agent-auto/state.json` 恢复项目状态
2. product-agent 修订 PRD（`docs/prd.md`）
3. design-agent 更新 HTML 原型（`prototype/`）
4. product-agent 设计评审（`docs/design-review.md`，APPROVED/REJECTED 循环）
5. dev-agent 增量开发（保留已有代码，只新增/修改）
6. test-agent 测试 + Bug 分类（`test-report.md`）
7. Bug 修复循环（CODE_BUG → dev-agent / DESIGN_BUG → design-agent / REQUIREMENT_BUG → product-agent）
8. 全部通过 → COMPLETE

**状态持久化**：进度保存在 `.agent-auto/state.json`，中断后可随时 `--resume` 继续。

**Agent 记忆**：每个 Agent 有独立记忆文件（`.agent-auto/{agent-name}/memory.md`），跨轮次保持上下文。

#### 变更日志维护
每次需求开发完成、测试验收通过后，**必须**在 `docs/changelog.md` 中记录本次变更：
- 按日期倒序添加新条目（最新的在最前面）
- 包含：变更标题、状态/验收、变更内容、变更文件、触发原因
- 文件末尾有模板可直接复制使用
- Direct AI 和 agent-auto 两种方式均需记录

#### 何时用哪种方式
| 场景 | 方式 |
|------|------|
| Bug 修复 / 单行改动 | Direct AI |
| UI 微调（按钮、颜色、文案） | Direct AI |
| 添加单个 API 端点 | Direct AI |
| 修改已有组件行为 | Direct AI |
| 新功能模块（3+ 文件） | agent-auto |
| 新增整页 CRUD（如管理页面） | agent-auto |
| 跨多文件重构 | agent-auto |
| 新增子系统（通知、支付、权限） | agent-auto |

### How to Add a New Page

1. Create page component in `web/src/pages/NewPage.tsx`
2. Add route in `web/src/App.tsx` inside `<Routes>`:
   ```tsx
   <Route path="/new-page" element={<ProtectedRoute><NewPage /></ProtectedRoute>} />
   ```
3. If it needs state, create store in `web/src/store/newPage.ts`
4. Add API calls in the store using `api.get()` / `api.post()` from `web/src/lib/api.ts`

### How to Add a New API Endpoint

1. Add view function in `backend/apps/generation/views.py` (or relevant app):
   ```python
   @api_view(['GET'])
   @permission_classes([IsAuthenticated])
   def new_endpoint_view(request):
       return Response({'data': ...})
   ```
2. Add URL pattern in `backend/apps/generation/urls.py`:
   ```python
   path('new/endpoint', views.new_endpoint_view, name='new_endpoint'),
   ```
3. Add TypeScript types in `web/src/types/index.ts`
4. Add API call in the relevant Zustand store

### How to Add a New Database Model

1. Define model in `backend/apps/generation/models.py` (or relevant app)
2. Run migrations:
   ```bash
   cd backend
   python manage.py makemigrations
   python manage.py migrate
   ```
3. Register in admin: `backend/apps/generation/admin.py`
4. Create serializer if needed: `backend/apps/generation/serializers.py`

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `DATABASE_URL` | MySQL connection string (prod) | Prod only |
| `SECRET_KEY` | Django secret key | Yes |
| `TOS_ACCESS_KEY` | Volcano Engine TOS AccessKeyId | Yes (upload) |
| `TOS_SECRET_KEY` | Volcano Engine TOS SecretAccessKey | Yes (upload) |
| `TOS_BUCKET` | Volcano TOS bucket name (default: `video-huoshan`) | Yes (upload) |
| `TOS_ENDPOINT` | TOS endpoint URL (default: `https://tos-cn-guangzhou.volces.com`) | Yes (upload) |
| `TOS_REGION` | TOS region (default: `cn-guangzhou`) | Yes (upload) |
| `ARK_API_KEY` | Volcano Engine ARK API key for Seedance | Yes (video gen) |
| `ARK_BASE_URL` | ARK API base URL (default: `https://ark.cn-beijing.volces.com/api/v3`) | No |

## Deployment

- **CI/CD**: Gitea Actions (`.gitea/workflows/deploy.yaml`)
- **Registry**: Huawei Cloud SWR
- **Orchestration**: Kubernetes (`k8s/` directory)
- **Backend URL**: `video-huoshan-api.airlabs.art`
- **Frontend URL**: `video-huoshan-web.airlabs.art`
- **Database**: Aliyun RDS MySQL (`rm-7xv1uaw910558p1788o.mysql.rds.aliyuncs.com:3306`)

## Testing

- **Unit Tests**: 227 tests in `web/` via Vitest — `cd web && npx vitest run`
- **E2E Tests**: 49 tests via Playwright — `cd web && npx playwright test`
- **Backend**: Django system checks — `cd backend && python manage.py check`
- **Status**: 211 passing, 16 pre-existing path-resolution failures in phase2/phase3 tests
- **Test DB Isolation**: E2E tests use `TESTING=true` env var → backend writes to `test_db.sqlite3` (not `db.sqlite3`). Playwright auto-starts a test backend on port 8000 with this env var. Dev data is never polluted by tests.

## Design Guidelines

- **Color Palette**: `#0a0a0f` (bg), `#111118`, `#16161e`, `#2a2a38`, `#00b8e6` (accent)
- **Typography**: Noto Sans SC (Chinese) + Space Grotesk (UI) + JetBrains Mono (code)
- **Style**: Linear/Vercel dark theme aesthetic
- **Responsive**: `grid-cols-4 max-lg:grid-cols-2`

## Change History

> 完整变更日志见 [`docs/changelog.md`](docs/changelog.md)，以下为摘要。

| Date | Change | Scope |
|------|--------|-------|
| 2025-01 | Phase 1: Core video generation UI | Frontend |
| 2025-02 | Phase 2: Backend + Auth + Admin panel | Full stack |
| 2025-03 | Phase 3: Seconds-based quota, profile page, ECharts dashboard | Full stack |
| 2026-03 | Added CLAUDE.md for AI-assisted incremental development | Documentation |
| 2026-03-13 | Phase 4: TOS upload + Seedance API integration + DB persistence | Full stack |
| 2026-03-13 | Test DB isolation: TESTING=true → test_db.sqlite3, Playwright auto-starts test backend | Backend + Config |
| 2026-03-13 | Removed mock data fallback from DashboardPage — charts show real data only | Frontend |
| 2026-03-13 | LogCenterMiddleware: Django 中间件兜底异常上报（捕获 DRF 之外的导入/中间件/URL 解析错误） | Backend |
| 2026-03-13 | custom_exception_handler: 未处理异常返回 JSON 500 而非 HTML | Backend |
| 2026-03-13 | 前端轮询间隔从 5 秒改为 3 分钟 | Frontend |
| 2026-03-13 | CLAUDE.md 增量开发指南更新为 agent-auto（替换 Autonomous Skill） | Documentation |

### Phase 4 Details (2026-03-13)

**Backend new files:**
- `backend/utils/tos_client.py` — Volcano Engine TOS upload via official `tos` SDK
- `backend/utils/seedance_client.py` — Seedance/ARK API client (create_task, query_task)

**Backend changes:**
- `backend/config/settings.py` — Added TOS and ARK config
- `backend/apps/generation/models.py` — Added `ark_task_id`, `result_url`, `error_message`, `reference_urls` (JSONField)
- `backend/apps/generation/views.py` — New endpoints: `upload_media_view`, `video_tasks_list_view`, `video_task_detail_view`; Rewritten `video_generate_view` with Seedance integration
- `backend/apps/generation/urls.py` — Added 3 routes: `media/upload`, `video/tasks`, `video/tasks/<uuid>`
- `backend/apps/generation/serializers.py` — Added `references` field to VideoGenerateSerializer
- `backend/requirements.txt` — Added `tos>=2.7`, `requests>=2.31`
- Migration: `0003_generationrecord_ark_task_id_and_more.py`

**Frontend changes:**
- `web/src/types/index.ts` — Added `BackendTask` interface, `tosUrl` to `UploadedFile`, `taskId`/`errorMessage` to `GenerationTask`
- `web/src/lib/api.ts` — Added `mediaApi.upload()`, `videoApi.getTasks()`, `videoApi.getTaskStatus()`; Changed `videoApi.generate()` to JSON
- `web/src/store/generation.ts` — Complete rewrite: async TOS upload + API calls + polling + `loadTasks()` for refresh persistence
- `web/src/components/VideoGenerationPage.tsx` — Added `loadTasks()` on mount
- `web/src/components/GenerationCard.tsx` — Video player for results, error state display

**Flow:** Upload files → TOS → Generate API (Seedance) → DB record → Poll status → Display result