AI Manga Platform

AI 漫剧 / AI 写真视频生成平台。当前优先开发系统 A：原创小说 / 上传小说 -> 韩漫 / 漫剧生成系统。

当前阶段

阶段 23：API 加密传输已完成，当前进入生产化补齐。AI 原创小说 3 集 MP4 与上传小说 1 集 MP4 两条闭环已跑通，并在 HTTPS 基础上叠加前后端应用层加密信封；真实图片/TTS/视频资产落库、OpenAI Sora 视频 Provider 驱动、后台用户高危操作审计、细粒度 RBAC 和审计导出已补齐。

当前已完成后端基础骨架、数据库 schema、JWT 认证、私有文件上传、项目创建流程、上传小说解析、AI 原创小说 mock、故事圣经、角色圣经、长篇记忆、分集计划、单集脚本和分镜、BullMQ 队列与任务状态流转、AI Provider 抽象层、真实 AI Provider 接入、真实图片/TTS/视频资产落库、Provider 成本阈值、worker 队列消费、TTS 音频、SRT 字幕、FFmpeg 视频合成、后台管理、用户端 H5 制作台、订单额度、内容审核、MVP 验收和 API 加密传输。后台管理已覆盖项目、任务、小说源、章节、角色资源、分镜资源、成品漫剧、订单额度、内容审核、Provider、成本、用户、素材、版权记录和审计日志，并补充资源详情/媒体预览、用户人工加余额、额度冲正、用户禁用/启用、改角色、重置密码和用户详情抽屉，高危用户操作带二次确认，后台接口按 admin/operator/finance/auditor 做细粒度权限校验。用户端已支持登录注册、项目创建、原创/上传入口、版权确认、故事/角色/记忆/分集/脚本/分镜/媒体生成、额度查看/冻结、内容审核、公开案例授权、进度查看和私有成品下载；当前内部测试不展示支付/套餐入口，额度由后台人工增加。AI Provider 已支持 OpenAI 真实调用，后台可配置 API Key、Base URL、模型、优先级、启停状态、单次成本上限和当日成本上限；API Key 使用服务端密钥加密落库，页面不回显明文。图片、TTS 和 OpenAI Sora 视频生产链路已能保存真实 Provider 返回的二进制素材，默认优先级仍可保持 mock，避免未确认成本前误消耗真实模型。

新手操作请先看 OPERATION_GUIDE.md，里面按用户端和后台分别说明从项目创建到成品视频、额度、审核、AI 接入和常见问题排查。产品内也已补充教程入口：后台左侧“使用教程”，用户端导航“教程”，并预留 src/pages/help/tutorial 独立页面。

目录结构

backend/     NestJS API 服务
admin/       Geeker-Admin 可接入的后台前端骨架
user-app/    uni-app 路由预留、H5 优先的用户端制作台
workers/     BullMQ / FFmpeg worker 入口
deploy/      本地依赖、Docker、Nginx、部署脚本预留
docs/        系统 A / B 需求和工程文档
storage/     本地 mock 存储目录

本地启动

安装依赖：

npm install

后端启动会自动加载根目录 .env 和 backend/.env；系统环境变量优先级最高。PROVIDER_SECRET_KEY 必须长期保持稳定，用于解密后台保存的 AI Provider Key。

启动后端空服务：

npm run dev:backend

后端默认监听：

http://127.0.0.1:3000/api/health

启动后台骨架：

npm run dev:admin

启动用户端 H5：

npm run dev:user

验证命令

npm run lint
npm run typecheck
npm test
npm run build

API 加密传输

阶段 23 已实现前后端应用层加密信封，并保留 HTTPS 作为生产必需底座。阶段 23 补充了后台配置开关：测试默认关闭，上线后可在后台“配置管理”手动开启。

实现范围：

• 前端先通过 GET /api/client-config 读取 api_crypto_enabled，默认不开启加密。
• 开关开启后，前端通过 GET /api/crypto/handshake 获取短期 ECDH 会话参数。
• 前端和后端使用 ECDH P-256 + HKDF-SHA256 派生会话 AES key。
• JSON API 请求体使用 AES-256-GCM 加密后发送。
• JSON API 响应体、异常响应体使用 AES-256-GCM 加密后返回。
• 用户端小说上传改为加密 JSON 文件 payload，不再裸传 multipart 正文。
• 私有素材下载在加密请求下返回加密 JSON 文件 payload，前端解密后再生成 Blob。
• 后台和用户端生产构建默认使用同源 /api；显式配置 VITE_API_BASE_URL 时生产环境禁止 http://。
• 后台管理新增“配置管理”，可维护 security.api_crypto_enabled。
• API_CRYPTO_ENABLED=true/false 可强制覆盖数据库配置；默认 auto 表示读取后台配置。

