HaniBlindBox/.kiro/specs/user-management-frontend/requirements.md

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
• User_Controller: 用户管理后端控制器，位于 server/HoneyBox/src/HoneyBox.Admin.Business/Controllers/UserController.cs
• User_Service: 用户业务服务，位于 server/HoneyBox/src/HoneyBox.Admin.Business/Services/UserBusinessService.cs
• Old_View: 老项目视图文件，位于 server/php/app/admin/view/User/
• Element_Plus: Vue 3 UI组件库
• Layui: 老项目使用的前端UI框架

Requirements

Requirement 1: 用户列表页面

User Story: As a 管理员, I want 查看和管理用户列表, so that 我可以了解用户情况并进行必要的管理操作。

Acceptance Criteria

1. WHEN 管理员访问用户管理页面 THEN Admin_Web SHALL 显示用户列表表格，包含用户信息、推荐人、余额、积分、钻石、货币信息、用户状态等字段
2. WHEN 管理员输入搜索条件（UID、推荐人UID、手机号、昵称、IP地址、登录时间范围）并点击搜索 THEN Admin_Web SHALL 根据条件筛选并显示匹配的用户列表
3. WHEN 用户列表加载完成 THEN Admin_Web SHALL 显示每个用户的消费统计（总消费、出货价值、盒柜价值、达达券）
4. WHEN 管理员点击分页控件 THEN Admin_Web SHALL 加载对应页码的用户数据
5. THE Admin_Web SHALL 在用户列表每行显示操作按钮组，包含资金变动、状态管理、赠送功能、查看详情等操作入口

Requirement 2: 资金变动功能

User Story: As a 管理员, I want 给用户充值或扣除余额/积分/钻石, so that 我可以处理用户的资金问题。

Acceptance Criteria

1. WHEN 管理员点击"充值余额/积分/钻石"按钮 THEN Admin_Web SHALL 弹出资金变动对话框，显示当前余额和操作表单
2. WHEN 管理员选择操作类型（充值/扣除）、输入金额和备注并提交 THEN Admin_Web SHALL 调用API完成资金变动操作
3. IF 资金变动请求参数无效（如扣除金额超过余额） THEN Admin_Web SHALL 显示错误提示信息
4. WHEN 资金变动成功 THEN Admin_Web SHALL 刷新用户列表显示最新余额

Requirement 3: 用户状态管理

User Story: As a 管理员, I want 管理用户账号状态, so that 我可以封禁违规用户或解封用户。

Acceptance Criteria

1. WHEN 管理员点击"封号"按钮 THEN Admin_Web SHALL 弹出确认对话框，确认后调用API封禁用户
2. WHEN 管理员点击"解封"按钮 THEN Admin_Web SHALL 弹出确认对话框，确认后调用API解封用户
3. WHEN 管理员点击"设为测试账号"按钮 THEN Admin_Web SHALL 调用API将用户标记为测试账号
4. WHEN 管理员点击"清空手机号"按钮 THEN Admin_Web SHALL 弹出确认对话框，确认后调用API清空用户手机号
5. WHEN 管理员点击"重置微信登录"按钮 THEN Admin_Web SHALL 弹出确认对话框，确认后调用API清空用户微信绑定
6. WHEN 管理员点击"绑定手机号"按钮 THEN Admin_Web SHALL 弹出输入对话框，输入手机号后调用API绑定

Requirement 4: 赠送功能

User Story: As a 管理员, I want 给用户赠送优惠券或卡牌, so that 我可以进行用户运营活动。

Acceptance Criteria

1. WHEN 管理员点击"赠送优惠券"按钮 THEN Admin_Web SHALL 弹出优惠券选择对话框，显示可用优惠券列表
2. WHEN 管理员选择优惠券、输入数量并提交 THEN Admin_Web SHALL 调用API完成优惠券赠送
3. WHEN 管理员点击"赠送卡牌"按钮 THEN Admin_Web SHALL 弹出卡牌选择对话框，支持选择盒子和奖品
4. WHEN 管理员选择盒子、奖品、输入数量并提交 THEN Admin_Web SHALL 调用API完成卡牌赠送

Requirement 5: 用户详情查看

User Story: As a 管理员, I want 查看用户的详细信息和相关数据, so that 我可以全面了解用户情况。

Acceptance Criteria

