HaniBlindBox/.kiro/specs/admin-frontend-migration/requirements.md

Requirements Document

Introduction

本文档定义了 HoneyBox 后台管理系统前端业务模块迁移的需求。后端 API（HoneyBox.Admin.Business）已完成，现需要在现有的 Vue 3 + Element Plus 前端项目（admin-web）中添加业务模块页面，实现与后端 API 的对接。

Glossary

• Admin_Web: 后台管理前端项目，使用 Vue 3 + Element Plus + TypeScript + Pinia 技术栈
• Business_Module: 业务模块，包括仪表盘、用户管理、商品管理、订单管理、财务管理、系统配置等
• API_Service: 前端 API 服务层，封装与后端的 HTTP 请求
• Page_Component: 页面组件，Vue 单文件组件（.vue）
• Router: Vue Router 路由配置
• Store: Pinia 状态管理

Requirements

Requirement 1: 仪表盘模块升级

User Story: As a 管理员, I want 在仪表盘看到业务数据概览, so that 我可以快速了解系统运营状况。

Acceptance Criteria

1. WHEN 管理员访问仪表盘页面 THEN THE Admin_Web SHALL 显示今日注册用户数、今日消费金额、今日订单数、总用户数等统计数据
2. WHEN 仪表盘页面加载 THEN THE Admin_Web SHALL 调用 /api/admin/business/dashboard 接口获取概览数据
3. WHEN 管理员查看广告账户 THEN THE Admin_Web SHALL 显示广告账户列表并支持新增和删除操作
4. IF 接口请求失败 THEN THE Admin_Web SHALL 显示错误提示信息

Requirement 2: 用户管理模块

User Story: As a 管理员, I want 管理平台用户, so that 我可以查看用户信息、处理用户问题、管理用户资金。

Acceptance Criteria

1. WHEN 管理员访问用户列表页面 THEN THE Admin_Web SHALL 显示分页用户列表，支持按用户ID、昵称、手机号搜索
2. WHEN 管理员点击用户详情 THEN THE Admin_Web SHALL 显示用户基本信息、账户余额、VIP等级等详细信息
3. WHEN 管理员执行资金变动操作 THEN THE Admin_Web SHALL 弹出对话框输入变动金额和备注，提交后调用 /api/admin/business/users/{id}/money 接口
4. WHEN 管理员执行封号/解封操作 THEN THE Admin_Web SHALL 调用 /api/admin/business/users/{id}/status 接口并刷新列表
5. WHEN 管理员设置测试账号 THEN THE Admin_Web SHALL 调用 /api/admin/business/users/{id}/test 接口
6. WHEN 管理员清空手机号或微信绑定 THEN THE Admin_Web SHALL 弹出确认对话框，确认后调用相应接口
7. WHEN 管理员赠送优惠券或卡牌 THEN THE Admin_Web SHALL 弹出选择对话框，选择后调用相应接口
8. WHEN 管理员查看用户盈亏统计 THEN THE Admin_Web SHALL 显示用户的消费、中奖、回收等统计数据
9. WHEN 管理员查看下级用户 THEN THE Admin_Web SHALL 显示该用户邀请的下级用户列表

Requirement 3: VIP管理模块

User Story: As a 管理员, I want 管理VIP等级配置, so that 我可以设置不同VIP等级的权益。

Acceptance Criteria

1. WHEN 管理员访问VIP管理页面 THEN THE Admin_Web SHALL 显示VIP等级列表
2. WHEN 管理员编辑VIP等级 THEN THE Admin_Web SHALL 弹出编辑对话框，支持修改等级名称、所需经验、权益等
3. WHEN 管理员保存VIP配置 THEN THE Admin_Web SHALL 调用 /api/admin/business/vip/{id} 接口

Requirement 4: 商品管理模块

User Story: As a 管理员, I want 管理抽奖盒子和奖品, so that 我可以配置抽奖活动。

Acceptance Criteria

1. WHEN 管理员访问商品列表页面 THEN THE Admin_Web SHALL 显示分页商品列表，支持按名称、类型、状态筛选
2. WHEN 管理员新增商品 THEN THE Admin_Web SHALL 显示新增表单，包含名称、类型、价格、图片、描述等字段
3. WHEN 管理员编辑商品 THEN THE Admin_Web SHALL 加载商品详情并显示编辑表单
4. WHEN 管理员删除商品 THEN THE Admin_Web SHALL 弹出确认对话框，确认后调用删除接口
5. WHEN 管理员上架/下架商品 THEN THE Admin_Web SHALL 调用 /api/admin/business/goods/{id}/status 接口
6. WHEN 管理员查看商品奖品 THEN THE Admin_Web SHALL 显示该商品的奖品列表
7. WHEN 管理员添加奖品 THEN THE Admin_Web SHALL 弹出添加奖品对话框，支持设置奖品名称、等级、库存、概率等

