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

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

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

项目名称	升鲜宝供应链管理系统
文档类型	模块设计说明 / 研发交付版
版本	V1.0
日期	2026-04-21

 

文档定位

本说明文档用于指导升鲜宝日志功能模块的产品设计、数据库设计、Java 后端实现、页面建设与分期落地。文档强调可上线、可审计、可追踪、可归档，重点覆盖单据审核/反审核、库存/成本过账、接口调用、异常排查与任务执行等核心链路。

 

 

1. 文档概述

 

1.1 建设背景

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

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

1.2 建设目标

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

1.3 适用范围

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

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

维度	说明
面向角色	产品经理、架构师、后端开发、前端开发、测试、运维
建设目标	审计追责、问题排查、业务回放、系统监控、归档分析
设计原则	分类型、可串联、可检索、可扩展、可归档

 

2. 设计原则与总体架构

 

2.1 设计原则

原则	说明
业务优先	日志建设必须围绕升鲜宝的核心链路展开，重点保障单据审核、库存过账、成本过账、反审核回滚等场景。
统一上下文	所有日志统一挂载 tenantId、companyId、shopId、userId、traceId、requestUri 等上下文信息。
采集与落库解耦	采集层负责拦截与组装，处理层负责脱敏、分类、补充上下文，存储层负责可靠写入和归档。
生产可用	优先采用异步写库、按月分表、冷热分离、失败重试和日志采样等机制控制容量与性能。
最小暴露	对手机号、密码、token、身份证、银行卡等敏感信息默认脱敏，日志查询界面遵循权限隔离。

 

2.2 总体架构

 

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

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

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

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

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

3. 日志分类与功能模块设计

 

3.1 分类清单

类型	定位	典型场景
操作日志	后台/移动端操作行为留痕	新增、修改、删除、审核、反审核、导入、导出、打印
单据业务日志	记录业务对象状态变化与轨迹	订单、入库、出库、盘点、报损、报溢、调拨、付款
字段变更日志	记录关键主数据字段变化	商品价格、客户授信、仓库启停、角色权限、系统参数
接口调用日志	记录内部与外部 API 调用	前端接口、开放 API、第三方同步、支付短信地图打印
异常日志	记录程序异常与业务错误	全局异常、集成异常、反审核回滚失败、重试失败
任务日志	记录定时任务与批处理执行过程	自动关单、自动完成、库存重算、同步任务、日报
登录与安全日志	记录身份认证与安全审计	登录成功/失败、密码修改、越权访问、账号锁定
消息推送日志	记录通知投递行为与结果	短信、邮件、站内信、企业微信、推送消息

 

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. 核心业务链路设计

 

4.1 审核 / 反审核链路

 

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

步骤	业务动作	日志要求
1	提交审核	记录操作日志 + 业务日志，写入 billId / billCode / beforeStatus
2	审核服务执行	记录执行开始、操作者、审核参数、幂等键
3	库存过账	写入库存流水、过账结果、数量变化、库位/批次信息
4	成本过账	写入成本方法、成本金额、成本流水号、是否成功
5	事件发布	发布业务事件，驱动业务轨迹、消息通知、告警等后续动作
6	结果返回	记录最终状态 afterStatus、耗时、异常原因或成功说明

 

4.2 traceId 串联策略

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

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

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

4.3 导入导出与消息推送

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

5. 数据库设计与核心表说明

 

5.1 核心表清单

表名	定位	说明
sys_operate_log	操作日志主表	记录页面/服务入口的通用操作留痕
biz_bill_log	单据业务日志表	记录单据状态变化、业务轨迹与关联单据
biz_field_change_log	字段变更日志表	记录关键主数据字段变更明细
sys_api_log	接口调用日志表	记录 API 请求、响应、耗时、来源系统
sys_exception_log	异常日志表	记录异常摘要、堆栈、请求参数与 traceId
sys_job_log	任务执行日志表	记录定时任务或批处理作业执行情况
sys_login_log	登录安全日志表	记录登录行为、失败原因、设备与 IP
sys_message_log	消息推送日志表	记录消息发送、重试、第三方返回结果

 

5.2 关键字段设计

字段设计说明

日志表中建议统一保留 tenant_id、company_id、shop_id、trace_id、create_time 等公共字段；业务型日志额外保留 bill_type、bill_id、bill_code、before_status、after_status、operator_id；安全型日志额外保留 ip、user_agent、device_info。

 

5.2.1 sys_operate_log

