# AirShelf 功能开发对齐文档

> 版本：v0.3  
> 日期：2026-05-29  
> 目的：把 PRD、页面流程定稿、v1 原型、原版补充页面和后端架构统一成一份可开发、可验收、可排期的功能清单，避免实现时遗漏或误用过时逻辑。

## 1. 对齐源优先级

实现时按下面顺序判断，不一致时以上层为准：

| 优先级 | 来源 | 用途 |
| --- | --- | --- |
| 1 | `PRD.md` | 业务范围、V1/V2 边界、核心规则、验收目标 |
| 2 | `电商AI平台/页面流程定稿.md` | 页面流转、交互边界、阶段拆分、哪些能力不做 |
| 3 | `v1/*.html` | 当前核心原型，是在原版基础上的修改和增加；已覆盖页面以 v1 为准 |
| 4 | `电商AI平台/*.html` | 原版完整原型；用于补齐 v1 未覆盖页面、设计系统、登录注册、团队、设置和图片工具 |
| 5 | `core/ARCHITECTURE.md` | 后端架构、任务编排、额度、存储、部署策略 |
| 6 | `account.md` 与环境变量 | 测试资源与真实配置来源，不进入代码和公开文档 |

## 2. 当前必须统一的产品口径

| 口径 | 开发结论 |
| --- | --- |
| 后端技术 | Django + DRF + Celery，MySQL 持久化，Redis 做缓存/任务/锁，TOS 存储文件。 |
| AI 服务 | 全部接火山服务：对话、文生图/图生图、生视频、可能的脚本优化和素材理解。 |
| 60s 生成 | V1 真实实现 `4 x 15s` 多段视频，再进入 Stage5 拼接导出。每段独立任务、独立状态、独立重跑、独立额度记录。 |
| 项目新建 | 新建项目页只选商品和可选项目名。脚本来源、卖点、风格、时长等放到 Stage1。 |
| 分镜 | Stage3 是可选增强能力，不是生成视频的硬阻塞。无分镜时 Stage4 仍可用脚本和基础资产生成视频。 |
| 用户上传视频 | 不进入 Stage4。上传视频只作为 Stage5 的素材池，可用于替换、补位、剪辑和导出。 |
| 额度扣费 | 所有 AI 调用必须先预估、确认、冻结或记账；失败不实际扣费；成功落账可追溯。 |
| 运营后台 | V1 全量真实实现时必须有后台：用户/团队/项目/任务/资产/额度/账单/模型配置/异常重试。 |
| 原型取舍 | 已迁移到 `v1` 的页面以 `v1` 为准；`v1` 未覆盖的页面回看原版。复制项目、归档、批量生成、审核流、爆款复刻、直接发布等仍不进入 V1 主路径，除非 PRD 明确升级。 |

## 3. V1 功能总目标

V1 的目标不是只做静态界面，而是跑通一条真实可计费、可追踪、可运营的 AI 视频生产链路：

1. 用户注册并自动创建团队。
2. 团队管理员配置成员、月度额度、充值或分配额度。
3. 用户创建商品，维护商品图、卖点、品牌、类目等基础资料。
4. 用户基于商品创建项目。
5. 项目进入 5 阶段生产管线：脚本、基础资产、故事板、视频片段、拼接导出。
6. 真实调用火山模型完成脚本、图片、视频生产。
7. 60s 视频按 4 个 15s 段落并发/排队生成，支持失败重试和单段重跑。
8. Stage5 支持轻量剪辑、字幕、BGM、转场、导出 9:16 1080p MP4。
9. 所有产物自动入资产库，支持搜索、筛选、下载、复用。
10. 所有消耗进入额度账本，团队、成员、项目、任务都能追溯。
11. 运营后台可介入排障、补额度、重试任务、管理模型和查看成本。

## 4. 页面与功能地图

