签入版本

RXThinkCMF_Laravel13_NaiveVue/zh/standards/deletion.md

@@ -3,7 +3,7 @@
 ## 软删除约定
 
 :::tip 核心原则
-所有业务数据统一使用软删除机制，通过 `is_delete` 字段标记记录状态，不物理删除数据。
+所有业务数据统一使用软删除机制，通过 `is_delete` 字段标记记录状态，不物理删除数据（`SoftDeletesByFlag` Trait + `SoftDeleteFlagScope` 全局范围，不使用 `deleted_at`）。
 :::
 
 | is_delete 值 | 含义 |
@@ -24,11 +24,11 @@ DELETE /api/{module}/delete/{id}
 ### Controller 示例
 
 ```php
-#[Log('案例演示-删除记录', Log::TYPE_DELETE, '删除案例演示ID:{id}')]
-#[Permission('sys:example:delete', '删除案例演示')]
-public function delete(int $id): Json
+#[OperationLog('案例演示-删除', OperationLog::TYPE_DELETE, '删除案例ID:{id}')]
+#[Permission('sys:example:delete', '删除案例')]
+public function delete(int $id): JsonResponse
 {
-    return parent::_remove($this->logic, $id);
+    return $this->_delete($this->exampleService, $id);
 }
 ```
 
@@ -38,17 +38,17 @@ public function delete(int $id): Json
 Controller::delete($id)
     │
     ▼
-BaseController::_remove($logic, $id)
+Controller 基类::_delete($service, $id)
     │
     ▼
-BaseLogic::delete($id)
-    │
-    ├─ beforeDelete($id) 钩子（抛异常可拦截）
+Service::delete($id) → HasCrudOperations::doDelete($id)
+    │  （DB::transaction 包裹）
+    ├─ beforeDelete($id) 钩子（抛异常可拦截，事务回滚）
     │
     ├─ $model->find($id)
     │   └─ 不存在 → return false
     │
-    ├─ $model->save(['is_delete' => 1])
+    ├─ $model->softDelete()   → UPDATE SET is_delete = 1
     │
     └─ afterDelete($id) 钩子
 ```
@@ -67,12 +67,12 @@ Content-Type: application/json
 ### Controller 示例
 
 ```php
-#[Log('案例演示-批量删除', Log::TYPE_DELETE)]
-#[Permission('sys:example:delete', '删除案例演示')]
-public function batchDelete(): Json
+#[OperationLog('案例演示-批量删除', OperationLog::TYPE_DELETE)]
+#[Permission('sys:example:batchDelete', '批量删除案例')]
+public function batchDelete(): JsonResponse
 {
     $ids = $this->getJsonBody()['ids'] ?? [];
-    return parent::_batchRemove($this->logic, $ids);
+    return $this->_batchDelete($this->exampleService, $ids);
 }
 ```
 
@@ -82,13 +82,13 @@ public function batchDelete(): Json
 Controller::batchDelete()
     │
     ▼
-BaseController::_batchRemove($logic, $ids)
+Controller 基类::_batchDelete($service, $ids)
     │
     ├─ ids 为空 → 返回失败 "请选择要删除的数据"
     │
     ▼
-BaseLogic::batchDelete($ids)
-    │
+Service::batchDelete($ids) → HasCrudOperations::doBatchDelete($ids)
+    │  （DB::transaction 包裹）
     ├─ beforeBatchDelete($ids) 钩子（整体校验）
     │
     ├─ 逐条 beforeDelete($id) 校验
@@ -99,12 +99,16 @@ BaseLogic::batchDelete($ids)
     └─ afterBatchDelete($ids) 钩子
 ```
 
+:::info 权限码区别
+单条删除权限为 `sys:{模块}:delete`，批量删除权限为 `sys:{模块}:batchDelete`（代码生成器创建菜单时分别生成），前端按钮需分别控制显隐。
+:::
+
 ## 删除前校验（beforeDelete 钩子）
 
-在 Logic 中重写 `beforeDelete` 方法，抛异常可拦截删除：
+在 Service 中重写 `beforeDelete` 方法，抛异常可拦截删除（事务自动回滚）：
 
 ```php
-class UserLogic extends BaseTenantLogic
+class DeptService extends BaseTenantService
 {
     protected function beforeDelete(int $id): void
     {
@@ -123,11 +127,13 @@ class UserLogic extends BaseTenantLogic
 }
 ```
 
+可用钩子（均在 `HasCrudOperations` 中声明）：`beforeDelete($id)`、`afterDelete($id)`、`beforeBatchDelete($ids)`、`afterBatchDelete($ids)`。
+
 ## 何时可物理删除
 
 | 场景 | 方式 | 说明 |
 |------|------|------|
-| 日志数据清理 | 定时任务 | CleanLogTask 清理 N 天前的日志 |
+| 日志数据清理 | 定时任务 | 通过「定时任务」模块（job 表）配置清理 N 天前的日志 |
 | 临时数据 | 定时任务 | 清理过期的临时文件 |
 | 其它 | 审批 | 需经过管理员审批 |
 
@@ -153,4 +159,4 @@ class UserLogic extends BaseTenantLogic
 >
   批量删除 ({{ selectedIds.length }})
 </el-button>
-```
+```