生产建议：

NODE_ENV=production
HTTPS_REQUIRED=true
HTTPS_ALLOW_LOCAL_HTTP=false
TRUST_PROXY=true
CORS_ORIGINS=https://manga.example.com,https://admin.manga.example.com
API_CRYPTO_ENABLED=auto
API_CRYPTO_SESSION_TTL_SECONDS=900
VITE_API_CRYPTO_ENABLED=auto
VITE_API_BASE_URL=/api

开启方式：

1. 保持 API_CRYPTO_ENABLED=auto 和 VITE_API_CRYPTO_ENABLED=auto。
2. 用管理员账号进入后台“配置管理”。
3. 点击“开启 API 加密”，之后普通 API 会强制要求加密信封。

注意：应用层加密保护的是请求体和响应体内容。HTTP 方法、路径、域名和查询字符串不能被前端 JS 在应用层隐藏，所以生产环境仍必须使用 HTTPS，并应避免把敏感业务内容放进 query string。多实例部署时，当前内存态加密会话需要粘性会话或迁移到 Redis。

数据库

阶段 02 选择 Prisma 作为 MySQL 8 ORM。原因是当前系统 A 表数量多、JSON 字段多、后续迁移频繁，Prisma 的 schema、migration 和类型生成更适合分阶段落地。

核心文件：

backend/prisma/schema.prisma
backend/prisma/migrations/20260531093000_init_system_a/migration.sql
backend/prisma/seed.ts

常用命令：

cp .env.example .env
DATABASE_URL="mysql://ai_manga:ai_manga_password@127.0.0.1:3306/ai_manga" npm run db:validate
DATABASE_URL="mysql://ai_manga:ai_manga_password@127.0.0.1:3306/ai_manga" npm run db:generate
DATABASE_URL="mysql://ai_manga:ai_manga_password@127.0.0.1:3306/ai_manga" npm run db:migrate
DATABASE_URL="mysql://ai_manga:ai_manga_password@127.0.0.1:3306/ai_manga" npm run db:deploy
DATABASE_URL="mysql://ai_manga:ai_manga_password@127.0.0.1:3306/ai_manga" npm run db:seed

db:migrate 用于开发环境生成/演进迁移，可能需要创建 shadow database 的权限。已有 migration 文件时，服务器环境优先使用 db:deploy。

认证接口

阶段 03 已实现基础 JWT 认证：

POST /api/auth/register
POST /api/auth/login
POST /api/auth/logout
GET  /api/auth/profile
GET  /api/profile

/api/auth/profile 和 /api/profile 都需要 Authorization: Bearer <token>。

项目接口

阶段 05 已实现登录用户的项目创建、列表、详情、更新、取消和软删除流程：

POST   /api/projects
GET    /api/projects
GET    /api/projects/:id
PATCH  /api/projects/:id
POST   /api/projects/:id/cancel
DELETE /api/projects/:id

要求：

• 请求必须带 Authorization: Bearer <token>。
• input_mode 当前支持 ai_original 和 upload，admin_import 预留给后台导入。
• 新项目默认进入 source_selecting 状态。
• DELETE /api/projects/:id 当前为软删除，会把可删除项目归档为 archived。

文件上传

阶段 04 已实现私有资产上传。当前本机未启动 MinIO 时，默认使用本地 mock 私有存储；后续将 STORAGE_DRIVER=minio 并配置 MINIO_* 即可切换。

POST /api/assets/upload
POST /api/projects/:projectId/novel/upload
GET  /api/assets/:assetId
GET  /api/assets/:assetId/download

要求：

• 请求必须带 Authorization: Bearer <token>。
• 上传字段名为 file。
• 小说上传当前支持 txt、md、docx 和文本型 pdf。
• 上传资产默认 visibility=private。
• 普通 asset 查询只返回内部 asset 信息，不返回原始文件公网地址。
• /api/assets/:assetId/download 需要 Bearer Token，会校验资产归属后返回私有文件流，用户端成品下载和视频预览使用该接口。

小说解析与版权

阶段 06 已实现上传小说解析链路：

POST /api/projects/:projectId/copyright/confirm
GET  /api/projects/:projectId/copyright
POST /api/projects/:projectId/novel/paste
POST /api/projects/:projectId/novel/parse
GET  /api/projects/:projectId/novel/parse-result
PATCH /api/novel-chapters/:chapterId

要求：

