系统架构
VVICAT 把同步页面请求与长耗时模型任务分离。Web 负责认证、校验、业务 API 和界面；Worker 消费生成任务；Watchdog 巡检异常运行；Bull Board 提供队列观察。
分层职责
| 层级 | 职责 | 主要实现 |
|---|---|---|
| 体验层 | 创作、无限画布、资产、设置、后台 | Next.js App Router、React 19、next-intl |
| 应用层 | API、认证、权限、工作流和任务状态 | Route Handler、服务模块、NextAuth |
| 执行层 | 长任务消费、模型调用、失败恢复 | BullMQ、Worker、Watchdog |
| 能力层 | 文本、图像、视频和语音统一接入 | Model Gateway、Provider Adapter |
| 数据层 | 业务、队列和媒体 | PostgreSQL、Redis、对象存储 |
一次生成请求
- 浏览器提交参数，API 校验身份、项目作用域和输入。
- 应用服务创建可追踪的任务或运行记录。
- 任务写入 Redis 队列，API 返回任务标识。
- Worker 通过模型网关选择模型并调用供应商。
- 媒体写入对象存储，数据库保存结构化信息与引用。
- 进度返回页面；成功后关联结果，失败时保留可诊断状态。
[!IMPORTANT] 浏览器不应直接持有或调用供应商密钥。权限、任务状态、重试和媒体归档必须经过服务端链路。
核心边界
- 工作区以项目和剧集为作用域，服务端业务状态是权威来源。
- 长任务复用统一队列、运行记录和事件协议，避免页面请求被模型调用阻塞。
- 模型网关把供应商字段归一化，上层工作流不直接依赖某家 API。
- 角色、场景、道具和声音可复用，但读取和修改必须通过用户及项目权限。
- 产品路由使用
[locale]；双语 MDX 由 Nextra 渲染，不依赖外部 CMS。
数据与权限原则
- PostgreSQL 保存结构化业务数据，Redis 保存队列状态，对象存储保存媒体文件。
- 项目、资产和任务查询必须带用户或项目作用域，不能仅凭可猜测 ID 访问。
- API Key、内部任务令牌和管理员凭据只能保存在服务端安全配置中。
- 初始化快照只包含全局初始化数据。系统画风封面会随
prisma/init-assets/art-styles一同迁移，并在npm run project:init时上传、绑定为稳定媒体引用；用户、项目、任务、密钥、其他业务媒体和通知不会进入快照。
扩展原则
- 新模型接入模型网关，不在页面或业务 API 中直接调用供应商。
- 新长任务复用现有运行时、队列和状态协议。
- 新媒体类型复用统一媒体引用，不在业务表散落临时 URL。
- 用户可见功能同步新增或更新中英文产品文档。
Last updated on