日志审计 PRD

文档信息

项目	内容
产品名称	PMForge - 日志审计
文档版本	v2.0
创建日期	2026-09-16
最后更新	2026-09-24
文档状态	评审中
优先级	P1

---

一、功能概述

1.1 功能定位

日志审计是系统的"黑匣子"——就像飞机上的飞行记录仪一样，它默默记录着系统中发生的一切关键事件，一旦出了问题，管理员可以回溯每一笔操作、每一次请求、每一个异常，快速定位根因。

具体来说，日志审计模块统一管理四类日志：

日志类型	通俗理解	记录什么
登录日志	门禁刷卡记录	谁在什么时间、从哪个 IP、用什么设备登录了系统，成功还是失败
操作日志	办公室监控录像	用户在系统里做了什么——新建了订单、修改了用户信息、删除了数据
API 访问日志	高速公路收费站记录	每一次接口调用的完整信息：谁调的、花了多长时间、返回了什么结果
API 错误日志	设备故障报警单	接口出了什么错、错在哪一行代码、完整的异常堆栈

此外，模块还规划了安全审计能力（P2），用于自动识别异常登录行为（如异地登录、暴力破解）和审计敏感操作（如批量删除、权限变更）。

1.2 目标用户

用户类型	核心诉求	主要使用的日志
系统管理员	"有人投诉数据被改了，我要查是谁改的"	登录日志、操作日志
运维工程师	"接口变慢了/报错了，我要定位问题"	API 访问日志、API 错误日志
安全审计员	"有没有异常的登录行为？合规审查需要导出报告"	登录日志、操作日志（导出）
开发人员	"线上报错了，我要看异常堆栈定位 Bug"	API 错误日志、API 访问日志

1.3 业务价值

• 🔍 操作可追溯：任何数据变更都有据可查，解决"谁改了我的数据"这类扯皮问题
• 🛡️ 安全合规保障：满足等保二级/三级对日志审计的强制要求，支持日志导出应对审查
• ⚡ 故障快速定位：通过链路追踪编号（traceId）串联一次请求的所有日志，分钟级定位问题
• 📊 性能可观测：API 访问日志记录每次请求的执行时长，快速识别慢接口
• 🚨 异常主动发现：安全审计自动识别暴力破解、异地登录等威胁，变被动为主动

1.4 功能范围

功能分类	后台管理端	优先级	说明
登录日志（查看/导出）	✅	P0	记录所有登录/登出/注册行为
操作日志（查看/导出）	✅	P0	记录用户的关键业务操作
API 访问日志（查看/导出）	✅	P0	记录每次 API 调用的请求响应详情
API 错误日志（查看/处理/导出）	✅	P0	记录 API 异常，支持处理状态流转
安全审计（异常检测/敏感操作审计）	✅（规划中）	P2	基于日志数据的安全分析能力

说明：日志审计是纯后台管理功能，没有前台用户端页面。

---

二、用户场景

2.1 用户角色

角色	描述	核心诉求
系统管理员	后台管理人员，负责日常运维	追溯用户行为、导出数据审计报告
运维工程师	技术运维人员，保障系统稳定	监控 API 性能、排查错误、处理异常日志
安全审计员	安全合规人员，确保系统安全	发现异常登录、审计敏感操作、满足合规要求
开发人员	研发人员，负责功能开发与 Bug 修复	通过错误日志定位 Bug、分析性能瓶颈

2.2 使用场景

场景1：数据变更追溯——"谁改了这个订单？"

• 用户：系统管理员王哥
• 背景：客服接到用户投诉，说订单金额被莫名修改了
• 操作步骤：
  1. 王哥进入「系统管理 → 操作日志」页面
  2. 在搜索栏输入操作模块"订单"，时间范围选择"最近 7 天"
  3. 列表中出现了所有订单相关的操作记录
  4. 王哥找到目标订单编号，点击"查看详情"
  5. 详情页显示：操作人"运营-小李"、操作时间、操作内容"修改编号为 20260915 的订单金额，从 299 改成 199"
  6. 王哥截图保存，找小李核实情况
• 期望：操作明细清晰可读、支持按模块和业务编号精准筛选
• 异常处理：如果操作日志中没有找到记录，可能是通过 API 直接调用（非页面操作），需进一步查看 API 访问日志

场景2：异常登录排查——"有人在暴力破解账号"

• 用户：安全审计员小赵
• 背景：收到安全告警，某账号短时间内多次登录失败
• 操作步骤：
  1. 小赵进入「系统管理 → 登录日志」页面
  2. 筛选条件：用户账号="zhangsan"，登录状态="失败"，时间="今天"
  3. 列表显示 15 条失败记录，全部来自同一个 IP 203.0.113.50
  4. 小赵查看 IP 归属地，发现是境外 IP
  5. 点击"导出 Excel"，保存证据
  6. 联系运维将该 IP 加入黑名单（联动认证授权模块的 IP 黑名单功能）
• 期望：支持 IP 归属地显示、支持按时间范围导出、登录失败原因明确
• 异常处理：如果失败记录来自多个不同 IP，可能是分布式攻击，需升级处理

场景3：API 错误排查——"这个接口为什么报错？"

• 用户：运维工程师小陈
• 背景：监控系统告警，某接口错误率突然飙升
• 操作步骤：
  1. 小陈进入「基础设施 → API 错误日志」页面
  2. 筛选条件：请求地址="/api/order/create"，处理状态="未处理"
  3. 列表显示最近 20 条错误记录
  4. 点击第一条进入详情，看到：
     • 异常类名：NullPointerException
     • 异常位置：OrderServiceImpl.java:156
     • 异常堆栈：完整的调用链路
     • 请求参数：{userId: 10086, productId: null}
  5. 通过 traceId "abc123def456" 跳转到 API 访问日志，查看完整请求上下文
  6. 定位到根因：productId 参数为空导致空指针
  7. 通知开发修复，修复后将该日志标记为"已处理"
