智影工场：基于 Vue3 + FastAPI 的电商 AI 视频素材工厂项目

适合发布平台：CSDN
项目类型：全栈 Web 应用 / AI 应用工程化 / 电商运营工具
技术栈：Vue 3、Vite、Pinia、FastAPI、SQLAlchemy Async、Pydantic、SQLite/MySQL、Playwright、FFmpeg、AI 视频生成 Provider

---

一、项目背景

随着短视频电商的发展，商品视频、投流素材、主图视频已经成为电商运营中非常重要的一环。对中小卖家和运营团队来说，视频素材的需求有几个明显特点：

• 需求量大：同一个商品往往需要多条不同角度、不同脚本、不同尺寸的视频。
• 更新频繁：投放素材容易疲劳，需要持续迭代。
• 成本敏感：完全依赖人工剪辑，时间成本和人力成本都较高。
• 审核复杂：电商平台对极限词、虚假宣传、价格表达、画面内容都有审核要求。
• 多平台适配：抖音、淘宝、拼多多等平台常用视频比例和内容风格不完全一致。

因此，本项目的目标不是做一个通用剪辑器，而是做一个面向电商运营的 AI 视频素材生产后台：用户输入商品信息后，系统可以完成商品建档、脚本生成、视频任务创建、素材入库、预览下载和历史管理。

项目最终命名为 智影工场，可以理解为一个“电商 AI 视频素材工厂”。

---

二、项目定位与 MVP 目标

项目最开始的规划比较完整，包含商品一键成片、多脚本工厂、过审预检、热点追拍、AI 数字人、素材管理、平台投放对接等能力。

但在实际开发时，如果一开始就按完整商业化 SaaS 来做，范围会非常大。因此我将项目收敛为一个可落地的 MVP：

登录/注册
-> 商品链接解析或手动建档
-> 商品图片与卖点整理
-> 多策略脚本生成与保存
-> 提交视频生成任务
-> 查看任务状态
-> 素材管理中预览、下载、打包

本期更关注“流程闭环”和“数据真实入库”，而不是一开始就追求完整的投放后台、支付体系或企业协作系统。

MVP 成功标准主要包括：

• 用户可以注册、登录并保持会话。
• 用户可以通过链接解析或手动输入创建商品档案。
• 用户可以基于商品生成多种策略脚本。
• 用户可以保存脚本并复用。
• 用户可以提交视频生成任务并查看进度。
• 生成结果可以进入素材库。
• 素材支持列表查看、详情查看、MP4 导出、交付包下载。
• 用户中心可以展示套餐和使用量。

---

三、技术选型

1. 前端

前端采用：

• Vue 3
• Vite
• TypeScript
• Pinia
• Vue Router

选择 Vue 3 + Vite 的原因是启动速度快，适合中小型后台快速迭代。Pinia 用于管理登录会话、生成流程中的商品、脚本、任务状态等数据。

前端主要页面包括：

• 登录注册页
• 工作台
• 视频生成页
• 素材管理页
• 热点追拍页
• 平台连接页
• 用户中心

2. 后端

后端采用：

• FastAPI
• SQLAlchemy Async
• Pydantic v2
• JWT 登录认证
• 本地 SQLite 开发环境 / MySQL 生产环境预留

FastAPI 的优势是接口开发效率高，类型提示清晰，自动生成 OpenAPI 文档，比较适合这类前后端分离项目。

3. 数据与文件

项目中的核心数据对象包括：

• User：用户账户和套餐额度
• Product：商品档案
• Script：脚本文案
• GenerationTask：生成任务
• Video：生成后的视频素材
• Hotspot：热点选题
• PlatformConnection：平台连接配置

文件层面，当前版本使用项目本地的 runtime 目录保存上传图片、封面、视频和交付包。后续如果正式上线，可以迁移到 OSS 或其他对象存储。

4. AI Provider 思路

项目没有把某一家 AI 供应商逻辑写死在接口层，而是尽量放到 services 层。

当前视频生成链路已经预留了 Provider 字段，例如：

• provider_name
• provider_job_id
• stage_code
• orchestration_notes

这样后续无论接入通义万相、可灵、数字人服务，还是企业内部渲染服务，都可以在服务层替换，而不需要重写前端主流程。

---

四、系统架构

整体架构可以分为四层：

前端页面层
  ├─ 登录注册
  ├─ 工作台
  ├─ 视频生成
  ├─ 素材管理
  ├─ 热点追拍
  └─ 用户中心

API 接口层
  ├─ auth
  ├─ product
  ├─ script
  ├─ video
  ├─ hotspot
  ├─ user
  ├─ plan
  └─ platform-connection