• 请求必须带 Authorization: Bearer <token>。
• 上传小说解析前必须先确认版权，否则 /novel/parse 返回 400。
• authorization_type 支持 author_self、licensed、public_domain、internal_test。
• /novel/parse 支持从已上传 asset 解析，也支持从粘贴文本 source 解析。
• 解析会清洗常见广告/水印行，识别章节标题，失败时按字数切分。
• 解析结果写入 novel_sources 和 novel_chapters。
• 章节可手动编辑，编辑后状态标记为 edited。

AI 原创小说 Mock

阶段 07 已实现 AI 原创小说 mock 链路：

POST /api/projects/:projectId/original/idea
POST /api/projects/:projectId/original/outline
POST /api/projects/:projectId/original/chapters
POST /api/projects/:projectId/original/self-check
GET  /api/projects/:projectId/original/result

要求：

• 请求必须带 Authorization: Bearer <token>。
• 项目 input_mode 必须为 ai_original，上传小说项目调用原创接口会返回 400。
• 当前实现为 deterministic mock，parse_report.provider=mock_novel_provider，不调用真实 AI Provider。
• 生成内容写入 novel_sources 和 novel_chapters。
• 默认按项目 target_episode_count 生成章节，MVP 场景通常为 3 章。
• 自检覆盖主角一致性、主线、冲突、可视化摘要和短视频钩子。

故事圣经

阶段 08 已实现故事圣经链路：

POST /api/projects/:projectId/story-bible/generate
GET  /api/projects/:projectId/story-bible
PATCH /api/projects/:projectId/story-bible
POST /api/projects/:projectId/story-bible/confirm

要求：

• 请求必须带 Authorization: Bearer <token>。
• 生成前必须已有小说来源和章节，支持上传解析链路和 AI 原创 mock 链路。
• 生成结果写入 story_bibles，状态为 waiting_confirm。
• 编辑故事圣经会创建新版本，不覆盖旧版本。
• 确认后故事圣经状态变为 confirmed，项目状态变为 story_confirmed。
• GET /story-bible?version=2 可查询指定版本；不传 version 返回最新版本和版本列表。

角色圣经

阶段 09 已实现角色圣经链路：

POST /api/projects/:projectId/characters/extract
GET  /api/projects/:projectId/characters
POST /api/projects/:projectId/characters
POST /api/projects/:projectId/characters/confirm
PATCH /api/characters/:characterId
DELETE /api/characters/:characterId

要求：

• 请求必须带 Authorization: Bearer <token>。
• 抽取角色前必须已有已确认故事圣经，否则 /characters/extract 返回 400。
• 角色抽取当前为 deterministic mock，从已确认故事圣经和小说章节生成主角、反派、配角等角色草稿。
• 角色数据写入 characters 表，支持列表、手动新增、编辑和软删除。
• 确认角色库会把 draft、generated、edited 状态角色锁定为 locked，项目状态变为 character_confirmed。
• locked 角色不可修改姓名、角色类型、性别、年龄、身份和核心外观字段；仍可补充服装规则、表情风格等非核心描述。
• 本阶段不生成角色图片、不生成 anchor 图，也不接入 ImageProvider 或队列。

长篇记忆

阶段 10 已实现长篇记忆链路：

GET  /api/projects/:projectId/plot-memories
POST /api/projects/:projectId/plot-memories/generate
POST /api/projects/:projectId/plot-memories
PATCH /api/plot-memories/:memoryId
GET  /api/projects/:projectId/memory-context?episode_no=5
GET  /api/characters/:characterId/memories
GET  /api/projects/:projectId/plot-threads
POST /api/projects/:projectId/plot-threads
PATCH /api/plot-threads/:threadId
POST /api/episodes/:episodeId/continuity-check

要求：

• 请求必须带 Authorization: Bearer <token>。
• 生成长篇记忆前必须已有 confirmed 故事圣经和 locked 角色库。
• 记忆生成当前为 deterministic mock，会写入 plot_memories、plot_threads 和 character_memories。
• 剧情记忆支持手动新增、标记 resolved/archived、按类型/状态/分集筛选。
• 剧情线支持新增、查询、更新状态，类型覆盖主线、反派计划、悬疑线、角色成长线等。
• GET /memory-context?episode_no=N 会返回故事圣经、锁定角色、活跃剧情记忆、开放剧情线、前 3 集摘要和上一集结尾钩子，供后续分集/脚本生成使用。
• locked 角色的非核心资料补充会自动记录 character_memories.profile_adjustment。
• 连续性检查当前为规则版 mock，可发现角色未承接、伏笔未推进、上一集钩子未承接、缺少结尾钩子、开放剧情线未推进和明显破坏世界观的内容。
• 本阶段不接入 EmbeddingProvider、不做向量检索、不进队列，也不调用真实 AI Provider。

