StormFlow

Appearance

COS 文件上传 ​

一句话目标 ​

用户在节点中上传的图片/视频文件能够持久化存储到腾讯 COS，并返回可访问的 CDN URL，供后续 AI 生成流程和画布持久化使用。

行为约束 ​

BC-01 文件上传 ​

  • 前置条件：用户在 ImageNode 或 VideoNode 中选择/拖拽了合法文件
  • 行为：系统获取 STS 临时凭证，将文件直传到腾讯 COS
  • 后置条件：节点数据中存储的是 CDN URL（非 blob URL），可跨会话访问

BC-02 文件校验 ​

  • 前置条件：用户选择了文件
  • 行为：上传前校验文件类型和大小（图片 JPG/PNG/WebP ≤30MB，视频 MP4/WebM ≤300MB）
  • 后置条件：不合法文件被拒绝并提示用户，不会发起上传请求

BC-03 上传进度 ​

  • 前置条件：文件通过校验，上传已开始
  • 行为：系统展示上传进度
  • 后置条件：用户可实时看到上传百分比

BC-04 上传失败处理 ​

  • 前置条件：上传过程中发生错误（网络问题、STS 过期等）
  • 行为：系统提示错误信息
  • 后置条件：节点恢复到可重试的状态，不会残留无效数据

BC-05 STS 凭证获取 ​

  • 前置条件：需要上传文件
  • 行为：向 https://base.ysjf.com 请求临时凭证，module 为 shot
  • 后置条件：获得有效的临时密钥用于 COS 直传

状态机 ​

状态含义
idle无上传任务，等待用户选择文件
validating校验文件类型和大小
requesting_sts正在获取 STS 临时凭证
uploading文件直传 COS 中，有进度
done上传完成，CDN URL 已写入节点数据
error上传失败，可重试

关键转换规则：

  • validating 失败 → error（提示文件不合法）
  • requesting_sts 失败 → error（提示凭证获取失败）
  • error 状态下用户重试 → idle
  • done 后节点数据更新为 CDN URL

验收标准 ​

  • [x] AC-01 用户在 ImageNode 中选择合法图片文件后，文件上传到腾讯 COS 并返回 CDN URL 写入节点数据
  • [x] AC-02 用户在 VideoNode 中选择合法视频文件后，文件上传到腾讯 COS 并返回 CDN URL 写入节点数据
  • [x] AC-03 拖拽文件到节点区域触发相同的上传流程
  • [x] AC-04 图片文件类型不在 JPG/PNG/WebP 范围内时，拒绝上传并提示用户
  • [x] AC-05 视频文件类型不在 MP4/WebM 范围内时，拒绝上传并提示用户
  • [x] AC-06 图片文件超过 30MB 时，拒绝上传并提示用户
  • [x] AC-07 视频文件超过 300MB 时，拒绝上传并提示用户
  • [x] AC-08 上传过程中显示进度百分比
  • [x] AC-09 STS 凭证获取失败时，提示错误信息，节点进入可重试状态
  • [x] AC-10 COS 上传失败时，提示错误信息，节点进入可重试状态
  • [x] AC-11 上传完成后的 CDN URL 可跨会话持久访问（非 blob URL）

BDD 场景 ​

gherkin
Feature: 文件上传到腾讯 COS

  # Happy Path

  Scenario: 图片节点上传合法图片
    Given 用户打开了一个包含 ImageNode 的画布
    When 用户在 ImageNode 中选择一张 2MB 的 PNG 图片
    Then 系统获取 STS 临时凭证
    And 文件上传到腾讯 COS
    And 节点数据中的图片 URL 为 CDN 地址
    And 图片可通过该 CDN URL 正常访问

  Scenario: 视频节点上传合法视频
    Given 用户打开了一个包含 VideoNode 的画布
    When 用户在 VideoNode 中选择一个 30MB 的 MP4 视频
    Then 系统获取 STS 临时凭证
    And 文件上传到腾讯 COS
    And 节点数据中的视频 URL 为 CDN 地址

  Scenario: 拖拽文件上传
    Given 用户打开了一个包含 ImageNode 的画布
    When 用户将一张 JPG 图片拖拽到 ImageNode 区域
    Then 触发与点击选择相同的上传流程
    And 上传完成后节点显示该图片

  Scenario: 上传过程中显示进度
    Given 用户在 ImageNode 中选择了一张合法图片
    When 文件正在上传到 COS
    Then 节点上显示上传进度百分比
    And 进度从 0% 递增到 100%

  # Error Path

  Scenario: 图片类型不合法
    Given 用户打开了一个包含 ImageNode 的画布
    When 用户选择一个 GIF 文件
    Then 系统拒绝上传
    And 提示"不支持的文件类型"

  Scenario: 图片超过大小限制
    Given 用户打开了一个包含 ImageNode 的画布
    When 用户选择一张 35MB 的 PNG 图片
    Then 系统拒绝上传
    And 提示"文件大小超过限制"

  Scenario: 视频超过大小限制
    Given 用户打开了一个包含 VideoNode 的画布
    When 用户选择一个 350MB 的 MP4 视频
    Then 系统拒绝上传
    And 提示"文件大小超过限制"

  Scenario: STS 凭证获取失败
    Given 用户在节点中选择了一个合法文件
    When STS 接口返回错误
    Then 提示"上传凭证获取失败"
    And 节点进入可重试状态

  Scenario: COS 上传失败
    Given STS 凭证已成功获取
    When COS 上传过程中网络中断
    Then 提示"上传失败"
    And 节点进入可重试状态

TDD 单元测试指针 ​

测试目标所属模块测试什么
文件类型校验useUpload给定各种 MIME type，验证合法/非法判断是否正确
文件大小校验useUpload给定不同大小的 File 对象，验证图片 ≤30MB、视频 ≤300MB 的边界
STS 凭证请求useUploadmock HTTP 响应，验证正确解析 STS 数据结构
STS 请求失败处理useUploadmock HTTP 错误响应，验证抛出正确错误
上传状态流转useUpload验证 idle → uploading → done 以及 idle → uploading → error 的状态机转换
CDN URL 拼接useUpload验证 ${sts.cdn}/${sts.dir} 返回正确的 URL 格式

范围外 ​

排除项说明
多文件批量上传当前每次上传单个文件，批量上传留待后续迭代
断点续传COS SDK 的分片上传已内置，但不做显式的断点续传 UI
文件管理（删除/替换已上传文件）用户重新上传会覆盖节点数据，但不会从 COS 删除旧文件
上传历史记录不记录用户的上传历史
图片/视频压缩或转码原文件直传，不做客户端预处理
TextNode 的文件上传TextNode 不涉及文件上传