molong/laravel_swoole

Template

Fork 0

Files

molong 334d2c6312 初始化项目

2026-02-08 22:38:13 +08:00

18 KiB

Raw Blame History

System 基础模块文档

概述

System 基础模块提供了完整的系统管理功能，包括系统配置、数据字典、操作日志、任务管理、城市数据和文件上传等功能。

控制器结构

app/Http/Controllers/System/
├── Admin/                    # 后台管理控制器
│   ├── Config.php            # 系统配置控制器
│   ├── Log.php               # 操作日志控制器
│   ├── Dictionary.php        # 数据字典控制器
│   ├── Task.php              # 任务管理控制器
│   ├── City.php              # 城市数据控制器
│   └── Upload.php           # 文件上传控制器
└── Api/                     # 公共API控制器
    ├── Config.php            # 系统配置API
    ├── Dictionary.php        # 数据字典API
    ├── City.php              # 城市数据API
    └── Upload.php           # 文件上传API

Admin 控制器

命名空间: App\Http\Controllers\System\Admin

路由前缀: /admin

中间件: auth.check:admin (后台管理认证)

Api 控制器

命名空间: App\Http\Controllers\System\Api

路由前缀: /api

中间件: auth:api (API认证，部分接口为公开接口)

技术栈

PHP 8.1+
Laravel 11
Redis 缓存
Intervention Image (图像处理)

数据库表结构

system_configs (系统配置表)

id: 主键
group: 配置分组（如：system, site, upload）
key: 配置键（唯一）
value: 配置值（JSON格式）
type: 数据类型（string, number, boolean, array, image, file）
name: 配置名称
description: 配置描述
options: 可选值（JSON数组）
sort: 排序
status: 状态（0:禁用, 1:启用）
created_at, updated_at: 时间戳

system_dictionaries (数据字典分类表)

id: 主键
name: 字典名称
code: 字典编码（唯一）
description: 描述
sort: 排序
status: 状态
created_at, updated_at: 时间戳

system_dictionary_items (数据字典项表)

id: 主键
dictionary_id: 字典ID
label: 显示标签
value: 实际值
sort: 排序
status: 状态
created_at, updated_at: 时间戳

system_logs (操作日志表)

id: 主键
user_id: 用户ID
username: 用户名
module: 模块
action: 操作
method: 请求方法
url: 请求URL
ip: IP地址
user_agent: 用户代理
request_data: 请求数据（JSON）
response_data: 响应数据（JSON）
duration: 执行时间（毫秒）
status_code: 状态码
created_at: 创建时间

system_tasks (任务表)

id: 主键
name: 任务名称
code: 任务编码（唯一）
command: 命令
description: 描述
cron_expression: Cron表达式
status: 状态（0:禁用, 1:启用, 2:运行中, 3:失败）
last_run_at: 最后运行时间
next_run_at: 下次运行时间
run_count: 运行次数
fail_count: 失败次数
last_message: 最后运行消息
sort: 排序
created_at, updated_at: 时间戳

system_cities (城市表)

id: 主键
name: 城市名称
code: 城市编码
level: 级别（1:省, 2:市, 3:区县）
parent_id: 父级ID
adcode: 行政区划编码
sort: 排序
status: 状态
created_at, updated_at: 时间戳

Admin API 接口文档

系统配置管理

获取配置列表

接口: GET /admin/configs
参数:
- page: 页码（默认1）
- page_size: 每页数量（默认20）
- keyword: 搜索关键词
- group: 配置分组
- status: 状态
- order_by, order_direction: 排序

获取所有配置分组

接口: GET /admin/configs/groups

按分组获取配置

接口: GET /admin/configs/all
参数:
- group: 配置分组（可选）

获取配置详情

接口: GET /admin/configs/{id}

创建配置

接口: POST /admin/configs

参数:

{
  "group": "site",
  "key": "site_name",
  "name": "网站名称",
  "description": "网站显示的名称",
  "type": "string",
  "value": "\"我的网站\"",
  "options": null,
  "sort": 1,
  "status": 1
}

数据类型说明:
- string: 字符串
- number: 数字
- boolean: 布尔值
- array: 数组
- image: 图片
- file: 文件

更新配置

接口: PUT /admin/configs/{id}

删除配置

接口: DELETE /admin/configs/{id}

批量删除配置

接口: POST /admin/configs/batch-delete
参数:
```
{
  "ids": [1, 2, 3]
}
```

批量更新配置状态