• 期望：异常信息完整（堆栈+行号）、支持 traceId 关联、支持处理状态流转
• 异常处理：如果同一异常大量重复出现，可以先标记为"已忽略"避免干扰，等开发统一修复

场景4：慢接口排查——"这个页面怎么加载这么慢？"

• 用户：运维工程师小陈
• 背景：用户反馈"项目列表页"打开要等 10 秒
• 操作步骤：
  1. 小陈进入「基础设施 → API 访问日志」页面
  2. 筛选条件：请求地址="/api/project/page"，执行时长=">= 3000ms"
  3. 列表显示多条慢请求记录，执行时长在 3000-8000ms 之间
  4. 点击查看详情，发现请求参数中 pageSize=1000——用户一次拉了 1000 条数据
  5. 进一步分析发现该接口没有限制 pageSize 上限
  6. 通知开发增加分页大小限制，并优化查询性能
• 期望：支持按执行时长筛选、展示完整请求参数和响应结果
• 异常处理：如果慢请求集中在某个时间段，可能是数据库压力导致，需结合监控运维模块分析

场景5：季度合规审计——"把日志报告导出来"

• 用户：安全审计员小赵
• 背景：每季度需要向合规部门提交日志审计报告
• 操作步骤：
  1. 小赵分别进入登录日志、操作日志、API 错误日志页面
  2. 设置时间范围为"本季度"
  3. 逐个点击"导出 Excel"
  4. 整理三份 Excel 报告，附上统计摘要（登录次数、失败率、错误处理率等）
  5. 提交合规部门审查
• 期望：导出格式规范、数据完整、支持大数量导出（最多 10 万条）
• 异常处理：如果导出数量超过 10 万条，需缩小时间范围分批导出

场景6：安全审计——自动检测异常登录（P2 规划中）

• 用户：安全审计员小赵
• 背景：希望系统自动识别异常登录行为，而不是人工逐条查看
• 操作步骤：
  1. 系统自动运行安全审计规则，检测到以下异常：
     • 用户"zhangsan"在凌晨 3 点登录（非常规时间）
     • 用户"lisi"的账号从北京和上海两个城市同时登录（异地登录）
     • IP 203.0.113.50 在 5 分钟内尝试登录 15 次（暴力破解）
  2. 系统自动发送站内通知给安全审计员
  3. 小赵查看告警详情，确认暴力破解属实，将该 IP 加入黑名单
  4. 对小赵标记"异地登录"为误报（用户出差）
• 期望：自动检测、自动告警、支持人工确认/排除

2.3 用户故事

编号	用户故事	优先级	验收标准
US-01	作为管理员，我希望查看登录日志列表，以便追溯用户登录行为	P0	① 支持按用户账号、IP、登录状态、时间范围筛选 ② 列表展示日志类型（登录/登出/注册）、用户账号、IP、浏览器、登录结果、时间 ③ 按时间倒序排列 ④ 分页查询响应 < 1s
US-02	作为管理员，我希望导出登录日志，以便提交审计报告	P1	① 导出内容与当前筛选条件一致 ② Excel 格式，包含所有列表字段 ③ 最大支持 10 万条 ④ 需要 system:login-log:export 权限
US-03	作为管理员，我希望查看操作日志及其详情，以便追溯数据变更	P0	① 支持按操作模块、操作名、操作人、时间范围筛选 ② 详情展示操作明细（如"将性别从男改成女"）和扩展字段 ③ 用户编号自动翻译为昵称显示
US-04	作为管理员，我希望导出操作日志，以便满足合规要求	P1	① 导出内容与筛选条件一致 ② 支持字典值翻译 ③ 需要 system:operate-log:export 权限
US-05	作为运维人员，我希望查看 API 访问日志，以便监控接口性能	P0	① 支持按应用名、请求地址、执行时长、结果码筛选 ② 展示执行时长（毫秒级） ③ 详情包含完整请求参数和响应结果
US-06	作为运维人员，我希望查看 API 错误日志，以便排查系统异常	P0	① 展示异常类名、异常消息、异常堆栈、出错位置（类名:行号） ② 支持按处理状态筛选 ③ 详情包含完整请求参数
US-07	作为运维人员，我希望标记错误日志的处理状态，以便跟踪处理进度	P1	① 支持标记为"已处理"或"已忽略" ② 自动记录处理人和处理时间 ③ 需要 infra:api-error-log:update-status 权限
US-08	作为安全审计员，我希望系统自动检测异常登录行为	P2	① 支持异地登录、暴力破解、非常规时间、新设备等检测规则 ② 检测到异常后自动发送通知 ③ 检测规则可配置
US-09	作为安全审计员，我希望审计敏感操作记录	P2	① 标记高风险操作（批量删除、权限变更等） ② 支持查看敏感操作汇总报告
US-10	作为运维人员，我希望通过 traceId 串联不同日志	P0	① 在错误日志详情中可通过 traceId 跳转到对应的访问日志 ② 在操作日志详情中可通过 traceId 跳转到访问日志 ③ 串联关系清晰可追溯

---

三、功能需求

3.1 后台管理端

3.1.1 功能清单

