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