init

2026-01-16 15:49:34 +08:00
commit 550d3e1f42
380 changed files with 62024 additions and 0 deletions
@@ -0,0 +1,509 @@
+# 系统架构文档
+
+本文档描述 Goravel Admin 后台管理系统的整体架构设计。
+
+## 目录
+
+- [系统概览](#系统概览)
+- [技术架构](#技术架构)
+- [后端架构](#后端架构)
+- [前端架构](#前端架构)
+- [数据库设计](#数据库设计)
+- [安全架构](#安全架构)
+- [部署架构](#部署架构)
+
+---
+
+## 系统概览
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         客户端 (Browser)                         │
+├─────────────────────────────────────────────────────────────────┤
+│                    Vue 3 SPA (Element Plus)                      │
+├─────────────────────────────────────────────────────────────────┤
+│                         Nginx / CDN                              │
+├─────────────────────────────────────────────────────────────────┤
+│                      Goravel API Server                          │
+├─────────────────────────────────────────────────────────────────┤
+│           MySQL / PostgreSQL          │         Redis            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 技术架构
+
+### 技术栈
+
+| 层级 | 技术 | 版本 |
+|------|------|------|
+| **后端框架** | Goravel | v1.14+ |
+| **编程语言** | Go | 1.21+ |
+| **前端框架** | Vue | 3.4+ |
+| **UI 组件** | Element Plus | 2.4+ |
+| **表格组件** | VXE-Table | 4.7+ |
+| **状态管理** | Pinia | 2.1+ |
+| **数据库** | MySQL/PostgreSQL | 8.0+ / 15+ |
+| **缓存** | Redis | 7.0+ |
+| **认证** | JWT | - |
+
+### 架构模式
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          前端 (Vue 3)                            │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
+│  │  Views   │  │Components│  │Composables│ │    Store (Pinia) │ │
+│  └────┬─────┘  └────┬─────┘  └────┬──────┘ └────────┬─────────┘ │
+│       └─────────────┴─────────────┴─────────────────┘           │
+│                              │ API                               │
+├──────────────────────────────┼──────────────────────────────────┤
+│                          后端 (Goravel)                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
+│  │  Controllers │  │  Middleware  │  │      Routes          │   │
+│  └──────┬───────┘  └──────┬───────┘  └──────────────────────┘   │
+│         │                 │                                      │
+│  ┌──────▼───────┐  ┌──────▼───────┐                             │
+│  │   Services   │  │   Helpers    │                             │
+│  └──────┬───────┘  └──────────────┘                             │
+│         │                                                        │
+│  ┌──────▼───────┐  ┌──────────────┐  ┌──────────────────────┐   │
+│  │    Models    │  │    Events    │  │       Jobs           │   │
+│  └──────┬───────┘  └──────────────┘  └──────────────────────┘   │
+├─────────┼───────────────────────────────────────────────────────┤
+│         ▼                                                        │
+│  ┌──────────────┐  ┌──────────────┐                             │
+│  │   Database   │  │    Redis     │                             │
+│  └──────────────┘  └──────────────┘                             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 后端架构
+
+### 目录结构
+
+```
+app/
+├── console/                 # 命令行
+│   └── commands/           # 自定义命令
+├── http/
+│   ├── controllers/        # 控制器
+│   │   └── admin/         # 后台管理控制器
+│   ├── middleware/         # 中间件
+│   ├── requests/           # 请求验证
+│   ├── helpers/            # 辅助函数
+│   ├── response/           # 统一响应
+│   └── trans/              # 翻译工具
+├── models/                  # 数据模型
+├── services/                # 业务逻辑
+├── utils/                   # 工具函数
+│   ├── logger/            # 日志工具
+│   ├── traceid/           # 链路追踪
+│   └── errorlog/          # 错误日志
+├── events/                  # 事件
+├── listeners/               # 事件监听器
+├── jobs/                    # 队列任务
+├── providers/               # 服务提供者
+├── rules/                   # 自定义验证规则
+└── websocket/               # WebSocket
+    └── notifications/      # 通知推送
+```
+
+### 分层架构
+
+#### 1. 控制器层 (Controllers)
+
+负责接收请求、验证参数、调用服务、返回响应。
+
+```go
+// app/http/controllers/admin/admin_controller.go
+func (a *AdminController) Index(ctx http.Context) http.Response {
+    // 1. 获取查询参数
+    // 2. 调用 Service 获取数据
+    // 3. 返回统一响应
+}
+```
+
+#### 2. 服务层 (Services)
+
+封装业务逻辑，可被多个控制器复用。
+
+```go
+// app/services/admin_service.go
+type AdminService struct{}
+
+func (s *AdminService) GetAdminWithRoles(id uint) (*models.Admin, error) {
+    // 业务逻辑处理
+}
+```
+
+#### 3. 模型层 (Models)
+
+定义数据结构和数据库映射。
+
+```go
+// app/models/admin.go
+type Admin struct {
+    orm.Model
+    Username     string       `gorm:"size:50;uniqueIndex" json:"username"`
+    Password     string       `gorm:"size:255" json:"-"`
+    Roles        []*Role      `gorm:"many2many:admin_role" json:"roles,omitempty"`
+}
+```
+
+#### 4. 中间件层 (Middleware)
+
+处理认证、权限、日志等横切关注点。
+
+```go
+// 中间件执行顺序
+Request → TraceID → JWT Auth → Permission → Controller → OperationLog → Response
+```
+
+**核心中间件：**
+
+| 中间件 | 功能 |
+|--------|------|
+| `jwt.go` | JWT 认证 |
+| `permission.go` | 权限验证 |
+| `operation_log.go` | 操作日志记录 |
+| `blacklist.go` | IP 黑名单检查 |
+| `rate_limiter.go` | 请求限流 |
+| `trace_id.go` | 链路追踪 |
+
+### 统一响应
+
+```go
+// 成功响应
+response.Success(ctx, data)
+
+// 错误响应
+response.Error(ctx, http.StatusBadRequest, "错误信息")
+
+// 泛型查找
+admin, resp := response.FindByID[models.Admin](ctx, id, nil)
+```
+
+---
+
+## 前端架构
+
+### 目录结构
+
+```
+html/src/
+├── api/                     # API 请求
+├── components/              # 通用组件
+│   ├── SearchForm.vue      # 搜索表单
+│   ├── Pagination.vue      # 分页组件
+│   ├── ErrorBoundary.vue   # 错误边界
+│   └── ColumnSettingDialog.vue  # 列设置
+├── composables/             # 可复用逻辑 (TypeScript)
+│   ├── useCrud.ts          # CRUD 操作
+│   ├── useDebounce.ts      # 防抖
+│   ├── useTableSort.ts     # 表格排序
+│   ├── usePermission.ts    # 权限检查
+│   ├── useListPage.js      # 列表页面
+│   └── useColumnSetting.js # 列设置
+├── i18n/                    # 国际化
+│   └── locales/
+│       ├── zh-CN.json
+│       └── en-US.json
+├── layouts/                 # 布局组件
+├── router/                  # 路由配置
+├── store/                   # 状态管理 (Pinia)
+│   ├── user.js             # 用户状态
+│   ├── app.js              # 应用状态
+│   └── tabs.js             # 标签页状态
+├── types/                   # TypeScript 类型
+│   ├── index.d.ts          # 实体类型
+│   └── composables.d.ts    # Composable 类型
+├── utils/                   # 工具函数
+│   ├── request.js          # Axios 封装
+│   ├── storage.js          # 存储工具
+│   └── validation.js       # 验证器
+└── views/                   # 页面组件
+    ├── admin/
+    ├── role/
+    ├── menu/
+    └── ...
+```
+
+### Composables 设计
+
+核心 Composables 采用 TypeScript 编写，提供完整类型支持：
+
+```typescript
+// useCrud.ts - CRUD 操作封装
+const { 
+  dialogVisible,      // 对话框状态
+  editId,             // 编辑ID
+  handleAdd,          // 添加
+  handleEdit,         // 编辑
+  handleDelete,       // 删除
+  handleBatchDelete   // 批量删除
+} = useCrud({ deleteApi, batchDeleteApi })
+```
+
+```typescript
+// usePermission.ts - 权限检查
+const { 
+  hasPermission,      // 检查权限
+  shouldShowButton,   // 是否显示按钮
+  getButtonState      // 获取按钮状态
+} = usePermission()
+```
+
+### 状态管理
+
+```
+┌─────────────────────────────────────────┐
+│              Pinia Store                 │
+├─────────────┬─────────────┬─────────────┤
+│  userStore  │  appStore   │  tabsStore  │
+├─────────────┼─────────────┼─────────────┤
+│ - userInfo  │ - sidebar   │ - tabs      │
+│ - token     │ - fullscreen│ - activeTab │
+│ - menus     │ - language  │             │
+│ - permissions│            │             │
+└─────────────┴─────────────┴─────────────┘
+```
+
+---
+
+## 数据库设计
+
+### ER 图
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   admins    │─────│ admin_role  │─────│    roles    │
+├─────────────┤     ├─────────────┤     ├─────────────┤
+│ id          │     │ admin_id    │     │ id          │
+│ username    │     │ role_id     │     │ name        │
+│ password    │     └─────────────┘     │ slug        │
+│ department_id│                        │ status      │
+└──────┬──────┘                        └──────┬──────┘
+       │                                       │
+       │    ┌─────────────┐                   │
+       │    │ departments │                   │
+       └────┤             │     ┌─────────────┴─────────────┐
+            │ id          │     │       role_permission      │
+            │ name        │     ├───────────────────────────┤
+            │ parent_id   │     │ role_id                   │
+            └─────────────┘     │ permission_id             │
+                               └─────────────┬─────────────┘
+                                             │
+                               ┌─────────────▼─────────────┐
+                               │       permissions         │
+                               ├───────────────────────────┤
+                               │ id                        │
+                               │ name                      │
+                               │ slug                      │
+                               │ method                    │
+                               │ path                      │
+                               │ menu_id                   │
+                               └───────────────────────────┘
+```
+
+### 核心表结构
+
+| 表名 | 说明 |
+|------|------|
+| `admins` | 管理员 |
+| `roles` | 角色 |
+| `permissions` | 权限 |
+| `menus` | 菜单 |
+| `departments` | 部门 |
+| `dictionaries` | 字典 |
+| `blacklists` | 黑名单 |
+| `operation_logs` | 操作日志 |
+| `login_logs` | 登录日志 |
+| `system_logs` | 系统日志 |
+| `personal_access_tokens` | Token 管理 |
+| `notifications` | 通知 |
+| `attachments` | 附件 |
+| `exports` | 导出任务 |
+
+---
+
+## 安全架构
+
+### 认证流程
+
+```
+┌─────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  Login  │───▶│ Validate    │───▶│ Generate    │───▶│   Return    │
+│ Request │    │ Credentials │    │   JWT       │    │   Token     │
+└─────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+                     │
+                     ▼
+              ┌─────────────┐
+              │ Rate Limit  │
+              │   Check     │
+              └─────────────┘
+```
+
+### 权限验证流程
+
+```
+Request → JWT Middleware → Permission Middleware → Controller
+              │                    │
+              ▼                    ▼
+        验证 Token           检查权限
+              │                    │
+              ▼                    ▼
+        解析用户信息         匹配路由权限
+              │                    │
+              ▼                    ▼
+        写入 Context         允许/拒绝
+```
+
+### 安全特性
+
+| 特性 | 实现方式 |
+|------|----------|
+| **认证** | JWT Token + 滑动过期 |
+| **授权** | RBAC 权限模型 |
+| **限流** | Token Bucket 算法 |
+| **黑名单** | IP/Token 双重黑名单 |
+| **日志** | 操作/登录日志全记录 |
+| **追踪** | TraceID 链路追踪 |
+| **敏感字段** | 密码等字段 `json:"-"` |
+
+---
+
+## 部署架构
+
+### 单机部署
+
+```
+┌────────────────────────────────────────┐
+│              Server                     │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
+│  │  Nginx  │──│ Goravel │──│  MySQL  │ │
+│  └─────────┘  └─────────┘  └─────────┘ │
+│                    │                    │
+│               ┌────▼────┐              │
+│               │  Redis  │              │
+│               └─────────┘              │
+└────────────────────────────────────────┘
+```
+
+### 高可用部署
+
+```
+                    ┌─────────────┐
+                    │   Client    │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │     CDN     │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │ Load Balancer│
+                    └──────┬──────┘
+           ┌───────────────┼───────────────┐
+           │               │               │
+    ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
+    │   Goravel   │ │   Goravel   │ │   Goravel   │
+    │   Server 1  │ │   Server 2  │ │   Server 3  │
+    └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
+           │               │               │
+           └───────────────┼───────────────┘
+                           │
+              ┌────────────┼────────────┐
+              │                         │
+       ┌──────▼──────┐          ┌──────▼──────┐
+       │ MySQL Master│──────────│ Redis Cluster│
+       └──────┬──────┘          └──────────────┘
+              │
+       ┌──────▼──────┐
+       │ MySQL Slave │
+       └─────────────┘
+```
+
+### Docker 部署
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    depends_on:
+      - mysql
+      - redis
+
+  mysql:
+    image: mysql:8.0
+    volumes:
+      - mysql_data:/var/lib/mysql
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis_data:/data
+```
+
+---
+
+## 性能优化
+
+### 后端优化
+
+| 优化项 | 实现 |
+|--------|------|
+| 数据库连接池 | 配置合理的连接数 |
+| 查询优化 | 预加载关联、索引优化 |
+| 缓存策略 | Redis 缓存热点数据 |
+| 日志分级 | Debug/Info 分离 |
+
+### 前端优化
+
+| 优化项 | 实现 |
+|--------|------|
+| 虚拟滚动 | VXE-Table 大数据渲染 |
+| 代码分割 | 路由懒加载 |
+| 状态管理 | Pinia 响应式优化 |
+| 防抖节流 | useDebounce composable |
+
+---
+
+## 扩展指南
+
+### 添加新模块
+
+1. **后端**
+   - 创建 Model: `app/models/xxx.go`
+   - 创建 Controller: `app/http/controllers/admin/xxx_controller.go`
+   - 创建 Request: `app/http/requests/admin/xxx_request.go`
+   - 注册路由: `routes/admin.go`
+
+2. **前端**
+   - 创建 API: `html/src/api/xxx.js`
+   - 创建页面: `html/src/views/xxx/XxxList.vue`
+   - 创建表单: `html/src/views/xxx/XxxForm.vue`
+   - 注册路由: `html/src/router/index.js`
+
+### 添加新权限
+
+1. 数据库添加权限记录 (`permissions` 表)
+2. 关联到菜单 (`menu_id`)
+3. 分配给角色 (`role_permission` 表)
+
+---
+
+## 参考资料
+
+- [Goravel 官方文档](https://www.goravel.dev)
+- [Vue 3 文档](https://vuejs.org)
+- [Element Plus 文档](https://element-plus.org)
+- [VXE-Table 文档](https://vxetable.cn)
+