# AirShelf 技术架构方案

> 版本：v1.0  
> 日期：2026-05-29  
> 定位：从原型走向真实可运营产品的顶层技术架构决策文档  
> 适用范围：Django 后端、前端产品化、火山 ARK AI 接入、额度账本、运营后台、60s 多段视频生产

---

## 1. 架构结论

AirShelf 不应该先横向补齐所有页面，而应该先打穿一条真实生产闭环：

商品创建 -> 项目创建 -> AI 脚本 -> 基础资产 -> 可选故事板 -> 4 段视频生成 -> FFmpeg 拼接导出 -> 额度确认扣费 -> 资产入库 -> 运营后台可观测

第一阶段采用“模块化单体 + 异步任务”的架构：

- 后端：Django + Django REST Framework
- 数据库：MySQL
- 缓存/队列/锁：Redis
- 异步任务：Celery Worker + Celery Beat
- 文件存储：火山 TOS
- AI 模型：火山 ARK，统一 Provider 抽象
- 运营后台：先用 Django Admin + 少量自定义后台页
- 前端：React + Vite 单页应用。以 `v1/*.html` 为核心视觉规格，`电商AI平台/*.html` 作为未迁移页面和原版能力补充，重建为真实前端应用
- 路由：正式业务入口使用 React History URL，例如 `/products`、`/projects/new`、`/pipeline/:id`。`/exact/*.html` 只作为像素级设计稿镜像和视觉回归基线，不作为产品业务路由

暂不采用微服务。当前阶段最大风险不是服务边界不够细，而是任务状态、扣费账本、AI 失败恢复、资产流转没有被一套一致的数据模型兜住。模块化单体更容易保证事务一致性，也更适合快速把 PRD 全量能力落地。

---

## 2. 核心原则

### 2.1 账本优先

额度系统不能后补。所有 AI 任务、导出任务、重跑任务都必须先经过额度预检，并由账本记录冻结、确认扣费、失败释放、人工调整。

关键原则：

- 失败不扣费
- 用户确认采用后扣费
- 预估消耗需要额度预检
- 扣费必须幂等
- 所有账务变更必须有流水

### 2.2 任务异步化

火山生图、生视频、视频拼接都不能放在同步 HTTP 请求里执行。API 只负责创建任务、返回 task_id；Worker 负责执行、轮询、重试、写状态。

### 2.3 资产对象化

图片、视频、成片不直接存数据库。数据库只存 TOS object key、元数据、归属、状态、引用关系。所有中间产物都应成为可追踪 Asset。

### 2.4 状态机先行

项目、阶段、AI 任务、视频片段、导出任务都必须有清晰状态机。不要只靠布尔字段拼状态，否则 60s 多段生产会很快失控。

### 2.5 单项目多段并发

60s 视频按 4 段 x 15s 生产。每段是独立 VideoSegment 和独立 AIJob，可并发、可单段失败、可单段重跑、可回选历史版本。

---

## 3. 系统拓扑

```text
Browser
  |
  | HTTPS
  v
Frontend Web
  |
  | REST / SSE or WebSocket
  v
Django API
  |
  | ORM
  v
MySQL

Django API
  |
  | enqueue task
  v
Redis broker
  |
  v
Celery Workers
  |       |        |
  |       |        +--> FFmpeg export
  |       +----------> TOS upload/download
  +------------------> Volcano ARK

Celery Workers
  |
  | status / ledger / asset metadata
  v
MySQL

Django Admin / Ops
  |
  v
MySQL + task logs + billing ledger
```

部署形态：

- `airshelf-web`：前端静态资源或 SSR 前端服务
- `airshelf-api`：Django API
- `airshelf-worker-default`：通用任务
- `airshelf-worker-ai`：AI 文本/图片/视频任务
- `airshelf-worker-media`：FFmpeg 拼接、转码、缩略图
- `airshelf-beat`：定时任务、超时扫描、TOS 临时文件清理

---

## 4. 应用模块划分

建议 Django apps：