| 页面 | 原型文件 | 后端模块 | 优先级 | 必须实现 |
| --- | --- | --- | --- | --- |
| 登录/注册 | `电商AI平台/login.html`, `电商AI平台/register.html` | `accounts`, `teams` | P0 | 注册、登录、登出、创建团队、JWT/Session、基础权限。 |
| 工作台 | `v1/index.html` | `projects`, `billing`, `assets` | P1 | 项目概览、待处理、最近资产、额度摘要、快速入口。 |
| 商品库 | `v1/products.html` | `products` | P0 | 商品列表、搜索筛选、网格/列表、创建、编辑、删除、详情跳转。 |
| 商品创建 | `电商AI平台/product-create*.html` | `products`, `assets` | P0 | 图片上传、商品信息、卖点、类目、素材绑定、校验。 |
| 商品详情 | `电商AI平台/product-detail.html` | `products`, `assets`, `projects` | P1 | 商品资料、关联素材、关联项目、可编辑。 |
| 项目列表 | `v1/projects.html` | `projects`, `tasks` | P0 | 状态筛选、搜索、排序、项目卡片/列表、继续/查看/重试。 |
| 新建项目 | `v1/projects-new.html` | `projects`, `products` | P0 | 只选择商品与项目名，创建后进入 Stage1。 |
| 生产管线 | `v1/pipeline.html` | `projects`, `tasks`, `ai`, `assets`, `billing` | P0 | 5 阶段完整闭环，真实 AI 调用，状态机和任务编排。 |
| 资产库 | `v1/library.html` | `assets`, `storage` | P0 | 素材分类、搜索、筛选、上传、下载、删除、复用。 |
| 消费/账单 | `v1/account.html` | `billing`, `teams` | P0 | 余额、充值记录、项目账单、成员账单、额度规则、流水。 |
| 团队管理 | `电商AI平台/team.html` | `teams`, `accounts`, `billing` | P1 | 成员、角色、邀请、禁用、月度额度、权限矩阵。 |
| 运营后台 | 无独立静态原型，按 PRD 和架构补齐 | `ops`/Django Admin | P0 | 用户团队、任务、资产、账单、模型配置、失败重试、人工补偿。 |
| 设置/消息 | `电商AI平台/settings.html`, `电商AI平台/messages.html` | `accounts`, `notifications` | P2 | 账户设置、消息中心、通知状态。 |
| 图片工具 | `电商AI平台/asset-factory.html` 等 | `ai`, `assets` | P2 | 可作为后续独立工具，不影响主生产闭环。 |

## 5. P0 主生产闭环

### 5.1 账号与团队

前端需要：

- 注册页、登录页、登出入口。
- 当前用户信息、当前团队信息、当前角色展示。
- 未登录拦截，登录后回跳原目标页。
- 团队额度不足、权限不足、账号禁用等通用提示。

后端需要：

- 用户模型、团队模型、团队成员模型、角色权限。
- 注册时自动创建默认团队，并把注册用户设为团队管理员。
- 登录认证、刷新 token 或 session、密码重置预留。
- 权限中间件：团队隔离、角色能力、资源归属校验。

验收标准：

- 新用户注册后能进入工作台并拥有一个默认团队。
- 同一团队成员能看到团队资源，不同团队不能互相访问。
- 非管理员不能进行充值、成员额度配置、后台敏感操作。

### 5.2 商品库

前端需要：

- 商品列表：网格/列表切换、搜索、类目筛选、时间筛选、排序。
- 商品卡片：封面图、名称、类目、素材数量、关联视频数量、最近更新时间。
- 商品创建/编辑：商品图、标题、品牌、类目、卖点、规格、目标人群、备注。
- 图片上传：本地上传到 TOS，生成可预览 asset。
- 删除保护：有关联项目时给出风险提示。

后端需要：

- `Product`、`ProductImage`、`ProductSellingPoint` 等模型。
- 商品 CRUD API、筛选分页 API。
- TOS 上传签名或后端中转上传。
- 商品与资产、项目的关联关系。

验收标准：

- 商品能创建、编辑、查询、删除。
- 项目创建时只能选择当前团队可用商品。
- 商品图片能进入资产库，并可在 Stage2 作为商品基础资产使用。

### 5.3 项目列表与新建

前端需要：

- 项目列表 tabs：全部、进行中、生成中、已完成、失败。
- 项目搜索、筛选、排序。
- 项目卡片展示：9:16 封面、商品、当前阶段、5 阶段进度、状态、最近更新时间。
- 操作：继续、查看、失败重试。
- 新建项目只选择商品和可选项目名，不放脚本来源、风格、时长等高级配置。

后端需要：

- `Project`、`ProjectStageState`、`ProjectProgress`。
- 项目状态机：草稿、脚本中、资产中、分镜中、视频中、导出中、完成、失败。
- 项目创建 API、项目列表 API、项目详情 API、阶段推进 API。

验收标准：

- 从商品创建项目后进入 Stage1。
- 项目当前阶段和每阶段状态能准确回显。
- 失败项目能看到失败原因，并能按任务粒度重试。

### 5.4 Stage1 脚本

前端需要：

- 中区脚本/读秒分镜工作台。
- 右侧 AI 对话、历史版本。
- 底部 AI 输入框。
- 脚本来源入口：AI 帮我写、我有脚本、一句话生成、复刻爆款入口置灰或隐藏。
- 商品卖点选择在 Stage1 完成。
- 脚本版本：生成、编辑、保存、采用、回滚。

后端需要：

- `ScriptVersion`、`ScriptSegment`。
- 火山对话/文本模型适配器。
- Prompt 模板管理：商品信息、卖点、平台风格、时长目标、脚本结构。
- 脚本生成任务、脚本优化任务、版本记录。
- 消耗预估和账本记录。

验收标准：

- 可从商品信息生成脚本。
- 可手工粘贴脚本并结构化成多个段落。
- 可保存多个版本，采用一个版本进入 Stage2。
- AI 失败不扣费，并可重试。

