# kumo-drama：AI 短剧 SaaS 整体项目文档

> 版本：设计稿 v1.0 · 日期：2026-10-16 · 状态：待产品与技术评审。  
> 本次交付：源码调研、产品与技术设计、实际生图模型生成的界面概念图。没有实现或部署平台，没有测试参考项目的生产可用性。

> 后续实现进度：已开始 `apps/api` 的 NestJS MVC 基础工程，加入配置、存活检查、开发文档、测试与 PM2 管理；未实现生产业务与平台部署。本文其余功能仍是目标设计，不表示已完成。

## 1. 一句话定义

阅读方式：[完整文字总览](README.md) · [浏览器离线图片画册](designGallery.html) · [图片生成与核验记录](imageGenerationNotes.md)。

**把一个故事变成可控、可追溯、可计费的短剧：AI 负责生成，创作者决定故事、人物、镜头与预算。**

平台不是四个互不相关的生成按钮，也不是模型部署系统。文本、图片、音频、视频围绕同一个项目、同一套资产和同一份生产计划协作，最终得到可下载的成片与素材包。

项目名称已确认为 **kumo-drama**，未进行商标与域名核验。

## 2. 用户已确认的要求

| 维度 | 已确认要求 | 设计落实 |
| --- | --- | --- |
| 产品核心 | 短剧／故事生产线 | 故事、剧本、角色、场景、分镜、声音、成片贯通 |
| 服务对象 | 面向公众的 SaaS | 用户隔离、项目权限、支付、审计、风控、运营后台 |
| AI 能力 | 视频、文本、音频、图片 | 独立能力入口与项目内上下文共存，不部署大模型 |
| 商业模式 | 积分／余额按次扣费 | 报价、授权、冻结、结算、解冻、退款、账本 |
| 技术倾向 | 优先 TypeScript | Web、API、Worker 与共享契约优先 TS；媒体处理使用 FFmpeg |
| 文件存储 | 使用七牛云 Kodo，用户已准备相关设置 | 通过六个 `QINIU_*` 环境变量接入，AK/SK 仅用于服务端；私有素材按权限签名访问 |
| 视觉风格 | 深色专业创作工具 | 大预览、分镜条、资产栏、检查器与轻量时间线 |
| 上游接入 | 兼容 New API 等聚合网关 | 可配置渠道、能力映射、协议适配、后台验证 |
| 管理方式 | 参考 cc-switch，由管理员添加 | 普通用户只选产品模型，不配置或读取平台凭据 |
| 数据初始状态 | 不保存默认 API Key 和 Base URL | 渠道、凭据、连接地址记录初始为空，不自动回退官方地址 |
| 文档图片 | 使用生图模型生成真实图片，禁止 ASCII art | PNG 概念图、提示词与生成记录保存在文档内 |

### 绝不妥协的五条规则

1. **未配置渠道就不能生成**：不能因为 SDK 自带默认域名而悄悄发出请求。
2. **确认后才发生付费副作用**：用户看见计划、价格与上限，再提交。
3. **网络超时不是重发许可**：无法确认上游是否受理时，先核对，不切换渠道重新生成。
4. **资产不可被静默覆盖**：每次生成产生新版本，历史付费产物保持可追溯。
5. **平台密钥不进入用户浏览器**：写入加密数据库，仅服务端调用时解密使用。

## 3. 产品主线与价值

### 创作者完成一集短剧的过程

1. 创建项目，选择画幅、目标时长、语言和故事风格。
2. 输入故事梗概，或导入自己有权使用的小说／剧本。
3. AI 辅助生成大纲、人物关系与分集剧本；用户编辑并确认版本。
4. 提取角色、场景和道具；生成参考图，锁定可复用的外观版本。
5. 拆解镜头，确认首帧、尾帧、运镜、对白和所引用的资产。
6. 先试做少量镜头，确认视觉，再批准批量计划和预算。
7. 调用远程服务生成镜头、配音和所需音频；任务中心跟踪进度。
8. 在轻量时间线中选择版本、排列、裁剪、调音和修正字幕。
9. 预览并导出 MP4、字幕与素材包；查看逐项积分消费。

