# 5.14 操作日志

:::tip 概述
操作日志由 **RouteSpec 声明驱动、中间件链尾采集、异步落库**——业务代码零参与。记什么、记不记、什么类型，全部来自路由声明与配置开关。
:::

## 声明驱动

```go
// internal/router/router.go（RouteSpec）
"Add": {Method: "POST", Path: "/api/example/add", Log: "案例演示-新增记录", LogType: "add"},
"Page": {Method: "GET", Path: "/api/example/page", Log: "案例演示-查询分页记录", LogType: "query"},
```

| 字段 | 语义 |
|---|---|
| Log | 日志标题（"模块-动作"格式）；空 = 不记录 |
| LogType | 动作字符串（add/update/delete/query/import/export/reset/generate/execute/pause…），落库时映射为数值枚举 |

**数值枚举**（`internal/consts/log_type.go`，前端按值映射显示，数值勿改动）：1 新增 / 2 修改 / 3 删除 / 4 查询 / 5 导入 / 6 导出 / 7 审批 / 8 驳回 / 9 提交 / 10 撤回 / 11 关闭 / 12 开启 / 13 启用 / 14 禁用 / 15 上传 / 16 下载 / 17 发送 / 18 同步 / 19 代码生成 / 20 清空 / 21 还原 / 22 登录 / 23 登出 / 24 重置 / 25 分配 / 26 授权 / 27 执行 / 28 暂停 / 29 恢复 / 30 发布 / 31 下架 / … / 40 解绑，99 其他，0 为自动推断占位（路由 LogType 为空时落 0）。

改一条声明即改变该接口的日志行为，authz/公开判断不受影响（同源）。

## 采集链路

```text
请求进入 → OperationLog 中间件（链尾）登记开始
        ↓
正常返回 / 拒绝 / panic  —— 中间件读到最终响应摘要
        ↓
组装条目（操作人、IP、UA、归属地、路径、入参摘要、结果码、耗时）
        ↓
异步写 gin_operation_log（不阻塞响应）
```

## 开关

```yaml
operationLog:
  enable: true      # 总开关
  logQuery: true    # 是否记录查询类（LogType=query）
```

审计要求高的环境两个都开；日志量敏感时关 logQuery（写操作仍记录）。

## 不记录的请求

被中间件链提前拒绝的请求不产生操作日志：限流拒绝、演示模式拒绝、未认证 401、租户拒绝、权限 403。这类拒绝在 metrics 中归类（denied/error），且运行日志有痕——避免日志表被攻击尝试刷爆。

## 归属地与 UA

条目含 IP 归属地（ip2region 离线库）与 User-Agent 解析——登录/操作审计可直接看出来源设备与地域。

## 消费

- 管理界面：日志管理页按操作人/类型/时间检索（见 [6.20 日志管理](/zh/modules/logger.html)）
- 保留期：`job.logRetentionDays`（默认 90 天），LogClean 任务超期物理清理

## 下一步

→ [5.15 登录日志](/zh/core/login-log.html)