上传规范文档

docs/API接口文档/日志模块接口文档.md

@@ -0,0 +1,121 @@
+# Hertz Studio Django 日志模块接口文档
+
+- 基础路径: `/api/log/`
+- 统一响应: 使用 `HertzResponse`，结构如下（参考 `hertz_studio_django_utils/responses/HertzResponse.py`）
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "操作成功",
+    "data": {}
+  }
+  ```
+- 路由挂载: 项目主路由中已通过 `path('api/log/', include('hertz_studio_django_log.urls'))` 挂载（`hertz_server_django/urls.py:46`）。
+- 认证与权限: 接口需要登录并具备相应权限，其中列表接口需 `system:log:list`，详情接口需 `system:log:query`（`hertz_studio_django_log/views/log_views.py:18`, `225`）。
+
+
+## 一、操作日志列表
+
+### 获取操作日志列表
+- 方法: `GET`
+- 路径: `/api/log/list/`
+- 权限: 仅管理员（`system:log:list`）
+- 查询参数:
+  - `user_id`: 用户ID
+  - `username`: 用户名（模糊匹配）
+  - `action_type`: 操作类型（`create|update|delete|view|list|login|logout|export|import|other`）
+  - `module`: 操作模块（模糊匹配）
+  - `status`: 操作状态（`0|1`）
+  - `ip_address`: IP地址
+  - `start_date`: 开始时间（ISO日期时间）
+  - `end_date`: 结束时间（ISO日期时间）
+  - `page`: 页码，默认 `1`
+  - `page_size`: 每页数量，默认 `20`
+- 实现: `operation_log_list`（`hertz_studio_django_log/views/log_views.py:117`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/log/list/?username=admin&action_type=login&page=1&page_size=10" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取操作日志列表成功",
+    "data": {
+      "logs": [
+        {
+          "log_id": 1001,
+          "username": "admin",
+          "action_type": "login",
+          "action_type_display": "登录",
+          "module": "认证",
+          "description": "用户登录",
+          "ip_address": "127.0.0.1",
+          "response_status": 200,
+          "status": 1,
+          "status_display": "成功",
+          "is_success": true,
+          "created_at": "2025-11-17T08:30:00Z"
+        }
+      ],
+      "pagination": {
+        "page": 1,
+        "page_size": 10,
+        "total_count": 1,
+        "total_pages": 1,
+        "has_next": false,
+        "has_previous": false
+      }
+    }
+  }
+  ```
+
+
+## 二、操作日志详情
+
+### 获取操作日志详情
+- 方法: `GET`
+- 路径: `/api/log/detail/{log_id}/`
+- 权限: 仅管理员（`system:log:query`）
+- 路径参数: `log_id` 日志ID
+- 实现: `operation_log_detail`（`hertz_studio_django_log/views/log_views.py:259`）
+- 请求示例:
+  ```bash
+  curl "http://localhost:8000/api/log/detail/1001/" \
+    -H "Authorization: Bearer <token>"
+  ```
+- 返回示例（节选）:
+  ```json
+  {
+    "success": true,
+    "code": 200,
+    "message": "获取操作日志详情成功",
+    "data": {
+      "log_id": 1001,
+      "user": 1,
+      "username": "admin",
+      "action_type": "login",
+      "action_type_display": "登录",
+      "module": "认证",
+      "description": "用户登录",
+      "target_model": null,
+      "target_id": null,
+      "ip_address": "127.0.0.1",
+      "user_agent": "Mozilla/5.0",
+      "request_data": {"username": "admin"},
+      "formatted_request_data": "{\n  \"username\": \"admin\"\n}",
+      "response_status": 200,
+      "status": 1,
+      "status_display": "成功",
+      "is_success": true,
+      "created_at": "2025-11-17T08:30:00Z"
+    }
+  }
+  ```
+
+
+## 三、备注
+- 列表返回采用 `OperationLogListSerializer` 字段子集以简化展示。
+- 详情返回使用 `OperationLogSerializer`，包含格式化的请求数据与成功判断等辅助字段。