签入版本

2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
@@ -1,22 +1,23 @@
 # 6.6 岗位管理

 :::tip 概述
-岗位管理维护用户的岗位属性数据。继承 BaseTenantLogic 实现租户隔离，是典型的零自定义方法模块——全部能力由属性配置自动装配。
+岗位管理维护用户的岗位属性数据。`PositionService` 继承 `BaseTenantService` 实现租户隔离，全部能力由属性配置自动装配，仅保留删除前的业务校验钩子——是"极简 CRUD"的典型模块。
 :::

 ## 模块特点

 | 特性 | 说明 |
 |------|------|
-| 基类 | BaseTenantLogic（租户隔离） |
-| 唯一校验 | name 全局唯一 |
-| 枚举映射 | status → position_status 字典（1=在用 2=停用） |
-| 自定义方法 | 无（全部由基类自动装配） |
+| 基类 | `BaseTenantService`（租户隔离） |
+| 唯一校验 | `name` 按租户分组唯一（`['name','tenant_id']`） |
+| 枚举映射 | `status` → position_status 字典（1=在用 2=停用） |
+| 删除保护 | `beforeDelete` 业务校验（如岗位被用户引用时阻止） |
+| 自定义方法 | 无（分页/详情/增删改全部由 Trait 自动装配） |

 ## 数据库表结构

 ```sql
-CREATE TABLE `think_position` (
+CREATE TABLE `laravel_position` (
  `id` int NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `name` varchar(255) NOT NULL COMMENT '岗位名称',
  `status` int DEFAULT 0 COMMENT '岗位状态：1-在用 2-停用',
@@ -36,135 +37,76 @@ CREATE TABLE `think_position` (
 |------|------|--------|------|
 | GET | `/api/position/page` | sys:position:page | 分页列表 |
 | GET | `/api/position/list` | sys:position:list | 全量列表 |
-| GET | `/api/position/detail/:id` | sys:position:detail | 详情 |
+| GET | `/api/position/detail/{id}` | sys:position:detail | 详情 |
 | POST | `/api/position/add` | sys:position:add | 新增 |
 | PUT | `/api/position/update` | sys:position:update | 修改 |
-| DELETE | `/api/position/delete/:id` | sys:position:delete | 删除 |
+| DELETE | `/api/position/delete/{id}` | sys:position:delete | 删除 |
 | DELETE | `/api/position/batchDelete` | sys:position:batchDelete | 批量删除 |

-## 核心代码
+## Service 配置（来自项目实际代码）

 ```php
-// app/logic/PositionLogic.php
-
-class PositionLogic extends BaseTenantLogic
+class PositionService extends BaseTenantService
 {
-    /**
-     * 关联的模型类
-     *
-     * @var string
-     */
+    use HasCrudOperations, HasQueryScopes, HasSerializeMaps, HasUniqueCheck;
+
    protected string $modelClass = Position::class;

-    /**
-     * LIKE 模糊匹配字段
-     *
-     * @var array
-     */
    protected array $pageLikeFields = ['name'];
-
-    /**
-     * 精确匹配字段
-     *
-     * @var array
-     */
    protected array $pageEqFields = ['status'];
+    protected array $pageOrderBy = ['field' => 'sort', 'type' => 'asc'];

-    /**
-     * 默认排序规则
-     *
-     * @var array
-     */
-    protected array $pageOrderBy = [
-        ['field' => 'tenant_id', 'type' => 'asc'],
-        ['field' => 'sort', 'type' => 'asc'],
-    ];
+    // name 在同一租户内唯一
+    protected array $uniqueFields = [['name', 'tenant_id']];

-    /**
-     * 唯一性校验字段
-     *
-     * @var array
-     */
-    protected array $uniqueFields = ['name'];
-
-    /**
-     * 枚举显示名映射
-     *
-     * @var array
-     */
+    // 字典翻译
    protected array $serializeMaps = [
        'status' => 'position_status',
    ];
+
+    // 删除前业务校验（如岗位被用户引用时抛 BizException 阻止删除）
+    protected function beforeDelete(int $id): void
+    {
+        // ... 业务约束检查 ...
+    }
 }
 ```

-### Controller 代码
+## Controller 代码（标准形态）

 ```php