接口: POST /admin/configs/batch-status
参数:
```
{
  "ids": [1, 2, 3],
  "status": 1
}
```

操作日志管理

获取日志列表

接口: GET /admin/logs
参数:
- page, page_size
- keyword: 搜索关键词（用户名/模块/操作）
- module: 模块
- action: 操作
- user_id: 用户ID
- start_date: 开始日期
- end_date: 结束日期
- order_by, order_direction

获取日志详情

接口: GET /admin/logs/{id}

删除日志

接口: DELETE /admin/logs/{id}

批量删除日志

接口: POST /admin/logs/batch-delete
参数:
```
{
  "ids": [1, 2, 3]
}
```

清理日志

接口: POST /admin/logs/clear
参数:
```
{
  "days": 30
}
```
说明: 删除指定天数之前的日志记录

获取日志统计

接口: GET /admin/logs/statistics
参数:
- start_date: 开始日期
- end_date: 结束日期

{
  "code": 200,
  "message": "success",
  "data": {
    "total_count": 1000,
    "module_stats": [
      {
        "module": "user",
        "count": 500
      }
    ],
    "user_stats": [
      {
        "user_id": 1,
        "username": "admin",
        "count": 800
      }
    ]
  }
}

数据字典管理

获取字典列表

接口: GET /admin/dictionaries
参数:
- page, page_size, keyword, status, order_by, order_direction

获取所有字典

接口: GET /admin/dictionaries/all

获取字典详情

接口: GET /admin/dictionaries/{id}

创建字典

接口: POST /admin/dictionaries

参数:

{
  "name": "用户状态",
  "code": "user_status",
  "description": "用户状态字典",
  "sort": 1,
  "status": 1
}

更新字典

接口: PUT /admin/dictionaries/{id}

删除字典

接口: DELETE /admin/dictionaries/{id}

批量删除字典

接口: POST /admin/dictionaries/batch-delete

批量更新字典状态

接口: POST /admin/dictionaries/batch-status

数据字典项管理

获取字典项列表

接口: GET /admin/dictionary-items
参数:
- page, page_size
- dictionary_id: 字典ID（必需）
- keyword: 搜索关键词
- status, order_by, order_direction

创建字典项

接口: POST /admin/dictionary-items

参数:

{
  "dictionary_id": 1,
  "label": "正常",
  "value": "1",
  "sort": 1,
  "status": 1
}

更新字典项

接口: PUT /admin/dictionary-items/{id}

删除字典项

接口: DELETE /admin/dictionary-items/{id}

批量删除字典项

接口: POST /admin/dictionary-items/batch-delete

批量更新字典项状态

接口: POST /admin/dictionary-items/batch-status

任务管理

获取任务列表

接口: GET /admin/tasks
参数:
- page, page_size, keyword, status, order_by, order_direction

获取所有任务

接口: GET /admin/tasks/all

获取任务详情

接口: GET /admin/tasks/{id}

创建任务

接口: POST /admin/tasks

参数:

{
  "name": "清理临时文件",
  "code": "cleanup_temp_files",
  "command": "cleanup:temp",
  "description": "每天清理过期临时文件",
  "cron_expression": "0 2 * * *",
  "sort": 1,
  "status": 1
}

Cron表达式说明:
- 格式：分时日月周
- 示例：0 2 * * * (每天凌晨2点执行)
- 示例：*/5 * * * * (每5分钟执行一次)

更新任务

接口: PUT /admin/tasks/{id}

删除任务

接口: DELETE /admin/tasks/{id}

批量删除任务

接口: POST /admin/tasks/batch-delete

批量更新任务状态

接口: POST /admin/tasks/batch-status

手动执行任务

接口: POST /admin/tasks/{id}/run
说明: 立即执行指定任务

获取任务统计

接口: GET /admin/tasks/statistics

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 10,
    "enabled": 8,
    "disabled": 2,
    "running": 0,
    "failed": 0
  }
}

城市数据管理

获取城市列表

接口: GET /admin/cities
参数:
- page, page_size, keyword, level, parent_id, status
- order_by, order_direction

获取城市树

接口: GET /admin/cities/tree
说明: 从缓存中获取完整的三级城市树

获取城市详情

接口: GET /admin/cities/{id}

获取子级城市

接口: GET /admin/cities/{id}/children
说明: 获取指定城市的下级城市

获取所有省份

接口: GET /admin/cities/provinces

获取指定省份的城市

接口: GET /admin/cities/{provinceId}/cities

获取指定城市的区县

