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. 逻辑分层示意

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 中说明变更要点。

6.3 KiB Raw Blame History Unescape Escape