24 KiB
24 KiB
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 是一个独立可复用的后台管理模块，具有以下特点：
- 自包含 - 内部包含 Entities、Services、DbContext，不依赖外部 Model 层
- 可移植 - 可以轻松复制到其他项目中使用
- 松耦合 - 通过可选引用
HoneyBox.Core/Model来访问业务数据 - 独立数据库 - 使用独立的
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)
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)
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)
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)
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 关联表
-- 管理员-角色关联
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)
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 响应格式
// 成功响应
{
"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 代码引用关系
// HoneyBox.Admin.csproj
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
</PropertyGroup>
<!-- 自包含的依赖 -->
<ItemGroup>
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.0" />
<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.0" />
<PackageReference Include="BCrypt.Net-Next" Version="4.0.3" />
<PackageReference Include="Mapster" Version="7.4.0" />
</ItemGroup>
<!-- 可选: 引用业务层访问业务数据 -->
<ItemGroup Condition="'$(IncludeBusinessLayer)' == 'true'">
<ProjectReference Include="..\HoneyBox.Core\HoneyBox.Core.csproj" />
<ProjectReference Include="..\HoneyBox.Model\HoneyBox.Model.csproj" />
</ItemGroup>
</Project>
8.3 复用到其他项目
当需要将 HoneyBox.Admin 复用到其他项目时：
- 复制项目 - 将
HoneyBox.Admin文件夹复制到新项目 - 修改命名空间 - 可选，根据新项目命名规范调整
- 配置数据库 - 修改
appsettings.json中的连接字符串 - 移除业务引用 - 删除对
HoneyBox.Core/Model的引用 - 注册服务 - 在新项目的
Program.cs中调用扩展方法
// 新项目中使用
builder.Services.AddHoneyBoxAdmin(options =>
{
options.ConnectionString = "your-connection-string";
options.JwtSecret = "your-jwt-secret";
});
九、前端管理系统 (后续规划)
9.1 推荐方案
使用 Vue3 + Element Plus 构建现代化管理后台，可选择：
- 从零搭建 - 完全自定义，灵活度高
- 使用模板 - 如 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
十、下一步行动
- 确认本文档 - 确认架构设计和迁移策略
- 创建项目结构 - 新建
HoneyBox.Admin和HoneyBox.Admin.Model项目 - 创建数据库 - 执行建表脚本创建
honey_box_admin数据库 - 实现登录认证 - 完成管理员登录 API
- 实现权限框架 - 完成菜单、角色、权限管理
确认后我可以开始创建项目和代码。