升鲜宝日志功能模块设计说明(一）---生鲜配送供应链管理系统源代码

面向 OMS / WMS / HWMS /CWMS/PUR/CUS/ 财务 / 基础资料的统一日志中心设计

1.1 建设背景

升鲜宝属于多域协同型业务系统，日常运行涉及商品、客户、订单、库存、成本、财务、消息、权限等多个模块。随着业务单据、自动任务与第三方接口逐步增加，系统对“操作留痕、轨迹追踪、异常排错、审计归档”的要求持续提升。

传统仅记录按钮点击的简单操作日志已经无法满足库存不一致排查、审核/反审核回滚确认、接口链路追踪、越权访问审计与导入导出追责等场景，因此需要建设统一日志中心。

1.2 建设目标

• 形成统一日志分类体系，覆盖操作、业务、字段变更、接口、异常、任务、安全与消息推送。
• 围绕单据审核链设计业务轨迹，确保任意一张单据都能回放“谁在何时做了什么”。
• 通过 traceId 串联 API、业务日志、库存流水、成本过账与异常日志，提升问题定位效率。
• 支持日志异步化、脱敏、冷热分离、归档与权限控制，满足生产环境性能与安全要求。

1.3 适用范围

本设计适用于升鲜宝后台管理端、门店协同端、接口开放端及定时任务执行体系。

重点关注的业务域包括：OMS 订单域、WMS 仓储域、HWMS 门店仓储域、财务域、主数据域、权限与安全域。

2.1 设计原则

2.2 总体架构

图 2-1  升鲜宝日志中心总体架构（图中使用英文标注以确保跨环境渲染稳定）

业务入口层包括后台页面请求、小程序/API 请求、定时任务、消息消费与第三方回调。

采集层由 Filter、AOP、Interceptor 与领域事件组成，负责识别操作对象、业务动作、请求参数与执行耗时。

处理层对日志进行异步化、脱敏、标准化转换与 trace 聚合；必要时补充业务上下文，如 billId、billCode、beforeStatus、afterStatus。

存储层以 MySQL 为主，结合 Redis 做短期聚合缓存，长周期归档可落对象存储，全文检索能力可预留 Elasticsearch。

3.1 分类清单

3.2 系统操作日志

系统操作日志用于记录“谁在什么时间，对哪个模块做了什么操作，结果如何”。该类日志以页面操作和服务入口为核心，主要通过注解 + AOP 采集。

• 建议采集字段：moduleName、businessType、requestUri、operatorId、operatorName、requestParam、responseResult、costMs、operateResult、ip、userAgent。
• 对导入、导出、打印、批量审核、批量反审核等高风险操作进行重点留痕。
• 成功日志可仅保存摘要；失败日志建议保存完整错误信息与 traceId。

3.3 单据业务日志

单据业务日志是升鲜宝最重要的日志类别，服务于业务回放、审核轨迹查看与库存/成本对账。任何一张单据都应具备完整业务轨迹。

• 建议记录 actionType、beforeStatus、afterStatus、billType、billId、billCode、relatedBillCode、remark、operator 与 traceId。
• 单据详情页应直接展示业务轨迹，而不是让用户到操作日志中反查。
• 审核与反审核必须成对记录，确保回滚链路可见。

3.4 字段变更日志

字段变更日志只建议覆盖关键主数据，而不是对所有字段做无差别记录，否则会带来无效数据和容量压力。

• 重点对象：商品、客户、供应商、仓库、库位、价格、系统参数、角色权限。
• 建议记录 oldValue、newValue、fieldName、fieldLabel、changeReason 与 operator。
• 对价格、授信额度、仓库启停状态等字段建议纳入重点审计列表。

3.5 接口/异常/任务/安全日志

接口、异常、任务与安全日志构成系统可观测能力，是排查生产问题和建立运维告警的基础。

• 接口日志强调 requestUrl、requestMethod、systemName、responseCode、successFlag、costMs。
• 异常日志强调 exceptionName、exceptionMsg、stackTrace、requestParam、traceId。
• 任务日志强调 jobCode、执行机器、开始结束时间、耗时、重试次数、结果摘要。

4.1 审核 / 反审核链路

图 4-1  审核 / 反审核链路中的日志落点示意（图中使用英文标注以确保跨环境渲染稳定）

4.2 traceId 串联策略

每个请求在进入系统时生成 traceId，并写入 MDC。日志中心所有表建议保留 traceId 字段，用于将操作日志、接口日志、异常日志、业务日志、库存流水和成本流水串联起来。

对于异步事件、MQ 消费与定时任务，应通过上下文透传方式延续 traceId 或生成 parentTraceId，保证链路完整。

在异常页面和单据页面中都应支持按 traceId 快速跳转。

4.3 导入导出与消息推送

• 导入日志应记录模板编码、导入文件名、总行数、成功条数、失败条数、失败文件地址、执行结果与操作者。
• 导出日志应记录筛选条件摘要、导出记录数、导出文件名、耗时与导出人。
• 消息日志应记录模板编码、接收对象、发送通道、内容摘要、第三方返回结果、重试次数与最终状态。

5.1 核心表清单

5.2 关键字段设计

5.2.1 sys_operate_log

5.2.2 biz_bill_log

5.2.3 sys_api_log / sys_exception_log

5.3 索引与分表建议

• 重点索引：trace_id、bill_type + bill_id、bill_code、operator_id、create_time、job_code、success_flag。
• 建议按月分表：如 sys_operate_log_202604、sys_api_log_202604，减少大表膨胀风险。
• 请求参数、响应结果、堆栈等大字段建议按“成功摘要、失败全量”原则保存。
• 近 3 个月日志保留在线库，3-12 个月迁移归档库，1 年以上压缩归档到对象存储。

6.1 代码分层建议

6.2 推荐实现模式

6.3 包结构建议

• com.sxb.log.annotation：日志注解定义，如 @SxbOperateLog、@SxbSensitiveLog。
• com.sxb.log.aspect：AOP 切面，实现操作日志采集。
• com.sxb.log.context：日志上下文对象 LogContext，统一承载 tenantId、userId、traceId 等信息。
• com.sxb.log.dispatch：日志派发层，负责异步分发、降级、失败重试。
• com.sxb.log.listener：领域事件监听器，负责将审核/反审核、消息推送等事件落为业务日志。
• com.sxb.log.mapper / entity / service：日志实体、DAO、服务实现。
• 敏感字段白名单与黑名单应同时支持，按字段名规则对 password、token、mobile、idCard、bankCard 等进行脱敏。
• 日志查询页面需要权限隔离：普通用户仅查看自己日志，管理员可查看所属组织日志，审计角色具备跨模块查看能力。
• 异常堆栈与完整请求体不建议向普通业务角色开放。

6.4 脱敏与权限控制

7.1 后台页面建议

7.2 单据详情页轨迹展示建议

• 在订单、入库、出库、盘点、报损报溢、调拨等单据详情页右侧或底部增加“操作轨迹”面板。
• 轨迹展示内容建议包括：时间、动作、状态变化、操作者、说明、关联单据、traceId。
• 系统动作与人工动作应区分展示，例如“系统生成库存流水”“系统回滚成本过账”。

8.1 非功能要求

8.2 分期实施建议

8.3 研发落地顺序

1. 先完成公共上下文、traceId、日志注解、AOP 与异步派发框架。

2. 再接入 OMS/WMS/HWMS 的审核、反审核、库存过账与成本过账日志。

3. 随后建设接口、异常、任务与安全日志页面，并加入查询权限控制。

4. 最后完善归档、采样、告警与分析能力。

升鲜宝日志系统不应只是“按钮点击记录器”，而应建设为面向审计追责、问题排查、业务回放、系统监控、长期归档的统一日志中心。

本设计建议以“分类型、可串联、可检索、可归档”为核心原则，优先围绕单据审核/反审核、库存/成本过账与关键主数据变更构建日志能力，逐步扩展为完整的可观测与审计体系。

建议下一步配套交付物：

1）MySQL 日志模块 DDL；2）Spring Boot + MyBatis-Plus 代码骨架；3）日志查询页面字段清单；4）审核/反审核日志链路实现说明；5）归档与清理作业设计。