# 项目概述

<cite>
**本文引用的文件**   
- [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)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

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

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

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

```mermaid
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
```

图表来源
- [pom.xml:17-27](file://pom.xml#L17-L27)
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
- [nflg-wms-auth/pom.xml:15-61](file://nflg-wms-auth/pom.xml#L15-L61)
- [nflg-wms-gateway/pom.xml:15-94](file://nflg-wms-gateway/pom.xml#L15-L94)

章节来源
- [pom.xml:17-27](file://pom.xml#L17-L27)
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
- [nflg-wms-auth/pom.xml:15-61](file://nflg-wms-auth/pom.xml#L15-L61)
- [nflg-wms-gateway/pom.xml:15-94](file://nflg-wms-gateway/pom.xml#L15-L94)

## 核心组件
- 通用层（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 收货、发运、质量模块作为独立服务，按需扩展。

章节来源
- [Constant.java:5-42](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L5-L42)
- [OrderState.java:10-28](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/OrderState.java#L10-L28)
- [OperationType.java:10-26](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/OperationType.java#L10-L26)
- [NflgException.java:6-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L6-L17)
- [BaseController.java:30-37](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L30-L37)
- [WmsOutPurchase.java:26-68](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/entity/WmsOutPurchase.java#L26-L68)
- [WmsOutPurchaseMapper.xml:5-26](file://nflg-wms-repository/src/main/resources/mapper/WmsOutPurchaseMapper.xml#L5-L26)

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

```mermaid
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
```

图表来源
- [GateWayApplication.java:10-12](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L10-L12)
- [AuthApplication.java:11-13](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L11-L13)
- [AdminApplication.java:13-17](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L13-L17)
- [application.yml（gateway）:10-19](file://nflg-wms-gateway/src/main/resources/application.yml#L10-L19)
- [application.yml（admin）:12-23](file://nflg-wms-admin/src/main/resources/application.yml#L12-L23)

## 详细组件分析

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

```mermaid
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 : 统一响应
```

图表来源
- [GateWayApplication.java:10-12](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L10-L12)
- [application.yml（gateway）:20-26](file://nflg-wms-gateway/src/main/resources/application.yml#L20-L26)

章节来源
- [GateWayApplication.java:10-12](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L10-L12)
- [application.yml（gateway）:20-26](file://nflg-wms-gateway/src/main/resources/application.yml#L20-L26)

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

```mermaid
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 : 返回业务结果
```

图表来源
- [AuthApplication.java:11-20](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L11-L20)
- [AdminApplication.java:12-25](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L25)
- [Constant.java:11-21](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L11-L21)

章节来源
- [AuthApplication.java:11-20](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L11-L20)
- [AdminApplication.java:12-25](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L25)
- [Constant.java:11-21](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L11-L21)

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

```mermaid
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 : "映射"
```

图表来源
- [WmsOutPurchase.java:26-68](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/entity/WmsOutPurchase.java#L26-L68)
- [WmsOutPurchaseMapper.xml:5-26](file://nflg-wms-repository/src/main/resources/mapper/WmsOutPurchaseMapper.xml#L5-L26)

章节来源
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
- [WmsOutPurchase.java:26-68](file://nflg-wms-repository/src/main/java/com/nflg/wms/repository/entity/WmsOutPurchase.java#L26-L68)
- [WmsOutPurchaseMapper.xml:5-26](file://nflg-wms-repository/src/main/resources/mapper/WmsOutPurchaseMapper.xml#L5-L26)

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

```mermaid
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 : 写入/更新仓储数据
```

图表来源
- [SapService.java:67-99](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/SapService.java#L67-L99)
- [SyncStorageFromSAPProcessor.java:55-69](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/SyncStorageFromSAPProcessor.java#L55-L69)

章节来源
- [SapService.java:67-99](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/SapService.java#L67-L99)
- [SyncStorageFromSAPProcessor.java:55-69](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/SyncStorageFromSAPProcessor.java#L55-L69)

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

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

图表来源
- [OrderState.java:10-28](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/OrderState.java#L10-L28)
- [InCostCenterBackController.java:167-170](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/InCostCenterBackController.java#L167-L170)

章节来源
- [OrderState.java:10-28](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/OrderState.java#L10-L28)
- [InCostCenterBackController.java:167-170](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/InCostCenterBackController.java#L167-L170)

## 依赖分析
- 技术栈与版本
  - 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 解耦，便于横向扩展。
  - 定时任务与仓储模块通过数据库交互，避免直接耦合业务服务。

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

图表来源
- [pom.xml:54-192](file://pom.xml#L54-L192)
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
- [nflg-wms-gateway/pom.xml:15-94](file://nflg-wms-gateway/pom.xml#L15-L94)
- [nflg-wms-auth/pom.xml:15-61](file://nflg-wms-auth/pom.xml#L15-L61)

章节来源
- [pom.xml:54-192](file://pom.xml#L54-L192)
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
- [nflg-wms-gateway/pom.xml:15-94](file://nflg-wms-gateway/pom.xml#L15-L94)
- [nflg-wms-auth/pom.xml:15-61](file://nflg-wms-auth/pom.xml#L15-L61)

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

## 故障排查指南
- 认证与会话
  - 若出现登录后无用户上下文，检查认证中心日志与 Sa-Token 配置，确认票据有效与扩展字段注入。
  - 参考：[AuthApplication.java:18-20](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L18-L20)、[AdminApplication.java:23-24](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L23-L24)

- 网关与服务发现
  - 网关无法路由到服务，检查 Nacos 地址、命名空间与组配置，确认服务已注册且健康。
  - 参考：[application.yml（gateway）:10-19](file://nflg-wms-gateway/src/main/resources/application.yml#L10-L19)

- 数据访问与异常
  - 使用通用异常类与状态码统一错误输出，便于前端与监控系统识别。
  - 参考：[NflgException.java:6-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L6-L17)

- 外部系统集成
  - SAP 调用失败时，检查参数组装与表参构造，关注日志中的 RFC 返回结构。
  - 参考：[SapService.java:67-99](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/SapService.java#L67-L99)

章节来源
- [AuthApplication.java:18-20](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L18-L20)
- [AdminApplication.java:23-24](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L23-L24)
- [application.yml（gateway）:10-19](file://nflg-wms-gateway/src/main/resources/application.yml#L10-L19)
- [NflgException.java:6-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L6-L17)
- [SapService.java:67-99](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/SapService.java#L67-L99)

## 结论
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](file://readme.md#L1-L10)