接口: GET /admin/cities/{cityId}/districts

创建城市

接口: POST /admin/cities

参数:

{
  "name": "北京市",
  "code": "110000",
  "level": 1,
  "parent_id": 0,
  "adcode": "110000",
  "sort": 1,
  "status": 1
}

级别说明:
- 1: 省级
- 2: 市级
- 3: 区县级

更新城市

接口: PUT /admin/cities/{id}

删除城市

接口: DELETE /admin/cities/{id}

批量删除城市

接口: POST /admin/cities/batch-delete

批量更新城市状态

接口: POST /admin/cities/batch-status

文件上传管理

单文件上传

接口: POST /admin/upload
参数:
- file: 文件（multipart/form-data，最大10MB）
- directory: 存储目录（默认：uploads）
- compress: 是否压缩图片（默认：false）
- quality: 图片质量（1-100，默认：80）
- width: 压缩宽度（可选）
- height: 压缩高度（可选）

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "http://example.com/uploads/2024/01/xxx.jpg",
    "path": "uploads/2024/01/xxx.jpg",
    "name": "xxx.jpg",
    "size": 102400,
    "mime_type": "image/jpeg"
  }
}

多文件上传

接口: POST /admin/upload/multiple
参数:
- files: 文件数组（multipart/form-data）
- 其他参数同单文件上传
返回: 文件数组

Base64上传

接口: POST /admin/upload/base64

参数:

{
  "base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
  "directory": "uploads",
  "file_name": "image.jpg"
}

删除文件

接口: POST /admin/upload/delete

参数:

{
  "path": "uploads/2024/01/xxx.jpg"
}

批量删除文件

接口: POST /admin/upload/batch-delete

参数:

{
  "paths": [
    "uploads/2024/01/xxx.jpg",
    "uploads/2024/01/yyy.jpg"
  ]
}

Public API 接口文档

系统配置 API

获取所有配置

接口: GET /api/system/configs
认证: 公开接口（无需认证）

{
  "code": 200,
  "message": "success",
  "data": {
    "site_name": "我的网站",
    "site_logo": "/uploads/logo.png"
  }
}

按分组获取配置

接口: GET /api/system/configs/group
参数:
- group: 配置分组
认证: 公开接口

根据键获取配置

接口: GET /api/system/configs/key
参数:
- key: 配置键
认证: 公开接口

数据字典 API

获取所有字典

接口: GET /api/system/dictionaries
认证: 公开接口

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "code": "user_status",
      "name": "用户状态",
      "items": [...]
    }
  ]
}

根据编码获取字典项

接口: GET /api/system/dictionaries/code
参数:
- code: 字典编码
认证: 公开接口

{
  "code": 200,
  "message": "success",
  "data": {
    "code": "user_status",
    "items": [
      {"label": "正常", "value": "1"},
      {"label": "禁用", "value": "0"}
    ]
  }
}

获取字典详情

接口: GET /api/system/dictionaries/{id}
认证: 公开接口

城市数据 API

获取城市树

接口: GET /api/system/cities/tree
认证: 公开接口
说明: 从缓存中获取完整的三级城市树

获取所有省份

接口: GET /api/system/cities/provinces
认证: 公开接口

获取指定省份的城市

接口: GET /api/system/cities/{provinceId}/cities
认证: 公开接口

获取指定城市的区县

接口: GET /api/system/cities/{cityId}/districts
认证: 公开接口

获取城市详情

接口: GET /api/system/cities/{id}
认证: 公开接口

文件上传 API

单文件上传

接口: POST /api/system/upload
认证: 需要认证（auth:api）
参数: 同Admin上传接口

多文件上传

接口: POST /api/system/upload/multiple
认证: 需要认证（auth:api）
参数: 同Admin上传接口

Base64上传

接口: POST /api/system/upload/base64
认证: 需要认证（auth:api）
参数: 同Admin上传接口

缓存机制

城市数据缓存

缓存键: city:tree
过期时间: 永久（手动清除）
更新时机: 城市数据增删改时自动清除

系统配置缓存

缓存键: config:all 或 config:group:{group}
过期时间: 60分钟
更新时机: 配置数据增删改时自动清除

数据字典缓存

缓存键: dictionary:all 或 dictionary:code:{code}
过期时间: 60分钟
更新时机: 字典数据增删改时自动清除

服务层说明

ConfigService

提供系统配置的CRUD操作和缓存管理。

主要方法:

