整体架构

CondorAdmin 是一款基于 PHP Webman + Vue 3 + Naive UI 的现代化中后台管理系统，采用前后端分离架构，提供开箱即用的权限管理、CRUD 生成、多语言、SSE 消息推送等核心功能。

技术栈概览

后端技术栈

技术	版本	用途
PHP	8.0+	后端运行环境
Webman	最新	高性能 PHP 框架
MySQL	8.0+	关系型数据库
Redis	6.0+	缓存与 Token 存储
Eloquent ORM	-	数据库操作
tinywan/storage	-	统一文件存储（本地/OSS/COS）
workerman/gateway-worker	-	WebSocket/SSE 消息推送

前端技术栈

技术	版本	用途
Vue	3.5+	渐进式前端框架
TypeScript	5.8+	类型安全
Vite	7.2+	构建工具
Naive UI	2.43+	UI 组件库
Pinia	3.0+	状态管理
Vue Router	4.6+	路由管理
UnoCSS	-	原子化 CSS 引擎
@wangeditor/editor	5.1+	富文本编辑器
ECharts	6.0+	数据可视化

架构设计

分层架构

┌─────────────────────────────────────────────────────────┐
│                      用户界面层 (UI)                       │
│  Vue 3 Components + Naive UI + Condor Components        │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    状态管理层 (Store)                      │
│  Pinia Modules: auth, route, tab, theme, condor         │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    服务接口层 (API)                        │
│  Axios/Alova HTTP Client + Request/Response Interceptors│
└─────────────────────────────────────────────────────────┘
                           ↓ HTTP/HTTPS
┌─────────────────────────────────────────────────────────┐
│                    中间件层 (Middleware)                   │
│  AuthToken → AuthPermission → Lang → OperateLog         │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    控制器层 (Controller)                   │
│  Backend Base Class + Specialized Controllers            │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    业务逻辑层 (Service)                    │
│  StorageService, Auth, Translation, etc.                │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    数据访问层 (Model)                      │
│  Eloquent ORM Models + Relationships                     │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│                    数据存储层 (Storage)                    │
│         MySQL (持久化) + Redis (缓存/Token)               │
└─────────────────────────────────────────────────────────┘

插件化架构

CondorAdmin 采用插件化设计，核心功能和业务模块均以 Webman 插件形式存在：

plugin/
├── condoradmin/        # 核心后台插件（基础架构）
│   ├── app/
│   │   ├── controller/ # 控制器
│   │   ├── middleware/ # 中间件
│   │   ├── library/    # 核心类库（Backend, Auth, StorageService）
│   │   └── model/      # 模型
│   └── config/         # 插件配置
├── condorauth/         # 认证增强插件
├── condorshop/         # 电商模块插件
├── condorsms/          # 短信模块插件
├── condorsupport/      # 客服模块插件
└── ...                 # 其他业务插件

插件设计优势：

• 模块化：功能模块独立，便于维护
• 可插拔：按需启用/禁用插件
• 隔离性：插件间互不干扰
• 可扩展：自定义业务插件

核心流程

请求生命周期

1. 用户发起 HTTP 请求
   ↓
2. Webman Router 路由匹配
   ↓
3. 中间件链处理（Middleware Pipeline）
   ├── CrossDomain（跨域处理）
   ├── AuthToken（Token 认证）
   ├── AuthPermission（权限验证）
   ├── Lang（多语言处理）
   └── OperateLog（操作日志记录）
   ↓
4. Controller 处理请求
   ├── 参数验证（Respect\Validation）
   ├── 业务逻辑处理
   ├── 数据权限过滤（dataLimit）
   └── 调用 Model/Service
   ↓
5. Model 数据库操作
   ├── Query Builder 构建查询
   ├── 执行 SQL（Eloquent ORM）
   └── 返回结果集
   ↓
6. Response 数据格式化
   ├── 统一响应格式：{code, msg, data}
   ├── 字段隐藏/脱敏
   └── JSON 序列化
   ↓
7. 响应返回客户端

前端请求流程

1. 用户操作触发事件
   ↓
2. Component 调用 API 方法
   ↓
3. Request Interceptor（请求拦截器）
   ├── 添加 Authorization Header（Bearer Token）
   ├── 添加语言标识（Accept-Language）
   └── 添加时间戳/签名（可选）
   ↓
4. HTTP 请求发送（Axios/Alova）
   ↓
5. 后端处理（见上述后端流程）
   ↓
6. Response Interceptor（响应拦截器）
   ├── Token 过期检测（401）→ 跳转登录
   ├── 权限不足检测（403）→ 显示提示
   ├── 业务错误提示（4000）→ Message/Notification
   └── 数据解包（返回 data 字段）
   ↓
7. Store 更新状态（Pinia）
   ↓
8. Component 重新渲染（Vue Reactivity）

数据流设计

单向数据流

CondorAdmin 遵循单向数据流原则（Unidirectional Data Flow）：

     ┌──────────────────────────────────────┐
     │         User Interaction             │
     │   (点击、输入、滚动等用户操作)           │
     └──────────────────────────────────────┘
                      ↓
     ┌──────────────────────────────────────┐
     │         Action Dispatch              │
     │   (调用 Store Actions 或 API 方法)    │
     └──────────────────────────────────────┘
                      ↓
     ┌──────────────────────────────────────┐
     │         API Request                  │
     │   (HTTP 请求到后端)                   │
     └──────────────────────────────────────┘
                      ↓
     ┌──────────────────────────────────────┐
     │         Backend Processing           │
     │   (中间件 → 控制器 → 模型 → 数据库)     │
     └──────────────────────────────────────┘
                      ↓
     ┌──────────────────────────────────────┐
     │         State Update                 │
     │   (更新 Pinia Store)                  │
     └──────────────────────────────────────┘
                      ↓
     ┌──────────────────────────────────────┐
     │         View Re-render               │
     │   (Vue 响应式更新 UI)                  │
     └──────────────────────────────────────┘

