HaniBlindBox/.kiro/specs/image-upload-feature/requirements.md

Requirements Document

Introduction

实现后台管理系统的图片上传功能，支持本地存储和腾讯云COS存储两种方式。系统需要根据上传配置自动选择存储方式，并提供统一的前端上传组件供各业务模块使用。

Glossary

• Upload_Service: 文件上传服务，负责处理文件上传逻辑
• Storage_Provider: 存储提供者，包括本地存储和腾讯云COS
• ImageUpload_Component: 前端图片上传组件
• Upload_Config: 上传配置，存储在数据库config表中

Requirements

Requirement 1: 后端上传接口

User Story: As a 管理员, I want to 上传图片到服务器, so that 我可以在各业务模块中使用图片。

Acceptance Criteria

1. WHEN 管理员上传图片文件 THEN THE Upload_Service SHALL 接收文件并返回图片URL
2. WHEN 上传的文件不是图片格式 THEN THE Upload_Service SHALL 返回错误提示"只支持图片格式"
3. WHEN 上传的文件超过10MB THEN THE Upload_Service SHALL 返回错误提示"文件大小不能超过10MB"
4. THE Upload_Service SHALL 支持 jpg、jpeg、png、gif、webp 格式的图片
5. THE Upload_Service SHALL 生成唯一的文件名避免文件覆盖

Requirement 2: 本地存储实现

User Story: As a 系统管理员, I want to 将图片存储到服务器本地, so that 无需配置云存储即可使用上传功能。

Acceptance Criteria

1. WHEN Upload_Config 的 type 为 "1" THEN THE Storage_Provider SHALL 将文件保存到服务器本地目录
2. THE Storage_Provider SHALL 按日期创建子目录（如 uploads/2026/01/19/）
3. THE Storage_Provider SHALL 返回可访问的图片URL路径
4. WHEN 本地存储目录不存在 THEN THE Storage_Provider SHALL 自动创建目录

Requirement 3: 腾讯云COS存储实现

User Story: As a 系统管理员, I want to 将图片上传到腾讯云COS, so that 可以利用CDN加速和更好的存储可靠性。

Acceptance Criteria

1. WHEN Upload_Config 的 type 为 "3" THEN THE Storage_Provider SHALL 将文件上传到腾讯云COS
2. THE Storage_Provider SHALL 使用配置中的 Bucket、Region、AccessKeyId、AccessKeySecret 连接COS
3. THE Storage_Provider SHALL 返回配置的 Domain 拼接文件路径作为访问URL
4. IF COS上传失败 THEN THE Storage_Provider SHALL 返回具体的错误信息
5. THE Storage_Provider SHALL 按日期创建COS对象路径（如 uploads/2026/01/19/xxx.jpg）

Requirement 4: 存储策略切换

User Story: As a 系统管理员, I want to 在上传配置页面切换存储方式, so that 可以灵活选择存储策略。

Acceptance Criteria

1. WHEN 管理员修改上传配置 THEN THE Upload_Service SHALL 立即使用新的存储策略
2. THE Upload_Service SHALL 在每次上传时读取最新的配置
3. IF 配置的存储类型无效 THEN THE Upload_Service SHALL 默认使用本地存储

Requirement 5: 前端上传组件

User Story: As a 前端开发者, I want to 使用统一的图片上传组件, so that 可以快速在各业务模块中集成图片上传功能。

Acceptance Criteria

1. THE ImageUpload_Component SHALL 支持点击上传和拖拽上传
2. THE ImageUpload_Component SHALL 支持手动输入图片URL
3. THE ImageUpload_Component SHALL 显示上传进度
4. THE ImageUpload_Component SHALL 支持图片预览和删除
5. THE ImageUpload_Component SHALL 通过 v-model 双向绑定图片URL
6. WHEN 上传成功 THEN THE ImageUpload_Component SHALL 自动更新绑定的URL值
7. WHEN 上传失败 THEN THE ImageUpload_Component SHALL 显示错误提示

Requirement 6: 业务页面改造

User Story: As a 管理员, I want to 在各业务表单中直接上传图片, so that 不需要手动复制粘贴图片URL。

Acceptance Criteria

1. THE System SHALL 将以下页面的图片输入改为使用 ImageUpload_Component:
   • GoodsAddDialog.vue (imgUrl, imgUrlDetail)
   • GoodsEditDialog.vue (imgUrl, imgUrlDetail)
   • PrizeAddDialog.vue (imgUrl, imgUrlDetail)
   • PrizeEditDialog.vue (imgUrl, imgUrlDetail)
   • DiamondFormDialog.vue (normalImage, normalSelectImage, firstChargeImage, firstSelectChargeImage)
   • FloatBallFormDialog.vue (image, imageBj, imageDetails)
   • AdvertFormDialog.vue (imageUrl)
   • SignConfigFormDialog.vue (icon)
   • WelfareHouseFormDialog.vue (image)
   • base.vue (erweima, share_image)
2. THE System SHALL 保持原有的表单验证逻辑不变
3. THE System SHALL 兼容已有的图片URL数据