业务服务层
  ├─ 商品解析
  ├─ 脚本生成
  ├─ 视频任务编排
  ├─ 过审预检
  ├─ 素材文件管理
  └─ 热点同步

数据与运行时层
  ├─ SQLite / MySQL
  ├─ runtime-assets
  ├─ 本地交付文件
  └─ 后续 OSS/CDN

核心业务链路如下：

商品输入
  -> 商品结构化
  -> 脚本生成
  -> 审核预检
  -> 视频任务
  -> 生成结果入库
  -> 素材管理
  -> 下载交付

---

五、核心模块实现

1. 用户登录与会话管理

用户模块主要完成注册、密码登录、短信登录、JWT token 保存和用户资料加载。

前端在登录成功后将 token 保存到 sessionStorage，之后所有业务请求都会自动带上：

Authorization: Bearer ${token}

后端通过依赖注入获取当前用户，所有业务接口都必须校验用户归属，避免用户访问到别人的商品、脚本或素材。

2. 商品建档

商品建档支持两种方式：

• 粘贴商品链接解析
• 手动输入商品信息

商品字段包括：

• 标题
• 品牌
• 类目
• 价格
• 原价
• 卖点
• 商品图片
• 目标人群
• 来源链接

商品解析采用“官方接口优先、页面状态兜底、浏览器抓取降级、手动补全兜底”的思路。遇到淘宝、京东、拼多多等平台的验证码或登录页时，系统不会强行绕过，而是提示用户配置 Cookie 或改用手动建档。

3. 脚本生成与保存

脚本模块支持多种策略：

• 智能组合
• 痛点切入
• 卖点转化
• 场景种草
• 对比表达
• 促销冲单

每条脚本包含：

• 标题
• Hook
• 正文
• CTA
• 完整口播
• 分镜
• 预计时长
• 生成说明

生成脚本后，用户可以保存入库。保存后的脚本可以在后续生成流程中复用为自定义口播，这对电商运营很重要，因为同一个商品往往会多次复盘和二次生成。

4. 视频生成任务

视频生成不是同步阻塞接口，而是先创建任务：

POST /api/v1/video/generate

接口会返回 task_id，前端再轮询：

GET /api/v1/video/status/{task_id}

任务状态包括：

• queued：已提交
• processing：处理中
• completed：已完成
• failed：失败

后端在任务执行过程中会更新：

• 进度百分比
• 当前阶段
• Provider 信息
• 生成结果视频 ID
• 错误信息

这样前端不需要关心具体 AI 供应商是同步接口、异步 job，还是本地生成，只需要围绕任务状态展示即可。

5. 素材管理

素材管理是项目的交付终点。

素材页支持：

• 视频列表
• 素材详情
• 封面预览
• 视频预览
• 脚本文案查看
• 分镜查看
• 审核风险查看
• MP4 导出
• 交付包下载
• 相似度检测

素材列表接口为：

GET /api/v1/video/list

素材详情接口为：

GET /api/v1/video/{id}

交付包下载会将视频、封面引用、脚本、商品信息、审核报告、发布建议等内容打包成 zip，方便运营归档和团队交接。

6. 热点追拍

热点模块的定位不是独立复杂玩法，而是给生成链路提供热点输入。

用户可以在热点页选择一个热点，将热点名称、建议策略和商品结合起来，再带回生成页创建视频任务。

热点数据当前支持种子数据和外部同步配置，后续可以对接抖音开放平台或其他榜单数据。

7. 用户中心与套餐额度

用户中心展示：

• 当前套餐
• 每日生成额度
• 今日已生成
• 本月完成数量
• 累计素材数量

视频生成接口会检查每日额度，超过限制时返回 429，避免用户无限制提交任务。

---

六、项目开发流程

我在完成项目时，大致按下面的顺序推进：

1. 先梳理 PRD，收敛 MVP 范围

原始项目设想比较大，包括商业化 SaaS、投放回流、竞品监控、API 开放平台等。如果直接全部做，开发周期会不可控。

所以我先把功能分成：

• P0：必须完成的主链路
• P1：增强体验的能力
• 后续版本：商业化和生产化能力

最终优先保证：

商品 -> 脚本 -> 任务 -> 素材 -> 下载

这条链路跑通。

2. 建立前后端工程骨架

前端使用 Vite 初始化 Vue 项目，配置路由和 Pinia。

后端使用 FastAPI 搭建接口结构：

backend/app/
  api/
  core/
  dependencies/
  models/
  schemas/
  services/

这样接口、模型、Schema 和业务服务相对独立，后续维护会清晰很多。

3. 优先打通用户和商品

用户登录是所有业务接口的基础，因此先完成认证和用户归属校验。

之后完成商品建档，因为后续脚本生成和视频生成都依赖商品对象。

