模块概览

模块概述

VideoFly 采用模块化设计，所有功能模块都组织在 src/ 目录下。

核心模块

1. AI 提供商抽象层 (`src/ai/`)

统一的 AI 视频生成提供商接口，支持多个 AI 服务。

src/ai/
├── providers/
│   ├── evolink.ts          # Evolink.ai 实现
│   └── kie.ts              # Kie.ai 实现
├── utils/
│   └── callback-signature.ts  # Webhook 签名验证
├── types.ts                # 接口定义
└── index.ts                # Provider 工厂

使用方法

import { getProvider } from "@/ai";
 
// 获取提供商
const provider = getProvider("evolink");
 
// 创建任务
const task = await provider.createTask({
  prompt: "A beautiful sunset",
  model: "sora-2",
  duration: 5,
  aspectRatio: "16:9",
});
 
// 查询状态
const status = await provider.getTaskStatus(task.id);

支持的提供商

提供商	文生视频	图生视频	模型
Evolink.ai	✅	✅	sora-2, wan2.6, veo-3.1, seedance-1.5-pro
Kie.ai	✅	❌	sora-2-text-to-video

2. 服务层 (`src/services/`)

业务逻辑的核心层，封装了所有复杂的业务操作。

模块	文件	职责
积分服务	`credit.ts`	积分冻结、结算、释放、充值
视频服务	`video.ts`	视频生成、状态查询、回调处理
客户服务	`customer.ts`	客户数据管理
账单服务	`billing.ts`	订阅和支付账单管理
K8s 服务	`k8s.ts`	K8s 集群管理

积分服务示例

import { creditService } from "@/services/credit";
 
// 获取余额
const balance = await creditService.getBalance(userId);
// { totalCredits, usedCredits, frozenCredits, availableCredits, expiringSoon }
 
// 冻结积分（任务创建）
await creditService.freeze({
  userId,
  credits: 10,
  videoUuid,
});
 
// 结算积分（任务成功）
await creditService.settle(videoUuid);
 
// 释放积分（任务失败）
await creditService.release(videoUuid);
 
// 充值积分
await creditService.recharge({
  userId,
  credits: 100,
  orderNo: "ORDER_123",
  transType: CreditTransType.ORDER_PAY,
});

3. 数据层 (`src/db/`)

使用 Drizzle ORM 的数据库层。

src/db/
├── schema.ts          # 数据库 Schema 定义
└── index.ts           # 数据库连接实例

使用方法

import { db } from "@/db";
import { users, videos } from "@/db/schema";
 
// 查询
const user = await db.select().from(users).where(eq(users.id, userId));
 
// 插入
await db.insert(videos).values({
  uuid,
  userId,
  prompt,
  model,
  status: "PENDING",
});
 
// 更新
await db.update(videos)
  .set({ status: "COMPLETED" })
  .where(eq(videos.uuid, uuid));

4. 配置层 (`src/config/`)

所有配置文件的集中管理。

配置文件	用途
`site.ts`	站点基本信息
`navigation.ts`	导航菜单配置
`i18n-config.ts`	国际化语言配置
`credits.ts`	积分和模型配置
`price/`	定价配置
`tool-pages/`	工具页面配置
`ui/`	UI 相关配置

积分配置示例

// src/config/credits.ts
export const CREDITS_CONFIG = {
  // 新用户赠送
  registerGift: {
    enabled: true,
    amount: 50,
    expireDays: 30,
  },
  // 积分过期
  expiration: {
    warnBeforeDays: 7,
    purchaseDays: 365,
    subscriptionDays: 30,
  },
  // 模型积分消耗
  modelCredits: {
    "sora-2": 10,
    "wan2.6": 8,
    "veo-3.1": 12,
    "seedance-1.5-pro": 5,
  },
};

5. 工具库 (`src/lib/`)

通用工具函数和辅助模块。

模块	文件	职责
API 工具	`api/`	API 响应格式化、认证中间件
验证	`validations/`	Zod 验证模式
类型	`types/`	TypeScript 类型定义
存储	`storage.ts`	R2/S3 存储抽象
视频 API	`video-api.ts`	视频 API 客户端
邮件	`emails/`	邮件模板和发送

