<div align="center">

# LarAdmin

基于 Laravel + Swoole + Vue3 的高性能后台管理系统

[![Laravel](https://img.shields.io/badge/Laravel-12.0-red.svg)](https://laravel.com)
[![PHP](https://img.shields.io/badge/PHP-8.2+-blue.svg)](https://php.net)
[![Vue](https://img.shields.io/badge/Vue-3.5-brightgreen.svg)](https://vuejs.org)
[![Swoole](https://img.shields.io/badge/Swoole-Latest-orange.svg)](https://www.swoole.com)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

</div>

## 📖 项目简介

LarAdmin 是一个基于 Laravel 12 + Swoole + Vue3 的高性能后台管理系统，采用模块化架构设计，提供完整的认证授权、系统管理、业务扩展等功能。项目集成了 `hhxsv5/laravel-s` 实现 Swoole 长生命周期服务，大幅提升系统并发性能和响应速度。

### ✨ 核心特性

- 🚀 **高性能**：基于 Swoole 协程，支持高并发、低延迟
- 📦 **模块化**：采用 `nwidart/laravel-modules` 实现业务模块化管理
- 🔐 **完整权限**：基于 RBAC 的权限控制系统，支持用户、角色、权限、部门管理
- 🎨 **现代前端**：Vue 3 + Ant Design Vue + Vite 构建的现代化管理界面
- 📊 **数据管理**：支持数据导入导出、在线编辑、批量操作
- 🌐 **WebSocket**：内置 WebSocket 支持，实现实时通信
- 📝 **操作日志**：完整的操作日志记录和审计功能
- 🏙️ **城市数据**：内置全国省市区三级联动数据
- ⚙️ **系统配置**：灵活的系统配置管理，支持多种数据类型
- 🔄 **任务调度**：可视化的定时任务管理界面

## 🛠 技术栈

### 后端

- **PHP**: 8.2+
- **Laravel**: 12.0
- **Laravel-S**: 3.8+ (Swoole 集成)
- **Swoole**: 最新稳定版
- **JWT-Auth**: 2.2+ (用户认证)
- **Laravel Modules**: 12.0+ (模块化开发)

### 前端

- **Vue**: 3.5+
- **Vite**: 7.2+
- **Ant Design Vue**: 4.2+
- **Vue Router**: 5.0+
- **Pinia**: 3.0+ (状态管理)
- **Axios**: HTTP 客户端
- **Vue I18n**: 国际化支持
- **CKEditor 5**: 富文本编辑器
- **ECharts**: 数据可视化

## 📁 项目结构

```
laradmin/
├── app/                          # 基础模块目录
│   ├── Http/Controllers/         # 控制器
│   │   ├── Auth/                 # 认证模块控制器
│   │   │   └── Admin/
│   │   │       ├── Auth.php
│   │   │       ├── User.php
│   │   │       ├── Role.php
│   │   │       ├── Permission.php
│   │   │       └── Department.php
│   │   └── System/               # 系统模块控制器
│   │       ├── Admin/
│   │       │   ├── Config.php
│   │       │   ├── Log.php
│   │       │   ├── Dictionary.php
│   │       │   ├── Task.php
│   │       │   ├── City.php
│   │       │   └── Upload.php
│   │       ├── Api/
│   │       └── WebSocket.php
│   ├── Models/                   # 模型
│   │   ├── Auth/
│   │   │   ├── User.php
│   │   │   ├── Role.php
│   │   │   ├── Permission.php
│   │   │   └── Department.php
│   │   └── System/
│   ├── Services/                 # 服务层
│   │   ├── Auth/
│   │   ├── System/
│   │   └── WebSocket/
│   ├── Exports/                  # 导出类
│   ├── Imports/                  # 导入类
│   └── Middleware/               # 中间件
├── Modules/                      # 业务模块目录
│   └── ModuleName/               # 业务模块示例
│       ├── App/
│       │   ├── Http/Controllers/
│       │   │   ├── Admin/       # 后台管理控制器
│       │   │   └── Api/         # 用户端API控制器
│       │   ├── Models/
│       │   ├── Services/
│       │   └── Providers/
│       ├── Database/
│       │   ├── migrations/
│       │   └── seeders/
│       ├── Resources/
│       └── Routes/
│           ├── admin.php
│           └── api.php
├── resources/
│   ├── admin/                    # 前端管理界面
│   │   ├── src/
│   │   │   ├── api/             # API 接口
│   │   │   ├── components/      # 公共组件
│   │   │   │   ├── scForm/      # 表单组件
│   │   │   │   ├── scTable/     # 表格组件
│   │   │   │   ├── scUpload/    # 上传组件
│   │   │   │   ├── scEditor/    # 富文本编辑器
│   │   │   │   ├── scImport/    # 导入组件
│   │   │   │   └── scExport/    # 导出组件
│   │   │   ├── layouts/         # 布局组件
│   │   │   ├── pages/           # 页面组件
│   │   │   ├── router/          # 路由配置
│   │   │   ├── stores/          # 状态管理
│   │   │   ├── utils/           # 工具函数
│   │   │   ├── hooks/           # 组合式 API
│   │   │   └── i18n/            # 国际化
│   │   └── package.json
│   └── views/
├── routes/                       # 路由定义
│   ├── admin.php                 # 后台管理路由
│   ├── api.php                   # 公共API路由
│   └── web.php                   # Web路由
├── config/                       # 配置文件
│   ├── laravels.php              # Laravel-S配置
│   ├── jwt.php                   # JWT配置
│   └── modules.php               # 模块配置
├── database/                     # 数据库
│   ├── migrations/
│   └── seeders/
├── docs/                         # 文档目录
│   ├── README_AUTH.md            # Auth模块文档
│   ├── README_SYSTEM.md          # System模块文档
│   └── README_WEBSOCKET.md       # WebSocket文档
└── storage/                      # 存储目录
```

## 🚀 快速开始

### 环境要求

- PHP >= 8.2
- Composer >= 2.0
- Node.js >= 18.0
- npm >= 9.0
- Redis >= 6.0
- MySQL >= 8.0
- Swoole 扩展 (>= 4.8)

### 安装步骤

#### 1. 克隆项目

```bash
git clone http://git.tensent.cn/molong/laravel_swoole.git laradmin
cd laradmin
```

#### 2. 自动安装（推荐）

```bash
# 一键安装所有依赖并初始化
composer run setup
```

此命令会自动执行：
- 安装后端依赖
- 配置环境文件
- 生成应用密钥
- 执行数据库迁移
- 安装前端依赖
- 构建前端资源

#### 3. 手动安装

```bash
# 安装后端依赖
composer install

# 复制环境配置文件
cp .env.example .env

# 生成应用密钥
php artisan key:generate

# 配置数据库、Redis等参数
# 编辑 .env 文件

# 执行数据库迁移
php artisan migrate

# 填充初始数据
php artisan db:seed

# 生成 JWT 密钥
php artisan jwt:secret

# 安装前端依赖
cd resources/admin
npm install

# 构建前端
npm run build
```

### 运行项目

#### 开发模式

```bash
# 一键启动所有服务
composer run dev
```

此命令会启动：
- Laravel 开发服务器 (http://localhost:8000)
- 队列监听器
- 日志监控
- Vite 前端开发服务器

#### 分步启动

```bash
# 终端1: 启动 Laravel 开发服务器
php artisan serve

# 终端2: 启动前端开发服务器
cd resources/admin
npm run dev

# 终端3: 启动队列监听器（可选）
php artisan queue:listen
```

#### Swoole 模式（推荐生产环境）

```bash
# 启动 Laravel-S 服务
php bin/laravels start

# 停止服务
php bin/laravels stop

# 重启服务
php bin/laravels restart

# 重载服务（平滑重启）
php bin/laravels reload

# 查看状态
php bin/laravels status
```

访问地址：http://localhost:5200 (默认)

### 默认账号

```
用户名: admin
密码: 123456
```

## 📚 核心模块

### Auth 模块（认证授权）

提供完整的用户认证和权限管理功能：

- **用户管理**：用户增删改查、批量操作、导入导出
- **角色管理**：角色管理、权限分配、角色复制
- **权限管理**：权限树管理、菜单配置、按钮权限
- **部门管理**：部门树管理、组织架构
- **在线用户**：在线用户监控、强制下线

详细文档：[docs/README_AUTH.md](docs/README_AUTH.md)

### System 模块（系统管理）

提供系统级别的管理功能：

- **系统配置**：配置分组管理、多种数据类型支持
- **数据字典**：字典分类管理、字典项管理
- **操作日志**：日志记录、日志查询、日志统计
- **任务管理**：定时任务管理、手动执行、任务监控
- **城市数据**：省市区三级联动、城市树
- **文件上传**：单文件/多文件上传、Base64上传、图片压缩

详细文档：[docs/README_SYSTEM.md](docs/README_SYSTEM.md)

### WebSocket 模块

实时通信功能支持：

- 实时消息推送
- 在线状态同步
- 系统通知广播

详细文档：[docs/README_WEBSOCKET.md](docs/README_WEBSOCKET.md)

## 📖 API 文档

### 后台管理 API

基础路径：`/admin`

主要接口：

- `POST /admin/auth/login` - 用户登录
- `POST /admin/auth/logout` - 用户登出
- `GET /admin/users` - 获取用户列表
- `GET /admin/roles` - 获取角色列表
- `GET /admin/permissions` - 获取权限列表
- `GET /admin/configs` - 获取系统配置
- `GET /admin/logs` - 获取操作日志

详细接口文档请参考各模块文档。

### 公共 API

基础路径：`/api`

主要接口：

- `GET /api/system/configs` - 获取系统配置（公开）
- `GET /api/system/dictionaries` - 获取数据字典（公开）
- `GET /api/system/cities/tree` - 获取城市树（公开）

## 🔧 开发规范

### 后端开发规范

详细开发规范请参考：[.clinerules/rule.md](.clinerules/rule.md)

#### 命名规范

- **控制器**：不加 Controller 后缀，如 `User.php`
- **服务类**：以 Service 结尾，如 `UserService.php`
- **模型**：单数形式，如 `User.php`
- **数据表**：`{module}_{names}` 格式，如 `auth_users`

#### 模块开发

```bash
# 创建业务模块
php artisan module:make ModuleName

# 创建模块控制器
php artisan module:make-controller Admin/Post Blog

# 创建模块模型
php artisan module:make-model Post Blog
```

### 前端开发规范

详细开发规范请参考：[.clinerules/admin-rule.md](.clinerules/admin-rule.md)

#### 技术栈

- Vue 3 Composition API
- Ant Design Vue 4
- Pinia 状态管理
- Vue Router 路由

#### 组件开发

```vue
<script setup>
import { ref, onMounted } from 'vue'

const state = ref({})

onMounted(() => {
  // 组件挂载
})
</script>
```

## 🔐 权限系统

### RBAC 模型

项目采用基于角色的访问控制（RBAC）：

```
User (用户)
  ↓ N:N
Role (角色)
  ↓ N:N
Permission (权限)
```

### 权限编码规则

采用 `模块.功能.操作` 格式：

- `system.user.list` - 系统管理-用户-列表
- `system.user.create` - 系统管理-用户-创建
- `system.user.update` - 系统管理-用户-更新
- `system.user.delete` - 系统管理-用户-删除

### 权限类型

- **menu**: 菜单类型，用于前端路由配置
- **api**: API接口类型，用于后端权限验证
- **button**: 按钮类型，用于前端按钮权限控制

## ⚡ 性能优化

### Swoole 优化

- 长生命周期，减少框架启动开销
- 协程支持，提高并发处理能力
- 连接池管理，减少连接创建开销

### 缓存策略

- Redis 缓存权限数据（60分钟）
- Redis 缓存城市数据（永久）
- Redis 缓存配置数据（60分钟）
- 权限数据变更时自动清除缓存

### 数据库优化

- 使用 Eloquent 关联避免 N+1 查询
- 合理使用索引
- 分页查询避免全表扫描

## 📦 常用命令

### Laravel 命令

```bash
# 数据库迁移
php artisan migrate
php artisan migrate:rollback
php artisan migrate:refresh

# 数据填充
php artisan db:seed

# 清除缓存
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# 队列处理
php artisan queue:work
php artisan queue:listen

# 测试
php artisan test
```

### Laravel-S 命令

```bash
# 启动服务
php bin/laravels start

# 停止服务
php bin/laravels stop

# 重启服务
php bin/laravels restart

# 重载服务（平滑重启）
php bin/laravels reload

# 查看状态
php bin/laravels status

# 查看帮助
php bin/laravels help
```

### Laravel Modules 命令

```bash
# 创建模块
php artisan module:make ModuleName

# 列出所有模块
php artisan module:list

# 启用/禁用模块
php artisan module:enable ModuleName
php artisan module:disable ModuleName

# 模块迁移
php artisan module:migrate ModuleName
php artisan module:migrate-rollback ModuleName

# 模块数据填充
php artisan module:seed ModuleName
```

### 前端命令

```bash
cd resources/admin

# 开发
npm run dev

# 构建
npm run build

# 预览
npm run preview

# 代码检查
npm run lint

# 代码格式化
npm run format
```

## 🔍 Swoole 开发注意事项

### 长生命周期注意事项

由于 Swoole 是长生命周期运行，需要注意：

1. **避免使用静态变量**
   ```php
   // ❌ 错误
   static $counter = 0;
   
   // ✅ 正确
   $counter = 0;
   ```

2. **避免使用全局变量**
   - 不要依赖 `$_GET`, `$_POST` 等超全局变量
   - 使用 Laravel 的 `Request` 对象获取请求数据

3. **连接池管理**
   - 数据库、Redis 等连接需要正确管理
   - 在 `config/laravels.php` 中配置连接池

4. **热重载机制**
   ```bash
   # 平滑重启
   php bin/laravels reload
   
   # 或使用文件监控（开发环境）
   bin/fswatch  # Linux/Mac
   bin/inotify  # Linux
   ```

## 🌟 特色功能

### 1. 动态菜单路由

前端支持动态路由加载，登录后自动根据权限生成菜单树：

```javascript
// 登录后获取菜单
const menus = await authApi.permissions.menu.get()
userStore.setMenu(menus)
```

### 2. 权限指令

前端提供权限指令，方便控制元素显示：

```vue
<!-- 只有拥有 user.create 权限时显示 -->
<a-button v-permission="'user.create'">新增</a-button>

<!-- 拥有多个权限之一时显示 -->
<a-button v-permission="['user.create', 'user.update']">编辑</a-button>
```

### 3. 数据导入导出

支持 Excel 数据导入导出：

```javascript
// 导出用户数据
await userApi.export.post(params)

// 导入用户数据
await userApi.import.post(formData)
```

### 4. 富文本编辑器

集成 CKEditor 5 富文本编辑器：

```vue
<sc-editor
  v-model="content"
  :height="400"
/>
```

### 5. 文件上传

支持多种上传方式：

```vue
<!-- 图片上传 -->
<sc-upload
  v-model="imageUrl"
  :limit="1"
  accept="image/*"
  list-type="picture-card"
/>

<!-- 文件上传 -->
<sc-upload
  v-model="fileList"
  :limit="5"
  :max-size="10"
/>
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

### Git 提交规范

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 类型：**
- `feat`: 新功能
- `fix`: 修复
- `docs`: 文档
- `style`: 格式
- `refactor`: 重构
- `test`: 测试
- `chore`: 构建/工具

**示例：**
```
feat(auth): 添加用户登录功能

- 实现 JWT 认证
- 添加登录接口
- 完善权限验证

Closes #123
```

## 📄 开源协议

本项目采用 MIT 协议开源。

## 📞 联系方式

如有问题或建议，欢迎联系：

- 项目地址：http://git.tensent.cn/molong/laravel_swoole
- Issue 提交：http://git.tensent.cn/molong/laravel_swoole/issues

## 🙏 致谢

感谢以下开源项目：

- [Laravel](https://laravel.com)
- [Swoole](https://www.swoole.com)
- [Laravel-S](https://github.com/hhxsv5/laravel-s)
- [Vue.js](https://vuejs.org)
- [Ant Design Vue](https://antdv.com)
- [Laravel Modules](https://nwidart.com/laravel-modules)
- [CKEditor 5](https://ckeditor.com)
- [ECharts](https://echarts.apache.org)

## 📝 更新日志

### v1.0.0 (2024-01-01)

- 🎉 初始版本发布
- ✅ 完成 Auth 模块（用户、角色、权限、部门）
- ✅ 完成 System 模块（配置、日志、字典、任务、城市、上传）
- ✅ 集成 Swoole 高性能服务
- ✅ 完成前端 Vue3 管理界面
- ✅ 实现 WebSocket 实时通信

---

<div align="center">

**LarAdmin** - 高性能后台管理系统

Made with ❤️ by [Tensent](http://git.tensent.cn)

</div>