4. 再做脚本和视频任务

脚本模块先做结构化输出，不直接黑盒出片。

视频生成模块采用任务模式，避免长时间请求阻塞，也方便未来接入真实视频 Provider。

5. 最后补素材管理和交付

素材管理是业务闭环的终点。只有素材可以查看、下载、归档，这个项目才真正从“生成 Demo”变成“生产工具”。

---

七、开发过程中遇到的问题与解决方案

问题 1：前端提示“请求失败”，但看不到真实原因

工作台和素材管理页都出现了“请求失败”，导致历史数据无法展示。

排查发现前端错误提示是统一兜底文案：

throw new Error(extractErrorMessage(payload, '请求失败'))

如果后端返回 500 且没有明确 detail，前端只能显示“请求失败”。

进一步排查后端接口，发现真正原因不是前端页面问题，而是历史数据库和新模型字段不一致。

解决方式：

• 补齐后端增量 Schema 升级逻辑。
• 对旧表缺失字段进行自动补列。
• 增加回归测试，模拟旧表结构执行升级。

问题 2：旧数据库缺少新字段，历史列表接口 500

项目迭代过程中，video、product、generation_task 等模型新增了字段，例如：

• video.hotspot_name
• video.is_archived
• video.expire_at
• product.cache_expire_at
• generation_task.custom_script

但是旧数据库表中没有这些字段。SQLAlchemy 查询模型时会读取映射字段，数据库缺列就会抛错。

解决方案是在启动时执行增量补表：

def ensure_additive_schema(sync_conn: Connection) -> None:
    inspector = inspect(sync_conn)
    for table_name, columns in ADDITIVE_COLUMNS.items():
        if not inspector.has_table(table_name):
            continue
        existing = {column["name"] for column in inspector.get_columns(table_name)}
        for column_name, ddl in columns.items():
            if column_name in existing:
                continue
            sync_conn.execute(text(f"ALTER TABLE {table_name} ADD COLUMN {column_name} {ddl}"))

同时提供独立升级脚本：

cd backend
.venv\Scripts\python.exe scripts\upgrade_schema.py

问题 3：历史视频尺寸 auto 与后端枚举不兼容

排查历史数据时发现，旧视频记录中存在：

size = "auto"

但是后端模型只允许：

Enum("9_16", "3_4", "1_1", name="video_size")

导致 SQLAlchemy 读取历史数据时出现枚举反序列化错误。

解决方式是将 auto 纳入后端兼容范围：

size: Mapped[str] = mapped_column(
    Enum("auto", "9_16", "3_4", "1_1", name="video_size"),
    default="9_16",
)

这个问题说明：数据库枚举字段在业务迭代中要非常谨慎。前端如果已经可能提交某个值，后端和数据库必须同步兼容。

问题 4：端口和环境配置不一致

项目开发过程中，前端默认请求后端 8000，而某些脚本或文档中又提到 8001，容易导致前端连不上后端。

解决方式：

• 前端默认使用相对路径 /api/v1。
• Vite dev server 通过 proxy 转发到后端。
• 根目录提供 start-dev.cmd 和 stop-dev.cmd 一键启动/停止。
• README 中补充启动方式和端口说明。

前端 API 基础路径最终改成：

const API_BASE_URL = import.meta.env.VITE_API_BASE_URL ?? '/api/v1'

这样开发环境可以走代理，生产环境也更容易部署。

问题 5：商品链接解析容易遇到反爬和验证码

电商平台页面经常出现：

• 登录页
• 验证码
• 安全验证
• 移动端跳转
• 页面结构变化

如果强行把商品解析作为唯一入口，用户体验会非常差。

所以项目采用兜底策略：

官方接口优先
-> 页面状态识别
-> 浏览器抓取
-> HTTP 降级
-> 手动补全

当系统识别到验证码或登录态问题时，会提示用户配置 Cookie 或使用手动建档，而不是让流程中断。

问题 6：视频下载路径需要安全校验

素材导出涉及本地文件路径，如果直接根据数据库路径读取文件，可能存在路径越权风险。

因此后端下载时必须确认文件在受控目录内：

def _resolve_video_file(raw_path: str) -> Path:
    target = Path(raw_path).resolve()
    allowed_root = VIDEO_ARTIFACT_ROOT.resolve()
    if allowed_root not in target.parents:
        raise HTTPException(status_code=400, detail="交付文件路径无效")
    if not target.exists():
        raise HTTPException(status_code=404, detail="交付文件不存在")
    return target

这类校验虽然不是页面功能，但对真实项目很关键。

问题 7：AI 供应商配置缺失时生成任务失败

项目预留了百炼图生视频、数字人 Provider 等能力。如果 API Key 没配置，任务生成会失败。