### 5.5 Stage2 基础资产

前端需要：

- 三类资产顺序：商品、人物、场景。
- 商品资产：商品三联图为一张 16:9 图片，不拆成 3 个独立槽位。
- 人物资产：AI 提取人物、生成 4 张候选肖像、选择 1 张、生成 16:9 三联图、采用。
- 场景资产：生成 4 张候选场景图、选择 1 张、采用。
- 支持重跑、版本历史、采用、预览。
- 人物资产可选择保存到人物库。

后端需要：

- `BaseAssetGroup`、`AssetVersion`、`AssetSelection`。
- 火山生图/图生图模型适配器。
- 图片任务队列、并发限制、失败重试。
- 资产与项目阶段绑定。
- TOS 存储、缩略图、元数据。

验收标准：

- 三类基础资产都能真实生成并保存。
- 每次重跑保留历史，不覆盖已采用版本。
- Stage2 至少采用商品、人物、场景各一组后，可进入 Stage3 或跳过分镜进入 Stage4。

### 5.6 Stage3 故事板

前端需要：

- 故事板为可选阶段。
- 支持按脚本段落生成故事板图。
- Prompt 可编辑，但不做复杂聊天。
- 显示绑定资产标签：商品、人物、场景。
- 当基础资产变更时，提示建议重新生成故事板。
- 支持跳过故事板直接进入 Stage4。

后端需要：

- `StoryboardVersion`、`StoryboardFrame`。
- 脚本段落到故事板帧的映射。
- 火山图片模型任务。
- 故事板版本、采用、重跑。

验收标准：

- 有故事板时，Stage4 默认使用故事板作为视频生成参考。
- 无故事板时，Stage4 能基于脚本和基础资产生成视频。
- 重跑故事板不影响已采用的视频片段，除非用户主动重新生成视频。

### 5.7 Stage4 视频片段

前端需要：

- 展示 4 个 15s 片段槽位，对应 60s 总视频。
- 每段显示状态：未开始、排队、生成中、成功、失败、已采用。
- 每段可编辑 prompt、生成、重跑、查看历史、采用。
- 支持并发生成，但前端必须展示每段独立进度。
- 单次生成一个候选视频，历史版本中保留多次结果。
- 用户上传视频不出现在 Stage4。

后端需要：

- `VideoSegment`、`VideoSegmentVersion`。
- 火山生视频模型适配器。
- Celery 任务：提交、轮询、下载、转存 TOS、回调处理。
- 任务幂等：同一段重试不产生重复扣费。
- 并发控制：团队级、用户级、模型级、全局级。
- 失败原因标准化：额度、模型、超时、内容安全、存储、未知。

验收标准：

- 60s 视频能由 4 段 15s 视频构成。
- 某一段失败时，不影响其他已成功段；可单段重跑。
- 每段成功后自动入资产库，并能被 Stage5 使用。
- 模型失败不实际扣费；模型成功但后处理失败要进入可补偿状态。

### 5.8 Stage5 拼接导出

前端需要：

- 轻量剪辑器：素材池、主轨道、字幕、BGM、转场、预览、导出。
- 素材池包含 AI 视频片段、用户上传视频、资产库视频。
- 单主轨，支持自动放置、拖拽排序、删除、替换、裁剪。
- 支持从脚本生成字幕，并允许编辑样式和文本。
- 支持 BGM 选择、音量设置。
- 导出结果页：预览、下载、复制链接、查看资产、继续编辑、返回项目。

后端需要：

- `Timeline`、`TimelineClip`、`SubtitleTrack`、`BgmTrack`、`ExportJob`。
- FFmpeg 拼接、转码、字幕烧录或外挂字幕策略。
- 输出规格：9:16、1080p、MP4。
- 导出任务队列、进度、失败重试。
- 导出文件转存 TOS，生成资产库记录。

验收标准：

- 4 段视频能拼接成一个 60s 成片。
- 用户上传素材能加入 Stage5 并参与导出。
- 导出成功后自动进入资产库的成片分类。
- 导出失败能保留 timeline 并允许重试。

## 6. P0 额度与账本

前端需要：

- 生成前显示本次预估消耗和账户余额。
- 额度不足时阻止提交，并给管理员充值或申请额度入口。
- 账单页按项目、成员、账单维度查看消耗。
- 团队页可配置成员月度额度。

后端需要：

- 四层额度：团队余额、成员月度额度、项目预算、单任务预估/实扣。
- `CreditAccount`、`CreditLedger`、`QuotaPolicy`、`CreditReservation`。
- 账本必须只追加，不直接覆盖历史。
- 支持预估、冻结、成功扣费、失败释放、人工调整。
- 每条账本关联：团队、用户、项目、任务、模型、输入输出资产。

验收标准：

- 所有 AI 与导出任务都有账本记录。
- 失败任务不会消耗最终余额。
- 管理员能看到团队、成员、项目三个维度的消耗。
- 后台人工补偿、充值、扣减都可追溯。