### 差异化不在“接入更多模型”

- 连贯性：同一角色、服装、场景和世界观被多镜头复用。
- 可控性：镜头能单独重做，成功镜头不因批次重试再次收费。
- 透明度：每次操作知道会生成什么、花多少、失败后如何处理。
- 稳定性：浏览器关闭、服务重启和上游响应不确定时，不丢失生产事实。
- 经营性：渠道、售价、成本、订单、用户和审计能在后台管理。

## 4. 实际生图的界面概念

以下图片均用于表达未来产品的布局与视觉方向，**不是已实现网页的截图**。其中角色、片名、积分、任务和价格均为虚构演示数据。模型绘制的细小文字、数值或状态若与正文冲突，以接口契约和文字设计为准。

生图提示词见 [imagePrompts.json](imagePrompts.json)，每张 PNG 的生成时间、模型、尺寸和 SHA-256 见 `images/` 中对应 JSON。没有把中转站地址或密钥复制到文档。

已完成九张图片，实际请求模型 `gpt-image-2`、质量 `high`，均为 2048×2048。生成模型可能补入不属于首版的控件；主要差异在 [界面设计第 5 节](interfaceDesign.md) 明确纠正，尤其不能照图实施自动换路、运行中取消、订阅或第二种积分单位。

### 4.1 项目总览：围绕作品，而不是围绕模型列表

![由生图模型生成的 kumo-drama 项目总览概念图](images/studioOverview.png)

重点：继续制作、项目进度、最近任务、新建短剧。用户不应先理解渠道、API 或供应商协议才能开始创作。

### 4.2 故事与剧本：AI 提议，人来确认

![由生图模型生成的剧本创作工作台概念图](images/scriptWorkspace.png)

剧本编辑器与创作助手并列。AI 的拆解、改写和角色提取先产出候选版本；已确认剧本不能被后续对话直接覆盖。付费计划需要显示上限与确认入口。

### 4.3 图片与资产：角色一致性是项目资产问题

![由生图模型生成的角色和图片资产工作台概念图](images/assetLibrary.png)

角色参考图、场景和道具归入资产库。锁定版本代表“后续引用这个明确版本”，不承诺生成模型能够百分之百保持身份一致。

### 4.4 分镜与视频：准备状态、任务状态分别表达

![由生图模型生成的分镜视频工作台概念图](images/storyboardWorkspace.png)

视频生成面板明确区分首帧、尾帧和普通参考图；只显示当前产品模型实际支持的参数。队列状态不伪装成 GPU 运行进度。批量生成前先展示逐镜头费用。

### 4.5 音频：配音、音效与字幕连接到同一集

![由生图模型生成的音频创作工作台概念图](images/audioWorkspace.png)

首版重点是对白／旁白 TTS、音色选择、音频上传、音量控制与字幕时间调整。音乐／音效生成由经过验证的远程渠道按能力启用；真人音色克隆不是默认能力。

### 4.6 成片：轻量剪辑，不复制完整专业 NLE

![由生图模型生成的成片编辑与导出概念图](images/editExportWorkspace.png)

支持镜头排列、裁剪、简单转场、配音与音乐轨、字幕和导出；复杂调色、任意特效、多人实时剪辑不进入首版。

### 4.7 积分钱包：可用、冻结、已结算一眼区分

![由生图模型生成的积分钱包概念图](images/walletBilling.png)

每条消费能回到项目和任务。生成失败、取消、上游状态不明、平台入库失败分别处理，不用一个“失败退款”按钮掩盖所有情形。

### 4.8 管理员渠道：配置、检测、发布分开

![由生图模型生成的管理员渠道配置概念图](images/adminChannels.png)

管理员手动添加聚合平台，配置协议与能力映射，检测后发布。已有配置只回显“密钥已配置”，不能读回明文。连接可用不等于四种模态都可用。

**图片文字纠正**：P0 媒体不自动切换；已受理任务固定原配置版本。图内任何“现有请求随配置切换”的示意文案不应照做。

### 4.9 全新安装：真正零渠道、零地址、零凭证

![由生图模型生成的全新安装零渠道状态概念图](images/adminEmptyState.png)