功能	优先级	说明
登录日志分页查询	P0	查看登录/登出/注册日志列表
登录日志详情	P1	查看单条登录日志完整信息
登录日志导出	P1	按筛选条件导出 Excel
操作日志分页查询	P0	查看操作日志列表
操作日志详情	P0	查看操作明细、扩展字段
操作日志导出	P1	按筛选条件导出 Excel
API 访问日志分页查询	P0	查看接口访问记录
API 访问日志详情	P1	查看请求参数、响应结果
API 访问日志导出	P1	按筛选条件导出 Excel
API 错误日志分页查询	P0	查看 API 异常记录
API 错误日志详情	P0	查看异常堆栈、定位信息
API 错误日志处理	P1	更新处理状态（已处理/已忽略）
API 错误日志导出	P1	按筛选条件导出 Excel
异常登录检测	P2	自动识别异地登录、暴力破解等异常
敏感操作审计	P2	标记和审计高危操作行为

---

3.1.2 登录日志

页面描述：

列表页展示所有登录/登出/注册记录。页面顶部是搜索区域，支持按用户账号（模糊匹配）、用户 IP（模糊匹配）、登录状态（成功/失败）、登录时间范围筛选。列表按时间倒序排列。

业务规则：

规则编号	规则描述	为什么这样设计
R-01	用户登录成功/失败、登出、注册时自动记录日志，无需人工干预	日志必须自动采集，不能依赖人工操作，否则会遗漏
R-02	日志类型区分：100-登录、101-登出、200-注册	区分不同事件类型，便于分类统计和筛选
R-03	登录结果包含多种失败原因：0-成功、10-密码错误、11-手机验证码错误、12-邮箱验证码错误、20-用户被禁用、30-IP 黑名单	细分失败原因有助于安全分析——密码错误可能是忘记密码，也可能是暴力破解
R-04	记录用户 IP 地址，解析 UserAgent 获取浏览器和操作系统信息	IP 用于追溯来源，UserAgent 用于识别设备类型，辅助安全判断
R-05	日志默认保留 30 天，可通过系统配置调整保留策略	平衡存储成本与审计需求，30 天覆盖大多数审计场景
R-06	导出 Excel 最大支持 10 万条记录	防止一次性导出过多数据导致系统卡顿或内存溢出
R-07	登录日志按创建时间倒序排列	最新日志在最前面，方便快速查看最近动态
R-08	用户账号冗余存储（不随用户修改账号而变化）	日志是历史记录，必须保留当时的账号信息，不能因为用户改名就丢失关联

数据字段：

字段名	类型	必填	说明
id	Long	是	日志编号
logType	Integer	是	日志类型（100-登录、101-登出、200-注册）
traceId	String	否	链路追踪编号（用于关联同一次请求的其他日志）
userId	Long	否	用户编号（登录失败时可能为空，因为还没确认身份）
userType	Integer	是	用户类型（1-会员、2-管理员）
username	String	是	用户账号（冗余存储，防止账号修改后日志丢失关联）
result	Integer	是	登录结果（0-成功、10-密码错误、11-手机验证码错误、12-邮箱验证码错误、20-用户被禁用、30-IP 黑名单）
userIp	String	是	用户 IP 地址
userAgent	String	否	浏览器 UserAgent（用于识别浏览器类型和操作系统）
createTime	DateTime	是	登录时间

接口设计：

接口名称	请求方式	接口路径	权限标识	说明
获取登录日志详情	GET	/admin-api/system/login-log/get	system:login-log:query	获取单条登录日志
获取登录日志分页	GET	/admin-api/system/login-log/page	system:login-log:query	分页查询登录日志
导出登录日志 Excel	GET	/admin-api/system/login-log/export-excel	system:login-log:export	按筛选条件导出

请求参数（分页查询）：

参数名	类型	必填	说明
userIp	String	否	用户 IP（模糊匹配）
username	String	否	用户账号（模糊匹配）
status	Boolean	否	登录状态（true-成功、false-失败）
createTime	DateTime[]	否	登录时间范围
pageNo	Integer	是	页码（从 1 开始）
pageSize	Integer	是	每页条数（默认 10）

返回结果（分页列表）：

字段名	类型	说明
id	Long	日志编号
logType	Integer	日志类型
userId	Long	用户编号
userType	Integer	用户类型
traceId	String	链路追踪编号
username	String	用户账号
result	Integer	登录结果
userIp	String	用户 IP
userAgent	String	浏览器 UA
createTime	DateTime	登录时间

---

3.1.3 操作日志

页面描述：

列表页展示用户在系统中的关键操作记录。支持按操作模块、操作名、操作人、操作时间范围筛选。点击"查看详情"可看到完整的操作描述（如"修改编号为 1 的用户信息，将性别从男改成女"）和扩展字段（JSON 格式的业务数据）。

详情弹窗：

业务规则：

规则编号	规则描述	为什么这样设计
R-01	通过 @OperateLog 注解自动记录操作日志，开发者在业务方法上标注即可	统一采集方式，避免每个模块自己写日志逻辑，减少遗漏
R-02	操作日志记录两级分类：操作模块类型（type，如"订单"）和操作名（subType，如"修改订单"）	两级分类便于按模块汇总统计，也便于按具体操作精准查找
R-03	操作明细（action）记录完整的操作描述，如"修改编号为 1 的用户信息，将性别从男改成女"	用自然语言描述变更内容，非技术人员也能看懂
R-04	扩展字段（extra）支持 JSON 格式，记录业务关键数据（如修改前后的值）	不同业务需要记录的数据不同，JSON 格式灵活可扩展
R-05	通过链路追踪编号（traceId）可关联 API 访问日志	当操作日志不够排查问题时，可以通过 traceId 查看完整的请求和响应
R-06	操作日志通过 userId 关联用户信息，列表展示时自动翻译为用户昵称	管理员看昵称比看编号直观得多
R-07	日志默认保留 30 天	与登录日志保持一致的保留策略
R-08	导出操作需要 system:operate-log:export 权限	操作日志可能包含敏感业务数据，导出需要额外权限控制

数据字段：

