admin/mcn-short-video
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
daf160447c030490c605cac5b3f806f00a2aa6d9
mcn-short-video/project/AI创作平台toc/ENGINEERING_BLUEPRINT.md
T

857 lines
27 KiB
Markdown
Raw Normal View History

Full upload: MCNVideo AI project with .workbuddy
2026-08-06 23:44:59 +08:00
# AI 短视频创作平台 — 工程骨架方案
> 本方案由 WorkBuddy 产出，交付给 Trae 执行。
> 定位：toC 产品，Python 后端 + React 前端，独立部署。
---
## 一、技术栈总览
| 层 | 技术 | 版本 | 角色 |
|---|---|---|---|
| **前端框架** | React | 19.x | UI 层 |
| **构建工具** | Vite | 6.x | 开发/打包 |
| **语言** | TypeScript | 5.x | 前端类型安全 |
| **UI 组件** | shadcn/ui | latest | 原子组件库 |
| **样式** | Tailwind CSS | 4.x | 原子化样式 |
| **拖拽** | @dnd-kit | latest | 时间轴/素材拖拽 |
| **画布** | react-konva | latest | 预览画布/文字贴纸 |
| **状态管理** | zustand | 5.x | 编辑器状态 + 撤销重做 |
| **数据请求** | @tanstack/react-query | 5.x | 服务端状态/缓存 |
| **动画** | framer-motion | 11.x | 过渡动效 |
| **路由** | react-router | 7.x | 页面路由 |
| **表单** | react-hook-form + zod | latest | 表单校验 |
| **后端框架** | FastAPI | 0.115+ | REST API + WebSocket |
| **ASGI 服务器** | uvicorn | latest | 生产级运行 |
| **数据库** | PostgreSQL + Redis | 16 / 7 | 持久化 + 缓存/队列 |
| **ORM** | SQLAlchemy 2.0 | 2.x | 数据库映射 |
| **任务队列** | Celery + Redis | 5.x | AI 异步生成 |
| **文件存储** | MinIO / S3 | — | 视频/素材存储 |
| **AI 集成** | OpenAI SDK / 本地模型 | — | 脚本生成/视频处理 |
---
## 二、目录结构
```
ai-video-platform/
├── frontend/ # React 前端
│ ├── index.html
│ ├── package.json
│ ├── tsconfig.json
│ ├── vite.config.ts
│ ├── tailwind.config.ts
│ ├── components.json # shadcn/ui 配置
│ ├── public/
│ │ └── favicon.svg
│ └── src/
│ ├── main.tsx # 入口
│ ├── App.tsx # 根组件 + 路由
│ ├── index.css # Tailwind 入口
│ ├── lib/
│ │ └── utils.ts # cn() 工具函数
│ ├── components/
│ │ ├── ui/ # shadcn/ui 组件（自动生成）
│ │ │ ├── button.tsx
│ │ │ ├── card.tsx
│ │ │ ├── dialog.tsx
│ │ │ ├── slider.tsx
│ │ │ ├── tabs.tsx
│ │ │ ├── dropdown-menu.tsx
│ │ │ ├─�� input.tsx
│ │ │ ├── textarea.tsx
│ │ │ ├── select.tsx
│ │ │ ├── toast.tsx
│ │ │ ├── tooltip.tsx
│ │ │ ├── sheet.tsx # 侧边栏
│ │ │ └── skeleton.tsx # 加载骨架
│ │ ├── layout/
│ │ │ ├── AppShell.tsx # 整体布局壳
│ │ │ ├── Sidebar.tsx # 左侧导航
│ │ │ └── Header.tsx # 顶部栏
│ │ ├── editor/ # 🔥 视频编辑器核心
│ │ │ ├── Timeline/
│ │ │ │ ├── Timeline.tsx # 时间轴容器
│ │ │ │ ├── Track.tsx # 单条轨道
│ �� │ │ ├── TrackItem.tsx # 轨道上的片段
│ │ │ │ ├── TimelineRuler.tsx # 时间标尺
│ │ │ │ └── TimelineControls.tsx # 缩放/播放控制
│ │ │ ├── Canvas/
│ │ │ │ ├── PreviewCanvas.tsx # 预览画布（react-konva）
│ │ │ │ ├── TextOverlay.tsx # 文字叠层
│ │ │ │ ├── StickerLayer.tsx # 贴纸层
│ │ │ │ └── VideoLayer.tsx # 视频画面层
│ │ │ ├── Toolbar/
│ │ │ │ ├── EditorToolbar.tsx # 编辑工具栏
│ │ │ │ ├── CropTool.tsx # 裁剪工具
│ │ │ │ └── TextTool.tsx # 文字工具
│ │ │ └── AssetPanel/
│ │ │ ├── AssetLibrary.tsx # 素材库面板
│ │ │ ├── MediaUploader.tsx # 上传组件
│ │ │ └── AIGenerator.tsx # AI 生成入口
│ │ ├── ai/ # AI 功能面板
│ │ │ ├── ScriptGenerator.tsx # 脚本生成
│ │ │ ├── VoiceGenerator.tsx # AI 配音
│ │ │ ├── SubtitleGenerator.tsx # 字幕生成
│ │ │ └── GenerationProgress.tsx # 生成进度（WebSocket）
│ │ └── common/
│ │ ├── LoadingSpinner.tsx
│ │ ├── ErrorBoundary.tsx
│ │ ├── EmptyState.tsx
│ │ └── ConfirmDialog.tsx
│ ├── pages/
│ │ ├── Home.tsx # 首页/项目列表
│ │ ├── Editor.tsx # 🔥 编辑器主页面
│ │ ├── Projects.tsx # 我的项目
│ │ ├── Templates.tsx # 模板市场
│ │ ├── Assets.tsx # 素材管理
│ │ └── Settings.tsx # 用户设置
│ ├── stores/ # zustand 状态
│ │ ├── editorStore.ts # 🔥 编辑器核心状态 + 撤销重做
│ │ ├── projectStore.ts # 项目元信息
│ │ ├── uiStore.ts # UI 状态（面板显隐等）
│ │ └── authStore.ts # 用户认证
│ ├── hooks/ # 自定义 hooks
│ │ ├── useEditor.ts # 编辑器逻辑入口
│ │ ├── useUndoRedo.ts # 撤销重做封装
│ │ ├── useWebSocket.ts # WebSocket 连接
│ │ ├── useMediaUpload.ts # 上传逻辑
│ �� └── useAIGeneration.ts # AI 生成调用
│ ├── api/ # API 层
│ │ ├── client.ts # axios/fetch 实例
│ │ ├── projects.ts # 项目 CRUD
│ │ ├── media.ts # 素材上传/管理
│ │ ├── generation.ts # AI 生成接口
│ │ └── auth.ts # 认证接口
│ ├── types/ # TypeScript 类型
│ │ ├── project.ts
│ │ ├── timeline.ts # 时间轴轨道类型
│ │ ├── media.ts
│ │ └── api.ts # API 响应类型
│ └── utils/
│ ├── time.ts # 时间格式化
│ └── file.ts # 文件工具
│
├── backend/ # Python 后端
│ ├── pyproject.toml # 项目管理（uv/poetry）
│ ├── alembic.ini # 数据库迁移配置
│ ├── Dockerfile
│ ├── docker-compose.yml # 本地开发环境
│ ├── app/
│ │ ├── __init__.py
│ │ ├── main.py # FastAPI 入口
│ │ ├── config.py # 配置管理（pydantic-settings）
│ │ ├── dependencies.py # 依赖注入
│ │ ├── api/
│ │ │ ├── __init__.py
│ │ │ ├── v1/
│ │ │ │ ├── __init__.py
│ │ │ │ ├── router.py # 路由聚合
│ │ │ │ ├── auth.py # 认证
│ │ │ │ ├── projects.py # 项目 CRUD
│ │ │ │ ├── media.py # 素材上传
│ │ │ │ ├── generation.py # AI 生成
│ │ │ │ ├─�� templates.py # 模板
│ │ │ │ └── websocket.py # WebSocket 进度推送
│ │ ├── models/
│ │ │ ├── __init__.py
│ │ │ ├── user.py
│ │ │ ├── project.py
│ │ │ ├── media.py
│ │ │ └── template.py
│ │ ├── schemas/
│ │ │ ├── __init__.py
│ │ │ ├── user.py
│ │ │ ├── project.py
│ │ │ ├── media.py
│ │ │ └── generation.py
│ │ ├── services/
│ │ │ ├── __init__.py
│ │ │ ├── project_service.py
│ │ │ ├── media_service.py
│ │ │ ├── script_generator.py # 🔥 AI 脚本生成
│ │ │ ├── voice_service.py # 🔥 AI 配音
│ │ │ ├── subtitle_service.py # 🔥 AI 字幕
│ │ │ ├── video_renderer.py # 🔥 视频合成
│ │ │ └── storage_service.py # 文件存储（MinIO/S3）
│ │ ├── tasks/ # Celery 异步任务
│ │ │ ├── __init__.py
│ │ │ ├── celery_app.py
│ │ │ ├── generation_tasks.py # AI 生成任务
│ │ │ └── media_tasks.py # 媒体处理任务
│ │ ├── core/
│ │ │ ├── __init__.py
│ │ │ ├── security.py # JWT / OAuth
│ │ │ ├── database.py # SQLAlchemy 引擎
│ │ │ └── exceptions.py
│ │ └── utils/
│ │ ├── __init__.py
│ │ └── helpers.py
│ ├── alembic/
│ │ ├── env.py
│ │ └── versions/
│ ├── tests/
│ │ ├── conftest.py
│ │ ├── test_projects.py
│ │ └── test_generation.py
│ └── requirements/
│ ├── base.txt
│ ├── dev.txt
│ └── prod.txt
│
└── docs/ # 文档
├── api-spec.md # API 接口说明
└── editor-architecture.md # 编辑器架构设计
```
---
## 三、前端核心依赖
```jsonc
// frontend/package.json (关键字段)
{
"name": "ai-video-platform",
"private": true,
"type": "module",
"scripts": {
"dev": "vite",
"build": "tsc -b && vite build",
"preview": "vite preview",
"lint": "eslint ."
},
"dependencies": {
"react": "^19.0.0",
"react-dom": "^19.0.0",
"react-router": "^7.0.0",
"@tanstack/react-query": "^5.0.0",
"zustand": "^5.0.0",
"@dnd-kit/core": "^6.1.0",
"@dnd-kit/sortable": "^8.0.0",
"@dnd-kit/utilities": "^3.2.0",
"react-konva": "^18.2.0",
"konva": "^9.3.0",
"framer-motion": "^11.0.0",
"react-hook-form": "^7.53.0",
"@hookform/resolvers": "^3.9.0",
"zod": "^3.23.0",
"axios": "^1.7.0",
"clsx": "^2.1.0",
"tailwind-merge": "^2.5.0",
"class-variance-authority": "^0.7.0",
"lucide-react": "^0.460.0",
"sonner": "^1.7.0"
},
"devDependencies": {
"@types/react": "^19.0.0",
"@types/react-dom": "^19.0.0",
"@vitejs/plugin-react": "^4.3.0",
"vite": "^6.0.0",
"typescript": "^5.6.0",
"tailwindcss": "^4.0.0",
"@tailwindcss/vite": "^4.0.0",
"eslint": "^9.0.0"
}
}
```
---
## 四、后端核心依赖
```
# backend/requirements/base.txt
# Web 框架
fastapi>=0.115,<1.0
uvicorn[standard]>=0.32,<1.0
python-multipart>=0.0.18 # 文件上传
# 数据库
sqlalchemy>=2.0,<3.0
asyncpg>=0.30,<1.0 # PostgreSQL 异步驱动
alembic>=1.14,<2.0 # 数据库迁移
pydantic>=2.10,<3.0
pydantic-settings>=2.6,<3.0
# 缓存 & 队列
redis>=5.2,<6.0
celery>=5.4,<6.0
# 认证
python-jose[cryptography]>=3.3,<4.0
passlib[bcrypt]>=1.7,<2.0
# 文件存储
boto3>=1.35,<2.0 # S3/MinIO
minio>=7.2,<8.0
# AI SDK
openai>=1.55,<2.0
# 工具
httpx>=0.28,<1.0
loguru>=0.7,<1.0
```
---
## 五、初始化步骤（逐条命令）
### 5.1 创建项目目录
```bash
mkdir ai-video-platform && cd ai-video-platform
```
### 5.2 前端初始化
```bash
# 1. Vite + React + TypeScript
npm create vite@latest frontend -- --template react-ts
cd frontend
npm install
# 2. 安装运行时依赖
npm install react-router @tanstack/react-query zustand @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities react-konva konva framer-motion react-hook-form @hookform/resolvers zod axios clsx tailwind-merge class-variance-authority lucide-react sonner
# 3. 安装开发依赖
npm install -D tailwindcss @tailwindcss/vite
# 4. 初始化 shadcn/ui
npx shadcn@latest init
# 选择：TypeScript / Neutral / CSS variables / Yes to all
# 5. 添加 shadcn 组件
npx shadcn@latest add button card dialog slider tabs dropdown-menu input textarea select toast tooltip sheet skeleton
```
### 5.3 Tailwind CSS v4 配置
```ts
// frontend/vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'
export default defineConfig({
plugins: [react(), tailwindcss()],
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
},
},
server: {
port: 3000,
proxy: {
'/api': {
target: 'http://localhost:8000',
changeOrigin: true,
},
'/ws': {
target: 'ws://localhost:8000',
ws: true,
},
},
},
})
```
```css
/* frontend/src/index.css */
@import "tailwindcss";
@import "tw-animate-css";
@custom-variant dark (&:is(.dark *));
:root {
--radius: 0.625rem;
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--card: oklch(1 0 0);
--card-foreground: oklch(0.145 0 0);
--popover: oklch(1 0 0);
--popover-foreground: oklch(0.145 0 0);
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
--secondary: oklch(0.97 0 0);
--secondary-foreground: oklch(0.205 0 0);
--muted: oklch(0.97 0 0);
--muted-foreground: oklch(0.556 0 0);
--accent: oklch(0.97 0 0);
--accent-foreground: oklch(0.205 0 0);
--destructive: oklch(0.577 0.245 27.325);
--border: oklch(0.922 0 0);
--input: oklch(0.922 0 0);
--ring: oklch(0.708 0 0);
--chart-1: oklch(0.646 0.222 41.116);
--chart-2: oklch(0.6 0.118 184.704);
--chart-3: oklch(0.398 0.07 227.392);
--chart-4: oklch(0.828 0.189 84.429);
--chart-5: oklch(0.769 0.188 70.08);
--sidebar: oklch(0.985 0 0);
--sidebar-foreground: oklch(0.145 0 0);
--sidebar-primary: oklch(0.205 0 0);
--sidebar-primary-foreground: oklch(0.985 0 0);
--sidebar-accent: oklch(0.97 0 0);
--sidebar-accent-foreground: oklch(0.205 0 0);
--sidebar-border: oklch(0.922 0 0);
--sidebar-ring: oklch(0.708 0 0);
}
.dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
/* ... 暗色主题变量 ... */
}
@theme inline {
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
--color-chart-1: var(--chart-1);
--color-chart-2: var(--chart-2);
--color-chart-3: var(--chart-3);
--color-chart-4: var(--chart-4);
--color-chart-5: var(--chart-5);
--color-sidebar: var(--sidebar);
--color-sidebar-foreground: var(--sidebar-foreground);
--color-sidebar-primary: var(--sidebar-primary);
--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
--color-sidebar-accent: var(--sidebar-accent);
--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
--color-sidebar-border: var(--sidebar-border);
--color-sidebar-ring: var(--sidebar-ring);
}
@layer base {
* {
@apply border-border;
}
body {
@apply bg-background text-foreground;
}
}
```
### 5.4 后端初始化
```bash
cd backend
# 1. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 2. 安装依赖
pip install -r requirements/base.txt
# 3. 初始化 Alembic
alembic init alembic
# 修改 alembic/env.py 指向你的数据库
# 4. 创建初始迁移
alembic revision --autogenerate -m "init"
alembic upgrade head
# 5. 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
### 5.5 本地基础设施
```bash
# docker-compose.yml — 一键启动 PostgreSQL + Redis + MinIO
docker compose up -d
```
```yaml
# backend/docker-compose.yml
services:
postgres:
image: postgres:16-alpine
environment:
POSTGRES_USER: video_dev
POSTGRES_PASSWORD: video_dev
POSTGRES_DB: ai_video_platform
ports:
- "5432:5432"
volumes:
- pgdata:/var/lib/postgresql/data
redis:
image: redis:7-alpine
ports:
- "6379:6379"
minio:
image: minio/minio:latest
command: server /data --console-address ":9001"
environment:
MINIO_ROOT_USER: minioadmin
MINIO_ROOT_PASSWORD: minioadmin
ports:
- "9000:9000"
- "9001:9001"
volumes:
- miniodata:/data
volumes:
pgdata:
miniodata:
```
---
## 六、编辑器核心状态设计（zustand store）
这是整个前端的灵魂。交给 Trae 后，它是编码优先级最高的模块。
```ts
// frontend/src/stores/editorStore.ts
import { create } from 'zustand';
import { temporal } from 'zundo'; // zustand 撤销重做中间件
interface TrackItem {
id: string;
type: 'video' | 'image' | 'audio' | 'text' | 'sticker';
trackId: string;
startTime: number; // 毫秒
duration: number; // 毫秒
properties: {
x?: number;
y?: number;
width?: number;
height?: number;
rotation?: number;
opacity?: number;
text?: string;
fontSize?: number;
fontColor?: string;
// ... 其他属性
};
source: {
url?: string; // 媒体文件 URL
fileId?: string; // 后端文件 ID
};
}
interface EditorState {
// 项目元信息
projectId: string | null;
projectName: string;
// 轨道数据
tracks: TrackItem[];
// 播放状态
currentTime: number;
isPlaying: boolean;
duration: number;
// 选中状态
selectedItemIds: string[];
// 缩放
zoom: number; // 0.25 ~ 4.0
// 操作
addTrackItem: (item: TrackItem) => void;
removeTrackItem: (id: string) => void;
updateTrackItem: (id: string, updates: Partial<TrackItem>) => void;
moveTrackItem: (id: string, newStartTime: number, newTrackId?: string) => void;
setCurrentTime: (time: number) => void;
togglePlay: () => void;
selectItems: (ids: string[]) => void;
setZoom: (zoom: number) => void;
}
export const useEditorStore = create<EditorState>()(
temporal(
(set) => ({
projectId: null,
projectName: '未命名项目',
tracks: [],
currentTime: 0,
isPlaying: false,
duration: 60000,
selectedItemIds: [],
zoom: 1,
addTrackItem: (item) =>
set((s) => ({ tracks: [...s.tracks, item] })),
removeTrackItem: (id) =>
set((s) => ({
tracks: s.tracks.filter((t) => t.id !== id),
selectedItemIds: s.selectedItemIds.filter((sid) => sid !== id),
})),
updateTrackItem: (id, updates) =>
set((s) => ({
tracks: s.tracks.map((t) =>
t.id === id ? { ...t, ...updates } : t
),
})),
moveTrackItem: (id, newStartTime, newTrackId) =>
set((s) => ({
tracks: s.tracks.map((t) =>
t.id === id
? { ...t, startTime: newStartTime, trackId: newTrackId ?? t.trackId }
: t
),
})),
setCurrentTime: (time) => set({ currentTime: time }),
togglePlay: () => set((s) => ({ isPlaying: !s.isPlaying })),
selectItems: (ids) => set({ selectedItemIds: ids }),
setZoom: (zoom) => set({ zoom }),
}),
{ limit: 50 } // 保留 50 步撤销历史
)
);
```
---
## 七、后端 FastAPI 入口骨架
```python
# backend/app/main.py
from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.api.v1.router import api_router
from app.core.database import engine, Base
from app.config import settings
@asynccontextmanager
async def lifespan(app: FastAPI):
# 启动时：创建表（开发环境）
# async with engine.begin() as conn:
# await conn.run_sync(Base.metadata.create_all)
yield
# 关闭时清理
await engine.dispose()
app = FastAPI(
title="AI 短视频创作平台",
version="0.1.0",
lifespan=lifespan,
)
# CORS
app.add_middleware(
CORSMiddleware,
allow_origins=settings.CORS_ORIGINS,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# 注册路由
app.include_router(api_router, prefix="/api/v1")
@app.get("/health")
async def health_check():
return {"status": "ok"}
```
### WebSocket 进度推送
```python
# backend/app/api/v1/websocket.py
from fastapi import APIRouter, WebSocket, WebSocketDisconnect
router = APIRouter()
class ConnectionManager:
def __init__(self):
self.active_connections: dict[str, WebSocket] = {}
async def connect(self, task_id: str, websocket: WebSocket):
await websocket.accept()
self.active_connections[task_id] = websocket
def disconnect(self, task_id: str):
self.active_connections.pop(task_id, None)
async def send_progress(self, task_id: str, data: dict):
ws = self.active_connections.get(task_id)
if ws:
await ws.send_json(data)
manager = ConnectionManager()
@router.websocket("/ws/generation/{task_id}")
async def generation_progress(websocket: WebSocket, task_id: str):
await manager.connect(task_id, websocket)
try:
while True:
# 保持连接，等待 Celery 任务推送进度
await websocket.receive_text()
except WebSocketDisconnect:
manager.disconnect(task_id)
```
---
## 八、前后端联调约定
### API 规范
| 事项 | 约定 |
|---|---|
| 接口前缀 | `/api/v1/` |
| 请求格式 | `application/json`，上传用 `multipart/form-data` |
| 响应格式 | `{ "code": 0, "data": {...}, "message": "ok" }` |
| 分页格式 | `{ "code": 0, "data": { "items": [...], "total": 100, "page": 1, "page_size": 20 } }` |
| 错误码 | 0=成功，4xxx=客户端错误，5xxx=服务端错误 |
| WebSocket | `/ws/generation/{task_id}` — AI 生成进度实时推送 |
| 认证 | Bearer Token（JWT），Header: `Authorization: Bearer <token>` |
### 统一响应模型
```python
# backend/app/schemas/common.py
from pydantic import BaseModel
from typing import Generic, TypeVar
T = TypeVar("T")
class ApiResponse(BaseModel, Generic[T]):
code: int = 0
message: str = "ok"
data: T | None = None
class PageResponse(BaseModel, Generic[T]):
items: list[T]
total: int
page: int
page_size: int
```
### 前端请求封装
```ts
// frontend/src/api/client.ts
import axios from 'axios';
const client = axios.create({
baseURL: '/api/v1',
timeout: 30000,
});
// 请求拦截：自动带 Token
client.interceptors.request.use((config) => {
const token = localStorage.getItem('token');
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
// 响应拦截：统一错误处理
client.interceptors.response.use(
(res) => res.data,
(err) => {
if (err.response?.status === 401) {
// 跳转登录
}
return Promise.reject(err);
}
);
export default client;
```
---
## 九、AI 生成核心功能拆解
按优先级排列，建议 Trae 按此顺序实现：
| 优先级 | 功能 | 前端关键组件 | 后端关键服务 | 复杂度 |
|---|---|---|---|---|
| P0 | **AI 脚本生成** | `ScriptGenerator.tsx`（输入主题/关键词 → 流式显示脚本） | `script_generator.py`（调用 LLM API，SSE 流式返回） | ⭐⭐ |
| P0 | **视频编辑器基础** | `Timeline/` + `Canvas/` + `editorStore` | 项目 CRUD、素材上传 | ⭐⭐⭐⭐⭐ |
| P1 | **AI 配音** | `VoiceGenerator.tsx`（选择音色 → 试听 → 插入时间轴） | `voice_service.py`（TTS API） | ⭐⭐⭐ |
| P1 | **AI 字幕** | `SubtitleGenerator.tsx`（语音识别 → 字幕轨道展示） | `subtitle_service.py`（ASR） | ⭐⭐⭐ |
| P2 | **模板市场** | `Templates.tsx`（模板浏览 → 一键套用） | `templates.py`（模板 CRUD） | ⭐⭐ |
| P2 | **视频合成导出** | 导出进度条 | `video_renderer.py`（FFmpeg 合成 + Celery 异步） | ⭐⭐⭐⭐ |
---
## 十、开发工作流
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ WorkBuddy │────▶│ Trae │────▶│ Git Commit │
│ 方案 & 架构 │ │ 编码 & 调试 │ │ 版本管理 │
└──────────────┘ └──────────────┘ └──────────────┘
▲ │
└────────────────────────────────────────┘
遇到架构问题回 WorkBuddy 讨论
```
1. WorkBuddy 产出本方案 → Trae 读者直接执行
2. Trae 按 P0 → P1 → P2 顺序编码
3. 每完成一个模块，前端 `npm run dev` 即时验证
4. 后端 `pytest` + `uvicorn --reload` 同步验证
5. 遇到技术选型/架构疑问 → 回 WorkBuddy 讨论
6. 确定方案后继续在 Trae 编码
---
## 十一、交付清单
给 Trae 的第一阶段任务（建议一次不要超过 5 个文件）：
- [ ] `frontend/package.json` — 按第四节配置
- [ ] `frontend/vite.config.ts` — 按 5.3 节配置
- [ ] `frontend/tailwind.config.ts` — 按 5.3 节配置
- [ ] `frontend/src/index.css` — 按 5.3 节配置
- [ ] `frontend/src/main.tsx` — React 入口
- [ ] `frontend/src/App.tsx` — 路由 + 布局壳
- [ ] `frontend/src/components/layout/AppShell.tsx` — shadcn/ui 侧边栏 + 顶栏
- [ ] `frontend/src/stores/editorStore.ts` — 编辑器核心状态（第六节）
- [ ] `frontend/src/pages/Home.tsx` — 首页占位
- [ ] `frontend/src/pages/Editor.tsx` — 编辑器主��面占位
- [ ] `backend/pyproject.toml` — 项目配置
- [ ] `backend/requirements/base.txt` — 按第四节配置
- [ ] `backend/app/main.py` — 第七节完整代码
- [ ] `backend/app/config.py` — pydantic-settings 配置
- [ ] `backend/app/core/database.py` — SQLAlchemy 引擎
- [ ] `backend/app/api/v1/router.py` — 路由聚合
- [ ] `backend/app/api/v1/websocket.py` — WebSocket 进度推送
- [ ] `backend/app/schemas/common.py` — 统一响应模型
- [ ] `backend/docker-compose.yml` — 本地基础设施
```
---
_方案版本：v1.0 | 产出日期：2026-07-31 | 产出工具：WorkBuddy | 执行工具：Trae_
Reference in new issue Copy Permalink