AirShelf/core/FEATURE_DEVELOPMENT_ALIGNMENT.md

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 轮仍失败，或外部服务/架构问题阻塞继续测试。

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

<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 来源：系统内置、用户上传、还是第三方库。
• 字幕样式默认模板数量。
• 成片是否加水印，测试环境和正式环境是否不同。
• 内容安全策略：由火山模型拦截、平台自审、还是两者结合。
• 导出文件保留周期和临时文件清理周期。