状态管理

全局状态（Pinia Store）：

• auth：用户信息、Token、权限列表
• route：路由信息、菜单树、面包屑
• tab：标签页列表、缓存页面
• theme：主题配置、暗黑模式、布局设置
• condor：字典数据、系统配置

本地状态（Component State）：

• 表单数据、临时变量、加载状态

持久化状态（LocalStorage）：

• Token、主题偏好、标签页历史

安全机制

认证与授权

1. Token 认证（JWT）

   • 前端：每次请求携带 Authorization: Bearer <token>
   • 后端：AuthToken 中间件验证 Redis 中的 Token 有效性
   • 过期处理：自动跳转登录页

2. RBAC 权限模型

   • 用户（Admin）→ 角色（Role）→ 权限（Menu/Button）
   • 细粒度控制：菜单权限 + 按钮权限
   • 数据权限：dataLimit 字段控制（个人/部门/全部）

3. 密码加密

   • 前端：RSA 公钥加密密码
   • 后端：私钥解密 + bcrypt 哈希存储

数据安全

• SQL 注入防护：Eloquent ORM 参数化查询
• XSS 防护：前端输出转义、后端富文本过滤
• CSRF 防护：Token 验证（可选）
• 字段脱敏：敏感字段（如密码）自动隐藏（$hidden 属性）

性能优化

后端优化

• 查询优化：

  • 字段白名单（$searchable、$sortable）
  • 独立查询构建器（getQueryBuilder()）避免模型状态污染
  • 关联预加载（$with）减少 N+1 查询
  • 分页限制（max 500 条/页）

• 缓存策略：

  • Redis 缓存 Token（过期自动删除）
  • 字典数据缓存
  • 配置项缓存

前端优化

• 代码分割：

  • 路由懒加载（() => import('./views/...')）
  • Vite 动态导入

• 构建优化：

  • Tree Shaking（自动移除未使用代码）
  • UnoCSS 按需生成（仅生成使用的 CSS）
  • Gzip/Brotli 压缩

• 运行时优化：

  • 虚拟滚动（长列表）
  • 防抖/节流（搜索、滚动）
  • keep-alive 缓存（标签页）

扩展性

水平扩展

• 负载均衡：Nginx 反向代理多个 Webman 实例
• Session 共享：Redis 存储 Token
• 文件存储：统一存储服务（本地 → OSS/COS）

垂直扩展

• 自定义插件：遵循 Webman 插件规范
• 自定义组件：继承 Backend 基类
• 自定义中间件：实现 MiddlewareInterface
• 自定义前端组件：遵循 Vue 3 Composition API

开发环境

后端环境

# 要求
PHP >= 8.0
MySQL >= 8.0
Redis >= 6.0
Composer >= 2.0

# 启动
cd condor-webman
composer install
cp .env.example .env  # 配置数据库
php start.php start   # 启动（Linux/macOS）
php windows.php       # 启动（Windows）

前端环境

# 要求
Node.js >= 20.19.0
pnpm >= 10.5.0

# 启动
cd condor-admin
pnpm install
pnpm run dev

项目结构

后端目录结构

condor-webman/
├── app/                    # 应用代码（基本用不到，插件化架构）
├── config/                 # 全局配置
│   ├── database.php       # 数据库配置
│   ├── redis.php          # Redis 配置
│   └── plugin/            # 插件配置
├── plugin/                # 插件目录
│   └── condoradmin/       # 核心插件
│       ├── app/
│       │   ├── controller/
│       │   ├── middleware/
│       │   ├── library/
│       │   └── model/
│       └── config/
├── runtime/               # 运行时文件（日志、缓存）
├── public/                # 静态资源
├── start.php              # 启动脚本
└── composer.json

前端目录结构

condor-admin/
├── packages/              # 内部包（Monorepo）
│   ├── materials/         # UI 布局组件
│   ├── hooks/             # 组合式函数
│   ├── utils/             # 工具函数
│   ├── axios/             # HTTP 客户端
│   └── ...
├── src/
│   ├── assets/            # 静态资源
│   ├── components/        # 全局组件
│   ├── composables/       # 组合式函数
│   ├── layouts/           # 布局组件
│   ├── plugins/           # Vue 插件
│   ├── router/            # 路由配置
│   ├── store/             # Pinia 状态管理
│   ├── typings/           # TypeScript 类型
│   ├── utils/             # 工具函数
│   ├── views/             # 页面组件
│   ├── App.vue
│   └── main.ts
├── vite.config.ts         # Vite 配置
├── uno.config.ts          # UnoCSS 配置
└── package.json

核心特性

1. SSE 消息推送

• 基于 workerman/gateway-worker
• 实时通知、进度推送
• 自动重连机制

2. CRUD 代码生成

• 根据数据库表结构生成：
  • 后端控制器
  • 前端页面（列表、表单）
  • API 接口定义

3. 多语言支持

• 前端：Vue I18n
• 后端：trans() 函数
• 翻译表：*_translations 表存储多语言数据

4. 数据权限

• dataLimit 字段：false | 'personal' | 'auth'
• 自动过滤当前用户可见数据

5. 操作日志

• OperateLog 中间件自动记录
• 记录内容：IP、路径、参数、响应

下一步

• 📖 API 交互规范 - 前后端接口约定
• 🔐 权限系统 - RBAC 权限设计
• 🔧 中间件系统 - 中间件详解