wsq
162 lines
6.3 KiB
Markdown
162 lines
6.3 KiB
Markdown
# waoowaoo 技术架构说明
|
||
|
||
本文档描述仓库当前的整体技术架构、运行时拓扑与主要模块职责，便于新成员理解与运维部署对照。
|
||
|
||
---
|
||
|
||
## 1. 产品定位
|
||
|
||
**waoowaoo** 是一款面向「小说 / 剧本 → 分镜、角色、场景 → 配音 → 成片」的 **AI 影视创作 Web 应用**。用户在浏览器中管理项目与创作流程；**长耗时生成与第三方 AI 调用**主要在服务端与独立 Worker 进程中异步完成。
|
||
|
||
---
|
||
|
||
## 2. 运行时拓扑（多进程）
|
||
|
||
生产与本地开发均采用 **Next.js Web 进程 + 多个常驻 Node 进程**（见根目录 `package.json` 中 `dev` / `start` 脚本，由 `concurrently` 编排）：
|
||
|
||
| 进程 | 说明 |
|
||
|------|------|
|
||
| **Next.js** | `next dev` / `next start`：App Router 页面、`src/app/api/**` 的 HTTP API、SSR |
|
||
| **BullMQ Workers** | `src/lib/workers/index.ts`：消费 Redis 队列，处理图片 / 视频 / 语音 / 文本等任务 |
|
||
| **Watchdog** | `scripts/watchdog.ts`：队列与健康类辅助脚本 |
|
||
| **Bull Board** | `scripts/bull-board.ts`：队列可视化（Express） |
|
||
|
||
**基础设施**（`docker-compose.yml` 与典型自建环境）：
|
||
|
||
- **MySQL 8**：业务与任务相关持久化（Prisma）
|
||
- **Redis 7**：BullMQ 队列与部分运行时状态
|
||
- **对象存储**：默认 **MinIO（S3 兼容）**；亦可对接 AWS S3、腾讯云 COS 等（见依赖与 `STORAGE_TYPE`）
|
||
|
||
---
|
||
|
||
## 3. 逻辑分层示意
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph client [浏览器]
|
||
UI[Next App Router + React]
|
||
RQ[TanStack Query]
|
||
end
|
||
|
||
subgraph next [Next.js 进程]
|
||
API[src/app/api]
|
||
Auth[NextAuth]
|
||
Prisma[Prisma Client]
|
||
end
|
||
|
||
subgraph infra [基础设施]
|
||
MySQL[(MySQL)]
|
||
Redis[(Redis)]
|
||
S3[(对象存储 S3 兼容)]
|
||
end
|
||
|
||
subgraph workers [Worker 进程]
|
||
W[BullMQ Workers]
|
||
Gen[Generators / Providers]
|
||
end
|
||
|
||
UI --> RQ --> API
|
||
API --> Auth
|
||
API --> Prisma --> MySQL
|
||
API --> Redis
|
||
API --> S3
|
||
W --> Redis
|
||
W --> Gen
|
||
W --> Prisma
|
||
W --> S3
|
||
Gen --> Ext[外部 AI / 媒体 API]
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 前端技术栈
|
||
|
||
| 领域 | 技术 |
|
||
|------|------|
|
||
| 框架 | **Next.js 15**（App Router）、**React 19** |
|
||
| 构建 / 开发 | **Turbopack**（`next dev --turbopack`）、TypeScript |
|
||
| 国际化 | **next-intl**；`src/middleware.ts` 与 `src/i18n.ts` 配置 **`localePrefix: 'always'`**（路径如 `/zh/...`、`/en/...`） |
|
||
| 服务端状态 | **TanStack React Query**（`@tanstack/react-query`） |
|
||
| 交互 | **@dnd-kit**（拖拽排序等） |
|
||
| 视频 / 时间线 | **Remotion**（`remotion`、`@remotion/player`、`@remotion/cli`） |
|
||
| 样式 | **Tailwind CSS v4**、**Geist** 字体、**lucide-react** |
|
||
|
||
**页面与业务模块**主要位于 `src/app/[locale]/...`，其中 **novel-promotion**（小说推广 / 分镜工作流）与 **asset-hub**（资产库）等为核心业务区。
|
||
|
||
---
|
||
|
||
## 5. 后端与数据层
|
||
|
||
| 领域 | 技术 |
|
||
|------|------|
|
||
| API | **Route Handlers**：`src/app/api/**`（与前端同仓部署） |
|
||
| ORM / 数据库 | **Prisma 6** + **MySQL**（`prisma/schema.prisma`） |
|
||
| 认证 | **NextAuth v4** + **`@next-auth/prisma-adapter`** |
|
||
|
||
数据模型围绕用户、项目、分集、分镜、角色、场景、媒体对象、异步任务与计费等展开，体量较大，属于典型创作类 SaaS 模型。
|
||
|
||
---
|
||
|
||
## 6. 异步任务与媒体管线
|
||
|
||
- **队列**：**BullMQ** + **ioredis**。
|
||
- **Worker 拆分**：`src/lib/workers/` 下按领域划分（如 `image.worker`、`video.worker`、`voice.worker`、`text.worker`），具体任务逻辑在 `src/lib/workers/handlers/**`。
|
||
- **设计意图**：HTTP 请求负责校验、落库、入队；长耗时生成在 Worker 中执行，避免 Next 请求超时，并便于重试与监控。
|
||
|
||
---
|
||
|
||
## 7. AI 与多厂商集成
|
||
|
||
- **抽象方式**：`src/lib/generators/**` 以工厂（如 `factory.ts`）按 `provider` 选择图片 / 视频 / 音频生成器；与用户或系统级 **`api-config`**、模型网关等配合。
|
||
- **依赖生态（节选）**：Vercel **AI SDK**（`ai`、`@ai-sdk/*`）、**OpenAI**、**Google GenAI**、**OpenRouter**、**FAL** 等；另有 `src/lib/providers/**` 等官方或兼容网关封装。
|
||
- **治理**：`package.json` 中大量 **`scripts/guards/*`** 与 **`check:*`**，用于约束 API 层不直连 LLM、模型能力不落硬编码、路由与计费契约等，体现「配置中心 + 契约 / 静态检查」的工程策略。
|
||
|
||
---
|
||
|
||
## 8. 存储与文件
|
||
|
||
- **初始化**：`npm run storage:init` → `src/lib/storage/init.ts`。
|
||
- **后端**：`src/lib/storage` 抽象多后端；支持 MinIO / S3 / COS 等，与 Docker 环境变量（如 `STORAGE_TYPE`、`MINIO_*`）对齐。
|
||
- **媒体引用**：数据库中记录存储键或媒体对象关联，Worker 上传后回写。
|
||
|
||
---
|
||
|
||
## 9. 工程化与质量
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| 类型检查 | `npm run typecheck`（`tsc --noEmit`） |
|
||
| Lint | ESLint（`eslint-config-next`） |
|
||
| 测试 | **Vitest**：`tests/unit`、`tests/integration`（api / provider / chain / task）、`tests/system`、`tests/regression`；计费有专项单测与并发测 |
|
||
| Git 钩子 | **Husky**（`prepare` 脚本） |
|
||
| 脚本门禁 | 大量 `check:*`、`test:guards` 聚合，与 CI / 本地校验流程配合 |
|
||
|
||
---
|
||
|
||
## 10. 目录与模块速查（开发向）
|
||
|
||
| 路径 | 职责 |
|
||
|------|------|
|
||
| `src/app/[locale]/` | 国际化下的页面与布局 |
|
||
| `src/app/api/` | HTTP API |
|
||
| `src/lib/workers/` | 队列 Worker 入口与任务处理器 |
|
||
| `src/lib/generators/` | 各厂商图片 / 视频 / 音频生成器与工厂 |
|
||
| `src/lib/prisma.ts` | Prisma 客户端单例等 |
|
||
| `src/lib/query/` | React Query 封装、mutation、keys |
|
||
| `prisma/` | Schema 与迁移 |
|
||
| `messages/` | next-intl 文案（如 `zh`、`en`） |
|
||
| `scripts/` | 运维脚本、守卫脚本、迁移脚本 |
|
||
| `tests/` | 各类自动化测试 |
|
||
|
||
---
|
||
|
||
## 11. 一句话总结
|
||
|
||
本项目采用 **「Next 全栈单体 + Prisma/MySQL + Redis/BullMQ 异步 Worker + S3 兼容对象存储 + 多厂商生成器工厂」** 架构：Web 负责交互与编排，**队列 Worker** 承载重任务与多模型调用，并通过 **守卫脚本与测试** 将模型与路由约束在可维护的配置与契约之内。
|
||
|
||
---
|
||
|
||
## 12. 文档维护
|
||
|
||
架构随版本迭代会变化；若重大变更（如队列方案、数据库、部署拓扑），请同步更新本文件并在 PR 中说明变更要点。
|