import{_ as i,o as a,c as h,a2 as t}from"./chunks/framework.BbmSSMjL.js";const g=JSON.parse('{"title":"6.5 职级管理","description":"","frontmatter":{},"headers":[],"relativePath":"zh/modules/level.md","filePath":"zh/modules/level.md"}'),n={name:"zh/modules/level.md"};function k(l,s,p,e,d,r){return a(),h("div",null,[...s[0]||(s[0]=[t(`

6.5 职级管理

概述

职级管理维护用户的职级属性数据，支持 Excel 导入导出。LevelService 继承 BaseTenantService 实现租户隔离，是"属性配置 + 导入导出扩展方法"的标准组合示例。

模块特点

特性	说明
基类	`BaseTenantService`（租户隔离）
唯一校验	`name` 按租户分组唯一（`['name','tenant_id']`）
枚举映射	`status` → level_status 字典（1=在用 2=停用）
删除保护	`beforeDelete` 检查业务约束
导入导出	支持 Excel 导入导出（`export` / `import` 扩展方法）

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	导入

Service 配置（来自项目实际代码）

php

class LevelService extends BaseTenantService
{
    use HasCrudOperations, HasQueryScopes, HasSerializeMaps, HasUniqueCheck;

    protected string $modelClass = Level::class;

    protected array $pageLikeFields = ['name'];
    protected array $pageEqFields = ['status'];
    protected array $pageOrderBy = [
        ['field' => 'tenant_id', 'type' => 'asc'],
        ['field' => 'sort', 'type' => 'asc'],
    ];

    // name 在同一租户内唯一
    protected array $uniqueFields = [['name', 'tenant_id']];

    // 字典翻译
    protected array $serializeMaps = [
        'status' => 'level_status',
    ];
}

导出方法

php

// app/Services/LevelService.php（来自项目实际代码）

public function export(array $params = []): string
{
    $list = $this->allList($params);

    $headers = [
        'name'        => '职级名称',
        'statusText'  => '状态',      // 枚举显示名（serializeMaps 已补全）
        'sort'        => '排序',
        'create_user' => '创建人',
        'create_time' => '创建时间',
    ];

    return ExcelService::export($list, $headers, '职级数据.xlsx');
}

导入方法

php

// app/Services/LevelService.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'] = DictCacheService::getValue('level_status', $row['status']);
        }
    }

    $count = 0;
    $errors = [];
    foreach ($data as $index => $row) {
        try {
            $this->add($row);        // 走完整 add 流程（钩子/唯一校验/事务）
            $count++;
        } catch (\\Exception $e) {
            $errors[] = [
                'row'    => $index + 2,   // +2：表头占第 1 行
                'name'   => $row['name'] ?? '',
                'reason' => $e->getMessage(),
            ];
        }
    }

    return ['count' => $count, 'errors' => $errors];
}

导入导出标准模板

LevelService 是导入导出的标准实现示例：导出用 allList() 取全量数据 + ExcelService::export()；导入用 ExcelService::importWithMap() 表头映射 + 字典反查 + 逐条 add()（单条失败不中断，明细汇总返回）。与 ExampleService 同构。

导入导出流程

text

导出：
GET /api/level/export → _export() → Service::export()
    → allList()（含字典翻译） → ExcelService::export() → 返回文件 URL

导入：
POST /api/level/import（FormData）
    → _import()（校验扩展名 xls/xlsx + MIME + 10MB 上限）
    → Service::import()
        → importWithMap 解析 → 字典反查 → 逐条 add()
    → 返回 { count, errors[] }

`,15)])])}const y=i(n,[["render",k]]);export{g as __pageData,y as default};

6.5 职级管理 ​

模块特点 ​

API 接口 ​

Service 配置（来自项目实际代码） ​

导出方法 ​

导入方法 ​