分集计划

阶段 11 已实现分集计划链路：

POST /api/projects/:projectId/episodes/generate-plan
GET  /api/projects/:projectId/episodes
PATCH /api/episodes/:episodeId
POST /api/projects/:projectId/episodes/confirm

要求：

• 请求必须带 Authorization: Bearer <token>。
• 生成分集前必须已有 confirmed 故事圣经、locked 角色库、小说章节和 active 长篇记忆。
• 分集生成当前为 deterministic mock，会写入 episodes 表。
• 每集包含标题、剧情摘要、开头钩子、中段冲突、结尾悬念、关联章节和预计时长。
• 生成时项目状态流转为 episode_planning，完成后为 waiting_episode_confirm。
• 分集可在确认前编辑，编辑后状态为 edited。
• 确认分集会把 draft、generated、edited 状态分集锁定为 confirmed，项目状态变为 episode_confirmed。
• 已确认分集不可继续编辑；如需重做，后续会通过返工/修改申请流程处理。
• 本阶段不生成单集脚本、不生成分镜、不进队列，也不调用真实 AI Provider。

脚本和分镜

阶段 12 已实现单集脚本和分镜链路：

POST /api/episodes/:episodeId/script/generate
GET  /api/episodes/:episodeId/script
PATCH /api/episodes/:episodeId/script
POST /api/episodes/:episodeId/script/confirm
POST /api/episodes/:episodeId/storyboard/generate
GET  /api/episodes/:episodeId/storyboard
PATCH /api/storyboard-shots/:shotId
DELETE /api/storyboard-shots/:shotId
POST /api/episodes/:episodeId/storyboard/confirm
POST /api/storyboard-shots/:shotId/regenerate-prompt

要求：

• 请求必须带 Authorization: Bearer <token>。
• 生成单集脚本前必须已有 confirmed 分集、confirmed 故事圣经和 locked 角色库。
• 单集脚本当前为 deterministic mock，会写入 episode_scripts，包含脚本文本、旁白和结构化台词。
• 脚本生成后项目状态进入 waiting_script_confirm；确认后脚本状态为 confirmed，项目状态为 script_confirmed。
• 生成分镜前必须已有 confirmed 单集脚本。
• 分镜生成当前为 deterministic mock，会写入 storyboard_shots，默认每集 10 个镜头。
• 每个镜头包含画面描述、人物、场景、动作、台词/旁白、镜头运动、特效、2-5 秒时长、Prompt 和负面 Prompt。
• Prompt 会带入角色固定描述，并包含防混脸、年龄/发色漂移、复杂多人镜头等负面约束。
• 分镜可在确认前编辑、删除和重生 Prompt；确认后镜头状态为 confirmed，项目状态为 storyboard_confirmed。
• 本阶段不生成分镜图片、不接入 ImageProvider、不进队列，也不调用真实 AI Provider。

BullMQ 队列

阶段 13 已实现任务记录、幂等入队、管理员重试/取消/人工介入和队列监控：

POST /api/projects/:projectId/tasks
GET  /api/projects/:projectId/tasks
GET  /api/tasks/:taskId
GET  /api/admin/tasks
POST /api/admin/tasks/recover-stale
POST /api/admin/tasks/:taskId/retry
POST /api/admin/tasks/:taskId/cancel
POST /api/admin/tasks/:taskId/manual-required
GET  /api/admin/queues

要求：

• 请求必须带 Authorization: Bearer <token>。
• 普通用户只能操作自己的项目任务，admin 可查看和管理全部任务。
• 创建任务会先写入 render_tasks，再尝试入 BullMQ；Redis 或 BullMQ 不可用时，任务仍保留为 pending / retrying，接口返回 queue_backend=bullmq_unavailable。
• 幂等 key 默认由 project_id + episode_id + shot_id + task_type + input_hash 组成，input_hash 基于稳定 JSON 序列化生成。
• 已支持 novel、parse、story、character、episode、script、storyboard、image、audio、subtitle、video、qc、review、analytics 等队列映射。
• 默认重试次数按任务类型区分：文本类 2 次、图片类 3 次、视频 2 次、TTS/字幕 2 次、QC 1 次、人工审核 0 次。
• 管理员可把失败任务重试为 retrying，可取消任务为 cancelled，可标记为 manual_required，可恢复过久未完成的 running / retrying 任务。
• /api/admin/queues 会返回 BullMQ 每个队列的 waiting、active、delayed、failed、completed、paused 计数。
• worker 包已接入 BullMQ 消费器，会订阅全部队列并调用后端内部接口 POST /api/internal/worker/tasks/:taskId/execute，通过 WORKER_SECRET 鉴权。
• worker 执行失败时后端会按 max_retry 自动重入队；达到上限后把任务转为 manual_required，后台任务页可继续人工处理。
• worker 当前执行的是通用 Provider 任务委托：按任务类型映射到 Text/Novel/Image/Voice/Video/Moderation/QC/FileParse Provider；图片、音频、视频资产生成的业务接口仍保留同步链路。

