168 lines
11 KiB
Markdown
168 lines
11 KiB
Markdown
# 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)
|