319 lines
15 KiB
Markdown
319 lines
15 KiB
Markdown
# 快速开始
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [pom.xml](file://pom.xml)
|
||
- [nflg-wms-admin/src/main/resources/application.yml](file://nflg-wms-admin/src/main/resources/application.yml)
|
||
- [nflg-wms-auth/src/main/resources/application.yml](file://nflg-wms-auth/src/main/resources/application.yml)
|
||
- [nflg-wms-gateway/src/main/resources/application.yml](file://nflg-wms-gateway/src/main/resources/application.yml)
|
||
- [nflg-wms-admin/src/main/resources/application-dev.yml](file://nflg-wms-admin/src/main/resources/application-dev.yml)
|
||
- [nflg-wms-auth/src/main/resources/application-dev.yml](file://nflg-wms-auth/src/main/resources/application-dev.yml)
|
||
- [nflg-wms-gateway/src/main/resources/application-dev.yml](file://nflg-wms-gateway/src/main/resources/application-dev.yml)
|
||
- [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-srm-receive/pom.xml](file://nflg-wms-srm-receive/pom.xml)
|
||
- [nflg-wms-shipment/pom.xml](file://nflg-wms-shipment/pom.xml)
|
||
- [nflg-wms-scheduled/pom.xml](file://nflg-wms-scheduled/pom.xml)
|
||
- [nflg-wms-repository/pom.xml](file://nflg-wms-repository/pom.xml)
|
||
- [nflg-wms-starter/pom.xml](file://nflg-wms-starter/pom.xml)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本指南面向首次接触 NFLG WMS 的用户，帮助你在约 30 分钟内完成环境准备、项目构建、配置与启动，并进行基础功能验证。系统基于 Spring Boot 3 和 Spring Cloud，采用 Maven 多模块管理，使用 PostgreSQL 作为主数据库，Redis 用于缓存与分布式能力，部分模块集成 SAP JCo 进行 SRM/收货流程对接。
|
||
|
||
## 项目结构
|
||
WMS 采用多模块聚合工程，核心模块包括：
|
||
- 网关模块：nflg-wms-gateway
|
||
- 认证中心：nflg-wms-auth
|
||
- 管理后台：nflg-wms-admin
|
||
- 发货服务：nflg-wms-shipment
|
||
- 计划任务执行器：nflg-wms-scheduled
|
||
- SRM 收货服务：nflg-wms-srm-receive
|
||
- 公共模块：nflg-wms-common
|
||
- 启动器模块：nflg-wms-starter
|
||
- 数据访问模块：nflg-wms-repository
|
||
|
||
```mermaid
|
||
graph TB
|
||
GW["网关模块<br/>nflg-wms-gateway"] --> AUTH["认证中心<br/>nflg-wms-auth"]
|
||
GW --> ADMIN["管理后台<br/>nflg-wms-admin"]
|
||
GW --> SHIP["发货服务<br/>nflg-wms-shipment"]
|
||
GW --> SRM["SRM收货服务<br/>nflg-wms-srm-receive"]
|
||
GW --> SCH["计划任务执行器<br/>nflg-wms-scheduled"]
|
||
ADMIN --> ST["启动器模块<br/>nflg-wms-starter"]
|
||
SHIP --> ST
|
||
SRM --> ST
|
||
SCH --> ST
|
||
ST --> REP["数据访问模块<br/>nflg-wms-repository"]
|
||
REP --> PG["PostgreSQL"]
|
||
ST --> REDIS["Redis"]
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml:17-27](file://pom.xml#L17-L27)
|
||
- [nflg-wms-starter/pom.xml:15-120](file://nflg-wms-starter/pom.xml#L15-L120)
|
||
- [nflg-wms-repository/pom.xml:14-63](file://nflg-wms-repository/pom.xml#L14-L63)
|
||
|
||
章节来源
|
||
- [pom.xml:17-27](file://pom.xml#L17-L27)
|
||
|
||
## 核心组件
|
||
- 网关模块：统一入口，启用服务发现与路由定位，暴露健康检查与指标端点。
|
||
- 认证中心：基于 Sa-Token 提供 SSO 与 JWT 能力，集中处理登录与票据校验。
|
||
- 管理后台：业务管理界面与接口，集成 Nacos 配置中心与服务注册。
|
||
- 发货服务：包含 PDF 生成、二维码打印、条码扫描等物流相关能力。
|
||
- 计划任务执行器：集成 PowerJob 与 Redisson，负责定时与分布式任务。
|
||
- SRM 收货服务：通过 SAP JCo 与外部系统交互，打包为可独立运行的 jar。
|
||
- 公共模块：通用工具、常量、异常与 DTO 定义。
|
||
- 启动器模块：统一引入 Nacos、Redis、Sa-Token、MyBatis Plus 等依赖。
|
||
- 数据访问模块：封装 MyBatis Plus、SQL 解析与重试机制。
|
||
|
||
章节来源
|
||
- [nflg-wms-gateway/src/main/resources/application.yml:1-43](file://nflg-wms-gateway/src/main/resources/application.yml#L1-L43)
|
||
- [nflg-wms-auth/src/main/resources/application.yml:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
|
||
- [nflg-wms-admin/src/main/resources/application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
|
||
- [nflg-wms-starter/pom.xml:15-120](file://nflg-wms-starter/pom.xml#L15-L120)
|
||
- [nflg-wms-repository/pom.xml:14-63](file://nflg-wms-repository/pom.xml#L14-L63)
|
||
|
||
## 架构总览
|
||
系统采用“网关 + 微服务 + 配置中心 + 注册中心”的分层架构。网关负责请求转发与服务发现；各业务模块通过 Nacos 获取配置并注册到注册中心；认证中心提供统一登录与票据；Redis 用于会话与分布式锁；PostgreSQL 存储业务数据。
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "客户端"
|
||
U["浏览器/移动端/第三方系统"]
|
||
end
|
||
subgraph "边缘层"
|
||
G["网关<br/>nflg-wms-gateway"]
|
||
end
|
||
subgraph "服务层"
|
||
A["认证中心<br/>nflg-wms-auth"]
|
||
M["管理后台<br/>nflg-wms-admin"]
|
||
S["发货服务<br/>nflg-wms-shipment"]
|
||
R["SRM收货服务<br/>nflg-wms-srm-receive"]
|
||
C["计划任务执行器<br/>nflg-wms-scheduled"]
|
||
end
|
||
subgraph "基础设施"
|
||
NACOS["Nacos 配置/注册中心"]
|
||
REDIS["Redis"]
|
||
PG["PostgreSQL"]
|
||
end
|
||
U --> G
|
||
G --> A
|
||
G --> M
|
||
G --> S
|
||
G --> R
|
||
G --> C
|
||
A --- NACOS
|
||
M --- NACOS
|
||
S --- NACOS
|
||
R --- NACOS
|
||
C --- NACOS
|
||
M --- REDIS
|
||
S --- REDIS
|
||
R --- REDIS
|
||
C --- REDIS
|
||
M --- PG
|
||
S --- PG
|
||
R --- PG
|
||
C --- PG
|
||
```
|
||
|
||
图表来源
|
||
- [nflg-wms-gateway/src/main/resources/application.yml:10-19](file://nflg-wms-gateway/src/main/resources/application.yml#L10-L19)
|
||
- [nflg-wms-auth/src/main/resources/application.yml:10-19](file://nflg-wms-auth/src/main/resources/application.yml#L10-L19)
|
||
- [nflg-wms-admin/src/main/resources/application.yml:13-23](file://nflg-wms-admin/src/main/resources/application.yml#L13-L23)
|
||
- [nflg-wms-starter/pom.xml:33-45](file://nflg-wms-starter/pom.xml#L33-L45)
|
||
- [nflg-wms-repository/pom.xml:23-30](file://nflg-wms-repository/pom.xml#L23-L30)
|
||
|
||
## 详细组件分析
|
||
|
||
### 环境要求与版本约束
|
||
- JDK：17（父 POM 显式声明）
|
||
- Maven：标准 Maven 工程，使用 Maven 3.6+ 建议版本
|
||
- 数据库：PostgreSQL（仓库与 starter 中均引入）
|
||
- 缓存/中间件：Redis（启动器与多个模块引入 Redis Starter）
|
||
- 可选集成：SAP JCo（SRM 与计划任务模块以 system 依赖方式引入）
|
||
|
||
章节来源
|
||
- [pom.xml:29-32](file://pom.xml#L29-L32)
|
||
- [nflg-wms-repository/pom.xml:23-30](file://nflg-wms-repository/pom.xml#L23-L30)
|
||
- [nflg-wms-starter/pom.xml:55-57](file://nflg-wms-starter/pom.xml#L55-L57)
|
||
- [nflg-wms-srm-receive/pom.xml:50-55](file://nflg-wms-srm-receive/pom.xml#L50-L55)
|
||
- [nflg-wms-scheduled/pom.xml:24-29](file://nflg-wms-scheduled/pom.xml#L24-L29)
|
||
|
||
### 安装与构建步骤
|
||
- 步骤 1：克隆仓库后，进入根目录执行构建
|
||
- 使用 Maven 清理并编译所有模块
|
||
- 若需打包独立服务（如 SRM/发货），可按模块执行对应插件配置
|
||
- 步骤 2：准备数据库与 Redis
|
||
- 初始化 PostgreSQL 数据库（表结构由业务模块或迁移脚本提供）
|
||
- 启动 Redis 服务
|
||
- 步骤 3：准备 Nacos（可本地或远程）
|
||
- 确认 application.yml 中的 Nacos 地址与命名空间
|
||
- 步骤 4：启动顺序建议
|
||
- 先启动认证中心与网关
|
||
- 再启动其他业务模块
|
||
- 如需 SRM/发货/计划任务，按需启动
|
||
|
||
章节来源
|
||
- [pom.xml:203-256](file://pom.xml#L203-L256)
|
||
- [nflg-wms-gateway/src/main/resources/application.yml:10-19](file://nflg-wms-gateway/src/main/resources/application.yml#L10-L19)
|
||
- [nflg-wms-auth/src/main/resources/application.yml:10-19](file://nflg-wms-auth/src/main/resources/application.yml#L10-L19)
|
||
- [nflg-wms-admin/src/main/resources/application.yml:13-23](file://nflg-wms-admin/src/main/resources/application.yml#L13-L23)
|
||
|
||
### 配置文件设置要点
|
||
- 网关模块
|
||
- 端口：8100
|
||
- Nacos 配置与发现：server-addr、namespace、group
|
||
- 开启 Gateway 服务发现与负载均衡
|
||
- 认证中心
|
||
- 端口：8101
|
||
- Sa-Token：token 名称、超时、SSO 相关配置
|
||
- 管理后台
|
||
- 端口：8102
|
||
- Nacos 配置导入与命名空间
|
||
- 日志与 Loki/OTLP 集成（开发环境）
|
||
- 数据源与连接池
|
||
- 开发环境示例中包含 HikariCP 连接池参数（最大池大小、空闲超时等）
|
||
- Redis 与缓存
|
||
- 启动器模块引入 Redis Starter，业务模块可直接使用
|
||
- SAP 集成
|
||
- SRM/计划任务模块以 system 依赖方式引入 sapjco3.jar，需确保本地 lib 目录存在对应 JCo 库
|
||
|
||
章节来源
|
||
- [nflg-wms-gateway/src/main/resources/application.yml:1-43](file://nflg-wms-gateway/src/main/resources/application.yml#L1-L43)
|
||
- [nflg-wms-auth/src/main/resources/application.yml:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
|
||
- [nflg-wms-admin/src/main/resources/application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
|
||
- [nflg-wms-admin/src/main/resources/application-dev.yml:26-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L26-L34)
|
||
- [nflg-wms-auth/src/main/resources/application-dev.yml:12-20](file://nflg-wms-auth/src/main/resources/application-dev.yml#L12-L20)
|
||
- [nflg-wms-gateway/src/main/resources/application-dev.yml:12-20](file://nflg-wms-gateway/src/main/resources/application-dev.yml#L12-L20)
|
||
- [nflg-wms-starter/pom.xml:55-57](file://nflg-wms-starter/pom.xml#L55-L57)
|
||
- [nflg-wms-srm-receive/pom.xml:50-55](file://nflg-wms-srm-receive/pom.xml#L50-L55)
|
||
- [nflg-wms-scheduled/pom.xml:24-29](file://nflg-wms-scheduled/pom.xml#L24-L29)
|
||
|
||
### 启动脚本与命令示例
|
||
- 构建与测试
|
||
- 在根目录执行：mvn clean install -DskipTests
|
||
- 或针对单模块：cd nflg-wms-admin && mvn spring-boot:run
|
||
- 独立服务打包与运行（如 SRM/发货）
|
||
- SRM 收货服务：在模块目录执行 maven 插件打包，生成含依赖的 jar，再通过 java -jar 运行
|
||
- 发货服务：同上，注意其 lib 目录包含外部依赖
|
||
- 启动顺序参考
|
||
- 认证中心：java -cp ... AuthApplication
|
||
- 网关：java -cp ... GatewayApplication
|
||
- 管理后台：java -cp ... AdminApplication
|
||
- 发货/计划任务/SRM：按需启动
|
||
|
||
章节来源
|
||
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:18-25](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L18-L25)
|
||
- [nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java:14-21](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L14-L21)
|
||
- [nflg-wms-srm-receive/pom.xml:117-129](file://nflg-wms-srm-receive/pom.xml#L117-L129)
|
||
- [nflg-wms-shipment/pom.xml:193-205](file://nflg-wms-shipment/pom.xml#L193-L205)
|
||
|
||
### 基本使用示例
|
||
- 登录系统
|
||
- 访问认证中心提供的登录入口，获取票据后访问受保护资源
|
||
- 查看基础数据
|
||
- 通过网关访问管理后台接口，查询物料、仓库、库位等基础数据
|
||
- 发货流程
|
||
- 调用发货服务接口，生成装箱单与二维码，完成出库扫描
|
||
- SRM 收货
|
||
- 触发 SRM 收货流程，系统通过 SAP JCo 与外部系统交互
|
||
|
||
章节来源
|
||
- [nflg-wms-auth/src/main/resources/application.yml:20-33](file://nflg-wms-auth/src/main/resources/application.yml#L20-L33)
|
||
- [nflg-wms-gateway/src/main/resources/application.yml:20-26](file://nflg-wms-gateway/src/main/resources/application.yml#L20-L26)
|
||
- [nflg-wms-srm-receive/pom.xml:50-55](file://nflg-wms-srm-receive/pom.xml#L50-L55)
|
||
|
||
## 依赖分析
|
||
- 版本与依赖管理
|
||
- Spring Boot 3.2.4、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.0
|
||
- Sa-Token 1.42.0、MyBatis Plus 3.5.12、Redisson 3.52.0、PostgreSQL 驱动 42.7.7
|
||
- 模块间耦合
|
||
- 启动器模块为其他业务模块提供统一依赖；数据访问模块向上被业务模块依赖
|
||
- 外部集成
|
||
- Nacos 配置与注册中心；Redis 缓存；PostgreSQL 数据存储；SAP JCo（可选）
|
||
|
||
```mermaid
|
||
graph LR
|
||
ROOT["根 POM<br/>pom.xml"] --> ST["启动器模块<br/>nflg-wms-starter"]
|
||
ROOT --> REP["数据访问模块<br/>nflg-wms-repository"]
|
||
ST --> ADMIN["管理后台<br/>nflg-wms-admin"]
|
||
ST --> SHIP["发货服务<br/>nflg-wms-shipment"]
|
||
ST --> SRM["SRM收货服务<br/>nflg-wms-srm-receive"]
|
||
ST --> SCH["计划任务执行器<br/>nflg-wms-scheduled"]
|
||
REP --> PG["PostgreSQL 驱动"]
|
||
ST --> REDIS["Redis Starter"]
|
||
```
|
||
|
||
图表来源
|
||
- [pom.xml:54-193](file://pom.xml#L54-L193)
|
||
- [nflg-wms-starter/pom.xml:33-45](file://nflg-wms-starter/pom.xml#L33-L45)
|
||
- [nflg-wms-repository/pom.xml:23-30](file://nflg-wms-repository/pom.xml#L23-L30)
|
||
|
||
章节来源
|
||
- [pom.xml:54-193](file://pom.xml#L54-L193)
|
||
- [nflg-wms-starter/pom.xml:15-120](file://nflg-wms-starter/pom.xml#L15-L120)
|
||
- [nflg-wms-repository/pom.xml:14-63](file://nflg-wms-repository/pom.xml#L14-L63)
|
||
|
||
## 性能考虑
|
||
- 连接池与数据库
|
||
- 开发环境示例中已配置 HikariCP 参数，生产环境建议结合压测调优
|
||
- 缓存策略
|
||
- 使用 Redis 缓存热点数据与会话，降低数据库压力
|
||
- 日志与可观测性
|
||
- Loki 与 OTLP 已在示例配置中启用，便于日志与链路追踪
|
||
- 并发与限流
|
||
- 网关层可配合限流与熔断策略，保障系统稳定性
|
||
|
||
章节来源
|
||
- [nflg-wms-admin/src/main/resources/application-dev.yml:26-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L26-L34)
|
||
- [nflg-wms-gateway/src/main/resources/application.yml:27-43](file://nflg-wms-gateway/src/main/resources/application.yml#L27-L43)
|
||
- [nflg-wms-auth/src/main/resources/application.yml:34-50](file://nflg-wms-auth/src/main/resources/application.yml#L34-L50)
|
||
|
||
## 故障排除指南
|
||
- 端口冲突
|
||
- 网关、认证中心、管理后台默认端口分别为 8100、8101、8102，若冲突请修改 application.yml 中 server.port
|
||
- Nacos 连接失败
|
||
- 检查 application.yml 中 nacos.server-addr、namespace、group 是否正确
|
||
- 数据库连接异常
|
||
- 确认 PostgreSQL 已启动且账号密码正确；开发环境示例中包含 HikariCP 参数，可据此排查
|
||
- Redis 连接异常
|
||
- 确认 Redis 服务可用；启动器模块已引入 Redis Starter，业务模块可直接使用
|
||
- SAP JCo 依赖缺失
|
||
- SRM/计划任务模块需要本地 lib 目录中的 sapjco3.jar，请确认文件存在且版本匹配
|
||
- 启动顺序错误
|
||
- 必须先启动认证中心与网关，再启动其他业务模块
|
||
|
||
章节来源
|
||
- [nflg-wms-gateway/src/main/resources/application.yml:1-43](file://nflg-wms-gateway/src/main/resources/application.yml#L1-L43)
|
||
- [nflg-wms-auth/src/main/resources/application.yml:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
|
||
- [nflg-wms-admin/src/main/resources/application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
|
||
- [nflg-wms-srm-receive/pom.xml:50-55](file://nflg-wms-srm-receive/pom.xml#L50-L55)
|
||
- [nflg-wms-scheduled/pom.xml:24-29](file://nflg-wms-scheduled/pom.xml#L24-L29)
|
||
|
||
## 结论
|
||
按照本指南完成环境准备、依赖安装、配置与启动后，你可以在 30 分钟内成功运行 NFLG WMS 的核心模块，并进行基础的登录与数据查询验证。后续可根据业务需求扩展模块与集成更多外部系统。
|
||
|
||
## 附录
|
||
- 快速命令清单
|
||
- 构建：mvn clean install -DskipTests
|
||
- 单模块运行：cd nflg-wms-admin && mvn spring-boot:run
|
||
- 独立服务运行：java -jar target/*.jar（SRM/发货模块）
|
||
- 关键端口
|
||
- 网关：8100
|
||
- 认证中心：8101
|
||
- 管理后台：8102 |