HaniBlindBox/.kiro/specs/admin-system/requirements.md

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