## 7. P0 资产库与存储

前端需要：

- Tabs：人物、场景、商品图、成片、我的上传、未分类。
- 搜索、类型筛选、来源筛选、排序。
- 上传素材、预览、下载、删除。
- 在项目中复用资产。

后端需要：

- `Asset`、`AssetFile`、`AssetTag`、`AssetUsage`。
- 文件类型：image、video、audio、subtitle、document。
- 来源：upload、ai_generated、exported、system。
- TOS object key、bucket、content type、size、duration、resolution、checksum。
- 缩略图、预览地址、临时下载链接。

验收标准：

- AI 生成图、视频片段、最终成片都自动入库。
- 用户上传文件可用于 Stage5。
- 资产被项目使用时有使用记录，删除时能提示风险。

## 8. P0 运营后台

运营后台可以先基于 Django Admin 扩展，后续再做独立后台页面。V1 全量真实 AI 必须具备这些能力：

| 模块 | 必须能力 |
| --- | --- |
| 用户与团队 | 查询、禁用、角色、团队归属、成员额度。 |
| 商品与项目 | 查询、状态查看、异常项目定位。 |
| AI 任务 | 查看入参摘要、模型、状态、耗时、失败原因、重试、取消。 |
| 资产 | 查看文件、归属、来源、TOS key、可用性检查。 |
| 账本 | 充值、扣费、释放、人工补偿、流水审计。 |
| 模型配置 | 模型 endpoint、能力类型、单价、限流、开关、降级策略。 |
| 系统配置 | Prompt 模板、BGM 库、字幕样式、导出参数。 |

验收标准：

- 任一用户反馈“生成失败”时，运营能在后台定位到项目、阶段、任务、模型错误和账本状态。
- 后台能安全重试任务，不产生重复扣费。
- 模型临时不可用时能关闭入口或切换备用配置。

## 9. 状态机与任务状态

项目阶段状态：

| 状态 | 含义 |
| --- | --- |
| `not_started` | 还未进入阶段。 |
| `draft` | 有编辑内容，但未确认提交。 |
| `queued` | 已进入队列。 |
| `running` | 正在执行。 |
| `succeeded` | 当前阶段已完成。 |
| `failed` | 当前阶段失败，可查看原因。 |
| `skipped` | 用户主动跳过，比如 Stage3。 |
| `needs_review` | 任务成功但需要用户选择或确认采用。 |

AI 任务状态：

| 状态 | 含义 |
| --- | --- |
| `created` | 任务已创建但未扣/未冻结。 |
| `reserved` | 已冻结或记录预估额度。 |
| `submitted` | 已提交火山。 |
| `polling` | 等待火山结果。 |
| `postprocessing` | 下载、转存、转码、生成缩略图。 |
| `succeeded` | 完成并落资产。 |
| `failed` | 失败并释放额度。 |
| `compensating` | 外部成功但本地后处理失败，需要补偿。 |
| `cancelled` | 用户或系统取消。 |

状态要求：

- 前端所有按钮必须根据状态禁用或显示正确动作。
- 后端所有阶段推进必须校验前置条件。
- Celery 任务必须幂等，重复执行不会重复创建资产或重复扣费。

## 10. API 开发清单

建议先按下面 API 分组开发，保证前后端可以并行：

| 分组 | API 能力 |
| --- | --- |
| Auth | 注册、登录、登出、当前用户、当前团队。 |
| Team | 团队详情、成员列表、邀请、禁用、角色、月度额度。 |
| Product | 商品 CRUD、图片上传、卖点、详情、关联项目。 |
| Project | 项目 CRUD、列表筛选、详情、阶段状态、失败重试。 |
| Script | 生成脚本、优化脚本、保存版本、采用版本。 |
| Base Assets | 生成商品图/人物/场景、候选列表、采用、重跑。 |
| Storyboard | 生成故事板、编辑 prompt、采用、跳过。 |
| Video | 生成片段、查询进度、重跑、采用、历史版本。 |
| Timeline | 素材池、轨道、字幕、BGM、保存 timeline。 |
| Export | 提交导出、查询进度、下载、复制链接、重试。 |
| Asset | 资产列表、筛选、上传、预览、下载、删除、复用。 |
| Billing | 余额、预估、确认、流水、账单筛选、人工调整。 |
| Ops | 任务查询、模型配置、重试、补偿、系统配置。 |

## 11. 数据模型开发清单

P0 最小模型集合：

- `User`
- `Team`
- `TeamMember`
- `Role`
- `Product`
- `ProductImage`
- `ProductSellingPoint`
- `Project`
- `ProjectStage`
- `ScriptVersion`
- `ScriptSegment`
- `Asset`
- `AssetFile`
- `AssetUsage`
- `BaseAssetGroup`
- `StoryboardVersion`
- `StoryboardFrame`
- `VideoSegment`
- `VideoSegmentVersion`
- `Timeline`
- `TimelineClip`
- `SubtitleTrack`
- `BgmTrack`
- `ExportJob`
- `AITask`
- `ModelProvider`
- `ModelConfig`
- `CreditAccount`
- `CreditLedger`
- `CreditReservation`
- `QuotaPolicy`