字段名	类型	必填	说明
id	Long	是	日志编号
traceId	String	否	链路追踪编号
userId	Long	是	用户编号
userType	Integer	是	用户类型
type	String	是	操作模块类型（如"订单"、"用户"）
subType	String	是	操作名（如"创建订单"、"修改用户"）
bizId	Long	否	操作模块业务编号
action	String	否	操作明细（完整操作描述，自然语言）
extra	String	否	扩展字段（JSON 格式，记录业务关键数据）
requestMethod	String	是	请求方法（GET/POST/PUT/DELETE）
requestUrl	String	是	请求地址
userIp	String	是	用户 IP
userAgent	String	否	浏览器 UA
createTime	DateTime	是	操作时间

接口设计：

接口名称	请求方式	接口路径	权限标识	说明
获取操作日志详情	GET	/admin-api/system/operate-log/get	system:operate-log:query	获取单条操作日志
获取操作日志分页	GET	/admin-api/system/operate-log/page	system:operate-log:query	分页查询操作日志
导出操作日志 Excel	GET	/admin-api/system/operate-log/export-excel	system:operate-log:export	按筛选条件导出

请求参数（分页查询）：

参数名	类型	必填	说明
userId	Long	否	用户编号
bizId	Long	否	操作模块业务编号
type	String	否	操作模块（模糊匹配）
subType	String	否	操作名（模糊匹配）
action	String	否	操作明细（模糊匹配）
createTime	DateTime[]	否	操作时间范围
pageNo	Integer	是	页码（从 1 开始）
pageSize	Integer	是	每页条数（默认 10）

返回结果（分页列表）：

字段名	类型	说明
id	Long	日志编号
traceId	String	链路追踪编号
userId	Long	用户编号
userName	String	用户昵称（自动翻译）
userType	Integer	用户类型
type	String	操作模块类型
subType	String	操作名
bizId	Long	操作模块业务编号
action	String	操作明细
extra	String	扩展字段
requestMethod	String	请求方法
requestUrl	String	请求地址
userIp	String	用户 IP
userAgent	String	浏览器 UA
createTime	DateTime	操作时间

---

3.1.4 API 访问日志

页面描述：

列表页展示每一次 API 请求的完整信息。支持按应用名、请求地址、执行时长（筛选慢接口）、结果码、时间范围筛选。

💡 提示：上表中"执行时长 5200ms"那条记录标红高亮，提示运维人员关注慢接口。

业务规则：

规则编号	规则描述	为什么这样设计
R-01	每次 API 请求自动记录访问日志，通过全局拦截器实现	全量采集，不遗漏任何请求，开发者无需手动埋点
R-02	记录完整的请求信息：请求方法、URL、参数、响应结果、执行时长	完整信息是性能分析和问题排查的基础
R-03	请求参数最大长度 8000 字符，超出部分截断	防止超大请求体（如文件上传）撑爆数据库
R-04	响应结果消息最大长度 512 字符，超出部分截断	只记录结果消息，不记录完整响应体，控制存储量
R-05	执行时长精确到毫秒	毫秒级精度是性能分析的基本要求，能区分"正常"和"偏慢"
R-06	应用名读取 spring.application.name 配置	未来拆分微服务时，可以通过应用名区分不同服务的日志
R-07	通过链路追踪编号（traceId）可串联操作日志和错误日志	一次请求可能同时产生操作日志和错误日志，traceId 是串联的线索
R-08	日志数据量大，默认保留 7 天（可通过配置调整）	API 访问日志日均 50 万条，全量保留存储成本太高
R-09	导出操作需要 infra:api-access-log:export 权限	访问日志包含请求参数，可能含敏感数据

数据字段：

字段名	类型	必填	说明
id	Long	是	日志编号
traceId	String	否	链路追踪编号
userId	Long	否	用户编号（未登录接口为空）
userType	Integer	否	用户类型
applicationName	String	是	应用名（微服务名称）
requestMethod	String	是	请求方法（GET/POST/PUT/DELETE）
requestUrl	String	是	请求地址
requestParams	String	否	请求参数（Query + Body，最大 8000 字符）
responseBody	String	否	响应结果
userIp	String	是	用户 IP
userAgent	String	否	浏览器 UA
operateModule	String	否	操作模块
operateName	String	否	操作名
operateType	Integer	否	操作分类（1-查询、2-新增、3-修改、4-删除、5-导出、6-导入）
beginTime	DateTime	是	开始请求时间
endTime	DateTime	是	结束请求时间
duration	Integer	是	执行时长（毫秒）
resultCode	Integer	是	结果码（0-成功，其他-失败）
resultMsg	String	否	结果提示（最大 512 字符）
createTime	DateTime	是	创建时间

接口设计：

接口名称	请求方式	接口路径	权限标识	说明
获取 API 访问日志详情	GET	/admin-api/infra/api-access-log/get	infra:api-access-log:query	获取单条访问日志
获取 API 访问日志分页	GET	/admin-api/infra/api-access-log/page	infra:api-access-log:query	分页查询访问日志
导出 API 访问日志 Excel	GET	/admin-api/infra/api-access-log/export-excel	infra:api-access-log:export	按筛选条件导出

请求参数（分页查询）：

参数名	类型	必填	说明
userId	Long	否	用户编号
userType	Integer	否	用户类型
applicationName	String	否	应用名（模糊匹配）
requestUrl	String	否	请求地址（模糊匹配）
duration	Integer	否	执行时长下限（毫秒），筛选 >= 该值的记录
resultCode	Integer	否	结果码
beginTime	DateTime[]	否	请求时间范围
pageNo	Integer	是	页码（从 1 开始）
pageSize	Integer	是	每页条数（默认 10）

返回结果（分页列表）：

