# HoneyBox 后台管理系统迁移计划 ## 一、迁移概述 ### 1.1 迁移目标 将 PHP (ThinkPHP 6.0) 后台管理系统迁移至 ASP.NET Core，采用前后端分离架构，实现现代化的后台管理系统。 ### 1.2 迁移策略 - **基础先行**：先搭建权限管理框架（登录、菜单、角色、权限），再逐步迁移业务模块 - **后端分离**：新建独立类库 `HoneyBox.Admin` 处理后台 API - **数据库分离**：独立的后台管理数据库 `honey_box_admin`，与业务库解耦 - **渐进式迁移**：按模块逐个迁移，降低风险 --- ## 二、架构设计 ### 2.1 整体架构 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 前端应用层 │ │ ┌─────────────────────────────┐ ┌─────────────────────────────────────┐ │ │ │ UniApp (小程序/H5/APP) │ │ Vue3 + Element Plus (后台管理) │ │ │ │ 用户端前端 │ │ 管理端前端 │ │ │ └─────────────────────────────┘ └─────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌───────────────────────────────┐ ┌─────────────────────────────────────────┐ │ HoneyBox.Api │ │ HoneyBox.Admin │ │ (用户端 API) │ │ (后台管理 - 独立可复用项目) │ │ ┌─────────────────────────┐ │ │ ┌─────────────────────────────────┐ │ │ │ /api/* (用户端接口) │ │ │ │ Controllers/ (后台管理 API) │ │ │ └─────────────────────────┘ │ │ │ Services/ (业务逻辑层) │ │ │ │ │ │ │ Entities/ (数据实体) │ │ │ ▼ │ │ │ Models/ (DTO/ViewModel) │ │ │ ┌─────────────────────────┐ │ │ │ Data/ (DbContext) │ │ │ │ HoneyBox.Core │ │ │ └─────────────────────────────────┘ │ │ │ (用户端业务逻辑) │ │ │ │ │ │ └─────────────────────────┘ │ │ │ (可选引用) │ │ │ │ │ ▼ │ │ ▼ │ │ ┌─────────────────────────────────┐ │ │ ┌─────────────────────────┐ │ │ │ HoneyBox.Core (业务数据查询) │ │ │ │ HoneyBox.Model │ │ │ │ HoneyBox.Model (业务实体) │ │ │ │ (业务数据模型) │ │ │ └─────────────────────────────────┘ │ │ └─────────────────────────┘ │ └─────────────────────────────────────────┘ │ │ │ │ │ ▼ │ ▼ │ ┌─────────────────────────┐ │ ┌─────────────────────────────────────────┐ │ │ honey_box │ │ │ honey_box_admin │ │ │ (业务数据库) │ │ │ (后台管理数据库) │ │ └─────────────────────────┘ │ └─────────────────────────────────────────┘ └───────────────────────────────┘ ``` ### 2.2 HoneyBox.Admin 设计理念 `HoneyBox.Admin` 是一个**独立可复用的后台管理模块**，具有以下特点： 1. **自包含** - 内部包含 Entities、Services、DbContext，不依赖外部 Model 层 2. **可移植** - 可以轻松复制到其他项目中使用 3. **松耦合** - 通过可选引用 `HoneyBox.Core/Model` 来访问业务数据 4. **独立数据库** - 使用独立的 `honey_box_admin` 数据库 ### 2.3 项目结构 ``` HoneyBox.sln ├── src/ │ ├── HoneyBox.Api/ # 用户端 API (现有) │ │ ├── Controllers/ # 用户端控制器 │ │ └── Filters/ │ │ │ ├── HoneyBox.Admin/ # 后台管理 (新增 - 独立可复用项目) │ │ ├── Controllers/ # 后台管理 API 控制器 │ │ │ ├── AuthController.cs # 登录认证 │ │ │ ├── MenuController.cs # 菜单管理 │ │ │ ├── RoleController.cs # 角色管理 │ │ │ ├── AdminUserController.cs # 管理员管理 │ │ │ ├── PermissionController.cs # 权限管理 │ │ │ └── Business/ # 业务模块控制器 (迁移后) │ │ │ ├── UserController.cs # 用户管理 │ │ │ ├── GoodsController.cs # 商品管理 │ │ │ ├── OrderController.cs # 订单管理 │ │ │ └── ... │ │ │ │ │ ├── Services/ # 业务服务层 │ │ │ ├── Interfaces/ # 接口定义 │ │ │ │ ├── IAuthService.cs │ │ │ │ ├── IMenuService.cs │ │ │ │ ├── IRoleService.cs │ │ │ │ └── ... │ │ │ ├── AuthService.cs # 认证服务 │ │ │ ├── MenuService.cs # 菜单服务 │ │ │ ├── RoleService.cs # 角色服务 │ │ │ ├── PermissionService.cs # 权限服务 │ │ │ └── AdminUserService.cs # 管理员服务 │ │ │ │ │ ├── Entities/ # 数据实体 (后台管理专用) │ │ │ ├── AdminUser.cs # 管理员 │ │ │ ├── Role.cs # 角色 │ │ │ ├── Menu.cs # 菜单 │ │ │ ├── Permission.cs # 权限 │ │ │ ├── AdminUserRole.cs # 管理员-角色关联 │ │ │ ├── RoleMenu.cs # 角色-菜单关联 │ │ │ ├── RolePermission.cs # 角色-权限关联 │ │ │ └── OperationLog.cs # 操作日志 │ │ │ │ │ ├── Models/ # DTO / ViewModel │ │ │ ├── Auth/ # 认证相关 │ │ │ │ ├── LoginRequest.cs │ │ │ │ ├── LoginResponse.cs │ │ │ │ └── AdminUserInfo.cs │ │ │ ├── Menu/ # 菜单相关 │ │ │ ├── Role/ # 角色相关 │ │ │ └── Common/ # 通用模型 │ │ │ ├── PagedRequest.cs │ │ │ └── ApiResponse.cs │ │ │ │ │ ├── Data/ # 数据访问层 │ │ │ └── AdminDbContext.cs # 后台管理数据库上下文 │ │ │ │ │ ├── Filters/ # 过滤器 │ │ │ ├── AdminAuthFilter.cs # 后台认证过滤器 │ │ │ └── PermissionFilter.cs # 权限验证过滤器 │ │ │ │ │ ├── Extensions/ # 扩展方法 │ │ │ └── ServiceCollectionExtensions.cs # DI 注册扩展 │ │ │ │ │ └── HoneyBox.Admin.csproj │ │ │ ├── HoneyBox.Core/ # 用户端业务层 (现有) │ ├── HoneyBox.Model/ # 用户端数据层 (现有) │ └── HoneyBox.Infrastructure/ # 基础设施层 (现有) │ └── tests/ └── HoneyBox.Admin.Tests/ # 后台管理测试 (新增) ``` ### 2.4 项目依赖关系 ``` HoneyBox.Admin (独立可复用) │ ├── 自包含: Entities, Services, Models, DbContext │ └── 可选引用 (访问业务数据时): ├── HoneyBox.Core (业务逻辑复用) └── HoneyBox.Model (业务实体查询) ``` **复用到其他项目时：** - 只需复制 `HoneyBox.Admin` 项目 - 修改 `AdminDbContext` 连接字符串 - 移除对 `HoneyBox.Core/Model` 的引用（如果不需要） - 即可获得完整的后台管理功能 --- ## 三、数据库设计 ### 3.1 数据库分离策略 | 数据库 | 用途 | 说明 | |--------|------|------| | `honey_box` | 业务数据库 | 用户、商品、订单等业务数据 | | `honey_box_admin` | 后台管理数据库 | 管理员、角色、菜单、权限、日志 | ### 3.2 后台管理数据库表设计 #### 3.2.1 管理员表 (admin_users) ```sql CREATE TABLE admin_users ( id BIGINT PRIMARY KEY IDENTITY(1,1), username NVARCHAR(50) NOT NULL UNIQUE, -- 用户名 password_hash NVARCHAR(256) NOT NULL, -- 密码哈希 real_name NVARCHAR(50), -- 真实姓名 avatar NVARCHAR(500), -- 头像 email NVARCHAR(100), -- 邮箱 phone NVARCHAR(20), -- 手机号 status TINYINT DEFAULT 1, -- 状态: 0禁用 1启用 last_login_time DATETIME2, -- 最后登录时间 last_login_ip NVARCHAR(50), -- 最后登录IP created_at DATETIME2 DEFAULT GETDATE(), updated_at DATETIME2, created_by BIGINT, -- 创建人 remark NVARCHAR(500) -- 备注 ); ``` #### 3.2.2 角色表 (roles) ```sql CREATE TABLE roles ( id BIGINT PRIMARY KEY IDENTITY(1,1), name NVARCHAR(50) NOT NULL UNIQUE, -- 角色名称 code NVARCHAR(50) NOT NULL UNIQUE, -- 角色编码 description NVARCHAR(200), -- 描述 sort_order INT DEFAULT 0, -- 排序 status TINYINT DEFAULT 1, -- 状态: 0禁用 1启用 is_system BIT DEFAULT 0, -- 是否系统角色(不可删除) created_at DATETIME2 DEFAULT GETDATE(), updated_at DATETIME2 ); ``` #### 3.2.3 菜单表 (menus) ```sql CREATE TABLE menus ( id BIGINT PRIMARY KEY IDENTITY(1,1), parent_id BIGINT DEFAULT 0, -- 父级ID name NVARCHAR(50) NOT NULL, -- 菜单名称 path NVARCHAR(200), -- 路由路径 component NVARCHAR(200), -- 组件路径 icon NVARCHAR(100), -- 图标 menu_type TINYINT DEFAULT 1, -- 类型: 1目录 2菜单 3按钮 permission NVARCHAR(100), -- 权限标识 sort_order INT DEFAULT 0, -- 排序 status TINYINT DEFAULT 1, -- 状态: 0隐藏 1显示 is_external BIT DEFAULT 0, -- 是否外链 is_cache BIT DEFAULT 1, -- 是否缓存 created_at DATETIME2 DEFAULT GETDATE(), updated_at DATETIME2 ); ``` #### 3.2.4 权限表 (permissions) ```sql CREATE TABLE permissions ( id BIGINT PRIMARY KEY IDENTITY(1,1), name NVARCHAR(50) NOT NULL, -- 权限名称 code NVARCHAR(100) NOT NULL UNIQUE, -- 权限编码 (如: user:list, user:add) module NVARCHAR(50), -- 所属模块 description NVARCHAR(200), -- 描述 created_at DATETIME2 DEFAULT GETDATE() ); ``` #### 3.2.5 关联表 ```sql -- 管理员-角色关联 CREATE TABLE admin_user_roles ( id BIGINT PRIMARY KEY IDENTITY(1,1), admin_user_id BIGINT NOT NULL, role_id BIGINT NOT NULL, UNIQUE(admin_user_id, role_id) ); -- 角色-菜单关联 CREATE TABLE role_menus ( id BIGINT PRIMARY KEY IDENTITY(1,1), role_id BIGINT NOT NULL, menu_id BIGINT NOT NULL, UNIQUE(role_id, menu_id) ); -- 角色-权限关联 CREATE TABLE role_permissions ( id BIGINT PRIMARY KEY IDENTITY(1,1), role_id BIGINT NOT NULL, permission_id BIGINT NOT NULL, UNIQUE(role_id, permission_id) ); ``` #### 3.2.6 操作日志表 (operation_logs) ```sql CREATE TABLE operation_logs ( id BIGINT PRIMARY KEY IDENTITY(1,1), admin_user_id BIGINT, -- 操作人ID username NVARCHAR(50), -- 操作人用户名 module NVARCHAR(50), -- 操作模块 action NVARCHAR(50), -- 操作类型 method NVARCHAR(10), -- 请求方法 url NVARCHAR(500), -- 请求URL ip NVARCHAR(50), -- IP地址 request_data NVARCHAR(MAX), -- 请求参数 response_data NVARCHAR(MAX), -- 响应数据 status TINYINT, -- 状态: 0失败 1成功 error_msg NVARCHAR(1000), -- 错误信息 duration INT, -- 耗时(ms) created_at DATETIME2 DEFAULT GETDATE() ); ``` --- ## 四、迁移阶段规划 ### 阶段一：基础框架搭建 (预计 1-2 周) #### 4.1.1 目标 - 创建后台管理相关项目 - 搭建数据库和基础表 - 实现登录认证 #### 4.1.2 任务清单 | 序号 | 任务 | 说明 | 优先级 | |------|------|------|--------| | 1 | 创建 `HoneyBox.Admin` 项目 | 独立可复用的后台管理项目 | P0 | | 2 | 创建 Entities 实体类 | AdminUser, Role, Menu, Permission 等 | P0 | | 3 | 创建 AdminDbContext | 后台管理数据库上下文 | P0 | | 4 | 创建 `honey_box_admin` 数据库 | 执行建表脚本 | P0 | | 5 | 实现管理员登录 API | JWT 认证 | P0 | | 6 | 实现后台权限过滤器 | 基于角色/权限的访问控制 | P0 | | 7 | 创建 DI 扩展方法 | `AddHoneyBoxAdmin()` 便于复用 | P0 | | 8 | 初始化超级管理员账号 | 默认 admin/admin123 | P0 | ### 阶段二：权限管理模块 (预计 1-2 周) #### 4.2.1 目标 - 实现完整的 RBAC 权限管理 - 菜单、角色、权限的增删改查 #### 4.2.2 任务清单 | 序号 | 任务 | 说明 | 优先级 | |------|------|------|--------| | 1 | 菜单管理 CRUD | 树形结构菜单 | P0 | | 2 | 角色管理 CRUD | 角色分配菜单/权限 | P0 | | 3 | 管理员管理 CRUD | 管理员分配角色 | P0 | | 4 | 权限管理 | 权限列表、分配 | P1 | | 5 | 操作日志 | 记录管理员操作 | P1 | | 6 | 登录日志 | 记录登录历史 | P2 | ### 阶段三：业务模块迁移 (预计 4-6 周) 按优先级逐步迁移 PHP 后台的业务模块： | 优先级 | 模块 | PHP 控制器 | 说明 | |--------|------|-----------|------| | P0 | 首页仪表盘 | Index | 数据统计概览 | | P0 | 用户管理 | User | 用户列表、封禁、资金变动 | | P0 | 商品管理 | Goods, GoodsType | 盒子管理、奖品配置 | | P0 | 订单管理 | Order | 订单列表、发货、退款 | | P1 | 财务管理 | Finance, Withdraw | 资金流水、提现审核 | | P1 | 抽奖配置 | Draw, Cardextractor | 抽奖活动配置 | | P1 | 系统配置 | Config | 支付、上传等配置 | | P2 | 营销管理 | Coupon, Reward, Rank | 优惠券、奖励、排行榜 | | P2 | 内容管理 | Advert, Danye, News | 广告、单页、公告 | | P2 | 统计报表 | Statistics | 数据分析报表 | --- ## 五、技术选型 ### 5.1 后端技术栈 | 技术 | 版本 | 用途 | |------|------|------| | ASP.NET Core | 8.0 | Web API 框架 | | Entity Framework Core | 8.0 | ORM | | SQL Server | 2019+ | 数据库 | | JWT | - | 身份认证 | | Serilog | - | 日志 | | Mapster | 7.4 | 对象映射 | | Redis | - | 缓存、Token 存储 | ### 5.2 前端技术栈 (建议) | 技术 | 版本 | 用途 | |------|------|------| | Vue.js | 3.x | 前端框架 | | Element Plus | 2.x | UI 组件库 | | Vite | 5.x | 构建工具 | | Pinia | 2.x | 状态管理 | | Vue Router | 4.x | 路由 | | Axios | 1.x | HTTP 请求 | | ECharts | 5.x | 图表 | --- ## 六、API 设计规范 ### 6.1 URL 规范 ``` 后台管理 API 统一前缀: /api/admin 认证相关: POST /api/admin/auth/login # 登录 POST /api/admin/auth/logout # 登出 GET /api/admin/auth/info # 获取当前用户信息 POST /api/admin/auth/refresh # 刷新 Token 菜单管理: GET /api/admin/menus # 菜单列表(树形) GET /api/admin/menus/{id} # 菜单详情 POST /api/admin/menus # 新增菜单 PUT /api/admin/menus/{id} # 编辑菜单 DELETE /api/admin/menus/{id} # 删除菜单 角色管理: GET /api/admin/roles # 角色列表 GET /api/admin/roles/{id} # 角色详情 POST /api/admin/roles # 新增角色 PUT /api/admin/roles/{id} # 编辑角色 DELETE /api/admin/roles/{id} # 删除角色 PUT /api/admin/roles/{id}/menus # 分配菜单 PUT /api/admin/roles/{id}/permissions # 分配权限 管理员管理: GET /api/admin/users # 管理员列表 GET /api/admin/users/{id} # 管理员详情 POST /api/admin/users # 新增管理员 PUT /api/admin/users/{id} # 编辑管理员 DELETE /api/admin/users/{id} # 删除管理员 PUT /api/admin/users/{id}/roles # 分配角色 PUT /api/admin/users/{id}/status # 启用/禁用 PUT /api/admin/users/{id}/password # 重置密码 ``` ### 6.2 响应格式 ```json // 成功响应 { "code": 0, "message": "success", "data": { ... } } // 分页响应 { "code": 0, "message": "success", "data": { "list": [...], "total": 100, "page": 1, "pageSize": 20 } } // 错误响应 { "code": 40001, "message": "用户名或密码错误", "data": null } ``` ### 6.3 错误码规范 | 错误码范围 | 说明 | |-----------|------| | 0 | 成功 | | 40001-40099 | 认证相关错误 | | 40101-40199 | 权限相关错误 | | 40201-40299 | 参数验证错误 | | 50001-50099 | 服务器内部错误 | --- ## 七、安全设计 ### 7.1 认证机制 - 使用 JWT Token 进行身份认证 - Token 有效期 24 小时，支持刷新 - 登录失败次数限制（5次锁定30分钟） - 支持多设备登录/单设备登录配置 ### 7.2 权限控制 - 基于 RBAC 模型 - 接口级别权限控制（通过 `[AdminPermission("user:list")]` 特性） - 菜单级别权限控制（前端动态路由） - 按钮级别权限控制（前端指令 `v-permission`） ### 7.3 安全措施 - 密码使用 BCrypt 加密存储 - 敏感操作记录操作日志 - 支持 IP 白名单 - 防止 SQL 注入（EF Core 参数化查询） - 防止 XSS 攻击（输入过滤） --- ## 八、HoneyBox.Admin 与业务系统的关系 ### 8.1 数据库关系 ``` honey_box (业务库) honey_box_admin (后台管理库) ┌─────────────────┐ ┌─────────────────┐ │ users │◄───────────│ admin_users │ (通过 user_id 关联查询) │ goods │ │ roles │ │ orders │ │ menus │ │ order_list │ │ permissions │ │ ... │ │ operation_logs │ └─────────────────┘ └─────────────────┘ ``` ### 8.2 代码引用关系 ```csharp // HoneyBox.Admin.csproj net8.0 ``` ### 8.3 复用到其他项目 当需要将 `HoneyBox.Admin` 复用到其他项目时： 1. **复制项目** - 将 `HoneyBox.Admin` 文件夹复制到新项目 2. **修改命名空间** - 可选，根据新项目命名规范调整 3. **配置数据库** - 修改 `appsettings.json` 中的连接字符串 4. **移除业务引用** - 删除对 `HoneyBox.Core/Model` 的引用 5. **注册服务** - 在新项目的 `Program.cs` 中调用扩展方法 ```csharp // 新项目中使用 builder.Services.AddHoneyBoxAdmin(options => { options.ConnectionString = "your-connection-string"; options.JwtSecret = "your-jwt-secret"; }); ``` --- ## 九、前端管理系统 (后续规划) ### 9.1 推荐方案 使用 Vue3 + Element Plus 构建现代化管理后台，可选择： 1. **从零搭建** - 完全自定义，灵活度高 2. **使用模板** - 如 vue-element-admin、vue-vben-admin ### 9.2 目录结构 (建议) ``` admin-web/ ├── src/ │ ├── api/ # API 接口 │ ├── assets/ # 静态资源 │ ├── components/ # 公共组件 │ ├── layout/ # 布局组件 │ ├── router/ # 路由配置 │ ├── store/ # 状态管理 │ ├── utils/ # 工具函数 │ └── views/ # 页面组件 │ ├── login/ # 登录页 │ ├── dashboard/ # 首页仪表盘 │ ├── system/ # 系统管理 │ │ ├── menu/ # 菜单管理 │ │ ├── role/ # 角色管理 │ │ └── user/ # 管理员管理 │ └── business/ # 业务模块 ├── package.json └── vite.config.js ``` --- ## 十、下一步行动 1. **确认本文档** - 确认架构设计和迁移策略 2. **创建项目结构** - 新建 `HoneyBox.Admin` 和 `HoneyBox.Admin.Model` 项目 3. **创建数据库** - 执行建表脚本创建 `honey_box_admin` 数据库 4. **实现登录认证** - 完成管理员登录 API 5. **实现权限框架** - 完成菜单、角色、权限管理 确认后我可以开始创建项目和代码。