```text
apps/
  accounts/      用户、登录、JWT、团队成员
  teams/         团队、角色、邀请、权限
  products/      商品库、卖点、商品图
  projects/      项目、阶段、脚本、分镜
  assets/        资产库、TOS 文件、引用关系
  ai/            火山 Provider、AIJob、模型配置
  pipeline/      5 阶段编排、视频片段、故事板
  billing/       额度账户、冻结、扣费、流水、套餐
  media/         FFmpeg 拼接、字幕、BGM、导出
  ops/           运营后台扩展、任务监控、财务对账
  common/        审计字段、软删除、幂等、锁、工具
```

模块边界：

- `ai` 不直接扣费，只上报任务结果和预估成本。
- `billing` 不调用火山，只处理额度、冻结、确认扣费和流水。
- `assets` 不理解业务阶段，只管理文件、资产类型、引用和权限。
- `pipeline` 负责把 PRD 的 5 个 Stage 串起来。
- `ops` 只读为主，人工调整必须写审计日志。

---

## 5. 关键数据模型

### 5.1 账户与团队

- `User`
- `Team`
- `TeamMember`
- `Invitation`
- `Role`

V1 决策：

- 一个用户默认属于一个团队。
- 注册自动创建团队，注册者为超管。
- 预留多团队字段，但 V1 不开放切换多团队。

### 5.2 商品与项目

- `Product`
- `ProductImage`
- `ProductSellingPoint`
- `Project`
- `ProjectStageState`
- `Script`
- `ScriptShot`

Project 关键字段：

- `team_id`
- `product_id`
- `creator_id`
- `target_duration_seconds`：30 / 45 / 60
- `segment_count`：2 / 3 / 4
- `current_stage`
- `status`

### 5.3 资产

- `Asset`
- `AssetVersion`
- `AssetReference`

资产类型：

- product_image
- product_triptych
- character_portrait
- character_triptych
- scene_image
- storyboard
- video_clip
- final_video
- bgm
- subtitle

关键字段：

- `team_id`
- `project_id`
- `owner_id`
- `tos_key`
- `mime_type`
- `duration_seconds`
- `width`
- `height`
- `source`
- `status`
- `is_shared`

### 5.4 AI 任务

- `AIJob`
- `AIJobAttempt`
- `ModelConfig`

AIJob 关键字段：

- `job_type`：text / image / video
- `provider`：volcengine
- `model_name`
- `request_payload`
- `response_payload`
- `external_task_id`
- `status`
- `progress`
- `error_code`
- `error_message`
- `estimated_cost`
- `actual_cost`
- `idempotency_key`

任务状态：

```text
created -> quota_checked -> queued -> submitted -> polling -> succeeded
                                                 -> failed
                                                 -> timeout
                                                 -> cancelled
```

### 5.5 视频片段与导出

- `VideoSegment`
- `VideoSegmentVersion`
- `ExportJob`
- `TimelineItem`
- `SubtitleCue`

VideoSegment：

- `project_id`
- `segment_index`
- `start_second`
- `end_second`
- `prompt`
- `use_storyboard`
- `adopted_version_id`
- `status`

60s 项目生成 4 个 VideoSegment：

- 0-15s
- 15-30s
- 30-45s
- 45-60s

### 5.6 额度与财务

- `Wallet`
- `QuotaPolicy`
- `QuotaUsage`
- `BillingTransaction`
- `BillingHold`
- `PricingRule`
- `RechargeOrder`

四层额度：

- 用户日额度
- 用户月额度
- 团队月额度
- 团队总额度池

账务动作：

- estimate
- hold
- release
- charge
- refund
- manual_adjust

所有扣费以 `BillingTransaction` 为准，不从任务表反推财务结果。

---

## 6. Redis 设计

Redis DB index：

- DB 0：Django cache
- DB 1：Celery broker
- DB 2：Celery result backend
- DB 3：分布式锁、幂等锁、防重复扣费锁
- DB 4：限流、验证码计数、短期风控
- DB 5：任务进度 pubsub / WebSocket 预留

锁设计：

- `lock:billing:confirm:{job_id}`
- `lock:project:generate:{project_id}`
- `lock:segment:generate:{segment_id}`
- `lock:export:{project_id}`

锁必须有 TTL，且所有关键写入仍要依赖数据库唯一约束保证最终幂等。

---

## 7. 火山 ARK Provider 设计

