README

Webman 通用业务扩展库，封装 UMaos 平台的多端（index 前台 / admin 管理 / system 中台）通用能力：控制器解析与权限节点生成、统一响应输出、登录鉴权（RBAC）、数据模型、构建/随机/字符串/HTTP 等工具。业务项目通过 Composer 引入即可复用，支持标准 app 结构与 plugin 插件结构。

• 命名空间：umaos\webman\
• 依赖：PHP >= 8.1、webman-framework ^2、think-orm ^2

特性

• 多端统一鉴权：Auth 类按 module 区分三端用户，统一登录/退出/权限校验，session 键 {module}_login_user
• RBAC 权限体系：用户 → 分组 → 规则节点（dir/menu/file 三级），超管规则 *
• 权限节点自动生成：ControllerScanner 扫描控制器目录 + Controller::getControllerInfo 反射解析类/方法注释与 noNeedLogin/noNeedRight，自动生成权限树
• 统一响应：Show 类按请求形态自动返回 JSON 或提示模板页（code: 0 成功 / 1 失败 / 2 警告 / 3 未登录）
• 视图布局渲染：Layout 类支持公共布局包裹，模板根目录可配置
• 工具集：树构建、查询条件构建、随机串/UUID、命名转换、HTTP 请求、文件操作

安装

composer require umaos/webman

若安装 dev 版本（使用未打 tag 的最新提交），需在项目 composer.json 中允许不稳定版本：

{
  "minimum-stability": "dev",
  "prefer-stable": true
}

目录结构

umaos/webman/
├── public/                        # 静态资源（前端库/样式/图片，安装时自动部署）
│   ├── axios.min.js
│   ├── pinia.iife.js
│   ├── umaos.css
│   ├── wallpaper.jpg
│   ├── element-plus/              # Element Plus 组件库资源
│   ├── icons-vue/                 # 图标库资源
│   └── vue/                       # Vue 运行时
├── src/
│   ├── Controller.php              # 控制器基类：反射解析 + 权限节点生成
│   ├── Install.php                 # Webman 基础插件安装类（部署独立配置到主项目）
│   ├── config/plugin/              # 基础插件独立配置（安装时自动部署到主项目 config/plugin/）
│   │   └── umaos/webman/           #   插件主配置 + 静态资源路由
│   │       ├── app.php             #     enable/debug/version
│   │       └── route.php           #     静态资源路由（/plugin/umaos/ → 包内 public/）
│   ├── helper/                     # 工具类
│   │   ├── Builder.php             # 树构建 buildTree / 查询条件构建 buildWhere
│   │   ├── Files.php               # 文件操作（递归建目录等）
│   │   ├── Http.php                # cURL 同步/异步请求、文件推送
│   │   ├── Layout.php              # 视图布局渲染（模板根可配置）
│   │   ├── Random.php              # 随机串 / UUID
│   │   ├── Show.php                # 统一响应输出（JSON / 提示模板）
│   │   └── Str.php                 # 命名转换（camel/snake/pascal）
│   ├── library/
│   │   ├── Auth.php                # 多端登录鉴权（登录/退出/取用户/权限校验）
│   │   └── ControllerScanner.php   # 控制器目录扫描
│   ├── middleware/
│   │   └── Worker.php              # 全局鉴权中间件
│   ├── model/                      # ThinkORM 模型（对应 fa_ 前缀表）
│   │   ├── User.php                # fa_index_user 前台用户
│   │   ├── Admin.php               # fa_admin_user 管理员
│   │   ├── System.php              # fa_system_user 系统用户
│   │   ├── AuthGroup.php           # fa_auth_group 权限分组
│   │   └── AuthRule.php            # fa_auth_rule 权限规则
│   └── traits/                     # 预留控制器特性
│       ├── Backend.php             # 管理端
│       ├── Frontend.php            # 前台
│       └── Sysend.php              # 中台
├── composer.json
└── README.md