字段名	类型	说明
id	Long	日志编号
traceId	String	链路追踪编号
userId	Long	用户编号
userType	Integer	用户类型
applicationName	String	应用名
requestMethod	String	请求方法
requestUrl	String	请求地址
requestParams	String	请求参数
responseBody	String	响应结果
userIp	String	用户 IP
userAgent	String	浏览器 UA
operateModule	String	操作模块
operateName	String	操作名
operateType	Integer	操作分类
beginTime	DateTime	开始请求时间
endTime	DateTime	结束请求时间
duration	Integer	执行时长（毫秒）
resultCode	Integer	结果码
resultMsg	String	结果提示
createTime	DateTime	创建时间

---

3.1.5 API 错误日志

页面描述：

列表页展示 API 异常记录。支持按应用名、请求地址、异常时间范围、处理状态筛选。列表展示异常名、异常消息、处理状态等关键信息。

详情页面（含处理操作）：

业务规则：

规则编号	规则描述	为什么这样设计
R-01	API 请求发生异常时自动记录错误日志，由全局异常处理器触发	自动采集，开发者无需手动记录，确保不遗漏任何异常
R-02	记录完整的异常信息：异常类名、异常消息、根异常消息、堆栈轨迹、异常发生的类/方法/行号	完整的异常信息是开发定位 Bug 的关键，尤其是行号可以直接定位代码位置
R-03	请求参数最大长度 8000 字符，超出部分截断	与 API 访问日志保持一致，防止超大参数撑爆存储
R-04	处理状态枚举：0-未处理、1-已处理、2-已忽略	三态设计覆盖所有场景——有些错误需要修复，有些是已知问题可以忽略
R-05	更新处理状态时自动记录处理人（当前登录用户）和处理时间	责任到人，避免"我以为别人处理了"的情况
R-06	通过链路追踪编号（traceId）可关联对应的 API 访问日志	错误日志只有异常信息，关联访问日志可以看到完整的请求上下文
R-07	日志默认保留 90 天	错误日志量不大（日均约 1000 条），保留更长时间有助于发现周期性 Bug
R-08	更新处理状态需要 infra:api-error-log:update-status 权限	处理状态是问题跟踪的依据，不能随意修改

数据字段：

字段名	类型	必填	说明
id	Long	是	日志编号
traceId	String	否	链路追踪编号
userId	Long	否	用户编号
userType	Integer	否	用户类型
applicationName	String	是	应用名
requestMethod	String	是	请求方法
requestUrl	String	是	请求地址
requestParams	String	否	请求参数（最大 8000 字符）
userIp	String	是	用户 IP
userAgent	String	否	浏览器 UA
exceptionTime	DateTime	是	异常发生时间
exceptionName	String	是	异常类全名（如 java.lang.NullPointerException）
exceptionMessage	String	否	异常消息
exceptionRootCauseMessage	String	否	根异常消息（嵌套异常的最底层原因）
exceptionStackTrace	String	否	异常堆栈轨迹（完整堆栈）
exceptionClassName	String	否	异常发生的类全名
exceptionFileName	String	否	异常发生的类文件名
exceptionMethodName	String	否	异常发生的方法名
exceptionLineNumber	Integer	否	异常发生的方法行号
processStatus	Integer	是	处理状态（0-未处理、1-已处理、2-已忽略）
processTime	DateTime	否	处理时间
processUserId	Long	否	处理用户编号
createTime	DateTime	是	创建时间

接口设计：

接口名称	请求方式	接口路径	权限标识	说明
获取 API 错误日志详情	GET	/admin-api/infra/api-error-log/get	infra:api-error-log:query	获取单条错误日志
获取 API 错误日志分页	GET	/admin-api/infra/api-error-log/page	infra:api-error-log:query	分页查询错误日志
更新错误日志处理状态	PUT	/admin-api/infra/api-error-log/update-status	infra:api-error-log:update-status	标记处理状态
导出 API 错误日志 Excel	GET	/admin-api/infra/api-error-log/export-excel	infra:api-error-log:export	按筛选条件导出

请求参数（分页查询）：

参数名	类型	必填	说明
userId	Long	否	用户编号
userType	Integer	否	用户类型
applicationName	String	否	应用名（模糊匹配）
requestUrl	String	否	请求地址（模糊匹配）
exceptionTime	DateTime[]	否	异常发生时间范围
processStatus	Integer	否	处理状态（0-未处理、1-已处理、2-已忽略）
pageNo	Integer	是	页码（从 1 开始）
pageSize	Integer	是	每页条数（默认 10）

请求参数（更新处理状态）：

参数名	类型	必填	说明
id	Long	是	错误日志编号
processStatus	Integer	是	处理状态（1-已处理、2-已忽略）

返回结果（更新处理状态）：

字段名	类型	说明
data	Boolean	操作结果（true-成功）

---

3.1.6 安全审计（P2 规划中）

以下功能为 P2 优先级，计划在核心日志功能完成后迭代开发。

3.1.6.1 异常登录检测

功能描述：

基于登录日志数据，自动识别异常登录行为并生成告警。就像小区的安保系统——不仅记录谁进了门，还会自动发现可疑人员。

检测规则：

规则编号	规则名称	检测逻辑	告警级别	通俗解释
SR-01	异地登录检测	同一用户短时间内 IP 归属地发生跨省变化	高	10 分钟前在北京登录，现在就从上海登录了——账号可能被盗
SR-02	暴力破解检测	同一 IP 在 5 分钟内登录失败超过 10 次	高	有人在疯狂尝试密码，大概率是攻击行为
SR-03	频繁失败检测	同一用户在 1 小时内登录失败超过 5 次	中	用户自己一直输错密码，可能需要帮助重置
SR-04	非常规时间登录	用户在凌晨 0:00-6:00 期间登录	低	半夜登录不一定有问题，但值得关注
SR-05	新设备登录	用户使用了从未出现过的 UserAgent 登录	低	可能换了手机或电脑，也可能是别人在用

