WuYongJie/gongxiangp2
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
gongxiangp2/.kiro/specs/product-package/requirements.md
chenpei ea9076df45 feat: 实现统一的下载错误处理系统并修复产品全案数据库Schema 
- 创建统一的下载错误处理模块 (lib/download-errors.ts)
- 实现13种错误类型分类和中文错误消息
- 后端统一使用 createDownloadError 创建标准化错误响应
- 前端统一使用 parseDownloadError 解析错误并显示
- 修复正式系统数据库Schema，添加产品全案相关字段和表
- 执行数据库迁移：添加 task_no, task_status, task_fetched_at 字段
- 创建 material_assets, api_keys, api_call_logs 表
2026-01-05 17:52:42 +08:00

8.9 KiB
Raw Blame History

需求文档：产品全案素材类型

简介

新增「产品全案」素材类型，用于整合一个产品的完整电商视觉资产（主图、SKU图、详情预览图、PSD源文件），并提供外部接口供任务系统对接。

术语表

  • Product_Package_System: 产品全案素材管理系统
  • Material_Asset: 素材资产（主图/SKU图/详情图/PSD）
  • External_API: 外部接口服务
  • Task_System: 外部任务系统
  • API_Key: 接口访问密钥
  • Download_Token: 下载令牌

需求

需求 1：素材上传

用户故事： 作为设计师，我想要上传产品全案素材，以便将一个产品的所有视觉资产整合在一起。

验收标准

  1. WHEN 用户选择「产品全案」素材类型 THEN THE Product_Package_System SHALL 显示任务号、SPU型号、店铺（必填）、场景（可选）输入字段
  2. WHEN 用户上传主图 THEN THE Product_Package_System SHALL 接受多张图片且不做压缩处理，保持原图质量
  3. WHEN 用户上传SKU图 THEN THE Product_Package_System SHALL 接受多张图片且不做压缩处理
  4. WHEN 用户上传详情预览图 THEN THE Product_Package_System SHALL 支持批量拖拽上传已切片的图片
  5. WHEN 用户上传PSD源文件 THEN THE Product_Package_System SHALL 接受 .psd/.zip/.rar/.7z 格式文件并存储到本地 uploads 目录
  6. WHEN 用户未上传PSD源文件 THEN THE Product_Package_System SHALL 允许提交（PSD为可选）
  7. WHEN 用户输入已存在的任务号 THEN THE Product_Package_System SHALL 返回错误提示「任务号已存在」
  8. WHEN 上传成功 THEN THE Product_Package_System SHALL 将任务状态设置为 completed

需求 2：详情图排序

用户故事： 作为设计师，我想要调整详情预览图的顺序，以便控制最终展示效果。

验收标准

  1. WHEN 用户上传多张详情预览图 THEN THE Product_Package_System SHALL 显示可拖拽排序的缩略图列表
  2. WHEN 用户拖拽调整顺序 THEN THE Product_Package_System SHALL 在左侧实时预览区显示按当前顺序拼接的详情图
  3. WHEN 用户点击某张缩略图 THEN THE Product_Package_System SHALL 在预览区滚动到对应位置并高亮显示
  4. WHEN 用户保存排序 THEN THE Product_Package_System SHALL 按 sortOrder 字段存储顺序

需求 3：素材详情展示

用户故事： 作为用户，我想要查看产品全案的详情，以便预览和下载所需资源。

验收标准

  1. WHEN 用户打开产品全案详情页 THEN THE Product_Package_System SHALL 在左侧显示主图轮播区和详情预览图滚动区
  2. WHEN 用户查看主图区域 THEN THE Product_Package_System SHALL 显示大图轮播和底部缩略图切换
  3. WHEN 用户查看右侧 THEN THE Product_Package_System SHALL 显示SKU图网格和下载按钮组
  4. WHEN 素材包含PSD文件 THEN THE Product_Package_System SHALL 显示「下载PSD源文件」按钮
  5. WHEN 素材不包含PSD文件 THEN THE Product_Package_System SHALL 隐藏PSD下载按钮

需求 4：下载功能

用户故事： 作为用户，我想要按类型下载素材，以便获取所需的资源文件。

验收标准

  1. WHEN 用户点击「下载全部」 THEN THE Product_Package_System SHALL 打包所有主图、SKU图、详情图为ZIP下载（不含PSD）
  2. WHEN 用户点击「下载主图」 THEN THE Product_Package_System SHALL 打包所有主图为ZIP下载
  3. WHEN 用户点击「下载SKU图」 THEN THE Product_Package_System SHALL 打包所有SKU图为ZIP下载
  4. WHEN 用户点击「下载详情图」 THEN THE Product_Package_System SHALL 打包所有详情预览图为ZIP下载
  5. WHEN 用户点击「下载PSD源文件」且有权限 THEN THE Product_Package_System SHALL 直接下载PSD文件
  6. WHEN 用户点击「下载PSD源文件」且无权限 THEN THE Product_Package_System SHALL 显示「无权限下载源文件」提示

需求 5：PSD下载权限控制

用户故事： 作为管理员，我想要控制哪些部门可以下载PSD源文件，以便保护设计资产。