存储服务示例

import { storage } from "@/lib/storage";
 
// 上传文件
await storage.uploadFile({
  key: `videos/${uuid}.mp4`,
  body: videoBuffer,
  contentType: "video/mp4",
});
 
// 下载并重新上传
await storage.downloadAndUpload({
  sourceUrl: aiProviderVideoUrl,
  key: `videos/${uuid}.mp4`,
});
 
// 获取公开 URL
const url = storage.getPublicUrl(`videos/${uuid}.mp4`);

6. Hooks (`src/hooks/`)

自定义 React Hooks，封装可复用的状态逻辑。

Hook	用途
`useVideoGeneration`	视频生成状态管理
`useCreditBalance`	积分余额查询
`useUserVideos`	用户视频列表
`useBreakpoint`	响应式断点

使用示例

import { useVideoGeneration } from "@/hooks/generator-hooks";
 
function VideoGenerator() {
  const { generate, isGenerating, progress, error } = useVideoGeneration();
 
  const handleSubmit = async (data) => {
    await generate(data);
  };
 
  return <form onSubmit={handleSubmit}>...</form>;
}

7. 状态存储 (`src/stores/`)

使用 Zustand 的客户端状态管理。

// 用户状态
export const useUserStore = create((set) => ({
  user: null,
  setUser: (user) => set({ user }),
  clearUser: () => set({ user: null }),
}));
 
// 使用
const { user, setUser } = useUserStore();

组件模块

视频生成器组件 (`src/components/video-generator/`)

核心的视频生成输入组件。

组件	文件	用途
`VideoGeneratorInput`	`video-generator-input.tsx`	主输入组件
`VideoGeneratorCore`	`video-generator-core.tsx`	核心逻辑
`VideoStatusCard`	`video-status-card.tsx`	状态卡片
`VideoCard`	`video-card.tsx`	视频卡片
`CompactGenerator`	`compact-generator.tsx`	紧凑版

使用方法

import { VideoGeneratorInput, DEFAULT_CONFIG } from "@/components/video-generator";
 
<VideoGeneratorInput
  config={DEFAULT_CONFIG}
  onSubmit={async (data) => {
    await handleGenerate(data);
  }}
/>

UI 组件库 (`src/components/ui/`)

基于 shadcn/ui 的基础组件库，包含 50+ 组件：

Button
Input
Textarea
Select
Checkbox
Radio Group
Switch
Slider
Date Picker

国际化模块 (`src/messages/`)

使用 next-intl 实现中英文双语。

src/messages/
├── en.json    # 英文翻译
└── zh.json    # 中文翻译

添加翻译

// src/messages/zh.json
{
  "common": {
    "save": "保存",
    "cancel": "取消"
  },
  "video": {
    "generate": "生成视频",
    "status": "生成状态"
  }
}

// 使用翻译
import { useTranslations } from "next-intl";
 
function Component() {
  const t = useTranslations("video");
  return <button>{t("generate")}</button>;
}

样式系统 (`src/styles/`)

Tailwind CSS

项目使用 Tailwind CSS 4.0，支持以下特性：

深色模式 - 基于 darkMode: 'class'
自定义主题 - 在 tailwind.config.ts 中配置
CSS 变量 - 使用 HSL 颜色空间

CSS 变量

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  /* ... */
}
 
.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... */
}

模块概述

核心模块

1. AI 提供商抽象层 (`src/ai/`)

使用方法

支持的提供商

2. 服务层 (`src/services/`)

积分服务示例

3. 数据层 (`src/db/`)

使用方法

4. 配置层 (`src/config/`)

积分配置示例

5. 工具库 (`src/lib/`)

存储服务示例

6. Hooks (`src/hooks/`)

使用示例

7. 状态存储 (`src/stores/`)

组件模块

视频生成器组件 (`src/components/video-generator/`)

使用方法

UI 组件库 (`src/components/ui/`)

国际化模块 (`src/messages/`)

添加翻译

样式系统 (`src/styles/`)

Tailwind CSS

CSS 变量

下一步

组件文档

视频生成器

On this page