AI Provider 抽象

阶段 14 已实现 mock-first Provider 抽象、管理员配置入口、执行日志和成本聚合；阶段 21 已补充 OpenAI / OpenAI 兼容真实驱动：

GET  /api/admin/providers
POST /api/admin/providers/bootstrap-mocks
POST /api/admin/providers/bootstrap-openai
POST /api/admin/providers/bootstrap-video
POST /api/admin/providers/execute
PATCH /api/admin/providers/:providerId
PATCH /api/admin/providers/openai/runtime-config
PATCH /api/admin/providers/:providerId/runtime-config
POST /api/admin/providers/:providerId/test
GET  /api/admin/provider-logs
GET  /api/admin/costs

要求：

• 请求必须带 Authorization: Bearer <token>；后台接口按 RBAC 权限校验，admin 拥有全部权限，operator/finance/auditor 只开放对应读写范围。
• 已声明 TextProvider、NovelProvider、ImageProvider、VideoProvider、VoiceProvider、ModerationProvider、QualityCheckProvider、FileParseProvider、EmbeddingProvider。
• /bootstrap-mocks 会写入或更新 9 个默认 mock provider 配置。
• /bootstrap-openai 会写入或更新 OpenAI real provider 配置，包含 Responses、Moderation、Embeddings、Image Generation、Sora Video 和 Text to Speech 驱动。
• 后台默认显示“OpenAI 统一接入”：运营只需填写一个 OpenAI API Key，PATCH /admin/providers/openai/runtime-config 会批量应用到全部 OpenAI 能力；未勾选“生产任务优先使用 OpenAI”时会把 OpenAI 优先级保持为 50，低于 mock，避免保存 Key 后立刻消耗真实额度。
• GET /admin/providers/openai/connection-check 只请求 OpenAI /models 检查 Key/网络，不生成文本、图片、语音或视频，不写 provider_logs。
• /execute 会从 provider_configs 选择启用 provider，执行 mock 或 real driver，写入 provider_logs。
• 如果传入 task_id，执行时会把对应 render_tasks 标记为 running，成功后回写 success、provider_id、provider_request_id、cost_estimate 和 cost_actual。
• primary provider 失败时会按 fallback provider 或同类型优先级继续尝试，并记录失败日志。
• provider 输入、配置输出和日志输出会拒绝/脱敏 api_key、secret、token、password、credential 等疑似密钥字段；后台运行配置接口会把 API Key 加密为 api_key_secure 后保存，列表只显示已配置状态。
• 真实 Provider 优先读取后台加密保存的 API Key；未配置时仍可回退读取 OPENAI_API_KEY。后台可配置 base_url 接入 OpenAI 兼容服务，也可修改模型名、优先级和启停状态。PROVIDER_SECRET_KEY 用于加密后台保存的 Provider 密钥，未设置时回退 JWT_SECRET；生产环境必须保持该值稳定，否则已保存 Key 无法解密，需要重新保存。
• 重复点击“初始化 OpenAI 接入”会刷新默认 Provider 定义，但会保留后台已加密保存的 API Key、Base URL、超时和成本阈值，避免误清空线上配置。
• 后台真实 Provider 的“付费测试”必须二次确认，后端 /admin/providers/:providerId/test 也要求 confirm_paid_test=true；真实视频 Provider 测试接口默认禁用，避免误触发高成本视频任务。
• Provider 可配置 max_cost_per_call 和 daily_cost_limit 成本阈值，也可通过 PROVIDER_MAX_COST_PER_CALL、PROVIDER_DAILY_COST_LIMIT 设置全局保护；超过阈值会在调用前拦截并写失败日志。
• openai_image_generation、openai_video_generation 和 openai_audio_speech 的日志只保存 URL/大小/hash 等元数据，不把 base64 图片、视频或音频字节写入 provider_logs；真实二进制只在业务生成链路中短暂返回，用于立即写入私有素材。
• OpenAI 图片、Sora 视频和 TTS real provider 默认优先级低于 mock；后台可提高优先级或禁用 mock 后让业务生产链路保存真实图片、真实视频或 TTS 音频资产。
• openai_video_generation 按 OpenAI Videos API 的异步流程执行：创建视频任务、轮询完成状态，业务链路需要二进制时再下载 MP4 并落库。可用 OPENAI_VIDEO_MODEL 覆盖默认 sora-2。
• 真人短剧链路已新增可替换 image-to-video Provider：minimax_hailuo_23_fast、minimax_hailuo_23、alibaba_wan26_i2v_flash、alibaba_wan26_i2v、vidu_q3_turbo_reference、vidu_q3_pro、jimeng_seedance、runway-image-to-video、kling-image-to-video。真实视频 Provider 默认禁用，用户端真实视频生成必须传 confirm_real_video=true，并受单片段成本上限、Provider 单次/每日成本阈值保护。
• configurable_image_to_video 驱动支持通用异步图生视频流程：创建任务、轮询任务、提取视频 URL；如果供应商只返回 file_id，可通过 output_url_endpoint_template 再取下载链接。MiniMax Hailuo、阿里 Wan、Vidu 和 Seedance 预设都走这类可配置模板，正式启用前应先用 1 个镜头小样核对字段、速度、质量和账单。
• VideoProvider 成本规则支持 unit=video_seconds、price_per_second、price_per_clip。后台配置真实视频价格后，用户端真人短剧面板会显示片段级成本预估。