基础插件（webman 官方规范）

本包是 webman 基础插件（通用组件，代码位于 vendor，composer 安装），遵循官方基础插件规范（workerman.net/doc/webman/plugin/base.html）：

• 独立配置：插件配置存放于主项目 config/plugin/umaos/webman/，由包内 Install 类在 composer 安装/更新时自动部署（卸载时自动清理），webman 启动时自动识别合并，访问方式 config('plugin.umaos.webman.app.xxx')
• 安装钩子：src/Install.php 定义 WEBMAN_PLUGIN 常量，webman 框架的 support\Plugin 在 composer 安装/更新时自动调用 install()/update()
• 静态资源走 Route：public/ 位于包内 vendor 目录，无需复制、无需 public_path 配置。仿照 webman/push 等官方基础插件，插件专属 URL 空间使用 /plugin/{插件名}/：route.php 动态扫描包内 public，为每个静态文件注册具体路径路由 /plugin/umaos/{相对路径}，返回文件响应（自动 Content-Type / 304 缓存），具体路径注册不与控制器路由（/umaos/）冲突
• 与项目内 umaos 业务应用（webman 官方多应用结构 app/{index,admin,system}）相互独立，互不干扰；公共模板由本包默认视图提供（可通过 config('umaos.template_dir') 自定义）

部署的配置文件（主项目 config/plugin/ 下）：

config/plugin/
└── umaos/
    └── webman/
        ├── app.php                 # 基础插件独立配置（enable/debug/version）
        └── route.php               # 静态资源路由（/plugin/umaos/ → 包内 public/）

静态资源访问示例：/plugin/umaos/vue/vue.global.prod.js → 路由 → vendor/umaos/webman/public/vue/vue.global.prod.js

部署的配置文件（主项目 config/plugin/ 下）：

config/plugin/
└── umaos/
    └── webman/
        ├── app.php                 # 基础插件独立配置（enable/debug/version）
        ├── autoload.php            # 助手函数自动加载（webman 插件 autoload 机制）
        └── route.php               # 静态资源路由（/plugin/umaos/ → 包内 public/）

全局助手函数

本包通过 webman 插件 autoload 机制（而非 composer autoload.files）提供全局助手函数：

• 由 Install 类部署 config/plugin/umaos/webman/autoload.php，其 files 声明 vendor/umaos/webman/src/helpers.php
• webman 启动时（support\bootstrap）自动 include_once 该文件，所有助手函数即刻全局可用，无需手动引入
• 每个函数以 function_exists() 包裹，避免与框架或其他包重复定义

可用的全局助手函数：

umaos 业务应用（webman 官方多应用 app/{index,admin,system}）已切换为本包助手函数（原应用插件 plugin/umaos 已迁移并移除）。

快速开始

1. 注册全局鉴权中间件

在项目 config/middleware.php 的全局中间件中加入：

return [
    '' => [
        \umaos\webman\middleware\Worker::class,
        // ...其他中间件
    ],
];

中间件会依次执行：记录 lang 到 session → Auth::init() 初始化请求上下文（module/auth/user/rule）→ Auth::access() 权限校验 → 放行控制器。

2. 控制器继承与权限节点

控制器类注释作为菜单标题、方法注释作为节点标题，默认属性控制免登录/免授权：

<?php

namespace app\index\controller;

use umaos\webman\library\Auth;

/**
 * 首页控制器
 */
class Index extends \umaos\webman\Controller
{
    // 免登录动作：login
    public $noNeedLogin = ['login'];
    // 免授权动作：index
    public $noNeedRight = ['index'];
    // 模块名（缺省时按路径推断）
    public $moduleName = 'index';

    /**
     * 首页
     */
    public function index()
    {
        // 未登录跳转登录页
        if (!request()->user) {
            return Auth::access();
        }
        return \umaos\webman\helper\Show::success('欢迎回来', request()->user);
    }
}

