8.5 KiB
8.5 KiB
Requirements Document
Introduction
本文档定义了HoneyBox后台管理系统商品管理模块前端迁移的需求。该模块需要将老项目（PHP ThinkPHP + Layui）的商品管理前端页面迁移到新项目（ASP.NET Core + Vue 3 + Element Plus）。
后端API已部分迁移完成，本次主要任务是创建前端页面并与已有API对接，同时补充缺失的API接口。
Glossary
- Admin_Web: 新项目后台管理前端，位于
server/HoneyBox/src/HoneyBox.Admin/admin-web - Goods_Controller: 商品管理后端控制器，位于
server/HoneyBox/src/HoneyBox.Admin.Business/Controllers/GoodsController.cs - Goods_Service: 商品业务服务，位于
server/HoneyBox/src/HoneyBox.Admin.Business/Services/GoodsService.cs - GoodsTypes_Controller: 盒子类型管理控制器，位于
server/HoneyBox/src/HoneyBox.Admin.Business/Controllers/GoodsTypesController.cs - Prizes_Controller: 奖品管理控制器，位于
server/HoneyBox/src/HoneyBox.Admin.Business/Controllers/PrizesController.cs - Old_View: 老项目视图文件，位于
server/php/app/admin/view/Goods/ - Element_Plus: Vue 3 UI组件库
- Layui: 老项目使用的前端UI框架
参考文档
- #file:docs/后台管理系统-功能分析清单.md - 模块功能分析
- #file:server/HoneyBox/src/HoneyBox.Admin.Business/Controllers/GoodsController.cs - 后端API
- #file:server/HoneyBox/src/HoneyBox.Admin.Business/Services/GoodsService.cs - 后端服务
- #file:server/php/app/admin/controller/GoodsType.php - 老项目盒子类型控制器
- #file:server/php/app/common/model/GoodsExtend.php - 老项目盒子扩展模型
盒子类型定义
系统支持多种盒子类型，每种类型有不同的字段配置：
| 类型值 | 类型名称 | 特有字段 |
|---|---|---|
| 1 | 一番赏 | 套数、锁箱、每日限购 |
| 2 | 无限赏 | 怒气值、道具卡 |
| 3 | 擂台赏 | 全局赏数量 |
| 5 | 福袋 | 套数 |
| 6 | 幸运赏 | 套数、锁箱、限购 |
| 8 | 领主赏 | 领主开关、领主返还、领主奖品 |
| 9 | 连击赏 | 连击次数、连击奖品 |
| 10 | 盲盒 | 套数、盒子描述 |
| 15 | 福利屋 | 开始/结束/开奖时间、限购次数 |
Requirements
Requirement 1: 盒子列表页面
User Story: As a 管理员, I want 查看和管理所有盒子, so that 我可以进行日常运营。
Acceptance Criteria
- WHEN 管理员访问盒子管理页面 THEN Admin_Web SHALL 显示盒子列表表格，包含盒子ID、类型、名称、价格、套数、图片、状态等字段
- WHEN 管理员输入搜索条件（盒子标题、状态、类型）并点击搜索 THEN Admin_Web SHALL 根据条件筛选并显示匹配的盒子列表
- WHEN 管理员点击状态开关 THEN Admin_Web SHALL 调用API切换盒子上架/下架状态
- WHEN 管理员点击"编辑"按钮 THEN Admin_Web SHALL 弹出盒子编辑对话框
- WHEN 管理员点击"删除"按钮 THEN Admin_Web SHALL 弹出确认对话框，确认后调用API删除盒子
- WHEN 管理员点击"复制"按钮 THEN Admin_Web SHALL 调用API复制盒子（含奖品）
- WHEN 管理员点击"奖品"按钮 THEN Admin_Web SHALL 弹出奖品列表对话框
- WHEN 管理员点击"扩展设置"按钮 THEN Admin_Web SHALL 弹出扩展设置对话框
- WHEN 管理员点击"清空抽奖"按钮 THEN Admin_Web SHALL 弹出危险操作确认对话框，确认后清空抽奖记录
- WHEN 盒子类型为福利屋 THEN Admin_Web SHALL 在列表中显示开始/结束/开奖时间
Requirement 2: 盒子新增功能
User Story: As a 管理员, I want 新增盒子, so that 我可以上架新的抽奖活动。
Acceptance Criteria
- WHEN 管理员点击"新增盒子"按钮 THEN Admin_Web SHALL 弹出盒子新增对话框，显示盒子类型选择
- WHEN 管理员选择盒子类型 THEN Admin_Web SHALL 根据类型动态显示/隐藏相关字段
- THE Admin_Web SHALL 支持配置基础信息（名称、价格、排序、描述）
- THE Admin_Web SHALL 支持配置首抽五折、是否最新开关
- THE Admin_Web SHALL 支持配置自动下架（利润值、抽数阈值、下架金额）
- THE Admin_Web SHALL 支持配置解锁金额
- THE Admin_Web SHALL 支持上传盒子封面图和详情图
- WHEN 盒子类型为一番赏/幸运赏 THEN Admin_Web SHALL 显示套数、锁箱、每日限购配置
- WHEN 盒子类型为无限赏/翻倍赏 THEN Admin_Web SHALL 显示怒气值、道具卡配置
- WHEN 盒子类型为福利屋 THEN Admin_Web SHALL 显示时间配置（开始/结束/开奖）
Requirement 3: 盒子编辑功能
User Story: As a 管理员, I want 编辑已有盒子, so that 我可以调整活动配置。
Acceptance Criteria
- WHEN 管理员打开盒子编辑对话框 THEN Admin_Web SHALL 禁用盒子类型选择（不可修改）
- THE Admin_Web SHALL 回显盒子当前配置数据
- WHEN 管理员修改配置并提交 THEN Admin_Web SHALL 调用API更新盒子并刷新列表
Requirement 4: 奖品列表管理
User Story: As a 管理员, I want 管理盒子的奖品, so that 我可以配置抽奖内容。
Acceptance Criteria
- WHEN 管理员打开奖品列表对话框 THEN Admin_Web SHALL 显示该盒子的所有奖品
- WHEN 管理员输入奖品标题搜索 THEN Admin_Web SHALL 筛选显示匹配的奖品
- THE Admin_Web SHALL 根据盒子类型动态显示不同列（数量/概率）
- WHEN 奖品类型为宝箱 THEN Admin_Web SHALL 支持树形表格展开显示子奖品
- THE Admin_Web SHALL 显示概率统计（无限赏等类型）
- THE Admin_Web SHALL 支持添加、编辑、删除奖品操作
Requirement 5: 奖品新增/编辑功能
User Story: As a 管理员, I want 新增和编辑奖品, so that 我可以配置抽奖奖品。
Acceptance Criteria
- THE Admin_Web SHALL 支持配置奖品基础信息（名称、售价、采购价、参考价）
- THE Admin_Web SHALL 支持选择奖品分类（现货/预售/货币/宝箱）
- THE Admin_Web SHALL 支持选择奖品等级（A/B/C/D/E等）
- THE Admin_Web SHALL 根据盒子类型显示数量或概率字段
- WHEN 盒子类型为翻倍赏 THEN Admin_Web SHALL 显示赠送倍率配置
- WHEN 奖品分类为预售 THEN Admin_Web SHALL 显示预售时间配置
- THE Admin_Web SHALL 支持配置赠送货币
- THE Admin_Web SHALL 支持上传奖品图片和详情图
Requirement 6: 盒子类型管理
User Story: As a 管理员, I want 管理盒子类型, so that 我可以配置类型属性。
Acceptance Criteria
- WHEN 管理员访问盒子类型管理页面 THEN Admin_Web SHALL 显示类型列表（ID、名称、Key、排序）
- THE Admin_Web SHALL 支持首页显示、分类显示开关
- THE Admin_Web SHALL 支持配置支付方式（微信/余额/积分/积分2/优惠券）
- THE Admin_Web SHALL 支持配置角标文字
- THE Admin_Web SHALL 支持新增、编辑、删除类型操作
Requirement 7: 盒子扩展设置
User Story: As a 管理员, I want 为单个盒子配置独立的支付方式, so that 我可以覆盖类型默认配置。
Acceptance Criteria
- WHEN 管理员打开扩展设置对话框 THEN Admin_Web SHALL 显示盒子基本信息
- THE Admin_Web SHALL 支持多选支付方式（微信/余额/积分/积分2/优惠券）
- THE Admin_Web SHALL 支持选择支付类型（抵扣模式/支付模式）
- WHEN 管理员点击"删除扩展设置" THEN Admin_Web SHALL 删除独立配置，恢复使用类型默认配置
Requirement 8: API补充迁移
User Story: As a 开发者, I want 补充缺失的后端API, so that 前端页面可以正常工作。
Acceptance Criteria
- THE GoodsTypes_Controller SHALL 提供创建盒子类型API（POST /api/admin/business/goods-types）
- THE GoodsTypes_Controller SHALL 提供更新盒子类型API（PUT /api/admin/business/goods-types/{id}）
- THE GoodsTypes_Controller SHALL 提供删除盒子类型API（DELETE /api/admin/business/goods-types/{id}）
- THE GoodsTypes_Controller SHALL 提供修改类型状态API（PUT /api/admin/business/goods-types/{id}/status）
- THE Goods_Controller SHALL 提供获取扩展设置API（GET /api/admin/business/goods/{id}/extend）
- THE Goods_Controller SHALL 提供更新扩展设置API（PUT /api/admin/business/goods/{id}/extend）
- THE Goods_Controller SHALL 提供删除扩展设置API（DELETE /api/admin/business/goods/{id}/extend）
- THE Goods_Controller SHALL 提供复制盒子API（POST /api/admin/business/goods/{id}/copy）
- THE Goods_Controller SHALL 提供清空抽奖API（POST /api/admin/business/goods/{id}/clear-lottery）