关键约束：

- 所有业务表必须带 `team_id`，必要时带 `created_by`。
- 所有 AI 产物必须能追溯到 `project_id`、`task_id`、`model_config_id`。
- 所有费用必须通过账本记录，不直接修改余额后丢失原因。
- 所有 TOS 文件必须有资产记录或临时文件清理机制。

## 12. 前端实现清单

前端不应该直接复制静态 HTML，而应该抽象为真实组件：

正式产品入口必须是 React History 路由，不使用 `*.html` 作为业务页面地址。当前 `/exact/*.html` 的用途是保存设计稿镜像、跑像素级视觉回归和子页面校对；真实页面使用 `/login`、`/register`、`/dashboard`、`/products`、`/products/new`、`/products/:id`、`/projects`、`/projects/new`、`/pipeline/:id` 等 React 路由。

| 组件/区域 | 开发要求 |
| --- | --- |
| App Shell | 顶部/侧边导航、当前团队、用户菜单、未读消息、额度提示。 |
| Resource Picker | 商品选择、资产选择、项目素材选择复用同一交互。 |
| Stage Stepper | 5 阶段进度，支持点击已完成阶段回看。 |
| Task Progress | 轮询任务状态，显示排队、进度、失败原因、重试。 |
| Version Panel | 脚本、图片、故事板、视频都复用版本历史/采用模式。 |
| Quota Modal | 生成前统一确认额度，不在每个页面重复造逻辑。 |
| Upload Widget | 图片/视频/音频上传到 TOS，支持进度和失败重试。 |
| Asset Card | 资产预览、类型、来源、下载、删除、复用。 |
| Timeline Editor | Stage5 主轨、素材池、字幕、BGM、导出。 |
| Empty/Error States | 首次使用、无数据、额度不足、模型失败、网络失败。 |

原型差异注意：

- 已迁移到 `v1` 的页面，视觉与信息层级优先参考 `v1`。
- `v1` 未覆盖的登录注册、商品详情、团队、设置、消息、图片工具等，参考 `电商AI平台` 原版页面补齐。
- 如果 `v1/projects-new.html` 仍保留旧的多步配置，开发时按页面流程定稿收敛，只保留商品和项目名。
- 复制、归档、批量、审核流等非 V1 主路径能力，不因原型里出现就默认开发。
- `pipeline.html` 的视觉和结构可参考，但真实实现必须以 API 状态为准。
- 图片工具页可以复用模型能力，但不能阻塞主生产链路。

## 13. 后端实现清单

后端优先级：

1. Django 项目基础、环境配置、MySQL、Redis、Celery、TOS、日志。
2. 账号、团队、权限、商品、资产、项目基础模型和 API。
3. 额度账本与任务系统先落地，再接火山模型。
4. 火山模型适配层：文本、图片、视频统一接口，支持模型配置化。
5. 生产管线状态机：Stage1 到 Stage5 的前置校验、推进和回滚。
6. Celery 异步任务：AI 提交/轮询/转存/后处理/账本落账。
7. Stage5 FFmpeg 导出服务。
8. Django Admin 运营后台增强。
9. 审计日志、告警、失败补偿、清理任务。

企业级要求：

- AI 调用不能写死模型名和价格，必须走 `ModelConfig`。
- 任务必须幂等，支持重试、取消和补偿。
- 额度扣费和任务成功必须在事务边界内保持一致。
- TOS 转存成功但数据库失败时，要有补偿或清理。
- 所有后台操作必须有审计日志。
- 所有外部 API key 只从环境变量读取。

## 14. 验收矩阵

| 编号 | 验收项 | 结果要求 |
| --- | --- | --- |
| A01 | 注册登录 | 新用户注册后自动创建团队并进入工作台。 |
| A02 | 商品创建 | 可上传商品图、填写信息、保存并在商品库搜索到。 |
| A03 | 项目创建 | 选择商品后创建项目，进入 Stage1。 |
| A04 | 脚本生成 | 调火山文本模型生成脚本，支持保存版本和采用。 |
| A05 | 基础资产 | 商品、人物、场景三类资产真实生成并采用。 |
| A06 | 故事板 | 可生成、采用、跳过，跳过不阻塞视频生成。 |
| A07 | 60s 视频 | 生成 4 个 15s 片段，支持单段失败重试。 |
| A08 | 拼接导出 | 4 段视频导出为 9:16 1080p MP4。 |
| A09 | 资产入库 | AI 图片、视频片段、成片自动进入资产库。 |
| A10 | 上传素材 | 用户上传视频能进入 Stage5 并参与导出。 |
| A11 | 额度预估 | 每次 AI 生成前展示预估消耗并校验余额。 |
| A12 | 失败不扣费 | 模型失败、超时、内容拦截时不最终扣费。 |
| A13 | 账单追溯 | 能按团队、成员、项目、任务查看费用流水。 |
| A14 | 后台排障 | 后台能查任务失败原因并安全重试。 |
| A15 | 团队隔离 | 不同团队无法访问彼此商品、项目、资产和账单。 |