图片生成 Mock

阶段 15 已实现角色图、锚点图、分镜预览图和正式图的 mock 生成：

POST /api/characters/:characterId/generate-images
GET  /api/characters/:characterId/images
POST /api/characters/:characterId/set-anchor
POST /api/storyboard-shots/:shotId/images/generate
GET  /api/storyboard-shots/:shotId/images
POST /api/episodes/:episodeId/shot-images/generate

要求：

• 请求必须带 Authorization: Bearer <token>。
• 角色图生成要求角色已 locked。
• 默认生成 front_reference、anchor、expression_pack，也可指定 image_types。
• 角色锚点会写入 character_images.is_anchor=true，并回写 characters.anchor_asset_id。
• 分镜图生成要求 storyboard_shots.status=confirmed。
• 分镜图 Prompt 会引用角色固定描述和 anchor_asset_id，降低混脸和漂移风险。
• 图片生成会创建 render_tasks，通过 ImageProvider 执行，写入 provider_logs，并保存本地/MinIO 私有图片资产。
• 生成结果写入 character_images 或 shot_images，图片资产写入 assets，visibility=private。
• 当 Provider 返回 content_base64 或可下载的 HTTP(S) asset_url 时，会保存真实位图；否则回退生成 SVG mock 占位图。图片任务会回填 render_tasks.output_asset_id，方便后台追踪产物。

TTS / 字幕 / FFmpeg

阶段 16 已实现单集音频、字幕和 FFmpeg 视频合成链路：

POST /api/episodes/:episodeId/audio/generate
POST /api/episodes/:episodeId/subtitle/generate
POST /api/episodes/:episodeId/video/render
GET  /api/episodes/:episodeId/media-assets

要求：

• 请求必须带 Authorization: Bearer <token>。
• 音频生成要求已有 confirmed 单集脚本，会调用 VoiceProvider，写入 render_tasks、provider_logs 和私有音频资产；真实 TTS 返回 content_base64 或可下载 URL 时保存真实音频，否则回退静音 WAV。
• 字幕生成要求已有 confirmed 分镜，会按镜头时长生成 SRT cues，写入本地私有 .srt 资产。
• 视频渲染要求已有 confirmed 分镜和已生成的分镜图；默认会复用或自动生成最新音频和字幕。
• 视频渲染要求项目已支付或冻结额度，否则会返回错误；阶段 19 用户端会在合成前调用额度冻结。
• 视频渲染会调用 VideoProvider 记录 provider 执行日志；若启用 openai-video，后端会创建 Sora 视频任务、轮询完成并下载 MP4，随后直接保存 Provider 渲染出的 MP4；若 Provider 未返回二进制，则读取私有分镜图、音频和 SRT 字幕，使用 FFmpeg 生成本地私有 MP4 资产。
• 默认优先使用 FFmpeg，成功时返回 ffmpeg_used=true 和 render_backend=ffmpeg；传入 prefer_ffmpeg=false 或本机缺少 FFmpeg 时会走 mock fallback。
• 生成结果写入 assets，asset_type 分别为 audio、subtitle、video，visibility=private。
• 当前不生成真实 BGM；图片、TTS 和 Sora 视频可切换真实 Provider 落库，视频也可保留 FFmpeg 本地合成，音频、字幕和视频目前仍为同步接口执行，worker 消费器后续接入。

