AdmincpCommon 说明文档

AdmincpCommon 是一个抽象类，继承自 AdmincpBase，为后台管理系统提供通用功能。它包含配置管理、数据映射、动态属性、分页查询等核心功能，适用于快速构建后台管理模块的基类。

核心功能概览

详细功能解析

1. 详情查看 (do_detail)

public function do_detail() {
    $model = self::$MODEL;
    $rs = $model::get($this->id); // 通过 ID 获取模型数据
    $fields = $model::fullFields(); // 获取模型完整字段定义
    include self::view(); // 渲染详情页视图
}

• 用途: 展示单个数据项的详细信息。
• 依赖: 需要模型类 (self::$MODEL) 实现 get() 和 fullFields() 方法。

2. 配置管理 (do_config, done_config)

public function do_config() {
    return ConfigView::display(self::$APPID); // 渲染配置页面
}

public function done_config() {
    $data = Request::post('config');
    Config::save(self::$APPID, $data); // 保存配置数据
}

• 流程:
  1. do_config 通过 ConfigView 显示配置表单。
  2. 表单提交后，done_config 接收并保存配置数据。
• 存储: 依赖 Config 类实现配置存储逻辑。

3. 数据映射接口

3.1 ID-字段映射 (done_mapper)

public function done_mapper() {
    $field = Request::sget('sdo') ?: 'name';
    $arr = $model::select();
    return array_column($arr, $field, 'id'); // 生成 [id => 字段值] 的映射
}

• 输出示例:

  {1: "Item1", 2: "Item2"}

• 用途: 用于需要 ID 与名称映射的下拉选择组件。

3.2 属性映射 (done_map)

public function done_map() {
    $field = Request::sget('sdo') ?: 'status';
    $arr = Prop::getMap($model, $field); // 获取预定义的属性映射
    return iJson::listData($list); // 标准化 JSON 输出
}

• 输出示例:

  [
    {"value":0, "text":"禁用"},
    {"value":1, "text":"启用"}
  ]

• 依赖: Prop 类需定义字段的映射关系。

4. 分页查询 (done_selectpage)

核心参数：

• pageSize: 每页条数
• searchKey/searchValue: 精确搜索字段
• q_word: 模糊搜索关键词
• orderBy: 排序规则

处理流程：

1. 条件构建：处理精确搜索 (WHERE IN) 和模糊搜索 (LIKE)。
2. 排序处理：解析 orderBy 参数生成 SQL 排序语句。
3. 分页查询：调用模型的分页方法，返回带分页信息的结果。
4. 结果格式化：使用 iJson::listItem 标准化输出格式。

示例请求：

// 前端请求示例
{
  pageNumber: 2,
  pageSize: 10,
  searchField: "title,content",
  q_word: ["重要"],
  orderBy: [["id", "DESC"]]
}

5. 动态属性管理

5.1 获取属性 (done_getmeta)

public function done_getmeta() {
    $appid = Request::spost('appid');
    $id = Request::spost('id');
    return AppsMeta::get($appid, $id, true); // 获取元数据
}

5.2 保存属性 (done_savemeta)

public function done_savemeta() {
    AppsMeta::saveData($appid, $id, [
        'mode' => $post['mode'], 
        'metadata' => (array)$post['metadata']
    ]);
}

• 模式说明:
  • mode: 'replace': 完全替换元数据
  • mode: 'merge': 合并现有元数据

继承与扩展

扩展点说明

1. 自定义属性:

   protected function prop_custom_field() {
       return [1 => '选项A', 2 => '选项B'];
   }

   • 通过实现 prop_字段名 方法，自定义字段的下拉选项。

2. 缓存逻辑:

   public static function autoCache() {
       // 自定义缓存更新逻辑
   }

3. 分页查询扩展:

   protected function selectpage() {
       return [
           'result' => function($param, $where, $whereOr, $orderby, &$response) {
               // 自定义数据获取逻辑
           },
           'item' => function($value, $param) {
               // 自定义列表项处理
           }
       ];
   }

安全与权限

• 无需鉴权的方法：使用 @auth no 注释标记（如 done_mapper），跳过权限验证。
• 输入过滤：关键方法使用 Request::sget() 进行安全参数获取。
• SQL 安全：通过模型类的方法构建查询，避免 SQL 注入。

使用建议

1. 模型约定：子类需定义 protected static $MODEL 指定关联的模型类。
2. 视图约定：模板文件应存放于 views/[模块名]/ 目录，按方法命名（如 detail.php）。
3. 前端集成：分页接口 (done_selectpage) 适配标准的前端分页组件。
4. 元数据管理：动态属性适合存储可变的结构化数据，如商品参数、文章扩展信息等。

// 示例子类定义
class ArticleAdmincp extends AdmincpCommon {
    protected static $MODEL = ArticleModel::class;
    protected static $APPID = 'article';
}