解决思路是：

• 在任务创建前检查 Provider 配置。
• 返回明确错误提示。
• 在 README 和 .env.example 中说明需要配置的变量。
• 保留本地文件交付和任务状态，避免用户看到空白页面。

---

八、测试与验证

项目中补充了多类后端测试：

• 商品解析辅助函数测试
• 脚本引擎校验测试
• 视频任务结果测试
• 视频 Provider 选择测试
• 视频交付文件清理测试
• SQLite 异步兼容测试
• 热点服务测试
• Schema 升级测试

本次修复历史数据加载问题后，执行：

cd backend
.venv\Scripts\python.exe -m unittest discover -s tests

测试结果：

Ran 57 tests
OK

另外还直接验证了本地历史数据链路：

用户：1
视频：7 条
商品：15 条
脚本：125 条
热点：5 条

这说明工作台和素材管理所依赖的数据接口已经可以正常返回。

---

九、项目启动方式

1. 后端启动

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
uvicorn app.main:app --reload --port 8000

2. 前端启动

cd frontend
pnpm install
pnpm dev

3. 一键启动

Windows 环境下可以直接执行：

start-dev.cmd

停止服务：

stop-dev.cmd

4. 数据库升级

如果已有旧数据库，建议启动前执行：

cd backend
.venv\Scripts\python.exe scripts\upgrade_schema.py

这个脚本会创建缺失表并补齐新增字段，不会删除历史数据。

---

十、项目收获

这个项目最大的收获不是简单做了几个页面，而是完整走了一遍 AI 应用工程化闭环。

我认为比较关键的经验有：

1. AI 项目首先要有业务闭环

很多 AI 项目容易停留在“调用模型生成一段内容”的 Demo 阶段。但真正可用的业务系统必须包括：

• 输入如何标准化
• 任务如何追踪
• 结果如何保存
• 历史如何复用
• 失败如何处理
• 文件如何交付

智影工场的核心价值就在于把商品、脚本、任务、视频、素材管理串成了一条完整链路。

2. 不要把第三方供应商写死

AI 供应商变化很快，价格、质量、接口稳定性都可能变。如果业务代码和供应商接口强绑定，后期切换成本会很高。

所以更合理的方式是：

接口层只创建任务
服务层封装 Provider
数据库记录 provider_name 和 provider_job_id
前端只关心任务状态

3. 历史数据兼容非常重要

这次“请求失败”问题的根因就是历史数据和新模型不兼容。

在真实项目中，字段新增、枚举调整、状态值变化都可能影响旧数据。如果没有迁移策略，项目很容易出现“新用户可用，老用户崩溃”的问题。

后续生产环境更推荐使用 Alembic 这类数据库迁移工具，而不是长期依赖自动建表。

4. 错误提示要能指导用户下一步

“请求失败”这种提示对用户帮助很小。

更好的提示应该告诉用户：

• 后端是否未启动
• 登录是否失效
• 数据库是否缺字段
• Provider 是否未配置
• 商品链接是否遇到验证码
• 文件是否不存在

这类提示能显著降低调试成本和用户挫败感。

---

十一、后续优化方向

项目后续可以继续从以下几个方向增强：

1. 引入 Alembic，规范数据库迁移。
2. 将视频生成任务迁移到 Celery + Redis。
3. 接入真实对象存储，例如阿里云 OSS。
4. 完善 AI Provider 抽象层，支持多个供应商切换。
5. 增加任务失败重试能力。
6. 素材管理增加分页、批量选择、归档恢复。
7. 增加独立的文案审核接口。
8. 增加生成任务日志，方便排查失败原因。
9. 平台连接从本地配置升级为真实 OAuth 授权。
10. 后续接入投放数据回流，形成“生成 -> 投放 -> 复盘 -> 优化”的闭环。

---

十二、总结

智影工场是一个面向电商运营场景的 AI 视频素材生产后台。项目从最初的产品设想出发，经过 MVP 收敛，最终实现了：

• 用户体系
• 商品建档
• 脚本生成
• 视频任务
• 素材管理
• 热点追拍
• 套餐用量
• 下载交付

在开发过程中，也遇到了很多真实工程问题，例如旧数据库字段缺失、枚举值不兼容、商品链接反爬、端口配置不一致、AI Provider 配置缺失、文件下载路径安全等。

这些问题让我更深刻地认识到：AI 应用不是只调用一个模型接口，更重要的是围绕业务场景建立稳定的数据流、任务流和交付流。

如果只做 Demo，生成一段视频就结束了；但如果要做一个真正可用的生产工具，就必须处理用户、商品、脚本、任务、素材、权限、下载、错误提示、历史兼容这些细节。

这也是本项目最有价值的地方。