这张图表达全新数据库的权威初态：渠道列表为空，Base URL 与密钥均未配置，普通用户生成功能不可用。其他图片中的已配置渠道是“管理员完成配置后”的演示状态，不是初始化数据。

## 5. 首版做什么，暂时不做什么

| 交付层级 | 范围 |
| --- | --- |
| P0：可交易、可完成一集 | 账户、个人工作区、项目与分集、剧本、角色／场景参考图、分镜、视频生成、TTS、轻量时间线、导出、积分钱包、一个正式支付渠道、管理员渠道／模型／价格／用户管理 |
| P0：必要可靠性 | 请求幂等、提交不确定性、持久任务、出站安全、支付回调、账本、审计、备份、内容安全、基础风控 |
| P1：提升生产效率 | 音效／音乐 API、更多协议、批次预算授权、增强字幕对齐、镜头候选对比、模板、项目成本分析、有限团队协作 |
| P2：扩展产品 | 可配置高级流程、完整团队席位、更多支付地区、公开 API、受控外部工具连接 |
| 不在当前范围 | 模型训练、模型权重部署、GPU 推理集群、无限制自治 Agent、任意代码插件、专业级完整剪辑器、社交社区 |

P0 的“支持四类 AI”至少落地文本生成、图片生成、视频生成、语音合成各一种经过真实联调的能力；不能只在导航栏放四个图标。P1 能力不应提前显示为可购买服务。

## 6. 推荐技术方案

| 层 | 推荐方案 | 原因 |
| --- | --- | --- |
| Web | Next.js、React、TypeScript、Tailwind、可访问的组件基座 | 创作工作台与管理后台共用设计系统 |
| API | NestJS，TypeScript | 模块化、权限、后台业务和明确边界；不拆大量微服务 |
| Worker | Node.js TS，按任务种类分进程 | 媒体生成、轮询、入库、渲染与 API 生命周期解耦 |
| 数据库 | PostgreSQL + Prisma，必要事务使用参数化 SQL | 业务事实、账本、版本与任务需要一致性 |
| 调度 | BullMQ + Redis，数据库 Outbox | 队列至少一次投递，业务以数据库去重与恢复 |
| 存储 | 七牛云 Kodo + 私有素材签名访问 | 原始素材、产物、预览、成片与租户隔离；复用现有 `QINIU_*` 配置 |
| 媒体 | FFmpeg / FFprobe | 不依赖本地大模型完成探测、转码、裁剪和合成 |
| 通信 | REST/OpenAPI；状态 SSE + 快照补偿 | 长任务刷新后可恢复，流式事件不是唯一事实 |
| 模型 | 后台配置的聚合平台与协议适配器 | SDK 不决定默认地址，数据库发布版本决定连接 |

首版是**模块化单体 API + 独立 Worker**，不是微服务集群。不承诺“只加一个 Base URL 就兼容所有视频接口”。协议差异、能力与价格必须被明确登记和验证。

## 7. 核心领域对象

| 领域 | 主要对象 | 必须守住的边界 |
| --- | --- | --- |
| 身份与隔离 | User、Workspace、Membership | 用户不能跨工作区读取项目、任务或素材 |
| 内容生产 | Project、Episode、ScriptVersion、Shot | 信息确认不等于已生成；改动需标记依赖过期 |
| 媒体资产 | Asset、AssetVersion、ShotReference | 当前选用版本与历史产物分离 |
| AI 接入 | Channel、ChannelRevision、CredentialVersion、ModelBinding | 配置可变，已提交执行身份不可变 |
| 执行 | Plan、Quote、Execution、Task、Attempt、ProviderJob | 计划授权、队列投递、外部副作用分别建模 |
| 资金 | WalletAccount、LedgerTransaction、Reservation、PaymentOrder | 资金变动只有一个受控账本入口 |

详见 [数据库设计](dataModel.md)，不是把全部状态塞到一张 `generation_tasks` 表。

## 8. 资金与任务的最关键闭环