-// app/controller/PositionController.php
+// app/Http/Controllers/Api/PositionController.php（形态示例）

-class PositionController extends BaseController
+#[OperationLog('岗位管理-查询分页', OperationLog::TYPE_QUERY)]
+#[Permission('sys:position:page', '岗位分页')]
+public function page(): JsonResponse
 {
-    protected PositionLogic $logic;
+    return $this->_page($this->positionService);
+}

-    protected function initialize(): void
-    {
-        $this->logic = new PositionLogic();
-    }
+#[OperationLog('岗位管理-新增', OperationLog::TYPE_ADD, '新增岗位：{name}')]
+#[Permission('sys:position:add', '添加岗位')]
+public function add(PositionRequest $request): JsonResponse
+{
+    return $this->_add($this->positionService, $request->validated());
+}

-    #[Log('岗位管理-查询分页记录', Log::TYPE_QUERY)]
-    #[Permission('sys:position:page', '岗位分页')]
-    public function page(): Json
-    {
-        return parent::_index($this->logic);
-    }
-
-    #[Log('岗位管理-查询全量列表', Log::TYPE_QUERY)]
-    public function list(): Json
-    {
-        return parent::_list($this->logic);
-    }
-
-    #[Log('岗位管理-查询详情', Log::TYPE_QUERY, '查询岗位ID:{id}')]
-    public function detail(int $id): Json
-    {
-        return parent::_detail($this->logic, $id);
-    }
-
-    #[Log('岗位管理-新增记录', Log::TYPE_ADD, '新增岗位：{name}')]
-    #[Permission('sys:position:add', '添加岗位')]
-    public function add(): Json
-    {
-        return parent::_add($this->logic, $this->getJsonBody());
-    }
-
-    #[Log('岗位管理-修改记录', Log::TYPE_UPDATE, '修改岗位ID:{id}')]
-    #[Permission('sys:position:update', '修改岗位')]
-    public function update(): Json
-    {
-        $data = $this->getJsonBody();
-        $id = $data['id'] ?? 0;
-        if (empty($id)) return $this->fail('缺少id参数');
-        return parent::_edit($this->logic, $id, $data);
-    }
-
-    #[Log('岗位管理-删除记录', Log::TYPE_DELETE, '删除岗位ID:{id}')]
-    #[Permission('sys:position:delete', '删除岗位')]
-    public function delete(int $id): Json
-    {
-        return parent::_remove($this->logic, $id);
-    }
-
-    #[Log('岗位管理-批量删除', Log::TYPE_DELETE)]
-    #[Permission('sys:position:delete', '删除岗位')]
-    public function batchDelete(): Json
-    {
-        $ids = $this->getJsonBody()['ids'] ?? [];
-        return parent::_batchRemove($this->logic, $ids);
-    }
+#[OperationLog('岗位管理-删除', OperationLog::TYPE_DELETE, '删除岗位ID:{id}')]
+#[Permission('sys:position:delete', '删除岗位')]
+public function delete(int $id): JsonResponse
+{
+    return $this->_delete($this->positionService, $id);
 }
 ```

 :::tip 极简 CRUD
-岗位模块是"零自定义方法"的典型示例——Logic 类只声明属性配置，Controller 调用父类通用方法，无需编写任何业务代码，即可获得完整的增删改查、分页、唯一性校验、枚举翻译能力。
-:::
+岗位模块几乎"零手写业务代码"——Service 只声明属性配置与删除校验钩子，Controller 调用基类通用方法，即可获得完整的增删改查、分页、唯一性校验、字典翻译能力。新模块建议从复制本模块结构开始。
+:::
+
+## 与其他模块的关系
+
+| 关系 | 说明 |
+|------|------|
+| 用户 → 岗位 | `laravel_user.position_id` 外键，用户表单级联选择 |
+| 详情回显 | 用户 `afterDetail` 中补全 `positionName` |
+| 导出映射 | 用户导出列「岗位」由岗位名称映射生成 |