后台管理

阶段 17 已实现后台管理 API 和可用的 Vue/Vite 管理端：

GET   /api/admin/dashboard
GET   /api/admin/rbac/me
GET   /api/admin/projects
GET   /api/admin/projects/:projectId
PATCH /api/admin/projects/:projectId/status
GET   /api/admin/users
GET   /api/admin/assets
GET   /api/admin/novel-sources
GET   /api/admin/novel-chapters
GET   /api/admin/characters
GET   /api/admin/storyboard-shots
GET   /api/admin/works
GET   /api/admin/copyright-records
GET   /api/admin/operation-logs
GET   /api/admin/operation-logs/export

已接入已有管理接口：

GET  /api/admin/tasks
POST /api/admin/tasks/:taskId/retry
POST /api/admin/tasks/:taskId/cancel
POST /api/admin/tasks/:taskId/manual-required
GET  /api/admin/queues
GET  /api/admin/providers
POST /api/admin/providers/bootstrap-mocks
GET  /api/admin/provider-logs
GET  /api/admin/costs
GET  /api/admin/orders
GET  /api/admin/quota-accounts
GET  /api/admin/users/:userId/detail
POST /api/admin/users/:userId/quota/grant
GET  /api/admin/content-reviews
PATCH /api/admin/content-reviews/:reviewId
GET  /api/admin/case-showcases
PATCH /api/admin/case-showcases/:showcaseId
GET  /api/admin/system-configs
PATCH /api/admin/system-configs/:configKey

要求：

• 请求必须带 Authorization: Bearer <token>；后台支持 admin、operator、finance、auditor 角色，接口按 projects/users/billing/reviews/tasks/providers/costs/settings/audit 等权限校验。
• npm run db:seed 会创建或更新本地 admin@example.com，默认开发密码为 Admin123!，可用 SEED_ADMIN_PASSWORD 覆盖。
• 管理端默认运行在 http://127.0.0.1:5175，API 默认指向 http://127.0.0.1:3000/api，可用 VITE_API_BASE_URL 覆盖。
• 当前后台已支持登录、仪表盘、项目管理、项目详情、项目状态调整、小说源/章节管理、角色资源、分镜资源、成品漫剧、订单额度、内容审核、公开案例授权、任务重试/取消/转人工、队列统计、Provider 配置、Provider 成本阈值、成本日志、用户列表、用户详情抽屉、用户人工加余额、额度冲正、禁用/启用用户、改角色、重置密码、素材列表、版权记录、系统配置管理和审计日志导出；小说、章节、角色、分镜、素材和成品资源支持详情/预览，高危用户操作在页面上会弹出二次确认。
• 模板管理深水区留到后续对应阶段继续扩展。

订单额度

阶段 19 已实现订单、额度账户和项目正式生成前冻结/扣减：

GET  /api/billing/packages
GET  /api/billing/quota
GET  /api/billing/quota/logs
GET  /api/billing/orders
POST /api/billing/orders
POST /api/billing/orders/:orderId/mock-pay
GET  /api/projects/:projectId/quota/estimate
POST /api/projects/:projectId/quota/freeze
POST /api/projects/:projectId/quota/release

要求：

• /api/billing/packages 可公开查看，其他用户额度接口需要 Bearer Token。
• 当前为内部测试额度模式：用户端不展示支付/套餐入口，运营在后台用户管理中人工增加额度。历史 mock 支付接口仍保留用于接口回归，不作为当前用户端入口。
• 项目额度预估按输入模式、目标集数和默认每集 6 个镜头估算。
• quota/freeze 会扣减可用额度、增加冻结额度，并把项目 payment_status 标记为 quota_frozen。
• 视频合成成功后会把冻结额度扣为已用额度，并把项目 payment_status 标记为 paid。
• 管理端新增“订单额度”页，可查看订单和额度账户；用户管理页支持管理员手动给用户增加余额/额度和执行额度冲正，并写入额度流水和操作日志，用户详情抽屉可查看额度流水、订单、项目、素材和最近操作。

内容审核

阶段 20 已实现文本、素材、成品视频和公开案例授权的审核闭环：