1. 服务端检查权限、输入、引用版本、模型能力、渠道、价格和预算上限。
2. 生成短期有效的报价快照，用户批准，服务端原子冻结积分并创建执行与 Outbox。
3. Worker 取得数据库提交权，再调用上游；立即持久化外部任务 ID。
4. 查询只围绕同一上游任务继续，不因为超时换渠道重新提交。
5. 远程完成后转存、校验并登记资产版本；结果能交付后按合同结算。
6. 失败释放符合条件的冻结；未知结果进入核对流程；账本不被任务代码直接修改。

预留余额不是额外收费。成功后只结算一次，剩余预留释放。财务状态与媒体状态分开，不能为了让账本看起来平衡而伪造生成失败。

## 9. 基于源码做出的取舍

- 借鉴 Toonflow 的能力组织与供应商管理体验，但不沿用文件式全局配置与自动填入地址。
- 借鉴 ViMax、OpenMontage 的分阶段创作与人工检查点，但不用无边界 Agent 决定预算和付费。
- 借鉴 Jellyfish 对准备状态、生成状态、任务中心的分离。
- 借鉴 ArcReel 的付费任务恢复与版本追踪，但不能把其单进程队列设计直接搬到公众 SaaS。
- 参考 waoowaoo 的报价／账本／提交身份设计，但不能未经授权复制成托管服务。
- 借鉴 cc-switch 的供应商卡片、配置、优先级与熔断；媒体付费请求增加更严格的提交边界。
- 14 个项目的具体文件、提交版本、许可证及限制集中在 [源码分析](sourceAnalysis.md)。

## 10. 建议按三个证明推进

| 阶段 | 要证明什么 | 评审标准 |
| --- | --- | --- |
| A：接入与资金闭环 | 四类 API 可调用，零默认渠道，账本可靠 | 重复请求不重复扣费，重启不重复生成，凭据不泄漏 |
| B：创作闭环 | 一个真实故事能做成一集 | 人物参考、镜头、音频、字幕、成片均能回溯 |
| C：商业运营闭环 | 普通用户能注册、充值、消费、恢复失败 | 支付核对、风控、支持工具、审计与备份通过上线验收 |

完整商业发布不应以“页面能打开”作为完成标准。实施与验收细目见 [交付计划](deliveryPlan.md)。

## 11. 仍需后续确认，不擅自决定

首发地区及合规要求、正式支付商、充值币种和售价、聚合网关实际版本与公开协议、素材保留期限、首发负载与预算、是否开放团队协作、品牌商标与域名核验。详见 [决策清单](decisionsAndOpenQuestions.md)。

## 12. 专题文档索引

| 文档 | 主要读者 | 内容 |
| --- | --- | --- |
| [产品需求](productRequirements.md) | 产品、前端、设计 | 用户、功能、业务流程、范围和验收编号 |
| [源码分析](sourceAnalysis.md) | 架构、技术负责人 | 14 个代码库、cc-switch、许可与设计取舍 |
| [系统架构](systemArchitecture.md) | 全栈、运维 | 技术栈、模块、部署边界、读写和扩展 |
| [渠道接入](providerGateway.md) | 后端、后台产品 | 空数据库、配置发布、凭据、New API 与协议 |
| [任务与流程](workflowAndTasks.md) | 后端、Worker、软测 | 状态机、重试、取消、恢复和版本依赖 |
| [数据库](dataModel.md) | 后端、DBA | 表、关键字段、关系、索引和事务不变量 |
| [接口契约](apiContracts.md) | 前后端、软测 | API、DTO、鉴权、幂等、事件与错误 |
| [计费支付](billingAndPayments.md) | 后端、财务、运营 | 预扣、用量、双分录、支付与对账 |
| [界面规范](interfaceDesign.md) | 设计、前端 | 页面、交互、组件、状态与效果图解读 |
| [安全运维](securityAndOperations.md) | 安全、运维、负责人 | 权限、SSRF、内容、部署、容量与备份 |
| [实施计划](deliveryPlan.md) | 项目负责人、软测 | 阶段、风险、验收场景与上线门禁 |
| [决策清单](decisionsAndOpenQuestions.md) | 产品与技术负责人 | 已确定、建议、未决，以及上线阻塞项 |