## 15. 首轮开发建议

为了最快证明系统可行，建议第一轮只做一条“真实最小闭环”，但所有核心架构都按全量方案预留：

1. 登录/注册、团队、商品、资产、项目基础。
2. Stage1 真实脚本生成。
3. Stage2 真实生成一组商品/人物/场景基础资产。
4. Stage4 真实生成 1 个 15s 视频片段。
5. Stage5 用 1 个片段导出 MP4。
6. 额度账本贯穿上述每一步。
7. 运营后台能查看和重试任务。

第二轮扩展到完整 60s：

1. Stage4 扩展为 4 个片段并行/排队生成。
2. Stage5 拼接 4 段并支持字幕、BGM、转场。
3. 补齐 Stage3 故事板。
4. 补齐项目列表、账单页、团队管理、资产库高级筛选。

## 16. 开发完成后的真实数据测试计划

本节参考 `/Users/maidong/Desktop/zyc/github/AI-Express/项目角色agent/test-agent.md` 的测试 Agent 规范，并结合 AirShelf 的真实 AI、额度、TOS、Celery 异步任务场景做项目化落地。

开发完成后的验收不能只看接口和页面静态效果，必须用测试环境真实资源、真实数据、真实浏览器点击，把主流程跑穿。这里的“真实”指：

- 使用测试 MySQL、Redis、TOS、火山模型，不用 mock 代替核心外部依赖。
- 用 Playwright 或同类工具启动真实浏览器，按用户视角点击、输入、上传、等待和下载。
- 每次测试生成独立 `run_id`，数据库记录、TOS object key、日志、账本、任务都能追踪到同一轮测试。
- 测试脚本不能直接调用业务 API 把项目状态改到下一步；只允许用 seed/cleanup 脚本准备和清理测试数据。

### 16.0 测试 Agent 执行规范

测试执行时按代码测试、浏览器实操、真实端到端、浏览器真实模拟、测试报告五层推进：

| 层级 | 名称 | 目标 | AirShelf 要求 |
| --- | --- | --- | --- |
| A | 代码层测试 | 验证后端、前端、任务代码基本正确。 | Django/DRF 单元测试、API 测试、Celery 任务测试、前端组件测试。 |
| B | 浏览器实操 | 打开真实页面，点击、输入、hover、拖拽、移动端检查。 | 每次关键操作后检查 console error/warning 并截图。 |
| D | 真实端到端 | 验证真实环境和真实数据流通。 | MySQL、Redis、TOS、火山模型、FFmpeg、Celery 全部接真实测试资源。 |
| E | Playwright 真实模拟 | 验证用户在浏览器里实际看到和操作的结果。 | 禁止 mock API；用真实账号、真实商品、真实上传、真实 AI 结果。 |
| C | 测试报告 | 输出可复查证据和 Bug 清单。 | 没有截图、trace、控制台日志、任务 ID 和账本 ID 的结论不算通过。 |

执行硬规则：

- 代码测试通过不等于测试完成；必须有 Playwright 浏览器截图验证。
- 每次点击、输入、提交、状态切换后都要检查控制台错误。
- 截图必须人工或视觉模型审查，不能只判断 DOM 存在。
- 初始判定默认是 `NEEDS WORK`，只有证据充分才给 `PASS`。
- 报告里如果声称 0 问题，需要追加一轮复测。
- P0 Bug 发现后立即反馈开发修复，不等全量测试跑完。
- 同一个模块最多测试 3 轮；第 3 轮仍失败则进入升级处理。

本机执行建议：

- 优先复用全局 Playwright CLI，不要重复项目级安装。
- 跑测试前先确认 `playwright --version` 和浏览器驱动是否存在。
- 缺浏览器驱动时只安装必需浏览器，优先 `chromium`。
- 可回归测试写成 Playwright spec；探索性排查可用 Playwright MCP 或交互式工具。

### 16.1 测试环境要求

| 类型 | 要求 |
| --- | --- |
| 数据库 | 使用 `account.md` 中的测试 MySQL 配置，单独测试库或测试 schema。 |
| Redis | 使用测试 Redis，按正式 DB index 规划区分 cache、Celery broker、result backend、lock。 |
| TOS | 使用测试 bucket 或测试前缀，例如 `e2e/{run_id}/...`，测试结束可清理。 |
| 火山模型 | 使用真实 ARK/生图/生视频配置，模型名、endpoint、价格来自 `ModelConfig`。 |
| Worker | Celery worker、Celery beat、FFmpeg、回调或轮询任务必须真实启动。 |
| 前端 | 使用接近正式构建的前端产物，不用开发模式里的假数据。 |
| 日志 | 后端日志、Celery 日志、浏览器 trace、截图、视频、导出文件都要保留到测试报告。 |