POST /api/projects/:projectId/reviews/text
GET  /api/projects/:projectId/reviews
POST /api/assets/:assetId/review
POST /api/projects/:projectId/showcase/authorize
GET  /api/projects/:projectId/showcase
GET  /api/admin/content-reviews
PATCH /api/admin/content-reviews/:reviewId
GET  /api/admin/case-showcases
PATCH /api/admin/case-showcases/:showcaseId

要求：

• 用户接口必须带 Bearer Token，并校验项目或素材归属。
• 文本审核会聚合项目中的小说、故事圣经、角色、分集、脚本和分镜文本，也支持请求体直接传入 content。
• 素材审核覆盖 image、video、audio、subtitle 和 document/text 类资产；用户端当前接入文本审核和成品视频审核按钮。
• 审核调用现有 ModerationProvider；未初始化真实 Provider 时使用 mock，初始化 OpenAI 接入并在后台保存 API Key 后会优先调用 openai-moderation，失败时回退 mock。
• 需要人工处理的审核会把项目状态标记为 manual_required，后台可执行通过、修改、驳回、屏蔽和转人工。
• 用户端可提交公开案例授权，后台可将案例授权、发布为 public 或驳回。
• 当前不接入真实内容安全平台，不做真实版权库比对；商业发布前仍需人工确认版权授权、平台规则和内容合规。
• mock moderation 会识别“不得/禁止/避免违法内容”这类安全规则提示，不再把合规约束本身误判为风险文本。

MVP 验收

阶段 22 已完成系统 A MVP 端到端验收：

• AI 原创小说链路：原创构思、章节、故事圣经、角色、角色锚点、长篇记忆、3 集分集、脚本、分镜、正式分镜图、音频、字幕、FFmpeg MP4、私有下载、视频审核和案例授权。
• 上传小说链路：TXT 上传、版权确认、小说解析、故事圣经、角色、角色锚点、长篇记忆、1 集分集、脚本、分镜、正式分镜图、音频、字幕、FFmpeg MP4、私有下载、视频审核和案例授权。
• 验收用户 mvp-1780243409631@example.com，原创项目 ID 28，上传项目 ID 29。
• 原创 3 个 MP4 与上传 1 个 MP4 均通过私有下载校验，返回 video/mp4，文件大小均大于 300 KB。
• 额度流程通过 mock 支付、项目冻结、视频成功后扣减；验收后账户 used_quota=196、available_quota=1004。
• 验收时发现并修复 mock 文本审核误伤安全规则提示的问题；复审记录 13、14 均为 passed。

用户端 H5

阶段 18 已实现 H5 优先、PC 自适应的用户端制作台，并保留 uni-app pages.json、manifest.json 和页面路由文件，后续微信小程序/App 可继续迁移：

登录 / 注册
新建项目
我的项目
制作台
生成进度
成品漫剧
用户中心

要求：

• 用户端 API 可用 VITE_API_BASE_URL 覆盖；未配置时，本机访问会请求 http://127.0.0.1:3000/api，外网 IP/域名访问会自动请求同主机的 :3000/api。
• 用户端默认运行在 http://127.0.0.1:5174。
• 公网调试访问需要服务器防火墙/安全组放行 TCP 5174 和 3000；当前本机 firewalld 已放行这两个端口。
• H5 为主布局，移动端底部导航和单列长表单优先；PC 宽屏自动切换为左侧导航和两栏制作台。
• 当前用户端已接入真实 API：认证、项目列表/创建、AI 原创小说、上传小说粘贴/文件入口、版权确认、故事圣经、角色库、长篇记忆、分集计划、单集脚本、分镜、分镜图、音频、字幕、FFmpeg 视频合成、任务进度、私有视频预览和下载。
• 阶段 19 已接入额度中心；当前用户端隐藏套餐、模拟支付和订单入口，仅展示额度账户、项目额度预估和合成前冻结额度。
• 阶段 20 已接入内容审核中心：项目文本审核、成品视频审核、审核状态列表和公开案例授权。
• 微信小程序/App 的文件选择、下载保存、支付能力、分享能力留到后续平台适配阶段；当前内部测试不开放用户端支付入口，图片/TTS 生产链路可切换真实 Provider，视频默认仍可用 FFmpeg 本地合成。

开发约束

• 按 AGENTS.md 和 docs/system_a/21_Codex开发任务拆解文档.md 分阶段开发。
• 真实 AI Provider 已接入执行层；原创小说、故事圣经、角色、记忆、分集、脚本、分镜等 deterministic 生成服务后续可逐步迁移到统一 Provider 调用。
• 密钥只放 .env，不要提交真实密钥。
• 用户上传小说和素材默认私有。
• 每个阶段完成后更新 CODEX_PROGRESS.md。