wms/.qoder/repowiki/zh/content/系统架构/系统架构.md

# 系统架构

<cite>
**本文引用的文件**
- [pom.xml](file://pom.xml)
- [readme.md](file://readme.md)
- [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-repository/pom.xml](file://nflg-wms-repository/pom.xml)
- [nflg-wms-scheduled/pom.xml](file://nflg-wms-scheduled/pom.xml)
- [nflg-wms-srm-receive/pom.xml](file://nflg-wms-srm-receive/pom.xml)
- [nflg-wms-shipment/pom.xml](file://nflg-wms-shipment/pom.xml)
- [nflg-qms-admin/pom.xml](file://nflg-qms-admin/pom.xml)
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java)
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java)
- [nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java)
- [nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java)
</cite>

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

## 引言
本架构文档面向架构师与高级开发者，系统化阐述NFLG WMS（仓库管理系统）在Spring Cloud生态下的微服务架构设计。该系统采用多模块聚合工程，围绕“网关层-业务服务层-基础设施层”进行服务拆分与职责划分，结合Nacos注册与配置中心、Sa-Token统一认证、MyBatis-Plus数据访问、Redisson缓存与分布式能力、OpenTelemetry链路追踪、PowerJob计划任务等技术栈，实现高可用、可扩展、可观测的仓储业务支撑平台。

## 项目结构
系统以Maven聚合工程组织，父POM统一管理版本与依赖，子模块按功能域拆分，形成清晰的模块边界与复用层：

- 核心公共层
  - nflg-wms-common：通用常量、异常、DTO/QO/VO、工具类
  - nflg-wms-starter：全局切面、拦截器、统一响应包装、基础配置
- 基础设施层
  - nflg-wms-repository：数据库访问抽象与MyBatis-Plus集成
  - nflg-wms-gateway：Spring Cloud Gateway网关与鉴权路由
- 业务服务层
  - nflg-wms-admin：WMS管理后台（含打印、报表、SAP对接）
  - nflg-wms-auth：统一认证中心（SSO）
  - nflg-wms-srm-receive：SRM订单接收服务
  - nflg-wms-shipment：发货相关业务
  - nflg-qms-admin：QMS质量管理后台
  - nflg-wms-scheduled：计划任务执行器（PowerJob Worker）
- 其他
  - readme.md：环境依赖说明（如wkhtmltoimage）

```mermaid
graph TB
subgraph "聚合工程"
ROOT["父POM<br/>统一版本与依赖管理"]
end
subgraph "公共与基础设施"
COMMON["nflg-wms-common"]
STARTER["nflg-wms-starter"]
REPO["nflg-wms-repository"]
GATEWAY["nflg-wms-gateway"]
end
subgraph "业务服务"
ADMIN["nflg-wms-admin"]
AUTH["nflg-wms-auth"]
SRM["nflg-wms-srm-receive"]
SHIPMENT["nflg-wms-shipment"]
QMS["nflg-qms-admin"]
SCHEDULED["nflg-wms-scheduled"]
end
ROOT --> COMMON
ROOT --> STARTER
ROOT --> REPO
ROOT --> GATEWAY
ROOT --> ADMIN
ROOT --> AUTH
ROOT --> SRM
ROOT --> SHIPMENT
ROOT --> QMS
ROOT --> SCHEDULED
ADMIN --> COMMON
ADMIN --> STARTER
ADMIN --> REPO
AUTH --> COMMON
AUTH --> STARTER
GATEWAY --> COMMON
GATEWAY --> REPO
SRM --> STARTER
SHIPMENT --> COMMON
SHIPMENT --> STARTER
QMS --> COMMON
QMS --> STARTER
SCHEDULED --> COMMON
SCHEDULED --> STARTER
```

**图表来源**
- [pom.xml:17-28](file://pom.xml#L17-L28)
- [nflg-wms-admin/pom.xml:14-22](file://nflg-wms-admin/pom.xml#L14-L22)
- [nflg-wms-auth/pom.xml:15-23](file://nflg-wms-auth/pom.xml#L15-L23)
- [nflg-wms-gateway/pom.xml:15-27](file://nflg-wms-gateway/pom.xml#L15-L27)
- [nflg-wms-repository/pom.xml:14-18](file://nflg-wms-repository/pom.xml#L14-L18)
- [nflg-wms-srm-receive/pom.xml:15-19](file://nflg-wms-srm-receive/pom.xml#L15-L19)
- [nflg-wms-shipment/pom.xml:14-22](file://nflg-wms-shipment/pom.xml#L14-L22)
- [nflg-qms-admin/pom.xml:17-25](file://nflg-qms-admin/pom.xml#L17-L25)
- [nflg-wms-scheduled/pom.xml:14-22](file://nflg-wms-scheduled/pom.xml#L14-L22)

**章节来源**
- [pom.xml:17-28](file://pom.xml#L17-L28)
- [readme.md:1-10](file://readme.md#L1-L10)

## 核心组件
- 父POM与版本治理
  - Spring Boot 3.2.4、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.0
  - MyBatis-Plus 3.5.12、Sa-Token 1.42.0、Redisson 3.52.0、PowerJob 5.1.1、OpenTelemetry等
- 应用入口与发现
  - 各服务通过@EnableDiscoveryClient启用服务注册与发现
  - 网关、管理后台、认证中心分别暴露HTTP端口，计划任务服务以非Web方式运行

**章节来源**
- [pom.xml:29-53](file://pom.xml#L29-L53)
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
- [nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java:9-13](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L9-L13)
- [nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java:10-17](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java#L10-L17)

## 架构总览
系统采用“网关+服务网格”的微服务体系，客户端请求经由网关统一接入，网关负责路由、鉴权与限流；业务服务通过Nacos完成注册与配置下发；认证中心提供SSO统一认证；数据访问层通过Repository模块与MyBatis-Plus对接PostgreSQL；计划任务通过PowerJob Worker异步执行；日志与链路追踪通过Loki与OpenTelemetry集成。

```mermaid
graph TB
CLIENT["客户端/前端"]
GW["Spring Cloud Gateway<br/>路由/鉴权/限流"]
REG["Nacos 注册与配置中心"]
AUTH["认证中心(nflg-wms-auth)<br/>SSO"]
ADMIN["管理后台(nflg-wms-admin)"]
SRM["SRM接收(nflg-wms-srm-receive)"]
SHIP["发货(nflg-wms-shipment)"]
QMS["QMS管理(nflg-qms-admin)"]
SCHED["计划任务(nflg-wms-scheduled)"]
DB["PostgreSQL 数据库"]
REDIS["Redis 缓存/分布式锁"]
LOG["Loki 日志"]
TRACE["OpenTelemetry 链路追踪"]
CLIENT --> GW
GW --> REG
GW --> AUTH
GW --> ADMIN
GW --> SRM
GW --> SHIP
GW --> QMS
GW --> SCHED
ADMIN --> DB
ADMIN --> REDIS
SRM --> DB
SRM --> REDIS
SHIP --> DB
SHIP --> REDIS
QMS --> DB
QMS --> REDIS
SCHED --> DB
SCHED --> REDIS
ADMIN -.日志/链路.-> LOG
ADMIN -.日志/链路.-> TRACE
AUTH -.日志/链路.-> LOG
AUTH -.日志/链路.-> TRACE
GW -.日志/链路.-> LOG
GW -.日志/链路.-> TRACE
```

**图表来源**
- [nflg-wms-gateway/pom.xml:29-49](file://nflg-wms-gateway/pom.xml#L29-L49)
- [nflg-wms-admin/pom.xml:14-18](file://nflg-wms-admin/pom.xml#L14-L18)
- [nflg-wms-srm-receive/pom.xml:15-19](file://nflg-wms-srm-receive/pom.xml#L15-L19)
- [nflg-wms-shipment/pom.xml:14-22](file://nflg-wms-shipment/pom.xml#L14-L22)
- [nflg-qms-admin/pom.xml:17-25](file://nflg-qms-admin/pom.xml#L17-L25)
- [nflg-wms-scheduled/pom.xml:14-22](file://nflg-wms-scheduled/pom.xml#L14-L22)
- [nflg-wms-repository/pom.xml:23-26](file://nflg-wms-repository/pom.xml#L23-L26)

## 详细组件分析

### 网关服务（nflg-wms-gateway）
- 职责
  - 作为统一入口，聚合路由规则，对接Nacos注册中心与配置中心
  - 集成Sa-Token鉴权能力，支持SSO与令牌校验
  - 提供负载均衡与限流策略
- 技术要点
  - spring-cloud-starter-gateway、spring-cloud-starter-loadbalancer
  - Sa-Token Reactor Starter、Redis Jackson
  - Actuator、Loki Logback、Redisson Starter

```mermaid
classDiagram
class GateWayApplication {
+main(args)
}
class GatewayRoutes {
+routeToAdmin()
+routeToAuth()
+routeToSrm()
+routeToShipment()
+routeToQms()
+routeToScheduled()
}
GateWayApplication --> GatewayRoutes : "加载路由规则"
```

**图表来源**
- [nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java:10-13](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L10-L13)
- [nflg-wms-gateway/pom.xml:29-49](file://nflg-wms-gateway/pom.xml#L29-L49)

**章节来源**
- [nflg-wms-gateway/pom.xml:15-94](file://nflg-wms-gateway/pom.xml#L15-L94)
- [nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java:9-18](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GateWayApplication.java#L9-L18)

### 认证服务（nflg-wms-auth）
- 职责
  - 提供SSO认证中心，统一发放与校验令牌
  - 对接LDAP/用户体系，支持角色权限模型
- 技术要点
  - Sa-Token Server/JWT/Jackson
  - Redisson、Actuator、Loki、JSch测试依赖

```mermaid
sequenceDiagram
participant C as "客户端"
participant GW as "网关"
participant AUTH as "认证中心"
participant SVC as "业务服务"
C->>GW : 请求受保护资源
GW->>AUTH : 校验令牌/跳转SSO
AUTH-->>GW : 返回认证结果
GW->>SVC : 转发带令牌请求
SVC-->>GW : 返回业务响应
GW-->>C : 返回最终响应
```

**图表来源**
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java:10-14](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L14)
- [nflg-wms-gateway/pom.xml:55-61](file://nflg-wms-gateway/pom.xml#L55-L61)

**章节来源**
- [nflg-wms-auth/pom.xml:15-61](file://nflg-wms-auth/pom.xml#L15-L61)
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java:10-21](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L21)

### 管理后台（nflg-wms-admin）
- 职责
  - 提供WMS管理界面与接口，覆盖入库、出库、移库、盘点、打印、报表等功能
  - 集成SAP JCo、PDF/二维码/Excel处理能力
- 技术要点
  - Spring Web、LDAP、Mail、Thymeleaf、iText7、Flying Saucer、EasyExcel、Retry、AOP、Validation、Redisson、Actuator、Loki、OpenTelemetry TSID

```mermaid
flowchart TD
Start(["请求进入"]) --> Validate["参数校验/权限检查"]
Validate --> Biz["业务处理仓储作业"]
Biz --> Repo["Repository持久化"]
Repo --> SAP["SAP JCo同步可选"]
SAP --> Resp["返回结果"]
Repo --> Resp
Validate --> |失败| Err["异常/错误响应"]
```

**图表来源**
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)

**章节来源**
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:12-18](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L18)

### SRM接收服务（nflg-wms-srm-receive）
- 职责
  - 接收SRM订单并落库，触发后续质检/收货流程
- 技术要点
  - Spring Web、Actuator、Redisson、SAP JCo

**章节来源**
- [nflg-wms-srm-receive/pom.xml:15-62](file://nflg-wms-srm-receive/pom.xml#L15-L62)

### 发货服务（nflg-wms-shipment）
- 职责
  - 处理发货相关的包装、装车、出库、单据打印等流程
- 技术要点
  - Spring Web、PDF/二维码/Excel、Validation、Redisson、Actuator、OpenTelemetry

**章节来源**
- [nflg-wms-shipment/pom.xml:14-138](file://nflg-wms-shipment/pom.xml#L14-L138)

### QMS管理后台（nflg-qms-admin）
- 职责
  - 质量管理相关后台能力，与WMS管理后台类似，但聚焦质量域
- 技术要点
  - Spring Web、LDAP、Mail、Thymeleaf、MongoDB、EasyExcel、Retry、AOP、Validation、Redisson、Actuator、Loki、OpenTelemetry

**章节来源**
- [nflg-qms-admin/pom.xml:17-185](file://nflg-qms-admin/pom.xml#L17-L185)

### 计划任务服务（nflg-wms-scheduled）
- 职责
  - 作为PowerJob Worker，执行周期性或调度性任务（如SAP同步）
- 运行方式
  - 以非Web方式启动，仅加载上下文与任务执行器
- 技术要点
  - PowerJob Worker、SAP JCo、Redisson、Actuator、LDAP、JUnit、JSch

**章节来源**
- [nflg-wms-scheduled/pom.xml:14-61](file://nflg-wms-scheduled/pom.xml#L14-L61)
- [nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java:10-17](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/ScheduledApplication.java#L10-L17)

### 数据访问层（nflg-wms-repository）
- 职责
  - 封装数据库访问，提供MyBatis-Plus基础能力与重试策略
- 技术要点
  - PostgreSQL、MyBatis-Plus、JSQLParser、Spring Retry、Redisson

**章节来源**
- [nflg-wms-repository/pom.xml:14-64](file://nflg-wms-repository/pom.xml#L14-L64)

## 依赖关系分析
- 版本治理
  - 父POM集中声明Spring Boot、Spring Cloud、Spring Cloud Alibaba、MyBatis-Plus、Sa-Token、Redisson、PowerJob、OpenTelemetry等版本
- 模块依赖
  - 业务服务均依赖common与starter，部分依赖repository
  - 网关依赖common与repository，并引入gateway、nacos、sa-token等
  - 计划任务依赖starter与repository，使用PowerJob Worker
- 外部依赖
  - 数据库：PostgreSQL
  - 缓存/分布式：Redisson
  - 认证：Sa-Token（Server/Client/JWT/Jackson）
  - 日志：Loki Logback Appender
  - 链路追踪：Micrometer Tracing Bridge OTel、OTLP Exporter、SDK Extension Autoconfigure
  - 打印与报表：wkhtmltoimage（环境依赖）

```mermaid
graph LR
POM["父POM版本管理"]
BOOT["Spring Boot 3.2.4"]
CLOUD["Spring Cloud 2023.0.1"]
ALIBABA["Spring Cloud Alibaba 2023.0.1.0"]
MP["MyBatis-Plus 3.5.12"]
ST["Sa-Token 1.42.0"]
RS["Redisson 3.52.0"]
PJ["PowerJob 5.1.1"]
OT["OpenTelemetry"]
POM --> BOOT
POM --> CLOUD
POM --> ALIBABA
POM --> MP
POM --> ST
POM --> RS
POM --> PJ
POM --> OT
```

**图表来源**
- [pom.xml:54-192](file://pom.xml#L54-L192)

**章节来源**
- [pom.xml:54-192](file://pom.xml#L54-L192)

## 性能考量
- 并发与限流
  - 网关侧建议结合限流与熔断策略，避免热点服务过载
- 缓存与热点
  - 使用Redisson进行热点数据缓存与分布式锁，降低数据库压力
- 数据库优化
  - MyBatis-Plus分页与JSQLParser动态SQL，配合索引与慢查询监控
- 链路追踪
  - OpenTelemetry采集指标与链路，定位瓶颈与异常
- 打印与报表
  - wkhtmltoimage需在服务器侧部署，避免阻塞主线程；可异步化打印任务

## 故障排查指南
- 认证问题
  - 检查认证中心SSO配置与令牌签发；确认网关路由是否正确转发至认证中心
- 网关路由
  - 核对Nacos路由配置，确保服务名与实例健康状态
- 数据库连接
  - 检查PostgreSQL连接参数与驱动版本，关注连接池配置
- 日志与链路
  - Loki日志采集与OpenTelemetry链路导出是否正常
- 计划任务
  - PowerJob Worker是否在线，任务执行日志与重试策略是否合理

**章节来源**
- [nflg-wms-gateway/pom.xml:76-94](file://nflg-wms-gateway/pom.xml#L76-L94)
- [nflg-wms-repository/pom.xml:23-26](file://nflg-wms-repository/pom.xml#L23-L26)
- [nflg-wms-scheduled/pom.xml:30-48](file://nflg-wms-scheduled/pom.xml#L30-L48)

## 结论
本系统通过Spring Cloud与多模块架构实现了清晰的服务边界与职责分离，结合统一认证、网关路由、数据库抽象与分布式能力，构建了可扩展、可观测的WMS平台。建议在生产环境中完善灰度发布、容量评估与灾备演练，持续优化链路与缓存策略，保障高并发与高可用。

## 附录
- 环境依赖
  - 需安装wkhtmltoimage以支持HTML转图片与标签打印

**章节来源**
- [readme.md:1-10](file://readme.md#L1-L10)