Requirement 5: 商品类型管理

User Story: As a 管理员, I want 管理商品类型, so that 我可以分类管理不同类型的抽奖盒子。

Acceptance Criteria

1. WHEN 管理员访问商品类型页面 THEN THE Admin_Web SHALL 显示商品类型列表
2. WHEN 管理员新增商品类型 THEN THE Admin_Web SHALL 弹出新增对话框
3. WHEN 管理员编辑商品类型 THEN THE Admin_Web SHALL 弹出编辑对话框

Requirement 6: 订单管理模块

User Story: As a 管理员, I want 管理用户订单, so that 我可以处理订单问题和发货。

Acceptance Criteria

1. WHEN 管理员访问订单列表页面 THEN THE Admin_Web SHALL 显示分页订单列表，支持按订单号、用户ID、状态、日期筛选
2. WHEN 管理员查看订单详情 THEN THE Admin_Web SHALL 显示订单基本信息和奖品明细
3. WHEN 管理员访问卡单列表 THEN THE Admin_Web SHALL 显示支付成功但未发奖的订单
4. WHEN 管理员访问兑换订单列表 THEN THE Admin_Web SHALL 显示用户回收奖品的订单
5. WHEN 管理员访问发货订单列表 THEN THE Admin_Web SHALL 显示待发货和已发货的订单
6. WHEN 管理员执行发货操作 THEN THE Admin_Web SHALL 弹出发货对话框，输入快递公司和单号后调用发货接口
7. WHEN 管理员导出订单 THEN THE Admin_Web SHALL 调用导出接口并下载CSV文件

Requirement 7: 财务管理模块

User Story: As a 管理员, I want 查看财务数据, so that 我可以了解平台的资金流动情况。

Acceptance Criteria

1. WHEN 管理员访问消费排行页面 THEN THE Admin_Web SHALL 显示用户消费排行榜
2. WHEN 管理员访问余额明细页面 THEN THE Admin_Web SHALL 显示用户余额变动记录
3. WHEN 管理员访问积分明细页面 THEN THE Admin_Web SHALL 显示用户积分变动记录
4. WHEN 管理员访问钻石明细页面 THEN THE Admin_Web SHALL 显示用户钻石变动记录
5. WHEN 管理员访问充值记录页面 THEN THE Admin_Web SHALL 显示用户充值记录列表

Requirement 8: 系统配置模块

User Story: As a 管理员, I want 配置系统参数, so that 我可以管理支付、上传等系统设置。

Acceptance Criteria

1. WHEN 管理员访问系统配置页面 THEN THE Admin_Web SHALL 显示配置分组列表
2. WHEN 管理员选择配置分组 THEN THE Admin_Web SHALL 显示该分组下的配置项
3. WHEN 管理员修改配置项 THEN THE Admin_Web SHALL 调用 /api/admin/business/config/{group} 接口保存配置
4. THE Admin_Web SHALL 支持不同类型的配置项输入（文本、数字、开关、图片上传等）

Requirement 9: 路由和导航

User Story: As a 管理员, I want 通过侧边栏导航访问各业务模块, so that 我可以方便地切换不同功能。

Acceptance Criteria

1. THE Admin_Web SHALL 在路由配置中添加业务模块路由
2. THE Admin_Web SHALL 根据后端返回的菜单数据动态生成导航菜单
3. WHEN 管理员点击导航菜单 THEN THE Admin_Web SHALL 跳转到对应的业务页面
4. THE Admin_Web SHALL 支持权限控制，无权限的菜单不显示

Requirement 10: API服务层

User Story: As a 开发者, I want 统一的API服务层, so that 我可以方便地调用后端接口。

Acceptance Criteria

1. THE Admin_Web SHALL 在 src/api/ 目录下创建业务模块API文件
2. THE Admin_Web SHALL 使用 axios 封装 HTTP 请求
3. THE Admin_Web SHALL 统一处理请求错误和响应格式
4. THE Admin_Web SHALL 支持请求拦截器自动添加认证Token