rakor
/
wms
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
wms/.qoder/repowiki/zh/content/快速开始.md

319 lines
15 KiB
Markdown
Raw Normal View History

docs(api): 新增完整API接口文档 - 覆盖仓储管理、物料管理、订单处理等业务域接口设计与规范 - 介绍统一返回体、状态码体系、认证授权机制及错误处理策略 - 详细描述接口清单管理及二维码内容生成机制 - 提供架构总览、依赖分析和性能考虑建议 - 包含故障排查指南及Postman集合和curl示例说明 docs(biz): 新增业务功能文档详解 - 系统化梳理仓储、物料、订单、生产、采购销售和质量管理业务流程 - 按功能划分控制层模块，明确数据模型和持久化结构 - 详细描述核心业务组件及关键操作流程图和时序图 - 分析业务依赖与耦合点，强调事务一致性和并发锁机制 - 提供故障排查和性能优化建议，支持批量操作分批处理
2026-04-14 08:26:07 +08:00
# 快速开始
<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