字段	类型建议	说明
id	bigint	主键
module_name	varchar(64)	模块名称，如 OMS订单、仓储入库
business_type	varchar(32)	新增/修改/删除/审核/反审核/导入/导出/打印
request_uri	varchar(255)	请求路径
operator_id	bigint	操作人ID
request_param	text	请求参数（脱敏后）
response_result	text	响应摘要
operate_result	tinyint	0失败 1成功
cost_ms	int	耗时毫秒
trace_id	varchar(64)	链路跟踪号

 

5.2.2 biz_bill_log

字段	类型建议	说明
bill_type	varchar(32)	单据类型，如 STOCKIN、STOCKOUT、STOCKTAKE
bill_id	bigint	单据ID
bill_code	varchar(64)	单据编号
action_type	varchar(32)	创建、提交、审核、反审核、作废、完成
before_status	varchar(32)	动作前状态
after_status	varchar(32)	动作后状态
related_bill_code	varchar(64)	关联单号，如由盘点生成报损单
remark	varchar(500)	动作说明或系统说明
operator_name	varchar(64)	操作者名称
trace_id	varchar(64)	链路跟踪号

 

5.2.3 sys_api_log / sys_exception_log

字段	类型建议	说明
system_name	varchar(64)	调用方或目标系统名称
request_method	varchar(16)	GET/POST/PUT/DELETE
response_code	varchar(32)	响应码或第三方返回码
success_flag	tinyint	接口是否成功
exception_name	varchar(128)	异常类名
exception_msg	varchar(1000)	异常信息摘要
stack_trace	longtext	异常堆栈（建议失败时才保留完整内容）
create_time	datetime	创建时间

 

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. 技术实现方案

 

6.1 代码分层建议

层次	建议组件	职责
采集层	Filter / Interceptor / AOP / 领域事件	统一采集请求、操作、异常与上下文
服务层	LogFacade / LogContext / LogDispatcher	统一封装日志入站与路由
持久层	MyBatis-Plus Mapper + Async Executor	异步落库与批量写入
扩展层	DesensitizeService / ArchiveJob / AlertService	脱敏、归档、告警与分析扩展

 

6.2 推荐实现模式

模式	适用说明
注解 + AOP	适用于通用操作日志，如新增、修改、删除、审核、导入、导出。
领域事件	适用于业务日志和审核链后置动作，如发布 BillAuditSuccessEvent、StockoutRollbackEvent。
全局异常处理	适用于统一落异常日志，并关联请求参数与 traceId。
异步落库	适用于降低主交易链路耗时，避免同步写日志影响接口响应。
脱敏处理	适用于保存请求参数与响应结果之前，对密码、token、手机号等字段自动脱敏。

 

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. 页面功能与查询能力设计

 

7.1 后台页面建议

页面	主要字段	补充要求
操作日志查询	时间、操作人、模块、业务类型、结果、IP、traceId	支持查看请求参数与响应摘要
单据轨迹页	单据类型、单号、状态、动作、操作者、时间	可直接嵌入单据详情页
接口日志页	URL、来源系统、响应码、耗时、成功标识、traceId	支持按耗时排序
异常日志页	模块、异常类、异常摘要、请求路径、traceId	支持快速跳转到业务链路
任务日志页	任务编码、执行机器、开始时间、结束时间、状态	显示重试次数与结果摘要
登录安全日志页	账号、登录结果、失败原因、设备、IP、时间	支持安全审计导出

 

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

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

8. 非功能要求与实施计划

 

8.1 非功能要求

维度	要求
性能	普通日志写入异步化；接口主链路不得因日志写库明显变慢
可靠性	日志写入失败可重试，并支持失败补偿队列
安全性	参数脱敏、权限隔离、导出控制、敏感日志访问审计
可维护性	统一字段、统一上下文、统一派发入口、统一枚举
可扩展性	预留 ES、告警、聚合分析、报表统计能力

 

8.2 分期实施建议

阶段	建设内容	阶段目标
一期	操作日志、单据业务日志、异常日志、接口日志、单据轨迹页	先解决留痕与排错问题
二期	字段变更日志、任务日志、登录安全日志、导入导出日志、消息日志	强化审计与运维能力
三期	日志归档中心、聚合统计、异常告警、ES 检索、慢接口分析	形成统一日志中心与分析能力

 

8.3 研发落地顺序

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

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

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

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

9. 结论

 

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

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

建议下一步配套交付物：

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