告警方式：

告警渠道	说明	实现方式
站内通知	推送给系统管理员和安全审计员	联动消息通知模块
邮件通知	发送给安全审计员邮箱	联动消息通知模块的邮件发送能力

3.1.6.2 敏感操作审计

功能描述：

标记系统中高风险操作，支持查看敏感操作汇总报告。就像银行的高柜业务——某些操作需要额外审批和记录。

敏感操作类型：

操作类型	示例	风险等级	为什么高风险
批量删除	批量删除用户、角色	高	误操作影响面大，且难以恢复
权限变更	修改角色权限、分配管理员	高	可能导致权限泄露或越权
数据导出	导出用户列表、导出日志	中	可能泄露敏感数据
系统配置变更	修改系统参数、修改安全策略	高	影响全局，可能导致系统异常
账号操作	重置密码、锁定/解锁账号	中	可能被用于社会工程攻击

---

四、非功能需求

4.1 性能要求

指标	要求	说明
登录日志分页查询	< 1s（30 天内数据）	登录日志量较小，查询应快速
操作日志分页查询	< 1s（30 天内数据）	操作日志量中等，需索引优化
API 访问日志分页查询	< 1s（当日数据）	访问日志量大（日均 50 万），需限制查询时间范围
API 错误日志分页查询	< 1s（90 天内数据）	错误日志量小，查询应快速
日志导出（10 万条）	< 30s	异步生成文件，避免阻塞页面
日志写入延迟	< 100ms	异步写入，不影响业务接口响应速度
日志对业务接口性能影响	< 5%	日志是辅助功能，不能拖慢核心业务

4.2 数据量预估

日志类型	日均数据量	月均数据量	默认保留天数	存储策略
登录日志	~1 万条	~30 万条	30 天	到期自动归档到冷存储
操作日志	~5 万条	~150 万条	30 天	到期自动归档到冷存储
API 访问日志	~50 万条	~1500 万条	7 天	量大，短保留 + 定期归档
API 错误日志	~1 千条	~3 万条	90 天	量小，长保留便于排查

💡 存储估算：以 MySQL 为例，API 访问日志每条约 2KB，日均 50 万条 ≈ 1GB/天，7 天 ≈ 7GB。建议生产环境配置定时任务自动清理过期数据。

4.3 安全要求

要求	说明	实现方式
日志不可篡改	日志写入后不支持修改和删除（错误日志仅支持标记处理状态）	不提供删除接口，数据库层面限制 UPDATE/DELETE
敏感信息脱敏	请求参数中的密码、Token 等敏感字段需脱敏存储	在日志写入前对敏感字段做掩码处理（如 ***）
访问权限控制	日志查看和导出需要对应权限	基于 RBAC 权限体系，每个操作都有独立的权限标识
日志传输加密	日志数据传输使用 HTTPS 加密	全站 HTTPS
操作留痕	日志导出操作本身也记录操作日志	导出接口标注 @OperateLog 注解

4.4 可用性要求

要求	说明
日志记录不阻塞业务	日志写入采用异步方式（线程池 + 消息队列），业务接口无需等待日志写入完成
日志写入容错	日志写入失败不影响业务接口正常执行——日志是辅助功能，不能因为日志出错导致业务中断
大数据量查询优化	支持分页查询、索引优化，避免全表扫描；对超大时间范围查询做限制

---

五、数据设计

5.1 数据模型

登录日志表（system_login_log）

字段名	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	日志主键
log_type	TINYINT	NOT NULL	日志类型（100-登录、101-登出、200-注册）
trace_id	VARCHAR(64)	-	链路追踪编号
user_id	BIGINT	-	用户编号（登录失败时可能为空）
user_type	TINYINT	NOT NULL	用户类型（1-会员、2-管理员）
username	VARCHAR(50)	NOT NULL	用户账号（冗余存储）
result	TINYINT	NOT NULL	登录结果（0-成功、10-密码错误、11-手机验证码错误、12-邮箱验证码错误、20-用户被禁用、30-IP 黑名单）
user_ip	VARCHAR(50)	-	用户 IP 地址
user_agent	VARCHAR(512)	-	浏览器 UserAgent
tenant_id	BIGINT	NOT NULL	租户编号
creator	VARCHAR(64)	-	创建者
create_time	DATETIME	NOT NULL	创建时间
updater	VARCHAR(64)	-	更新者
update_time	DATETIME	NOT NULL	更新时间
deleted	BIT(1)	NOT NULL, DEFAULT 0	删除标记

索引设计：

索引名	字段	类型	说明
idx_username	username	普通索引	按用户账号查询
idx_user_ip	user_ip	普通索引	按 IP 查询（排查暴力破解）
idx_result	result	普通索引	按登录结果筛选失败记录
idx_create_time	create_time	普通索引	按时间范围查询
idx_tenant_create	tenant_id, create_time	联合索引	租户 + 时间范围查询（最常用组合）

操作日志表（system_operate_log）

字段名	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	日志主键
trace_id	VARCHAR(64)	-	链路追踪编号
user_id	BIGINT	-	用户编号
user_type	TINYINT	-	用户类型
type	VARCHAR(50)	-	操作模块类型（如"订单"、"用户"）
sub_type	VARCHAR(50)	-	操作名（如"创建订单"）
biz_id	BIGINT	-	操作模块业务编号
action	TEXT	-	操作明细（完整操作描述）
extra	VARCHAR(2000)	-	扩展字段（JSON 格式）
request_method	VARCHAR(16)	-	请求方法
request_url	VARCHAR(512)	-	请求地址
user_ip	VARCHAR(50)	-	用户 IP
user_agent	VARCHAR(512)	-	浏览器 UA
tenant_id	BIGINT	NOT NULL	租户编号
creator	VARCHAR(64)	-	创建者
create_time	DATETIME	NOT NULL	创建时间
updater	VARCHAR(64)	-	更新者
update_time	DATETIME	NOT NULL	更新时间
deleted	BIT(1)	NOT NULL, DEFAULT 0	删除标记

