# 审计日志查询

所有上传/下载请求由审计中间件自动落库（需求 ③），管理端分页查询。
认证：`Authorization: Bearer <token>`。

## 审计记录内容

每条审计日志覆盖以下维度（需求 ③）：

| 维度 | 字段 | 说明 |
|---|---|---|
| 操作时间 | `created_at` | RFC 3339 |
| 客户端 | `ip` | 可信代理场景解析 XFF 后的真实 IP |
| 终端信息 | `user_agent` | 原始 UA |
| 设备解析 | `device_os` / `device_browser` / `device_type` | 由 UA 解析（如 Windows/Chrome/desktop） |
| 动作 | `action` | `upload`（上传类） / `download`（取件/下载类） / `admin`（管理端敏感操作，26.9 新增） |
| 结果 | `result` | `success` / `denied`（拒绝：401/403/423/428）/ `failed`（失败：其余 4xx/5xx 或业务报错） |
| 字节数 | `size_bytes` | 文件总大小；`transferred_bytes` 实际传输（**Range 下载只计实际区间字节**；下载由中间件自动统计，上传由各 handler 填充） |
| 耗时 | `duration_ms` | 毫秒 |
| 角色 | `actor` | `admin`（有效管理员令牌）/ `guest` |
| 业务 | `file_code` / `file_name` | 取件码 / 文件名（分片上传时 `file_code` 为 `upload_id`） |
| 错误 | `error_msg` | 失败/拒绝原因 |

**命中审计的端点**：上传类 `POST /share/text`、`POST /share/file`、`/chunk/upload*`、`/presign*`（POST/PUT）；
下载类 `GET /share/download`、`GET /share/select`、`GET /share/metadata`；
管理类（`action=admin`）`POST /admin/login`、`POST /admin/logout`、`PATCH|POST /admin/config/update`、
`PATCH|POST /admin/settings/password`、`POST /admin/storage/switch`、`PATCH|DELETE /admin/file/update|delete|batch-delete|batch-update|policy-action|batch-policy-action`。
管理类动作未显式填结果时按 HTTP 状态兜底落库（401/403/423 → `denied`，5xx → `failed`，其余 → `success`）。
失败与被拒绝的请求同样落库。

## 查询接口：GET /admin/audit/list

**参数**：

| 参数 | 默认 | 说明 |
|---|---|---|
| `page` | 1 | 页码（≥1） |
| `size` | 20 | 每页条数（1~200；兼容 `pageSize`） |
| `action` | - | `upload` / `download` / `admin` |
| `result` | - | `success` / `denied` / `failed` |
| `ip` | - | 按客户端 IP 过滤 |
| `start_time` / `end_time` | - | 时间范围，ISO 8601（如 `2025-06-01T00:00:00+08:00`；也接受 `2006-01-02 15:04:05` / 日期） |

```bash
curl -s "http://localhost:8466/admin/audit/list?page=1&size=20&action=download&result=success&start_time=2025-06-01T00:00:00%2B08:00" \
  -H "Authorization: Bearer $TOKEN"
```

**成功响应**（200）：

```json
{
  "code": 200, "msg": "ok",
  "data": {
    "data": [
      {
        "id": 318,
        "action": "download",
        "file_code": "K3P9W",
        "file_name": "report.pdf",
        "size_bytes": 1048576,
        "transferred_bytes": 524288,
        "ip": "203.0.113.7",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
        "device_os": "Windows",
        "device_browser": "Chrome",
        "device_type": "desktop",
        "actor": "guest",
        "result": "success",
        "error_msg": "",
        "duration_ms": 128,
        "created_at": "2025-06-01T12:03:45+08:00",
        "fileCode": "K3P9W",
        "fileName": "report.pdf",
        "sizeBytes": 1048576,
        "transferredBytes": 524288,
        "userAgent": "Mozilla/5.0 …",
        "deviceOs": "Windows",
        "deviceBrowser": "Chrome",
        "deviceType": "desktop",
        "errorMsg": "",
        "durationMs": 128,
        "createdAt": "2025-06-01T12:03:45+08:00"
      }
    ],
    "total": 1180,
    "page": 1,
    "size": 20
  }
}
```

> 行字段以 snake_case 为准；camelCase 为兼容双份输出（文档不再重复列出）。

**错误响应**：

```json
{ "code": 400, "msg": "start_time 时间格式错误" }
```

```json
{ "code": 401, "msg": "令牌无效或已过期" }
```

## 别名：GET /admin/audit/logs

与 `/admin/audit/list` 完全相同（同一 handler 的兼容别名），参数与响应一致。

## 典型查询

```bash
# 最近的下载行为
curl -s "http://localhost:8466/admin/audit/list?action=download&size=50" -H "Authorization: Bearer $TOKEN"

# 某 IP 的全部被拒请求（限流/鉴权失败）
curl -s "http://localhost:8466/admin/audit/list?ip=203.0.113.7&result=denied" -H "Authorization: Bearer $TOKEN"

# 今天 0 点以来的上传失败
curl -s "http://localhost:8466/admin/audit/list?action=upload&result=failed&start_time=2025-06-01T00:00:00%2B08:00" \
  -H "Authorization: Bearer $TOKEN"
```