215 lines
12 KiB
Markdown
215 lines
12 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
HoneyBox 后台管理系统基础框架，提供完整的 RBAC 权限管理功能。采用 ASP.NET Core 后端 + Vue3 + Element Plus 前端的架构，前端打包后部署到后端 wwwroot 目录，实现一体化部署。
|
||
|
||
## Glossary
|
||
|
||
- **Admin_System**: 后台管理系统，包含认证、菜单、角色、权限、部门等核心功能
|
||
- **Admin_User**: 后台管理员，拥有登录后台的权限
|
||
- **Department**: 部门，支持无限层级嵌套的组织架构单元
|
||
- **Role**: 角色，权限的集合，可分配给管理员
|
||
- **Menu**: 菜单，前端路由和导航项，支持树形结构
|
||
- **Permission**: 权限，API 级别的访问控制标识
|
||
- **JWT_Token**: JSON Web Token，用于身份认证
|
||
- **RBAC**: Role-Based Access Control，基于角色的访问控制
|
||
- **Refresh_Token**: 刷新令牌，用于在 Access Token 过期后获取新的 Token
|
||
- **Captcha**: 图形验证码，用于防止暴力破解和机器人攻击
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: 项目结构搭建
|
||
|
||
**User Story:** As a developer, I want to create the HoneyBox.Admin project structure, so that I can have an independent and reusable admin module.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Admin_System SHALL create a new ASP.NET Core project named HoneyBox.Admin
|
||
2. THE Admin_System SHALL contain Entities, Services, Models, Data, Controllers folders
|
||
3. THE Admin_System SHALL configure static file serving from wwwroot folder
|
||
4. THE Admin_System SHALL support SPA fallback routing for Vue3 frontend
|
||
5. THE Admin_System SHALL register all services via extension method AddHoneyBoxAdmin()
|
||
|
||
|
||
### Requirement 2: 数据库实体设计
|
||
|
||
**User Story:** As a developer, I want to define database entities for admin management, so that I can persist admin users, roles, menus and permissions.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Admin_System SHALL create AdminUser entity with username, password_hash, real_name, avatar, status, last_login_time, department_id fields
|
||
2. THE Admin_System SHALL create Role entity with name, code, description, sort_order, status, is_system fields
|
||
3. THE Admin_System SHALL create Menu entity with parent_id, name, path, component, icon, menu_type, permission, sort_order, status fields
|
||
4. THE Admin_System SHALL create Permission entity with name, code, module, description fields
|
||
5. THE Admin_System SHALL create AdminUserRole, RoleMenu, RolePermission, DepartmentMenu, AdminUserMenu junction entities for many-to-many relationships
|
||
6. THE Admin_System SHALL create Department entity with parent_id, name, code, sort_order, status fields
|
||
7. THE Admin_System SHALL create OperationLog entity for audit logging
|
||
8. THE Admin_System SHALL create AdminDbContext with all entity configurations
|
||
|
||
### Requirement 3: 管理员认证
|
||
|
||
**User Story:** As an admin user, I want to login with username and password, so that I can access the admin system securely.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN an admin user submits valid credentials, THE Auth_Service SHALL return a JWT token and user info
|
||
2. WHEN an admin user submits invalid credentials, THE Auth_Service SHALL return an authentication error
|
||
3. WHEN an admin user's account is disabled, THE Auth_Service SHALL reject the login attempt
|
||
4. WHEN login fails 5 times consecutively, THE Auth_Service SHALL lock the account for 30 minutes
|
||
5. THE Auth_Service SHALL record login time and IP address on successful login
|
||
6. WHEN a valid JWT token is provided, THE Admin_System SHALL authenticate the request
|
||
7. WHEN an invalid or expired JWT token is provided, THE Admin_System SHALL return 401 Unauthorized
|
||
|
||
|
||
### Requirement 4: 菜单管理
|
||
|
||
**User Story:** As an admin user, I want to manage system menus, so that I can configure the navigation structure.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN requesting menu list, THE Menu_Service SHALL return menus as a tree structure
|
||
2. WHEN creating a menu, THE Menu_Service SHALL validate required fields and save to database
|
||
3. WHEN updating a menu, THE Menu_Service SHALL update the existing record
|
||
4. WHEN deleting a menu with children, THE Menu_Service SHALL prevent deletion and return an error
|
||
5. WHEN deleting a menu without children, THE Menu_Service SHALL remove the menu record
|
||
6. THE Menu_Service SHALL support three menu types: directory, menu, and button
|
||
7. WHEN requesting user menus, THE Menu_Service SHALL return menus merged from user's department, roles, and direct assignments
|
||
|
||
### Requirement 5: 角色管理
|
||
|
||
**User Story:** As an admin user, I want to manage roles, so that I can group permissions and assign them to users.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN requesting role list, THE Role_Service SHALL return paginated role data
|
||
2. WHEN creating a role, THE Role_Service SHALL validate unique code and save to database
|
||
3. WHEN updating a role, THE Role_Service SHALL update the existing record
|
||
4. WHEN deleting a system role, THE Role_Service SHALL prevent deletion and return an error
|
||
5. WHEN deleting a non-system role, THE Role_Service SHALL remove the role and its associations
|
||
6. WHEN assigning menus to a role, THE Role_Service SHALL update the role-menu associations
|
||
7. WHEN assigning permissions to a role, THE Role_Service SHALL update the role-permission associations
|
||
|
||
|
||
### Requirement 6: 管理员管理
|
||
|
||
**User Story:** As an admin user, I want to manage admin accounts, so that I can control who has access to the system.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN requesting admin user list, THE AdminUser_Service SHALL return paginated user data with role info
|
||
2. WHEN creating an admin user, THE AdminUser_Service SHALL validate unique username and hash the password
|
||
3. WHEN updating an admin user, THE AdminUser_Service SHALL update the existing record
|
||
4. WHEN deleting the last super admin, THE AdminUser_Service SHALL prevent deletion
|
||
5. WHEN assigning roles to an admin user, THE AdminUser_Service SHALL update the user-role associations
|
||
6. WHEN enabling/disabling an admin user, THE AdminUser_Service SHALL update the status field
|
||
7. WHEN resetting password, THE AdminUser_Service SHALL generate a new hashed password
|
||
|
||
### Requirement 7: 权限控制
|
||
|
||
**User Story:** As a system, I want to enforce permission checks on API endpoints, so that unauthorized access is prevented.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN an API endpoint has permission attribute, THE Permission_Filter SHALL verify user has the required permission
|
||
2. WHEN user lacks required permission, THE Permission_Filter SHALL return 403 Forbidden
|
||
3. WHEN user has required permission, THE Permission_Filter SHALL allow the request to proceed
|
||
4. THE Permission_Service SHALL cache user permissions for performance
|
||
5. WHEN user roles change, THE Permission_Service SHALL invalidate the permission cache
|
||
|
||
|
||
### Requirement 8: 操作日志
|
||
|
||
**User Story:** As an admin user, I want to view operation logs, so that I can audit system activities.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN an admin performs a create/update/delete operation, THE Log_Service SHALL record the operation details
|
||
2. THE Operation_Log SHALL include admin_user_id, username, module, action, method, url, ip, request_data, response_status, duration
|
||
3. WHEN requesting operation logs, THE Log_Service SHALL return paginated log data with filters
|
||
4. THE Log_Service SHALL support filtering by admin user, module, action, and date range
|
||
|
||
### Requirement 9: Vue3 前端框架
|
||
|
||
**User Story:** As a developer, I want to create a Vue3 + Element Plus frontend, so that admins can interact with the system through a modern UI.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Frontend SHALL use Vue3 with Composition API and TypeScript
|
||
2. THE Frontend SHALL use Element Plus as the UI component library
|
||
3. THE Frontend SHALL use Pinia for state management
|
||
4. THE Frontend SHALL use Vue Router with dynamic route generation based on user menus
|
||
5. THE Frontend SHALL implement login page with form validation
|
||
6. THE Frontend SHALL implement layout with sidebar menu, header, and main content area
|
||
7. THE Frontend SHALL implement permission directive v-permission for button-level control
|
||
8. WHEN built, THE Frontend SHALL output to HoneyBox.Admin/wwwroot folder
|
||
|
||
### Requirement 10: 部门管理
|
||
|
||
**User Story:** As an admin user, I want to manage departments with hierarchical structure, so that I can organize users and assign permissions at department level.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Admin_System SHALL create Department entity with parent_id supporting unlimited nesting levels
|
||
2. WHEN requesting department list, THE Department_Service SHALL return departments as a tree structure
|
||
3. WHEN creating a department, THE Department_Service SHALL validate required fields and parent existence
|
||
4. WHEN updating a department, THE Department_Service SHALL prevent setting parent to itself or its descendants
|
||
5. WHEN deleting a department with children, THE Department_Service SHALL prevent deletion and return an error
|
||
6. WHEN deleting a department with users, THE Department_Service SHALL prevent deletion and return an error
|
||
7. WHEN assigning menus to a department, THE Department_Service SHALL update the department-menu associations
|
||
8. THE Admin_System SHALL support assigning users to departments
|
||
|
||
### Requirement 11: 用户菜单多维度配置
|
||
|
||
**User Story:** As an admin user, I want to configure user menus from multiple sources (department, role, direct assignment), so that I can have flexible permission control.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Admin_System SHALL support assigning menus directly to individual users
|
||
2. WHEN requesting user menus, THE Menu_Service SHALL merge menus from three sources: department menus, role menus, and user-specific menus
|
||
3. THE final user menu SHALL be the union of department menus, role menus, and user-specific menus
|
||
4. WHEN a user belongs to multiple departments, THE Menu_Service SHALL merge menus from all departments
|
||
5. WHEN user's department/role/direct menus change, THE Permission_Service SHALL invalidate the menu cache
|
||
|
||
### Requirement 12: 数据初始化
|
||
|
||
**User Story:** As a developer, I want to initialize default data, so that the system is ready to use after deployment.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Admin_System SHALL create default super admin account (admin/admin123) on first run
|
||
2. THE Admin_System SHALL create default super admin role with all permissions
|
||
3. THE Admin_System SHALL create default system menus for admin management
|
||
4. THE Admin_System SHALL create default permissions for all admin APIs
|
||
5. THE Admin_System SHALL create default root department
|
||
|
||
### Requirement 13: Token 刷新机制
|
||
|
||
**User Story:** As an admin user, I want my session to be automatically refreshed, so that I don't need to re-login frequently while actively using the system.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN an admin user logs in successfully, THE Auth_Service SHALL return both an Access Token (short-lived, 30 minutes) and a Refresh Token (long-lived, 7 days)
|
||
2. THE Refresh_Token SHALL be stored securely in the database with user_id, token_hash, expires_at, and created_at fields
|
||
3. WHEN the Access Token is about to expire (within 5 minutes), THE Frontend SHALL automatically call the refresh endpoint
|
||
4. WHEN a valid Refresh Token is provided, THE Auth_Service SHALL issue a new Access Token and optionally rotate the Refresh Token
|
||
5. WHEN an invalid or expired Refresh Token is provided, THE Auth_Service SHALL return 401 and require re-login
|
||
6. WHEN a user logs out, THE Auth_Service SHALL invalidate the Refresh Token
|
||
7. WHEN a user's account is disabled, THE Auth_Service SHALL invalidate all Refresh Tokens for that user
|
||
8. THE Admin_System SHALL support revoking all Refresh Tokens for a user (force logout from all devices)
|
||
|
||
### Requirement 14: 图形验证码
|
||
|
||
**User Story:** As a system administrator, I want to require captcha verification during login, so that I can prevent brute force attacks and bot access.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN requesting the login page, THE Frontend SHALL display a captcha image alongside the login form
|
||
2. THE Captcha_Service SHALL generate a random alphanumeric code (4-6 characters) with visual noise and distortion
|
||
3. THE Captcha_Service SHALL store the captcha code in cache with a unique key and 5-minute expiration
|
||
4. WHEN submitting login credentials, THE Auth_Service SHALL validate the captcha code before checking username/password
|
||
5. WHEN the captcha code is incorrect or expired, THE Auth_Service SHALL return an error and require a new captcha
|
||
6. WHEN the captcha is validated (success or failure), THE Captcha_Service SHALL invalidate the used captcha code
|
||
7. THE Frontend SHALL provide a refresh button to request a new captcha image
|
||
8. THE Captcha image SHALL be returned as base64 encoded string with the captcha key
|