签入版本

RXThinkCMF_Laravel13_EleVue/zh/core/attributes.md

@@ -1,7 +1,7 @@
 # 5.17 注解系统总览
 
 :::tip 概述
-项目使用 PHP 8 原生注解（Attribute）实现声明式配置，目前有三个注解类（`app/Attributes/`）。注解标注在控制器方法上，中间件在请求处理过程中通过**反射（ReflectionMethod）读取**并执行对应逻辑（日志记录、权限校验、演示放行）——业务代码零侵入。
+项目使用 PHP 8 原生注解（Attribute）实现声明式配置，目前有四个注解类（`app/Attributes/`）。注解标注在控制器方法上，中间件在请求处理过程中通过**反射（ReflectionMethod）读取**并执行对应逻辑（日志记录、跳过日志、权限校验、演示放行）——业务代码零侵入。
 :::
 
 ## 注解清单
@@ -9,6 +9,7 @@
 | 注解 | 文件 | 作用域 | 读取方 | 用途 | 必填参数 |
 |------|------|--------|--------|------|---------|
 | `#[OperationLog]` | `OperationLog.php`（275 行） | 方法 | `LogOperation` 中间件 | 操作日志记录 | title |
+| `#[WithoutOperationLog]` | `WithoutOperationLog.php` | 方法 | `LogOperation` 中间件 | 跳过操作日志（标注即不记录） | 无 |
 | `#[Permission]` | `Permission.php` | 方法 | `Authenticate` 中间件 | 权限校验 | code |
 | `#[DemoAllow]` | `DemoAllow.php` | 方法 | `DemoMiddleware` | 演示环境放行 | 无 |
 
@@ -35,7 +36,7 @@ DemoMiddleware（demo，认证路由组内）
     │
     ▼
 LogOperation（log.operation）
-    │ handle：反射读取 #[OperationLog] 注解，判断是否记录
+    │ handle：反射读取 #[WithoutOperationLog]（标注即跳过）与 #[OperationLog] 注解，判断是否记录
     │ terminate：响应后写入操作日志
     │
     ▼
@@ -231,6 +232,42 @@ public function add(UserRequest $request): JsonResponse { ... }
 
 详见 [5.7 演示模式](/zh/core/demo-mode.html)。
 
+## #[WithoutOperationLog] 跳过操作日志注解
+
+**文件：** `app/Attributes/WithoutOperationLog.php`
+**读取方：** `LogOperation` 中间件（反射读取，异常静默视为未标注）
+**作用域：** 方法（仅 `TARGET_METHOD`，不支持类级）
+**参数：** 无（标记型注解）
+
+### 基本用法
+
+```php
+// 标注后，该方法不写入 OperationLog（写操作同样跳过）
+#[WithoutOperationLog]
+public function logout(Request $request): JsonResponse { ... }
+```
+
+### 工作原理
+
+```text
+LogOperation 判定逻辑：
+  1. 方法有 #[WithoutOperationLog] → 不记录（优先级最高，先于记录规则）
+  2. 否则按记录规则判定：
+     ├─ 写方法（POST/PUT/DELETE/PATCH）→ 一律记录
+     ├─ GET + 导出/导入/下载类型注解 → 记录
+     └─ 其它 → 不记录
+```
+
+### 典型场景
+
+已有专门日志载体的接口——登出的记录写入登录日志（`login_log`，`log_type=2`），不再重复产生操作日志：
+
+```php
+#[DemoAllow]
+#[WithoutOperationLog]
+public function logout(Request $request): JsonResponse { ... }
+```
+
 ## 注解组合使用
 
 ```php
@@ -248,6 +285,11 @@ public function page(): JsonResponse { ... }
 #[Permission('sys:dict:update', '修改字典')]
 #[DemoAllow]
 public function refreshCache(): JsonResponse { ... }
+
+// 演示放行 + 跳过操作日志（登出：演示环境可退出，记录只写登录日志）
+#[DemoAllow]
+#[WithoutOperationLog]
+public function logout(Request $request): JsonResponse { ... }
 ```
 
 ## 反射读取机制