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

Requirements Document

Introduction

本文档定义了 HoneyBox 后台管理系统业务模块迁移的需求。目标是将 PHP (ThinkPHP 6.0) 后台管理的业务功能迁移至 ASP.NET Core，采用独立的 HoneyBox.Admin.Business 类库架构，实现业务模块与基础后台管理框架的解耦。

Glossary

• Admin_System: 后台管理系统，包含认证、菜单、角色、权限等基础功能
• Business_Module: 业务模块，包含用户管理、商品管理、订单管理等业务功能
• HoneyBox_Admin: 后台管理基础项目，包含认证、菜单、角色、权限等核心功能
• HoneyBox_Admin_Business: 后台业务模块类库，包含所有业务相关的控制器和服务
• HoneyBoxDbContext: 业务数据库上下文，访问 honey_box 业务库
• AdminDbContext: 后台管理数据库上下文，访问 honey_box_admin 管理库
• Config_Table: 系统配置表，存储各类配置的 JSON 数据
• User_Table: 用户表，存储用户基本信息
• Goods_Table: 商品表，存储盒子信息
• Order_Table: 订单表，存储订单信息
• Box_Type: 盒子类型，包含一番赏、无限赏、擂台赏、抽卡机等9种类型

Requirements

Requirement 1: 项目架构搭建

User Story: As a developer, I want to create an independent HoneyBox.Admin.Business class library, so that business modules can be easily added or removed without affecting the core admin system.

Acceptance Criteria

1. THE HoneyBox_Admin_Business project SHALL be created as a separate class library
2. THE HoneyBox_Admin_Business project SHALL reference HoneyBox.Model for business entity access
3. WHEN HoneyBox.Admin starts, THE Admin_System SHALL load controllers from HoneyBox_Admin_Business assembly via AddApplicationPart
4. THE HoneyBox_Admin_Business project SHALL provide a ServiceCollectionExtensions class with AddAdminBusiness extension method
5. WHEN AddAdminBusiness is called, THE Admin_System SHALL register all business services and controllers automatically
6. THE HoneyBox_Admin_Business project SHALL have its own Controllers, Services, and Models directories

Requirement 2: 跨库数据访问配置

User Story: As a developer, I want to configure cross-database access, so that the admin system can query both admin database and business database.

Acceptance Criteria

1. WHEN the application starts, THE Admin_System SHALL inject both AdminDbContext and HoneyBoxDbContext
2. THE HoneyBoxDbContext SHALL connect to the honey_box business database
3. THE AdminDbContext SHALL connect to the honey_box_admin management database
4. WHEN a business service needs business data, THE Business_Module SHALL use HoneyBoxDbContext for queries
5. THE connection strings for both databases SHALL be configurable in appsettings.json

Requirement 3: 系统配置模块迁移

User Story: As an administrator, I want to manage system configurations, so that I can configure payment settings, upload settings, and other system parameters.

Acceptance Criteria

1. WHEN an administrator requests configuration by key, THE Config_Service SHALL return the configuration JSON data
2. WHEN an administrator updates configuration, THE Config_Service SHALL validate and save the JSON data to Config_Table
3. THE Config_Service SHALL support the following configuration keys: base, weixinpay_setting, alipay_setting, miniprogram_setting, h5_setting, uploads, systemconfig, sign
4. WHEN weixinpay_setting is updated, THE Config_Service SHALL validate that merchant prefixes are unique and exactly 3 characters
5. WHEN miniprogram_setting is updated, THE Config_Service SHALL validate that at least one default miniprogram is set
6. WHEN h5_setting is updated, THE Config_Service SHALL validate that at least one default H5 app is set
7. WHEN configuration is updated, THE Config_Service SHALL clear related Redis cache
8. IF configuration validation fails, THEN THE Config_Service SHALL return a descriptive error message

Requirement 4: 用户管理模块迁移

User Story: As an administrator, I want to manage users, so that I can view user information, modify user status, and handle user-related operations.

Acceptance Criteria

1. WHEN an administrator requests user list, THE User_Service SHALL return paginated user data with consumption statistics
2. THE user list SHALL include: user ID, UID, nickname, avatar, mobile, balance, integral, diamond, VIP level, registration time, last login IP
3. THE user list SHALL support filtering by: user_id, mobile, nickname, last_login_ip, registration date range, parent_id
4. WHEN an administrator modifies user balance/integral/diamond, THE User_Service SHALL record the change in profit tables
5. WHEN an administrator bans a user, THE User_Service SHALL set user status to disabled
6. WHEN an administrator unbans a user, THE User_Service SHALL set user status to enabled
7. WHEN an administrator sets test account flag, THE User_Service SHALL update the istest field
8. WHEN an administrator clears mobile binding, THE User_Service SHALL set mobile field to empty
9. WHEN an administrator clears WeChat binding, THE User_Service SHALL generate new random openid
10. WHEN an administrator gifts coupon to user, THE User_Service SHALL create coupon_receive records
11. WHEN an administrator gifts card to user, THE User_Service SHALL create order_list records with order_type=9
12. THE User_Service SHALL provide VIP level management with CRUD operations
13. THE User_Service SHALL provide user profit/loss statistics calculation
14. THE User_Service SHALL provide subordinate user list query

