概述

日志模块负责记录系统运行过程中的关键操作和请求轨迹，帮助团队快速定位问题、追溯操作历史。模块包含两大核心部分：

统一约定

• 所有接口需在 Header 中携带Authorization: Bearer <token>
• 所有接口统一返回格式：{ code, message, logId, data }
• code = 0表示成功
• 基础地址：开发环境http://localhost:8000

一、操作日志（前端上报）

操作日志用于记录用户在前端执行的关键操作。user字段由后端通过 JWT 自动注入，前端无需手动传递。

1.1 上报操作日志（新增）

POST /api/operation-logs/

请求参数（JSON Body）

请求示例

{"action":"update","module":"部门管理","target_name":"研发组","request_method":"PUT","request_url":"/api/departments/5/","ip_address":"187.68.233.93","address":"中国河南省信阳市","browser":"Edge 151","os":"Windows 10","device":"PC","duration_ms":128,"result":"success","log_id":"a1b2c3d4e5f6g7h8"}

返回参数（JSON）

1.2 分页查询列表（查询）

GET /api/operation-logs/

请求参数（Query String）

请求示例

GET /api/operation-logs/?search=张三&action=update&page=1&page_size=20&ordering=-created_at

返回参数（JSON）

data.results[]中每条记录的结构：

返回示例

{"code":0,"message":"success","logId":"c3d4e5f6g7h8i9j0","data":{"count":150,"next":"http://localhost:8000/api/operation-logs/?page=2","previous":null,"results":[{"id":1,"log_id":"a1b2c3d4e5f6g7h8","user_info":{"id":1,"name":"管理员"},"action":"update","module":"部门管理","target_id":"5","target_name":"研发组","request_method":"PUT","request_url":"/api/departments/5/","request_params":"{\"name\":\"研发组\"}","ip_address":"187.68.233.93","address":"中国河南省信阳市","browser":"Edge 151","os":"Windows 10","device":"PC","duration_ms":128,"result":"success","error_message":"","remark":"","created_by_info":{"id":1,"name":"管理员"},"created_at":"2026-08-07T10:30:00Z","updated_at":"2026-08-07T10:30:00Z"}]}}

1.3 查看详情（查询）

GET /api/operation-logs/{id}/

请求参数（路径参数）

返回参数（JSON）

1.4 软删除（删除）

DELETE /api/operation-logs/{id}/

软删除仅标记记录为已删除，不会从数据库中物理移除。

请求参数（路径参数）

返回参数（JSON）

1.5 批量删除（删除）

POST /api/operation-logs/batch-delete/

请求参数（JSON Body）

请求示例

{"ids":[1,2,3]}

返回参数（JSON）

1.6 清空全部（删除）

DELETE /api/operation-logs/clear/

⚠️注意：此操作会清空所有操作日志数据，请谨慎使用。

请求参数无

返回参数（JSON）

1.7 今日统计（查询）

GET /api/operation-logs/stats/today/

请求参数无

返回参数（JSON）

操作日志 — action 枚举

二、系统审计日志（后端自动记录）

系统审计日志由后端中间件自动记录，覆盖所有/api/请求的完整请求和响应。前端仅允许查询和删除，不允许新增和修改。

每条日志会记录以下完整信息：

• 请求端：HTTP 方法、路径、所属模块、查询参数、请求头（Authorization已脱敏）、请求体
• 响应端：HTTP 状态码、业务码、响应消息、响应头（Set-Cookie已隐藏）、响应体
• 环境信息：客户端 IP、地理位置（IP 自动解析）、浏览器、操作系统、设备类型、耗时
• 操作人：通过 JWT 自动识别

2.1 分页查询列表（查询）

GET /api/system-logs/

请求参数（Query String）

返回参数（JSON）

data.results[]中每条记录的结构：

返回示例

{"code":0,"message":"success","logId":"g7h8i9j0k1l2m3n4","data":{"count":1520,"next":"http://localhost:8000/api/system-logs/?page=2","previous":null,"results":[{"id":1,"log_id":"a1b2c3d4e5f6g7h8","user_info":{"id":1,"name":"管理员"},"request_method":"POST","request_path":"/api/members/","module":"成员管理","query_params":"","request_headers":"{\"HTTP_CONTENT_TYPE\":\"application/json\",\"HTTP_AUTHORIZATION\":\"Bearer eyJhbGc...\",\"HTTP_ORIGIN\":\"http://localhost:5173\"}","request_body":"{\"name\":\"李四\",\"email\":\"lisi@example.com\"}","response_status":201,"response_code":0,"response_message":"创建成功","response_headers":"{\"Content-Type\":\"application/json\",\"Allow\":\"GET, POST, HEAD, OPTIONS\"}","response_body":"{\"code\":0,\"message\":\"创建成功\",\"logId\":\"a1b2c3d4e5f6g7h8\",\"data\":{\"id\":42,\"name\":\"李四\"}}","ip_address":"192.168.1.100","address":"内网","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...","browser":"Chrome 120","os":"Windows 10","device":"PC","duration_ms":156,"exception_info":"","created_by_info":{"id":1,"name":"管理员"},"created_at":"2026-08-07T10:30:00Z"}]}}

2.2 查看详情（查询）

GET /api/system-logs/{id}/

请求参数（路径参数）

返回参数（JSON）

2.3 软删除（删除）

DELETE /api/system-logs/{id}/

软删除仅标记记录为已删除，不会从数据库中物理移除。

请求参数（路径参数）

返回参数（JSON）

2.4 批量删除（删除）

POST /api/system-logs/batch-delete/

请求参数（JSON Body）

请求示例

{"ids":[1,2,3]}

返回参数（JSON）

2.5 清空全部（删除）

DELETE /api/system-logs/clear/

⚠️注意：此操作会清空所有系统审计日志，请谨慎使用。

请求参数无

返回参数（JSON）

2.6 今日请求统计（查询）

GET /api/system-logs/stats/today/

请求参数无

返回参数（JSON）

三、附录

统一响应格式

所有接口均返回以下标准结构：

{"code":0,"message":"success","logId":"16位追踪ID","data":{}}

常见错误码

认证方式

所有接口需在 Header 中携带 JWT Token：

Authorization: Bearer <登录返回的 token>

系统日志请求头采集说明

后端中间件会采集以下请求头信息：

系统日志响应头采集说明

• 采集Content-Type、Allow、Content-Length等所有响应头
• Set-Cookie已做安全处理，显示为(已隐藏)

关联查询

系统审计日志中的log_id与 API 响应中的logId保持一致。前端在捕获 API 响应中的logId后，可在上报操作日志时携带该字段，从而实现操作日志 ↔ 系统审计日志 ↔ API 响应三端串联，方便进行全链路问题排查。