所有模型通过统一 Provider 调用：

```text
AIProvider
  generate_text()
  generate_image()
  create_video_task()
  get_video_task()
```

当前模型决策来自 `account.md`，代码只读取环境变量：

- 文本主模型：DeepSeek-V3-2
- 文本备用模型：Doubao Seed 2.0 Pro / Lite
- 图片模型：Seedream 5.0 Lite / 5.0 / 4.5
- 视频模型：Seedance 2.0 / 2.0 Fast / 1.5 Pro

接口策略：

- 文本：OpenAI-compatible chat
- 图片：同步或短异步，统一落成 AIJob
- 视频：异步任务，提交后轮询
- 所有外部响应原文进入 `response_payload`，便于排障

模型配置不硬编码在业务流程中。业务流程只声明用途：

- script_generation
- asset_prompt_generation
- product_image_optimize
- storyboard_generation
- video_segment_generation

由 ModelConfig 决定具体模型。

---

## 8. 60s 多段生产流程

### 8.1 Stage 1 脚本

输入：

- 商品信息
- 卖点
- 目标时长
- 用户指令

输出：

- Script
- ScriptShot
- 自动切段结果

60s 输出要求：

- `segment_count = 4`
- 每段约 15s
- 每个镜头必须归属 segment_index

### 8.2 Stage 2 基础资产

生成：

- 商品三视图
- 人物立绘
- 人物三视图
- 场景图

资产候选规则：

- 创意选择型一次 4 张
- 结构转换型一次 1 张
- 采用后才进入当前项目引用

### 8.3 Stage 3 故事板

故事板是可选项，不是硬前置。

如果生成：

- 每段 1 张故事板图
- 60s 项目最多 4 张
- 每张可独立重跑

### 8.4 Stage 4 视频片段

每个 VideoSegment 独立生成：

- 输入：脚本分段、基础资产、可选故事板、视频提示词
- 输出：VideoSegmentVersion
- 用户采用某一版后，才进入可拼接素材

并发策略：

- 单项目最多 4 段并发
- 全局并发由 Worker 数和 Redis 队列控制
- 外部配额不足时降级到每项目 2 段并发

### 8.5 Stage 5 拼接导出

输入：

- 已采用的视频片段
- 时间线配置
- 字幕
- BGM
- 转场

输出：

- final_video Asset
- ExportJob

第一版导出能力：

- 单主轨
- 排序
- 裁剪
- 字幕烧录
- BGM 混音
- 9:16
- 1080P MP4

---

## 9. API 设计原则

API 应按资源和动作拆分，不把复杂动作塞进一个“大生成接口”。

示例：

```text
POST   /api/products/
GET    /api/products/
POST   /api/projects/
GET    /api/projects/{id}/

POST   /api/projects/{id}/script/generate/
POST   /api/projects/{id}/script/confirm/

POST   /api/projects/{id}/assets/generate/
POST   /api/assets/{id}/adopt/

POST   /api/projects/{id}/storyboards/generate/
POST   /api/storyboards/{id}/adopt/

POST   /api/video-segments/{id}/generate/
POST   /api/video-segment-versions/{id}/adopt/

POST   /api/projects/{id}/exports/
GET    /api/exports/{id}/

GET    /api/ai-jobs/{id}/
POST   /api/billing/estimate/
GET    /api/billing/transactions/
```

前端轮询策略：

- AIJob 详情接口提供统一进度。
- Stage 页面不直接轮询火山。
- 后续可用 SSE/WebSocket 替代轮询。

---

## 10. 运营后台

第一版用 Django Admin 承担运营后台，不另起复杂后台前端。

必须有：

- 用户管理
- 团队管理
- 额度账户
- 消费流水
- AIJob 任务监控
- 视频片段与导出任务
- 模型配置
- PricingRule
- 人工补偿/退款/额度调整

人工操作要求：

- 必须写审计日志
- 财务调整必须写 BillingTransaction
- 禁止直接改余额字段绕过账本

---

## 11. 部署与环境

环境：

- local
- test
- production

敏感配置：

- 本地测试凭据记录在 `account.md`
- 代码与架构文档不保存真实密钥
- K8s 使用 Secret 注入环境变量

K8s 工作负载：