验收标准

  1. WHEN 管理员配置部门权限 THEN THE Product_Package_System SHALL 显示「可下载源文件」选项（独立于「可下载」权限）
  2. WHEN 部门的 canDownloadSource 为 true THEN THE Product_Package_System SHALL 允许该部门用户下载PSD文件
  3. WHEN 部门的 canDownloadSource 为 false THEN THE Product_Package_System SHALL 禁止该部门用户下载PSD文件
  4. WHEN 用户是超级管理员 THEN THE Product_Package_System SHALL 允许下载所有PSD文件

需求 6：素材编辑

用户故事： 作为设计师，我想要编辑已上传的产品全案，以便更新或补充资源。

验收标准

  1. WHEN 用户编辑产品全案 THEN THE Product_Package_System SHALL 允许增删改主图、SKU图、详情图
  2. WHEN 用户编辑产品全案 THEN THE Product_Package_System SHALL 允许替换或删除PSD源文件
  3. WHEN 用户编辑产品全案 THEN THE Product_Package_System SHALL 允许调整图片排序
  4. WHEN 素材已被外部系统获取（taskStatus=fetched） THEN THE Product_Package_System SHALL 显示警告「该素材已被外部系统获取，修改后可能影响对方数据」
  5. WHEN 用户确认编辑 THEN THE Product_Package_System SHALL 保存更改并更新 updatedAt

需求 7：外部查询接口

用户故事： 作为外部任务系统，我想要通过任务号查询素材详情，以便获取下载链接。

验收标准

  1. WHEN 外部系统调用 GET /api/external/product-assets 且 API Key 有效 THEN THE External_API SHALL 返回素材详情和下载链接
  2. WHEN 外部系统提供有效任务号 THEN THE External_API SHALL 返回主图、SKU图、详情图、PSD的图片列表和下载链接
  3. WHEN 外部系统提供无效任务号 THEN THE External_API SHALL 返回 TASK_NOT_FOUND 错误
  4. WHEN API Key 无效或缺失 THEN THE External_API SHALL 返回 INVALID_API_KEY 错误
  5. WHEN 查询成功 THEN THE External_API SHALL 将任务状态更新为 fetched 并记录 taskFetchedAt
  6. WHEN 返回下载链接 THEN THE External_API SHALL 生成带 token 的下载链接（有效期24小时）

需求 8：外部下载接口

用户故事： 作为外部任务系统，我想要通过下载链接获取文件，以便同步资源。

验收标准

  1. WHEN 外部系统调用 GET /api/external/download 且 token 有效 THEN THE External_API SHALL 返回对应文件
  2. WHEN token 已过期 THEN THE External_API SHALL 返回 TOKEN_EXPIRED 错误
  3. WHEN token 无效 THEN THE External_API SHALL 返回 INVALID_TOKEN 错误
  4. WHEN 下载类型为 all THEN THE External_API SHALL 打包主图+SKU图+详情图为ZIP（不含PSD）
  5. WHEN 下载类型为 psd THEN THE External_API SHALL 返回PSD源文件

需求 9：外部删除接口

用户故事： 作为外部任务系统，我想要删除已完成的任务素材，以便同步删除操作。

验收标准

  1. WHEN 外部系统调用 DELETE /api/external/product-assets 且 API Key 有效 THEN THE External_API SHALL 软删除对应素材
  2. WHEN 删除成功 THEN THE External_API SHALL 返回删除确认信息
  3. WHEN 任务号不存在 THEN THE External_API SHALL 返回 TASK_NOT_FOUND 错误
  4. WHEN 素材已被删除 THEN THE External_API SHALL 返回 MATERIAL_DELETED 错误

需求 10：API Key 管理

用户故事： 作为管理员，我想要管理外部接口的访问密钥，以便控制接口访问权限。

验收标准

  1. WHEN 管理员访问 API 管理页面 THEN THE Product_Package_System SHALL 显示 API Key 列表
  2. WHEN 管理员创建 API Key THEN THE Product_Package_System SHALL 生成唯一密钥并显示（仅显示一次）
  3. WHEN 管理员禁用 API Key THEN THE Product_Package_System SHALL 将该 Key 标记为无效
  4. WHEN 管理员查看调用日志 THEN THE Product_Package_System SHALL 显示调用时间、任务号、状态码、耗时等信息
  5. WHEN 调用日志超过90天 THEN THE Product_Package_System SHALL 自动清理旧日志

需求 11：素材卡片展示

用户故事： 作为用户，我想要在素材列表中识别产品全案类型，以便快速找到所需素材。

验收标准

  1. WHEN 素材列表显示产品全案 THEN THE Product_Package_System SHALL 使用第一张主图作为封面
  2. WHEN 素材列表显示产品全案 THEN THE Product_Package_System SHALL 显示「产品全案」类型角标
  3. IF 素材没有主图 THEN THE Product_Package_System SHALL 使用第一张SKU图作为封面

需求 12：任务号状态管理

用户故事： 作为管理员，我想要追踪任务的处理状态，以便了解素材的使用情况。

验收标准

  1. WHEN 素材上传完成 THEN THE Product_Package_System SHALL 将 taskStatus 设置为 completed
  2. WHEN 外部系统首次查询素材 THEN THE Product_Package_System SHALL 将 taskStatus 更新为 fetched 并记录时间
  3. WHEN 管理员查看素材详情 THEN THE Product_Package_System SHALL 显示任务状态和获取时间