19 KiB

Raw Blame History

项目概述

**本文引用的文件** - [pom.xml](file://pom.xml) - [readme.md](file://readme.md) - [AdminApplication.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java) - [AuthApplication.java](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java) - [GateWayApplication.java](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java) - [application.yml（admin）](file://nflg-wms-admin/src/main/resources/application.yml) - [application.yml（gateway）](file://nflg-wms-gateway/src/main/resources/application.yml) - [Constant.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java) - [OrderState.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/OrderState.java) - [OperationType.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/OperationType.java) - [NflgException.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java) - [BaseController.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java) - [WmsOutPurchase.java](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/entity/WmsOutPurchase.java) - [WmsOutPurchaseMapper.xml](file://nflg-wms-repository/src/main/resources/mapper/WmsOutPurchaseMapper.xml) - [SyncStorageFromSAPProcessor.java](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/SyncStorageFromSAPProcessor.java) - [SapService.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/SapService.java) - [InCostCenterBackController.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/InCostCenterBackController.java) - [nflg-wms-admin/pom.xml](file://nflg-wms-admin/pom.xml) - [nflg-wms-auth/pom.xml](file://nflg-wms-auth/pom.xml) - [nflg-wms-gateway/pom.xml](file://nflg-wms-gateway/pom.xml)

引言

本项目是 NFLG WMS 仓储管理系统，旨在通过微服务架构实现对仓库、物料、订单等核心业务的数字化管理。系统围绕“统一认证、网关路由、业务服务、数据持久化、定时任务、外部集成”构建，覆盖入库、出库、移库、盘点、退库、订单执行、打印与报表等典型场景，并通过 Nacos 进行服务注册与配置管理，结合 Sa-Token 实现单点登录与会话管理，借助 MyBatis-Plus 提升数据访问效率。

本项目适合初学者理解 WMS 基本概念与系统边界，也面向有经验的开发者提供技术选型、模块职责、数据模型与流程细节，帮助快速落地与扩展。

项目结构

项目采用多模块聚合工程组织，父 POM 定义版本与依赖管理，子模块按职责划分：通用层、启动器、仓储实体与映射、网关、认证、管理后台、定时任务、SRM 收货、发运、质量模块等。

graph TB
subgraph "聚合工程"
ROOT["父POM<br/>版本与依赖管理"]
end
subgraph "通用与基础设施"
COMMON["nflg-wms-common<br/>常量/异常/工具"]
STARTER["nflg-wms-starter<br/>基础控制器/拦截器/注解"]
REPO["nflg-wms-repository<br/>实体/映射/DAO"]
end
subgraph "服务网关与认证"
GATEWAY["nflg-wms-gateway<br/>Spring Cloud Gateway"]
AUTH["nflg-wms-auth<br/>统一认证中心"]
end
subgraph "业务服务"
ADMIN["nflg-wms-admin<br/>管理后台/业务接口"]
SRM["nflg-wms-srm-receive<br/>SRM收货"]
SHIPMENT["nflg-wms-shipment<br/>发运"]
SCHEDULED["nflg-wms-scheduled<br/>定时任务"]
QMS["nflg-qms-admin<br/>质量模块"]
end
ROOT --> COMMON
ROOT --> STARTER
ROOT --> REPO
ROOT --> GATEWAY
ROOT --> AUTH
ROOT --> ADMIN
ROOT --> SRM
ROOT --> SHIPMENT
ROOT --> SCHEDULED
ROOT --> QMS

图表来源

章节来源

核心组件

通用层（nflg-wms-common）
- 提供系统级常量、状态枚举、异常定义与通用工具，确保各模块一致性与可复用性。
- 关键点：统一的跟踪 ID 头部、登录扩展字段、字典服务标识、超级管理员角色等。
启动器（nflg-wms-starter）
- 封装基础控制器、全局校验、常用工具方法，降低业务重复代码。
- 示例：二维码内容生成、参数校验等。
仓储与映射（nflg-wms-repository）
- MyBatis-Plus 实体与 Mapper XML，承载仓储业务数据模型与查询能力。
- 示例：退库-采购中心退库实体与查询映射。
网关（nflg-wms-gateway）
- Spring Cloud Gateway + Nacos 发现，负责请求路由、负载均衡与安全策略入口。
认证（nflg-wms-auth）
- 统一认证中心，结合 Sa-Token 实现 SSO 与会话管理。
管理后台（nflg-wms-admin）
- 业务主服务，提供仓储、物料、订单、打印、报表等接口；集成 LDAP、邮件、PDF、二维码、MongoDB、PowerJob 等能力。
定时任务（nflg-wms-scheduled）
- 基于 PowerJob 的分布式调度，支撑 SAP 数据同步等周期性任务。
其他模块
- SRM 收货、发运、质量模块作为独立服务，按需扩展。

章节来源

架构总览

系统采用“网关 + 微服务 + 配置中心 + 认证中心”的云原生架构。客户端请求经网关进入，由服务发现与负载均衡分发到具体业务服务；认证中心统一鉴权；配置中心集中管理环境配置；定时任务与外部系统（如 SAP）通过适配器对接。

graph TB
CLIENT["客户端/前端/第三方系统"]
subgraph "边缘与治理"
GW["Spring Cloud Gateway<br/>路由/限流/鉴权"]
NACOS["Nacos<br/>注册与配置"]
AUTH["统一认证中心(Sa-Token)<br/>SSO/会话"]
end
subgraph "业务服务"
ADMIN["管理后台服务"]
SRM["SRM收货服务"]
SHIP["发运服务"]
SCHED["定时任务服务"]
QMS["质量服务"]
end
DB["数据库(PostgreSQL)"]
REDIS["Redis(缓存/会话/分布式锁)"]
SAP["SAP系统(外部)"]
CLIENT --> GW
GW --> ADMIN
GW --> SRM
GW --> SHIP
GW --> SCHED
GW --> QMS
ADMIN --- NACOS
SRM --- NACOS
SHIP --- NACOS
SCHED --- NACOS
QMS --- NACOS
ADMIN --- AUTH
SRM --- AUTH
SHIP --- AUTH
SCHED --- AUTH
QMS --- AUTH
ADMIN --- DB
ADMIN --- REDIS
SRM --- DB
SRM --- REDIS
SHIP --- DB
SHIP --- REDIS
SCHED --- DB
SCHED --- REDIS
ADMIN -. SAP同步 .-> SAP

图表来源

详细组件分析

网关与服务发现

网关应用启用服务发现与负载均衡，基于 Nacos 注册中心自动感知服务实例，实现动态路由与健康检查。
管理后台与认证服务均通过 Nacos 注册，网关统一对外暴露。

sequenceDiagram
participant C as "客户端"
participant GW as "Gateway"
participant N as "Nacos"
participant A as "Admin服务"
C->>GW : 请求 /admin/...
GW->>N : 查询服务实例
N-->>GW : 返回可用实例列表
GW->>A : 转发请求(带负载均衡)
A-->>GW : 返回响应
GW-->>C : 统一响应

图表来源

章节来源

统一认证与会话

认证中心提供 SSO 与会话管理，管理后台在启动时初始化 Sa-Token SSO 客户端配置，实现跨系统单点登录。
登录扩展字段（姓名、工号、邮箱、部门、角色、类型等）贯穿系统，便于权限与审计。

sequenceDiagram
participant U as "用户"
participant A as "Admin服务"
participant AS as "认证中心"
participant GW as "Gateway"
U->>GW : 访问受控资源
GW->>AS : 校验票据/会话
AS-->>GW : 校验通过(附带扩展信息)
GW->>A : 转发并注入用户上下文
A-->>U : 返回业务结果

图表来源

章节来源

业务服务与数据模型

管理后台服务提供仓储、物料、订单、打印、报表等能力，集成 LDAP、邮件、PDF、二维码、MongoDB、PowerJob 等。
仓储实体与 Mapper 映射支撑退库、库存、移库等核心业务。

classDiagram
class WmsOutPurchase {
+id : Long
+no : String
+ebeln : String
+lifnr : String
+matDoc : String
+docYear : String
+createBy : String
+createTime : LocalDateTime
}
class WmsOutPurchaseMapper {
+search(request) : OutPurchaseVO[]
}
WmsOutPurchaseMapper --> WmsOutPurchase : "映射"

图表来源

章节来源

外部系统集成（SAP）

管理后台通过服务封装调用 SAP RFC 接口，支持生产订单副产品入库查询等场景。
定时任务处理器可按工厂、仓库、日期范围同步仓储数据，保障数据一致性。

sequenceDiagram
participant S as "SAP系统"
participant SVC as "SapService"
participant PROC as "SyncStorageFromSAPProcessor"
participant DB as "数据库"
PROC->>SVC : 组装参数/表参
SVC->>S : 调用RFC函数模块
S-->>SVC : 返回结构化数据
SVC-->>PROC : 转换为领域对象
PROC->>DB : 写入/更新仓储数据

图表来源

章节来源

订单与状态机

订单状态与操作类型通过枚举定义，保证状态流转与操作语义的一致性。
控制器示例展示如何根据订单状态进行业务校验与返回。

flowchart TD
Start(["开始"]) --> LoadOrder["加载订单"]
LoadOrder --> CheckState{"状态校验"}
CheckState --> |未完成| Proceed["继续处理"]
CheckState --> |已完成| Stop["终止并提示"]
Proceed --> End(["结束"])
Stop --> End

图表来源

章节来源

依赖分析

技术栈与版本
- Spring Boot 3.2.4、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.0
- Sa-Token 1.42.0（含 SSO、Reactor、JWT、Redis Jackson）
- MyBatis-Plus 3.5.12
- PostgreSQL 42.7.7
- Loki 日志采集、Redisson 分布式能力、PowerJob 调度
- ZXing 二维码、iText7 PDF、Apache Commons、Hutool 工具集
模块间耦合
- 管理后台依赖通用层与启动器，复用常量、异常与基础能力。
- 网关与认证中心通过 Nacos 与 Sa-Token 解耦，便于横向扩展。
- 定时任务与仓储模块通过数据库交互，避免直接耦合业务服务。

graph LR
ADMIN["管理后台"] --> COMMON["通用层"]
ADMIN --> STARTER["启动器"]
GATEWAY["网关"] --> NACOS["Nacos"]
AUTH["认证中心"] --> NACOS
ADMIN --> DB["PostgreSQL"]
ADMIN --> REDIS["Redis"]
SCHED["定时任务"] --> DB
SCHED --> REDIS

图表来源

章节来源

性能考虑

服务发现与负载均衡：网关启用负载均衡，结合 Nacos 实现实例弹性伸缩与故障隔离。
缓存与会话：Redisson 提供分布式锁与缓存能力，Sa-Token 结合 Redis 存储会话，降低数据库压力。
数据访问：MyBatis-Plus 减少 SQL 开销，合理使用分页与索引提升查询性能。
日志与可观测：Loki 日志采集、Actuator 指标暴露、OpenTelemetry 链路追踪，便于问题定位与容量规划。
文件与大对象：上传与导出限制在配置中设置，避免内存溢出；PDF 与二维码生成建议异步化。

故障排查指南

认证与会话
- 若出现登录后无用户上下文，检查认证中心日志与 Sa-Token 配置，确认票据有效与扩展字段注入。
- 参考：AuthApplication.java:18-20、AdminApplication.java:23-24
网关与服务发现
- 网关无法路由到服务，检查 Nacos 地址、命名空间与组配置，确认服务已注册且健康。
- 参考：application.yml（gateway）:10-19
数据访问与异常
- 使用通用异常类与状态码统一错误输出，便于前端与监控系统识别。
- 参考：NflgException.java:6-17
外部系统集成
- SAP 调用失败时，检查参数组装与表参构造，关注日志中的 RFC 返回结构。
- 参考：SapService.java:67-99

章节来源

结论

NFLG WMS 以微服务为核心，结合 Nacos、Gateway、Sa-Token、MyBatis-Plus 等技术栈，构建了高内聚、低耦合、可扩展的仓储管理体系。通过统一认证、集中配置与外部系统集成，系统能够稳定支撑入库、出库、移库、盘点、退库、订单执行等核心业务，并为后续扩展与优化奠定坚实基础。

附录

部署拓扑建议
- 基础设施：Nacos、Redis、PostgreSQL、SAP
- 服务编排：Gateway、Auth、Admin、SRM、Shipment、Scheduled、QMS
- 监控与日志：Prometheus/Grafana、Loki、OpenTelemetry
应用场景与收益
- 场景：多工厂、多仓库、多订单类型的协同作业；跨系统数据同步与一致性保障。
- 收益：提升出入库效率、降低人工差错、增强可视化与审计能力、加速报表与打印流程。
实施建议
- 分环境管理：dev/sit/prod，配置按环境隔离。
- 安全加固：启用 HTTPS、最小权限、敏感配置加密。
- 性能优化：热点数据缓存、慢查询分析、连接池与线程池调优。
- 可观测性：完善链路追踪、指标与告警，建立故障演练机制。

章节来源

readme.md:1-10

19 KiB Raw Blame History Unescape Escape

项目概述

目录

引言

项目结构

核心组件

架构总览

详细组件分析

网关与服务发现

统一认证与会话

业务服务与数据模型

外部系统集成（SAP）

订单与状态机

依赖分析

性能考虑

故障排查指南

结论

附录

19 KiB

Raw Blame History