### 16.2 真实测试数据

每轮 E2E 测试用 seed 脚本准备下面数据：

| 数据 | 内容 |
| --- | --- |
| 测试团队 | `E2E Team {run_id}`，包含 owner、member、no_quota_user、disabled_user。 |
| 测试额度 | owner 有足够额度；member 有月度额度；no_quota_user 额度为 0。 |
| 测试商品 | 至少 3 个真实商品样例：护肤品、小家电、服饰；每个包含真实商品图、标题、品牌、类目、卖点。 |
| 测试素材 | 上传 1 个短视频、1 张商品图、1 张场景图、1 个 BGM 样例。 |
| 模型配置 | 文本、图片、视频、导出任务均有启用状态、单价、限流和能力类型。 |
| 管理员账号 | 可登录 Django Admin 或运营后台，验证任务、账本和补偿。 |

测试数据要求：

- 商品图片和上传视频必须是真文件，能上传到 TOS 并回显预览。
- 商品标题、卖点、脚本输入要覆盖中文、数字、标点和较长文本。
- 所有 seed 数据带 `run_id`，避免和人工测试数据混在一起。

### 16.3 浏览器 E2E 主流程

这些用例必须通过真实浏览器点击完成：

| 编号 | 场景 | 浏览器动作 | 验收结果 |
| --- | --- | --- | --- |
| E01 | 注册登录 | 打开注册页，填写账号，提交，进入工作台。 | 自动创建团队，导航和当前用户信息正确。 |
| E02 | 创建商品 | 进入商品库，点击新建，上传商品图，填写信息并保存。 | 商品出现在商品库，图片可预览，数据库和 TOS 有记录。 |
| E03 | 创建项目 | 从项目列表点击新建，选择商品，填写项目名，提交。 | 创建项目并进入 Stage1，项目绑定正确商品。 |
| E04 | 生成脚本 | 在 Stage1 选择卖点，输入需求，点击 AI 生成，采用脚本版本。 | 真实调用文本模型，脚本版本落库，账本有预估和实扣。 |
| E05 | 生成基础资产 | 在 Stage2 依次生成商品、人物、场景资产，选择候选并采用。 | 真实生成图片，TOS 有文件，资产库有记录，项目阶段可推进。 |
| E06 | 故事板 | Stage3 生成故事板并采用；另跑一条项目验证跳过故事板。 | 生成和跳过两条路径都能进入 Stage4。 |
| E07 | 生成 60s 视频 | Stage4 点击生成 4 个 15s 片段，等待完成，失败段单独重试。 | 4 段视频独立状态正确，成功片段入库，失败不扣最终费用。 |
| E08 | 拼接导出 | Stage5 自动放置片段，上传额外视频，添加字幕/BGM，点击导出。 | 导出 9:16 1080p MP4，能预览、下载、复制链接。 |
| E09 | 资产回查 | 进入资产库，按成片/视频/图片筛选，搜索本轮项目名。 | AI 产物、上传素材、最终成片都能找到并下载。 |
| E10 | 账单回查 | 进入消费页，按项目和成员筛选本轮流水。 | 每个 AI 任务和导出任务都有账本记录，余额变化正确。 |
| E11 | 团队权限 | 用 member、no_quota_user、disabled_user 分别登录访问同一流程。 | 权限、额度不足、账号禁用提示正确，不能越权。 |
| E12 | 运营后台 | 管理员打开后台，搜索本轮项目和任务，查看日志并触发安全重试。 | 能定位任务、资产、账本，重试不会重复扣费。 |

浏览器测试规则：

- 使用 Chromium 作为必跑浏览器；上线前增加 WebKit/Safari 兼容验证。
- 桌面视口必跑，移动视口至少覆盖项目列表、生产管线、资产库、账单页。
- 每次关键操作后检查 console error/warning。
- 每个关键阶段保存截图；失败时保存 Playwright trace、console log、network log。
- 截图中出现空白、错位、遮挡、placeholder 数据、异常报错，一律判失败。
- 长任务要通过 UI 轮询等待，不允许测试脚本直接改数据库状态。
- 下载的最终 MP4 要用 `ffprobe` 校验分辨率、时长、编码和文件大小。

### 16.4 异步任务与失败恢复测试

必须单独测试这些异常路径：

| 场景 | 验收要求 |
| --- | --- |
| 火山文本失败 | Stage1 显示失败原因，账本释放，支持重试。 |
| 图片生成超时 | Stage2 单项失败不污染已采用资产，支持重跑。 |
| 视频单段失败 | Stage4 只重跑失败段，其他段保持成功状态。 |
| TOS 转存失败 | 任务进入 `compensating` 或 `failed`，后台可补偿处理。 |
| Celery worker 重启 | 已提交任务能继续轮询或恢复，不能重复扣费。 |
| Redis 锁过期 | 同一任务重复提交时保持幂等。 |
| 导出失败 | Timeline 保存不丢失，用户可重新导出。 |
| 额度不足 | 前端阻止提交，后台没有创建实际 AI 任务。 |