索引设计：

索引名	字段	类型	说明
idx_user_id	user_id	普通索引	按用户查询操作记录
idx_type	type	普通索引	按操作模块查询
idx_biz_id	biz_id	普通索引	按业务编号精准查询
idx_create_time	create_time	普通索引	按时间范围查询
idx_tenant_create	tenant_id, create_time	联合索引	租户 + 时间范围查询

API 访问日志表（infra_api_access_log）

字段名	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	日志主键
trace_id	VARCHAR(64)	-	链路追踪编号
user_id	BIGINT	-	用户编号
user_type	TINYINT	-	用户类型
application_name	VARCHAR(50)	-	应用名
request_method	VARCHAR(16)	-	请求方法
request_url	VARCHAR(512)	-	请求地址
request_params	TEXT	-	请求参数（最大 8000 字符）
response_body	TEXT	-	响应结果
user_ip	VARCHAR(50)	-	用户 IP
user_agent	VARCHAR(512)	-	浏览器 UA
operate_module	VARCHAR(50)	-	操作模块
operate_name	VARCHAR(50)	-	操作名
operate_type	INT	-	操作分类
begin_time	DATETIME	-	开始请求时间
end_time	DATETIME	-	结束请求时间
duration	INT	-	执行时长（毫秒）
result_code	INT	-	结果码
result_msg	VARCHAR(512)	-	结果提示
tenant_id	BIGINT	NOT NULL	租户编号
creator	VARCHAR(64)	-	创建者
create_time	DATETIME	NOT NULL	创建时间
updater	VARCHAR(64)	-	更新者
update_time	DATETIME	NOT NULL	更新时间
deleted	BIT(1)	NOT NULL, DEFAULT 0	删除标记

索引设计：

索引名	字段	类型	说明
idx_user_id	user_id	普通索引	按用户查询
idx_request_url	request_url(191)	普通索引	按请求地址查询（前缀索引，兼容 utf8mb4）
idx_duration	duration	普通索引	按执行时长筛选慢接口
idx_result_code	result_code	普通索引	按结果码筛选
idx_begin_time	begin_time	普通索引	按请求时间查询
idx_tenant_begin	tenant_id, begin_time	联合索引	租户 + 时间范围查询

API 错误日志表（infra_api_error_log）

字段名	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	日志主键
trace_id	VARCHAR(64)	-	链路追踪编号
user_id	BIGINT	-	用户编号
user_type	TINYINT	-	用户类型
application_name	VARCHAR(50)	-	应用名
request_method	VARCHAR(16)	-	请求方法
request_url	VARCHAR(512)	-	请求地址
request_params	TEXT	-	请求参数（最大 8000 字符）
user_ip	VARCHAR(50)	-	用户 IP
user_agent	VARCHAR(512)	-	浏览器 UA
exception_time	DATETIME	-	异常发生时间
exception_name	VARCHAR(128)	-	异常类全名
exception_message	TEXT	-	异常消息
exception_root_cause_message	TEXT	-	根异常消息
exception_stack_trace	TEXT	-	异常堆栈轨迹
exception_class_name	VARCHAR(256)	-	异常发生的类全名
exception_file_name	VARCHAR(256)	-	异常发生的类文件名
exception_method_name	VARCHAR(256)	-	异常发生的方法名
exception_line_number	INT	-	异常发生的方法行号
process_status	TINYINT	NOT NULL, DEFAULT 0	处理状态（0-未处理、1-已处理、2-已忽略）
process_time	DATETIME	-	处理时间
process_user_id	BIGINT	-	处理用户编号
tenant_id	BIGINT	NOT NULL	租户编号
creator	VARCHAR(64)	-	创建者
create_time	DATETIME	NOT NULL	创建时间
updater	VARCHAR(64)	-	更新者
update_time	DATETIME	NOT NULL	更新时间
deleted	BIT(1)	NOT NULL, DEFAULT 0	删除标记

索引设计：

索引名	字段	类型	说明
idx_user_id	user_id	普通索引	按用户查询
idx_request_url	request_url(191)	普通索引	按请求地址查询
idx_exception_time	exception_time	普通索引	按异常时间查询
idx_process_status	process_status	普通索引	按处理状态筛选未处理记录
idx_tenant_process	tenant_id, process_status	联合索引	租户 + 处理状态查询

5.2 数据字典

字典类型	字典标识	字典值	说明
登录日志类型	system_login_log_type	100-登录、101-登出、200-注册	登录日志的事件类型
登录结果	system_login_result	0-成功、10-账号密码错误、11-手机验证码错误、12-邮箱验证码错误、20-用户被禁用、30-IP 黑名单	登录/登出的结果
用户类型	system_user_type	1-会员、2-管理员	用户类型
操作分类	infra_operate_type	1-查询、2-新增、3-修改、4-删除、5-导出、6-导入	API 操作分类
API 错误处理状态	infra_api_error_process_status	0-未处理、1-已处理、2-已忽略	API 错误日志的处理状态

5.3 处理状态流转

API 错误日志的处理状态遵循以下流转规则：

• 未处理 → 已处理：运维/开发人员确认问题已修复
• 未处理 → 已忽略：确认为已知问题或误报，暂不处理
• 处理时自动记录：处理人（当前登录用户）+ 处理时间

---

六、跨模块联动

6.1 联动关系总览

日志审计作为基础模块，与多个模块存在数据交互或功能依赖：