getList(): 获取配置列表
getByGroup(): 按分组获取配置
getConfigValue(): 获取配置值
create(): 创建配置
update(): 更新配置
delete(): 删除配置

LogService

提供操作日志的记录、查询和清理功能。

主要方法:

getList(): 获取日志列表
getStatistics(): 获取统计数据
clearLogs(): 清理过期日志
record(): 记录日志（由中间件自动调用）

DictionaryService

提供数据字典和字典项的管理功能。

主要方法:

getList(): 获取字典列表
getItemsByCode(): 按编码获取字典项
create(): 创建字典
createItem(): 创建字典项
update(): 更新字典
updateItem(): 更新字典项

TaskService

提供任务的管理和执行功能。

主要方法:

getList(): 获取任务列表
run(): 手动执行任务
getStatistics(): 获取任务统计
updateStatus(): 更新任务状态

CityService

提供城市数据的管理和缓存功能。

主要方法:

getList(): 获取城市列表
getCachedTree(): 从缓存获取城市树
getProvinces(): 获取省份列表
getCities(): 获取城市列表
getDistricts(): 获取区县列表

UploadService

提供文件上传和删除功能。

主要方法:

upload(): 单文件上传
uploadMultiple(): 多文件上传
uploadBase64(): Base64上传
delete(): 删除文件
compressImage(): 图片压缩

初始化数据

# 执行迁移
php artisan migrate

# 填充初始数据
php artisan db:seed --class=SystemSeeder

初始数据包括：

基础系统配置
常用数据字典
全国省市区数据

注意事项

Swoole环境注意事项:
- 文件上传时注意临时文件清理
- 使用Redis缓存避免内存泄漏
- 图片压缩使用协程安全的方式
安全注意事项:
- 文件上传必须验证文件类型和大小
- 敏感操作必须记录日志
- 配置数据不要存储密码等敏感信息
性能优化:
- 城市数据使用Redis缓存
- 大量日志数据定期清理
- 图片上传时进行压缩处理
文件上传:
- 限制文件上传大小
- 验证文件MIME类型
- 定期清理临时文件

扩展建议

日志告警: 添加日志异常告警功能
配置加密: 敏感配置数据加密存储
多语言: 支持配置数据的多语言
任务监控: 添加任务执行监控和通知
CDN集成: 文件上传支持CDN分发

常见问题

Q: 如何清除城市数据缓存？

A: 调用 CityService::clearCache() 方法或运行 php artisan cache:forget city:tree。

Q: 图片上传后如何压缩？

A: 上传时设置 compress=true 和 quality 参数，系统会自动压缩。

Q: 如何配置定时任务？

A: 在Admin后台创建任务，设置Cron表达式，系统会自动调度执行。

Q: 数据字典如何使用？

A: 通过Public API获取字典数据，前端根据数据渲染下拉框等组件。

Q: 日志数据过多如何处理？

A: 定期使用 /admin/logs/clear 接口清理过期日志，或在后台设置自动清理任务。

18 KiB Raw Blame History Unescape Escape

System 基础模块文档

概述

控制器结构

Admin 控制器

Api 控制器

技术栈

数据库表结构

system_configs (系统配置表)

system_dictionaries (数据字典分类表)

system_dictionary_items (数据字典项表)

system_logs (操作日志表)

system_tasks (任务表)

system_cities (城市表)

Admin API 接口文档

系统配置管理

获取配置列表

获取所有配置分组

按分组获取配置

获取配置详情

创建配置

更新配置

删除配置

批量删除配置

批量更新配置状态

操作日志管理

获取日志列表

获取日志详情

删除日志

批量删除日志

清理日志

获取日志统计

数据字典管理

获取字典列表

获取所有字典

获取字典详情

创建字典

更新字典

删除字典

批量删除字典

批量更新字典状态

数据字典项管理

获取字典项列表

创建字典项

更新字典项

删除字典项

批量删除字典项

批量更新字典项状态

任务管理

获取任务列表

获取所有任务

获取任务详情

创建任务

更新任务

删除任务

批量删除任务

批量更新任务状态

手动执行任务

获取任务统计

城市数据管理

获取城市列表

获取城市树

获取城市详情

获取子级城市

获取所有省份

获取指定省份的城市

获取指定城市的区县

创建城市

更新城市

删除城市

批量删除城市

批量更新城市状态

文件上传管理

单文件上传

多文件上传

Base64上传

删除文件

批量删除文件

Public API 接口文档

系统配置 API

18 KiB

Raw Blame History