Requirement 5: 商品管理模块迁移

User Story: As an administrator, I want to manage products (boxes), so that I can create, edit, and configure lottery boxes and their prizes.

Acceptance Criteria

1. WHEN an administrator requests goods list, THE Goods_Service SHALL return paginated box data
2. THE goods list SHALL support filtering by: title, status, type
3. THE Goods_Service SHALL support 9 box types: 一番赏(1), 无限赏(2), 擂台赏(3), 抽卡机(4), 福袋(5), 幸运赏(6), 盲盒(8), 扭蛋(9), 福利屋(15)
4. WHEN creating a box, THE Goods_Service SHALL validate required fields based on box type
5. WHEN editing a box, THE Goods_Service SHALL prevent stock reduction
6. WHEN increasing box stock, THE Goods_Service SHALL automatically copy prize configurations for new sets
7. THE Goods_Service SHALL provide prize management: add, edit, delete, stock adjustment
8. WHEN a prize is added to a box, THE Goods_Service SHALL generate unique prize_code
9. THE Goods_Service SHALL provide box type management with CRUD operations
10. WHEN box status changes, THE Goods_Service SHALL log the operation in admin_goods_log

Requirement 6: 订单管理模块迁移

User Story: As an administrator, I want to manage orders, so that I can view order details, handle shipping, and process refunds.

Acceptance Criteria

1. WHEN an administrator requests order list, THE Order_Service SHALL return paginated order data with user information
2. THE order list SHALL support filtering by: user_id, mobile, order_num, date range, status
3. THE Order_Service SHALL provide separate views for: purchase orders, stuck orders, recovery orders, shipping orders
4. WHEN viewing order details, THE Order_Service SHALL return prize list grouped by prize_code
5. WHEN an administrator ships an order, THE Order_Service SHALL update order status and record courier information
6. WHEN an administrator cancels a shipping order, THE Order_Service SHALL restore prizes to user's inventory
7. IF shipping order has freight payment, THEN THE Order_Service SHALL process refund via WeChat
8. THE Order_Service SHALL support batch shipping with Excel import
9. THE Order_Service SHALL support order export to Excel format
10. THE export function SHALL include: order number, user info, box info, amounts, payment details, time

Requirement 7: 财务管理模块迁移

User Story: As an administrator, I want to view financial data, so that I can monitor consumption rankings, balance changes, and recharge records.

Acceptance Criteria

1. WHEN an administrator requests consumption ranking, THE Finance_Service SHALL return users sorted by total consumption
2. THE consumption ranking SHALL include: user info, total consumption, WeChat payment, balance payment, integral payment
3. WHEN an administrator requests balance details, THE Finance_Service SHALL return profit_money records with user info
4. WHEN an administrator requests integral details, THE Finance_Service SHALL return profit_integral records with user info
5. WHEN an administrator requests score details, THE Finance_Service SHALL return profit_score records with user info
6. WHEN an administrator requests recharge records, THE Finance_Service SHALL return profit_pay records with user info
7. ALL financial queries SHALL support filtering by: user_id, mobile, date range

Requirement 8: 首页仪表盘模块迁移

User Story: As an administrator, I want to view dashboard statistics, so that I can monitor today's registrations, consumption, and advertising data.

Acceptance Criteria

1. WHEN an administrator visits dashboard, THE Dashboard_Service SHALL return today's registration count
2. WHEN an administrator visits dashboard, THE Dashboard_Service SHALL return today's consumption amount
3. WHEN an administrator visits dashboard, THE Dashboard_Service SHALL return today's new consumer count
4. WHEN an administrator visits dashboard, THE Dashboard_Service SHALL return total advertising revenue
5. THE Dashboard_Service SHALL provide advertising account management with CRUD operations

Requirement 9: API 响应格式标准化

User Story: As a frontend developer, I want consistent API response format, so that I can handle responses uniformly.

Acceptance Criteria

1. THE Business_Module SHALL return success responses in format: { code: 0, message: "success", data: {...} }
2. THE Business_Module SHALL return error responses in format: { code: error_code, message: "error description", data: null }
3. THE Business_Module SHALL return paginated responses in format: { code: 0, message: "success", data: { list: [...], total: N, page: N, pageSize: N } }
4. WHEN validation fails, THE Business_Module SHALL return code 40201 with field-specific error messages
5. WHEN authentication fails, THE Business_Module SHALL return code 40001
6. WHEN permission denied, THE Business_Module SHALL return code 40101

Requirement 10: 权限控制集成

User Story: As an administrator, I want business module APIs to be protected by permissions, so that only authorized users can access specific functions.

Acceptance Criteria

1. WHEN a business API is called, THE Admin_System SHALL verify user authentication via JWT token
2. WHEN a business API requires specific permission, THE Admin_System SHALL check user's role permissions
3. THE Business_Module SHALL use AdminPermission attribute to declare required permissions
4. IF user lacks required permission, THEN THE Admin_System SHALL return 403 Forbidden response
5. THE permission codes SHALL follow pattern: module:action (e.g., user:list, goods:add, order:ship)