权限节点生成流程：ControllerScanner::getLists() 汇总全部控制器 → Controller::getControllerInfo() 反射解析 → 生成 dir/menu/file 三级规则写入 fa_auth_rule。

3. 统一响应

use umaos\webman\helper\Show;

// JSON（ajax 请求自动返回 JSON；浏览器直开自动渲染提示模板）
return Show::success('操作成功', ['id' => 1]);
return Show::error('操作失败');
return Show::warn('请注意');
return Show::login('请先登录');   // code:3，前端据此跳转登录页

// 强制 JSON / 强制模板
return Show::success('成功', [], false); // 强制 JSON
return Show::error('失败', [], true);    // 强制渲染 error 模板

响应结构：{code, msg, data, auth}；渲染模板时额外附带 name（页面标题）。

4. 登录鉴权

use umaos\webman\library\Auth;

// 登录（按当前 module 查对应用户表，md5(md5(pwd)+salt) 校验）
return Auth::setLogin($username, $password);

// 退出
return Auth::setOut();

// 获取当前登录用户与规则（返回 ['user' => [], 'rule' => []]）
$login = Auth::getLogin();

// 权限校验（中间件内自动调用；返回 false 表示放行）
if ($block = Auth::access()) {
    return $block;
}

登录成功时自动写入 session（键 {module}_login_user = 用户 ID），响应中的用户信息已剔除 password/salt 敏感字段。

5. 数据模型

三端用户模型均提供 getInfo / getGroup / getRules 静态方法：

use umaos\webman\model\User;

$user = User::getInfo($userId);          // 已剔除敏感字段
$groups = User::getGroup($userId);       // 分组 ID 数组
$rules = User::getRules($userId);        // 权限规则集合（超管为 ['*']）

6. 工具类

use umaos\webman\helper\Builder;
use umaos\webman\helper\Random;
use umaos\webman\helper\Str;
use umaos\webman\helper\Http;

// 树构建
$tree = Builder::buildTree($flatList);   // 列表需含 id/pid

// 查询条件构建（ThinkORM where 闭包）
$where = Builder::buildWhere(
    ['status' => 1, 'name' => 'admin'],
    ['status' => '=', 'name' => 'LIKE']
);
$list = Model::where($where)->select();

// 随机串
Random::alnum(6);    // 数字+字母
Random::alpha(6);    // 纯字母
Random::numeric(4);  // 纯数字
Random::uuid();      // UUID v4

// 命名转换
Str::camelToSnake('AdminUser');   // admin_user
Str::snakeToCamel('admin_user');  // adminUser
Str::snakeToPascal('admin_user'); // AdminUser

// HTTP 请求
Http::get($url, ['a' => 1]);
Http::post($url, ['b' => 2]);
Http::sendAsyncRequest($url, $data);   // 异步，不等待响应
Http::sendToBrowser($filePath);        // 推送文件到浏览器

模板路径配置

提示模板（tip/error/login）与布局模板（layout）的查找规则：

• 默认（包内自带视图）：直接使用包内默认视图 vendor/umaos/webman/src/view，无需任何配置

• 自定义视图：将包内 src/view 目录复制到项目中（如 app/umaos/view），通过基础插件配置 config/plugin/umaos/webman/app.php 指定模板根：

  <?php
  return [
      // 公共模板根目录（tip/error/login/layout 所在目录，项目根相对路径；留空 = 包内默认视图）
      'template_dir' => '/app/umaos/view',
  ];
  

  模板目录约定：

  {template_dir}/
  ├── tip/            # 成功/警告提示页（success.html / warn.html）
  ├── error/          # 失败提示页，按模块分文件（{module}.html）
  ├── login/          # 未登录提示页，按模块分文件（{module}.html）
  └── layout/         # 公共布局，按应用分文件（{module}.html，{@body} 为内容占位符）
  

版本记录

许可证

MIT