### 16.5 账本一致性测试

每轮 E2E 完成后必须自动核对：

- 团队余额 = 初始余额 + 充值/调整 - 成功任务实扣。
- `CreditLedger` 每条流水都有 team、user、project、task、model 或 export job。
- 失败任务没有最终扣费；如果有冻结记录，必须有释放记录。
- 重试任务不能重复扣同一次失败费用。
- 后台人工补偿必须产生审计日志。
- 页面展示余额、数据库余额、账本汇总三者一致。

### 16.6 文件与成片质量测试

每个生成文件都要校验：

- TOS object 存在，content type 正确，文件大小大于 0。
- 图片能打开，缩略图能显示。
- 视频片段能播放，时长接近 15s。
- 最终成片为 9:16、1080p、MP4，60s 成片时长允许合理浮动。
- 下载链接有过期时间，不暴露永久私有地址。
- 删除测试数据后，TOS 测试前缀可被清理，不留下大量临时文件。

### 16.7 发布前测试门禁

进入正式部署前，必须满足：

- P0 浏览器 E2E 全部通过。
- P0 API 集成测试全部通过。
- 账本一致性核对为 0 差异。
- 没有 `compensating`、`running`、`reserved` 状态的遗留测试任务。
- TOS 没有孤儿文件，或孤儿文件已进入清理队列。
- 后台可查到本轮测试的项目、任务、资产、账本和导出记录。
- 测试报告包含：run_id、测试账号、项目 ID、任务 ID、账本 ID、导出文件地址、截图和失败 trace。

### 16.8 测试报告与交接格式

每轮测试必须产出可追溯报告，建议目录：

- `test-reports/{run_id}/summary.md`
- `test-reports/{run_id}/screenshots/`
- `test-reports/{run_id}/traces/`
- `test-reports/{run_id}/videos/`
- `test-reports/{run_id}/logs/`

报告必须包含：

| 模块 | 内容 |
| --- | --- |
| 测试概览 | run_id、环境、前端版本、后端版本、测试账号、测试时间。 |
| 数据策略 | 全真实、真实+seed、mock 降级；必须说明原因。 |
| 服务状态 | 前端、后端、MySQL、Redis、Celery、TOS、火山模型、FFmpeg。 |
| 用例结果 | E01-E12 每一步的通过/失败、截图、任务 ID、账本 ID。 |
| 控制台错误 | 页面、操作、错误内容、严重度、截图。 |
| 网络/API 错误 | URL、状态码、响应摘要、复现步骤。 |
| Bug 清单 | 严重度、描述、定位、复现步骤、截图或 trace。 |
| 账本核对 | 初始余额、预估、冻结、实扣、释放、最终余额。 |
| 文件核对 | TOS key、文件大小、content type、视频时长、分辨率。 |
| 结论 | `QA PASS`、`QA FAIL`、`INCOMPLETE` 或 `ESCALATION`。 |

判定标准：

- `QA PASS`：P0/P1 全部通过，账本 0 差异，浏览器截图和 trace 证据完整。
- `QA FAIL`：存在阻塞 Bug，必须带复现步骤和证据返回开发。
- `INCOMPLETE`：环境未跑通、缺截图、缺真实数据、或跳过浏览器测试。
- `ESCALATION`：同一模块第 3 轮仍失败，或外部服务/架构问题阻塞继续测试。

交接给开发时，最后必须附结构化摘要：

```xml
<task-completion>
<status>completed | partial | failed</status>
<summary>一句话说明本轮测试结论</summary>
<deliverables>
- summary.md: done | partial | skipped
- screenshots: done | partial | skipped
- traces: done | partial | skipped
</deliverables>
<self-check-results>
- [x] 真实浏览器点击: PASS
- [x] 控制台错误检查: PASS
- [x] 真实数据验证: PASS
- [x] 账本一致性核对: PASS
</self-check-results>
<escalations>无，或列出需要上报的问题</escalations>
</task-completion>
```

## 17. 待确认项

这些项不阻塞开发，但进入正式计费和对外交付前需要确认：

- 火山各模型的正式 endpoint、并发限制、回调能力、计费口径。
- 60s 视频默认脚本分段策略：固定 4 段，还是按脚本语义自动切 4 段。
- 失败重试的免费次数和计费边界。
- BGM 来源：系统内置、用户上传、还是第三方库。
- 字幕样式默认模板数量。
- 成片是否加水印，测试环境和正式环境是否不同。
- 内容安全策略：由火山模型拦截、平台自审、还是两者结合。
- 导出文件保留周期和临时文件清理周期。