关联模块	联动方式	联动内容	优先级
认证授权	数据写入	登录/登出/注册事件触发登录日志写入；IP 黑名单拦截时记录日志	P0
用户管理	数据读取	操作日志通过 userId 读取用户昵称展示；登录日志通过 userId 关联用户信息	P0
租户管理	数据隔离	所有日志按 tenant_id 隔离，查询时自动过滤当前租户	P0
角色权限	权限控制	日志查看和导出操作受 RBAC 权限控制	P0
消息通知	告警推送	P2 安全审计检测到异常后，通过消息通知模块发送站内信/邮件告警	P2
工作流	操作记录	工作流审批操作通过 @OperateLog 注解记录到操作日志	P0
支付模块	操作记录	支付相关操作（退款、调账等）通过 @OperateLog 记录到操作日志	P0
监控运维	数据共享	API 访问日志的性能数据可被监控运维模块引用，生成性能报表	P1

6.2 关键联动流程

6.2.1 登录日志自动采集流程

6.2.2 操作日志自动采集流程

6.2.3 traceId 串联查询流程

6.3 数据一致性要求

场景	一致性要求	实现方式
登录日志写入	最终一致	异步写入，允许极小延迟，但必须保证写入成功（失败重试）
操作日志写入	最终一致	异步写入，业务操作成功但日志写入失败时，通过补偿机制重试
错误日志处理状态	强一致	同步更新，处理状态变更立即生效
日志不可篡改	强一致	数据库层面限制，不提供物理删除接口

---

七、附录

7.1 名词解释

术语	通俗解释	在系统中的角色
日志审计	就像飞机的"黑匣子"，记录系统中发生的一切关键事件	本模块的名称，涵盖日志的记录、查询、导出、分析
TraceId（链路追踪编号）	就像快递单号，一次请求不管经过多少个环节，凭这个单号都能查到	串联同一次请求产生的所有日志（登录日志、操作日志、访问日志、错误日志）
登录日志	就像小区门禁的刷卡记录	记录谁在什么时间、从哪里登录了系统
操作日志	就像办公室的监控录像	记录用户在系统里做了什么操作（新建、修改、删除等）
API 访问日志	就像高速公路收费站的过车记录	记录每一次接口调用的详细信息（请求参数、响应结果、执行时长）
API 错误日志	就像设备的故障报警单	记录接口出错时的完整信息（异常类型、堆栈、出错位置）
UserAgent（浏览器标识）	就像身份证上的"民族"字段，标识你用什么设备访问系统	用于识别用户的浏览器类型和操作系统
@OperateLog 注解	就像给摄像头贴标签——告诉系统"这个操作需要被记录"	开发者在代码中标注此注解，系统就会自动记录操作日志
处理状态	就像工单的"待处理/已处理/已关闭"状态	错误日志的生命周期管理，确保每个错误都有人跟进
异步写入	就像你把信投进邮筒就可以走了，不用等邮递员上门	日志写入在后台进行，不阻塞用户的操作
日志归档	就像把旧文件从办公桌搬到档案室	将过期日志从主库转移到冷存储，释放空间但保留数据
暴力破解	就像小偷一把一把地试钥匙	攻击者通过大量尝试密码来破解账号
IP 归属地	就像电话区号能告诉你对方是哪个城市的	通过 IP 地址解析出地理位置（省/市），用于安全分析
敏感信息脱敏	就像在快递单上隐藏手机号中间四位	将密码、Token 等敏感数据替换为 ***，防止泄露
数据字典	就像代码本——把数字翻译成人类能懂的文字	把登录结果"10"翻译成"账号密码错误"，方便理解

7.2 权限配置

权限标识	权限名称	说明	建议分配角色
system:login-log:query	查看登录日志	查看登录日志列表和详情	系统管理员、安全审计员
system:login-log:export	导出登录日志	导出登录日志 Excel	系统管理员、安全审计员
system:operate-log:query	查看操作日志	查看操作日志列表和详情	系统管理员
system:operate-log:export	导出操作日志	导出操作日志 Excel	系统管理员、安全审计员
infra:api-access-log:query	查看 API 访问日志	查看 API 访问日志列表和详情	运维工程师、开发人员
infra:api-access-log:export	导出 API 访问日志	导出 API 访问日志 Excel	运维工程师
infra:api-error-log:query	查看 API 错误日志	查看 API 错误日志列表和详情	运维工程师、开发人员
infra:api-error-log:update-status	处理 API 错误日志	更新 API 错误日志的处理状态	运维工程师、开发人员
infra:api-error-log:export	导出 API 错误日志	导出 API 错误日志 Excel	运维工程师

7.3 接口汇总

接口组	接口数量	接口路径前缀	说明
登录日志	3	/admin-api/system/login-log	详情、分页、导出
操作日志	3	/admin-api/system/operate-log	详情、分页、导出
API 访问日志	3	/admin-api/infra/api-access-log	详情、分页、导出
API 错误日志	4	/admin-api/infra/api-error-log	详情、分页、更新状态、导出
合计	13

7.4 变更记录

版本	日期	修改内容	修改人
v1.0	2026-09-16	初始版本，包含登录日志、操作日志、API 访问日志、API 错误日志、安全审计规划	PM Team
v2.0	2026-09-19	全面增强：① 增加 6 个详细用户场景（含命名角色和异常处理）② 用户故事增加可量化验收标准 ③ 新增 ASCII 页面原型 ④ 业务规则增加设计理由 ⑤ 新增跨模块联动章节（含 3 个关键流程图）⑥ 新增名词解释（15 个术语+通俗类比）⑦ 新增处理状态流转图 ⑧ 接口汇总和权限配置优化	PM Team

---

本文档为日志审计模块 PRD v2.0，如有问题请联系产品负责人。