AdmincpCommon 后台应用通类说明文档

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

# AdmincpCommon 说明文档

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

---

## 核心功能概览

| 功能模块 | 关键方法                        | 描述                                                               |
| -------- | ------------------------------- | ------------------------------------------------------------------ |
| 详情查看 | `do_detail`                     | 显示数据详情页，展示模型完整字段信息                               |
| 配置管理 | `do_config`, `done_config`      | 处理后台配置页面的展示和保存逻辑                                   |
| 数据映射 | `done_mapper`, `done_map`       | 生成 ID-字段映射或字段属性映射，用于下拉选项、表单联动等场景       |
| 动态属性 | `done_getmeta`, `done_savemeta` | 管理应用的元数据（动态属性），支持增删改查操作                     |
| 分页查询 | `done_selectpage`               | 通用分页查询接口，支持复杂搜索、排序、字段过滤，返回标准 JSON 结构 |
| 缓存管理 | `done_cache`, `autoCache`       | 提供缓存更新机制，子类可重写`autoCache` 实现自定义缓存逻辑         |
| 属性获取 | `done_prop`                     | 动态生成字段属性列表，支持自定义回调处理 (`prop_字段名` 方法)      |

---

## 详细功能解析

### 1. 详情查看 (`do_detail`)

```php
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`)

```php
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`)

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

- **输出示例**:
  ```json
  {1: "Item1", 2: "Item2"}
  ```
- **用途**: 用于需要 ID 与名称映射的下拉选择组件。

#### 3.2 属性映射 (`done_map`)

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

- **输出示例**:
  ```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` 标准化输出格式。

**示例请求**：

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

---

### 5. 动态属性管理

#### 5.1 获取属性 (`done_getmeta`)

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

#### 5.2 保存属性 (`done_savemeta`)

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

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

---

## 继承与扩展

### 扩展点说明

1. **自定义属性**:

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

- 通过实现 `prop_字段名` 方法，自定义字段的下拉选项。
2. **缓存逻辑**:

```php
   public static function autoCache() {
       // 自定义缓存更新逻辑
   }
   ```
3. **分页查询扩展**:

```php
   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. **元数据管理**：动态属性适合存储可变的结构化数据，如商品参数、文章扩展信息等。

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

最后更新 2025-01-25 20:52.

AdmincpCommonTrait 后台应用类说明文档

AdmincpCommonTrait 是一个用于后台管理的通用 Trait，提供了常见的增删改查（CRUD）操作、批处理、数据保存、更新等功能的封装。通过使用该 Trait，开发者可以快速构建后台管理功能，减少重复代码的编写。

AdmincpBase 后台基础类说明文档

AdmincpBase` 是后台管理系统的核心基础类，继承自 `AdmincpView`，提供通用功能如模型管理、权限控制、数据操作等，为其他管理类提供统一的基础能力。