1. WHEN 管理员点击"查看下级"按钮 THEN Admin_Web SHALL 弹出下级用户列表对话框，显示该用户邀请的下级用户
2. WHEN 管理员点击"查看盒柜"按钮 THEN Admin_Web SHALL 弹出用户盒柜对话框，显示用户的中奖物品列表
3. WHEN 管理员点击"查看订单"按钮 THEN Admin_Web SHALL 弹出用户订单对话框，显示用户的订单列表
4. WHEN 管理员点击"余额流水明细"按钮 THEN Admin_Web SHALL 弹出流水明细对话框，显示用户余额变动记录
5. WHEN 管理员点击"积分流水明细"按钮 THEN Admin_Web SHALL 弹出流水明细对话框，显示用户积分变动记录
6. WHEN 管理员点击"钻石流水明细"按钮 THEN Admin_Web SHALL 弹出流水明细对话框，显示用户钻石变动记录
7. WHEN 管理员点击"查看IP登录列表"按钮 THEN Admin_Web SHALL 弹出IP登录历史对话框

Requirement 6: 用户盈亏统计

User Story: As a 管理员, I want 查看用户的盈亏统计数据, so that 我可以分析用户的消费和收益情况。

Acceptance Criteria

1. WHEN 管理员访问用户盈亏统计页面 THEN Admin_Web SHALL 显示用户盈亏列表，包含用户信息、支付金额、发货金额、背包金额、盈亏计算
2. WHEN 管理员输入筛选条件（用户ID、时间范围）并搜索 THEN Admin_Web SHALL 根据条件筛选显示盈亏数据
3. WHEN 管理员点击"导出Excel"按钮 THEN Admin_Web SHALL 导出当前筛选结果到Excel文件
4. THE Admin_Web SHALL 在盈亏列表中用不同颜色区分盈利和亏损状态

Requirement 7: VIP等级管理

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

Acceptance Criteria

1. WHEN 管理员访问VIP管理页面 THEN Admin_Web SHALL 显示VIP等级列表，包含等级名称、升级所需积分、享受折扣、权益说明
2. WHEN 管理员点击"编辑"按钮 THEN Admin_Web SHALL 弹出VIP等级编辑对话框
3. WHEN 管理员修改VIP等级信息并提交 THEN Admin_Web SHALL 调用API更新VIP等级配置

Requirement 8: 用户邀请统计

User Story: As a 管理员, I want 查看用户邀请统计数据, so that 我可以了解推广效果。

Acceptance Criteria

1. WHEN 管理员访问用户邀请统计页面 THEN Admin_Web SHALL 显示邀请统计列表，包含邀请人数、绑定手机数、消费人数、消费总金额
2. WHEN 管理员点击某行展开 THEN Admin_Web SHALL 显示被邀请用户的详细信息列表
3. WHEN 管理员点击"导出"按钮 THEN Admin_Web SHALL 导出邀请统计数据到Excel文件

Requirement 9: 用户登录统计

User Story: As a 管理员, I want 查看用户登录统计图表, so that 我可以了解用户活跃情况。

Acceptance Criteria

1. WHEN 管理员访问登录统计页面 THEN Admin_Web SHALL 显示登录统计图表和筛选条件
2. WHEN 管理员选择统计类型（日/周/月）和时间范围 THEN Admin_Web SHALL 更新图表显示对应的登录趋势
3. THE Admin_Web SHALL 在图表下方显示总登录次数和活跃用户数统计

Requirement 10: API补充迁移

User Story: As a 开发者, I want 补充缺失的后端API, so that 前端页面可以正常工作。

Acceptance Criteria

1. THE User_Controller SHALL 提供用户盒柜列表查询API（GET /api/admin/business/users/{id}/box）
2. THE User_Controller SHALL 提供用户订单列表查询API（GET /api/admin/business/users/{id}/orders）
3. THE User_Controller SHALL 提供用户流水明细查询API（GET /api/admin/business/users/{id}/money-detail、/integral-detail、/score-detail）
4. THE User_Controller SHALL 提供用户IP登录历史查询API（GET /api/admin/business/users/{id}/ip-logs）
5. THE User_Controller SHALL 提供用户邀请统计查询API（GET /api/admin/business/users/invite-stats）
6. THE User_Controller SHALL 提供用户登录统计查询API（GET /api/admin/business/users/login-stats）
7. THE User_Controller SHALL 提供用户盈亏列表查询API（GET /api/admin/business/users/profit-loss-list）
8. THE User_Controller SHALL 提供绑定手机号API（PUT /api/admin/business/users/{id}/mobile）
9. THE User_Controller SHALL 提供重置签到数据API（PUT /api/admin/business/users/{id}/sign-reset）
10. THE User_Controller SHALL 提供清空UID API（DELETE /api/admin/business/users/{id}/uid）