签入版本

2026-10-20 21:19:44 +08:00
commit 7e70ed6942
2943 changed files with 498573 additions and 0 deletions
@@ -0,0 +1,148 @@
+# 6.5 职级管理
+
+:::tip 概述
+职级管理维护用户的职级属性数据，支持 Excel 导入导出。继承 BaseTenantLogic 实现租户隔离。
+:::
+
+## 模块特点
+
+| 特性 | 说明 |
+|------|------|
+| 基类 | BaseTenantLogic（租户隔离） |
+| 唯一校验 | name 全局唯一 |
+| 枚举映射 | status → level_status 字典（1=在用 2=停用） |
+| 导入导出 | 支持 Excel 导入导出 |
+
+## API 接口
+
+| 方法 | 路径 | 权限码 | 说明 |
+|------|------|--------|------|
+| GET | `/api/level/page` | sys:level:page | 分页列表 |
+| GET | `/api/level/list` | sys:level:list | 全量列表 |
+| GET | `/api/level/detail/:id` | sys:level:detail | 详情 |
+| POST | `/api/level/add` | sys:level:add | 新增 |
+| PUT | `/api/level/update` | sys:level:update | 修改 |
+| DELETE | `/api/level/delete/:id` | sys:level:delete | 删除 |
+| DELETE | `/api/level/batchDelete` | sys:level:batchDelete | 批量删除 |
+| GET | `/api/level/export` | sys:level:export | 导出 |
+| POST | `/api/level/import` | sys:level:import | 导入 |
+
+## 核心代码
+
+### Logic 配置
+
+```php
+// app/logic/LevelLogic.php
+
+class LevelLogic extends BaseTenantLogic
+{
+    /**
+     * 关联的模型类
+     *
+     * @var string
+     */
+    protected string $modelClass = Level::class;
+
+    /**
+     * LIKE 模糊匹配字段
+     *
+     * @var array
+     */
+    protected array $pageLikeFields = ['name'];
+
+    /**
+     * 精确匹配字段
+     *
+     * @var array
+     */
+    protected array $pageEqFields = ['status'];
+
+    /**
+     * 默认排序规则
+     *
+     * @var array
+     */
+    protected array $pageOrderBy = [
+        ['field' => 'tenant_id', 'type' => 'asc'],
+        ['field' => 'sort', 'type' => 'asc'],
+    ];
+
+    /**
+     * 唯一性校验字段
+     *
+     * @var array
+     */
+    protected array $uniqueFields = ['name'];
+
+    /**
+     * 枚举显示名映射
+     *
+     * @var array
+     */
+    protected array $serializeMaps = [
+        'status' => 'level_status',
+    ];
+}
+```
+
+### 导出方法
+
+```php
+public function export(array $params = []): string
+{
+    $list = $this->allList($params);
+
+    $headers = [
+        'name'        => '职级名称',
+        'statusText'  => '状态',      // 枚举显示名
+        'sort'        => '排序',
+        'create_user' => '创建人',
+        'create_time' => '创建时间',
+    ];
+
+    return ExcelService::export($list, $headers, '职级数据.xlsx');
+}
+```
+
+### 导入方法
+
+```php
+public function import(string $filePath): array
+{
+    $headerMap = [
+        '职级名称' => 'name',
+        '状态'    => 'status',
+        '排序'    => 'sort',
+    ];
+
+    $data = ExcelService::importWithMap($filePath, $headerMap);
+
+    // 枚举字段反向映射：文字转数字
+    foreach ($data as &$row) {
+        if (!empty($row['status']) && !is_numeric($row['status'])) {
+            $row['status'] = DictService::getValue('level_status', $row['status']);
+        }
+    }
+
+    $count = 0;
+    $errors = [];
+    foreach ($data as $index => $row) {
+        try {
+            $this->add($row);
+            $count++;
+        } catch (\Exception $e) {
+            $errors[] = [
+                'row'    => $index + 2,
+                'name'   => $row['name'] ?? '',
+                'reason' => $e->getMessage(),
+            ];
+        }
+    }
+
+    return ['count' => $count, 'errors' => $errors];
+}
+```
+
+:::tip 导入导出模式
+LevelLogic 是导入导出的标准实现示例。导出使用 `allList()` 获取全量数据，导入使用 `ExcelService::importWithMap()` 解析文件，枚举字段通过 `DictService::getValue()` 反向映射。
+:::