```text
Deployment airshelf-web
Deployment airshelf-api
Deployment airshelf-worker-default
Deployment airshelf-worker-ai
Deployment airshelf-worker-media
Deployment airshelf-beat
Service airshelf-web
Service airshelf-api
Ingress airshelf
Secret airshelf-env
ConfigMap airshelf-config
```

CI/CD 需要从当前纯静态部署升级为多镜像构建：

- web image
- api image
- worker image 可复用 api image，启动命令不同

---

## 12. 可观测性

日志：

- API request log
- AI provider request/response summary
- Celery task log
- billing ledger log
- export job log

指标：

- AI 任务成功率
- AI 平均耗时
- 视频段失败率
- 导出失败率
- 队列长度
- Worker 并发
- TOS 上传失败率
- 额度冻结未释放数量

告警：

- AI 任务连续失败
- 队列堆积
- 导出任务超时
- Billing hold 超时未释放
- Redis / MySQL 不可用

---

## 13. 安全与权限

权限模型：

- 超管：团队所有权限、充值、额度划拨、财务查看
- 团管：成员管理、成员额度分配、团队资产管理
- 成员：创建项目、使用额度、管理自己的项目

安全要求：

- 所有 API 必须按 team_id 做数据隔离
- 资产下载使用签名 URL
- 上传文件做类型、大小、时长校验
- 后台人工操作写审计
- ARK/TOS/Redis/MySQL 密钥只走环境变量
- JWT refresh token 需要轮换和黑名单

---

## 14. 关键风险与架构应对

| 风险 | 应对 |
| --- | --- |
| PRD 60s 与页面流程 15s 口径冲突 | 以 60s 多段为工程目标，页面文案后续统一 |
| AI 任务失败或超时 | AIJob 状态机 + Attempt + 重试 + 单段重跑 |
| 重复扣费 | BillingHold + 幂等 key + Redis lock + DB 唯一约束 |
| 外部模型并发不足 | 队列限流，单项目并发可降级 |
| TOS 文件失控增长 | tmp 前缀清理任务，资产软删除，引用检查 |
| 视频导出耗时长 | media worker 独立队列，任务进度入库 |
| 运营后台需求膨胀 | V1 先 Django Admin，后续再独立后台 |

---

## 15. 开发路线

### Phase 0：工程初始化

- 创建 Django 项目
- 配置 MySQL / Redis / Celery / TOS
- Dockerfile 与 K8s 基础部署
- 健康检查与环境变量管理

验收：

- API 可启动
- Worker 可启动
- 能连接 MySQL / Redis
- 能上传测试文件到 TOS

### Phase 1：业务地基

- 用户、团队、角色
- 商品库
- 项目
- 资产模型
- AIJob
- Billing 账本

验收：

- 注册自动建团队
- 商品 CRUD
- 项目创建
- 额度预检、冻结、释放、确认扣费可跑通

### Phase 2：AI 纵向闭环

- 脚本生成
- 基础资产生成
- 故事板生成
- 4 段视频生成
- 结果入 TOS 和资产库

验收：

- 一个 60s 项目可生成 4 个视频片段
- 单段失败可重跑
- 用户采用后扣费

### Phase 3：导出与前端联调

- FFmpeg 拼接
- 字幕
- BGM
- 1080P MP4 导出
- 前端接真实 API

验收：

- 4 段视频可导出成 60s 成片
- 成片入库
- 可下载、可预览

### Phase 4：运营后台与上线硬化

- Django Admin 增强
- 任务监控
- 财务对账
- 模型配置
- 日志告警
- 并发压测

验收：

- 运营能查任务、查用户、查流水、人工调整额度
- 失败任务可定位
- 队列堆积可观测

---

## 16. 最终判断

AirShelf 的架构核心不是“页面数量”，而是“AI 生产系统 + 账本系统 + 资产系统”的一致性。

正确的第一目标是：

> 用 Django + Celery + TOS + 火山 ARK 打穿真实 60s 多段视频生产闭环，并保证失败恢复和扣费一致性。

页面可以逐步接入，运营后台可以先用 Django Admin，但账本、任务状态机、资产引用和 AI Provider 必须从第一天按真实产品设计。