AdmincpBase 后台基础类说明文档

# AdmincpBase 后台基础类说明文档 `AdmincpBase` 是后台管理系统的核心基础类，继承自 `AdmincpView`，提供通用功能如模型管理、权限控制、数据操作等，为其他管理类提供统一的基础能力。 --- ## 核心功能概览 | **功能模块** | **关键方法/属性** | **说明** | | ------------ | ----------------------------- | -------------------------------------------------- | | **模型管理** | `modelInit`, `getModel` | 动态初始化模型类，支持自动推断模型类名或手动指定 | | **错误处理** | `error`, `alert` | 统一错误提示机制，支持直接中断流程或返回错误信息 | | **数据映射** | `getFieldMap`, `getMapOption` | 获取模型字段的映射关系，生成`<option>` 等表单元素 | | **排序控制** | `getTableOrderBy` | 根据请求参数生成 SQL 排序语句 | | **分页查询** | `tableData` | 通用表格数据获取方法，支持复杂查询条件与回调处理 | | **权限控制** | `setEditor` | 设置编辑者信息并进行权限校验 | | **动态按钮** | `actionBtns` | 根据配置生成操作按钮，支持图标、数据属性等动态配置 | | **静态资源** | `do_assets` | 统一加载前端静态资源 | --- ## 核心属性说明 ```php // 排序字段配置 (示例) public static $orderBy = [ 'id' => 'ID', 'sortnum' => '排序值' ]; // 基础权限标识 public $ACCESC_BASE = [ 'ADD' => '新增权限', 'INDEX' => '管理权限', 'EDIT' => '编辑权限', 'DELETE' => '删除权限' ]; // 状态映射 (SDOMAP 示例) public static $SDOMAP = [ 'inbox' => '0', // 草稿 'normal' => '1', // 正常 'trash' => '2', // 回收站 // ...其他状态 ]; ``` --- ## 核心方法详解 ### 1. 模型初始化 (`modelInit`) ```php public static function modelInit($name = null) { // 自动推断模型类名 (如 ArticleAdmincp → ArticleModel) if(empty(self::$MODEL)){ $modelClass = sprintf('%sModel', substr(get_called_class(),0,-7)); class_exists($modelClass) && self::$MODEL = $modelClass; } } ``` - **用途**: 动态绑定数据模型类 - **触发时机**: 类实例化时自动调用 --- ### 2. 表格数据获取 (`tableData`) ```php public static function tableData($model, $query=[], $func=null) { // 构建查询条件 $obj = $model->where($query['where']) ->field($query['field']) ->orderBy(self::getTableOrderBy()); // 执行分页查询 $rows = $obj->paging($pageSize); // 回调处理数据 $func && $rows = call_user_func($func, $rows); return [ 'total' => Paging::$count, 'rows' => $rows, 'sql' => $obj->getQueryLog() ]; } ``` **参数说明**: - `$model`: 模型类名或查询对象 - `$query`: 查询条件数组 (where/field/orderby等) - `$func`: 数据处理回调函数 **典型调用**: ```php // 在子类中获取文章列表 public function do_index() { $query = ['where' => ['status' => 1]]; return self::tableData(ArticleModel::class, $query, function($rows){ return array_map(function($row){ $row['pubdate'] = date('Y-m-d', $row['pubdate']); return $row; }, $rows); }); } ``` --- ### 3. 操作按钮生成 (`actionBtns`) **配置示例** (`/etc/admincp/article.index.action.json`): ```json { "edit": { "title": "编辑", "icon": "edit", "url": "article/edit?id={$v.id}", "class": "btn-primary" }, "delete": { "title": "删除", "icon": "trash", "action": "delete", "data-toggle": "confirm" } } ``` **生成逻辑**: 1. 读取匹配 `admincp/*.index.action*` 的配置文件 2. 解析占位符如 `{$v.id}` 替换为实际数据 3. 生成带图标和事件的 HTML 按钮代码 --- ### 4. 权限控制 (`setEditor`) ```php public static function setEditor(&$post, $row, $field1='userid', $field2='editor') { // 非管理员只能修改自己的数据 if(!Admin::isSuperRole() && $row[$field1] != $post[$field1]){ self::alert('无权操作他人数据'); } } ``` **典型使用场景**: 在保存数据前校验编辑权限，防止越权修改。 --- ## 继承与扩展 ### 扩展模型类 ```php class ArticleAdmincp extends AdmincpBase { protected static $MODEL = ArticleModel::class; // 指定模型 protected static $orderBy = ['pubdate' => '发布时间']; // 扩展排序字段 } ``` ### 自定义状态映射 ```php class ProductAdmincp extends AdmincpBase { public static $SDOMAP = [ 'draft' => 0, 'onsale' => 1, 'offline' => 2 ]; } ``` --- ## 安全机制 1. **输入过滤**: 关键方法使用 `Request::sparam()` 进行安全参数获取 2. **SQL 防护**: 通过模型类方法构建查询，避免 SQL 注入 3. **权限校验**: - `setEditor` 验证数据归属 - `ACCESC_BASE` 定义基础权限点 4. **错误隔离**: 错误提示统一通过 `alert/error` 方法处理 --- ## 最佳实践 1. **模型规范**: 保持 `XXXAdmincp` 与 `XXXModel` 命名对应 2. **配置驱动**: 将按钮、状态等配置外置到 `/etc/` 目录 3. **分页优化**: 大数据量表查询时，在 `tableData` 中指定必要字段 4. **权限细化**: 在子类中扩展 `ACCESC_BASE` 添加业务权限点 ```php class OrderAdmincp extends AdmincpBase { public $ACCESC_BASE = [ // 继承基础权限 ...parent::$ACCESC_BASE, // 扩展新权限 'EXPORT' => '导出权限', 'AUDIT' => '审核权限' ]; } ```