20 KiB

Raw Blame History

核心模块

**本文引用的文件** - [nflg-wms-common/pom.xml](file://nflg-wms-common/pom.xml) - [nflg-wms-starter/pom.xml](file://nflg-wms-starter/pom.xml) - [nflg-wms-repository/pom.xml](file://nflg-wms-repository/pom.xml) - [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-scheduled/pom.xml](file://nflg-wms-scheduled/pom.xml) - [nflg-wms-shipment/pom.xml](file://nflg-wms-shipment/pom.xml) - [nflg-wms-srm-receive/pom.xml](file://nflg-wms-srm-receive/pom.xml) - [nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java) - [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java) - [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) - [nflg-wms-shipment/src/main/java/com/nflg/wms/shipment/ShipmentApplication.java](file://nflg-wms-shipment/src/main/java/com/nflg/wms/shipment/ShipmentApplication.java) - [nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/SrmReceiveApplication.java](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/SrmReceiveApplication.java)

简介

本文件面向NFLG WMS系统的核心模块，系统性梳理各微服务模块的职责边界、技术实现与协作方式，并覆盖通用模块(nflg-wms-common)、基础模块(nflg-wms-starter)、数据访问模块(nflg-wms-repository)、管理后台(nflg-wms-admin)、认证(nflg-wms-auth)、网关(nflg-wms-gateway)、定时任务(nflg-wms-scheduled)、发货(nflg-wms-shipment)、SRM集成(nflg-wms-srm-receive)等。文档同时给出模块间依赖关系、配置要点、使用示例与最佳实践建议，帮助开发者快速理解与高效维护。

项目结构

模块分层清晰：以“通用能力(nflg-wms-common)”为基础，向上衍生“基础设施(nflg-wms-starter)”、“数据访问(nflg-wms-repository)”；再由“业务服务”(admin、auth、shipment、scheduled、srm-receive)以及“网关(nflg-wms-gateway)”构成完整体系。
公共常量与工具集中在common中，统一对外暴露；starter封装通用Web、鉴权、注册发现、Redis、OSS/S3等能力；repository聚焦数据库与MyBatis-Plus；业务服务各自独立打包并可单独部署。

graph TB
subgraph "通用层"
COMMON["nflg-wms-common<br/>公共常量/异常/工具"]
end
subgraph "基础设施层"
STARTER["nflg-wms-starter<br/>基础控制器/注解/过滤器/配置"]
REPO["nflg-wms-repository<br/>数据库/MyBatis-Plus"]
end
subgraph "业务服务层"
ADMIN["nflg-wms-admin<br/>管理后台"]
AUTH["nflg-wms-auth<br/>认证中心"]
SHIPMENT["nflg-wms-shipment<br/>发货服务"]
SCHEDULED["nflg-wms-scheduled<br/>计划任务执行器"]
SRM["nflg-wms-srm-receive<br/>SRM订单接收"]
GATEWAY["nflg-wms-gateway<br/>网关"]
end
COMMON --> STARTER
COMMON --> REPO
STARTER --> ADMIN
STARTER --> AUTH
STARTER --> SHIPMENT
STARTER --> SCHEDULED
STARTER --> SRM
REPO --> ADMIN
REPO --> AUTH
REPO --> SHIPMENT
REPO --> SCHEDULED
REPO --> SRM
GATEWAY --> ADMIN
GATEWAY --> AUTH
GATEWAY --> SHIPMENT
GATEWAY --> SCHEDULED
GATEWAY --> SRM

图表来源

章节来源

核心组件

通用模块(nflg-wms-common)
- 职责：提供全局常量、异常体系、工具类与通用DTO/QO/VO模型，作为所有模块的公共依赖。
- 关键点：包含统一的常量定义、Hutool工具、Jackson、OkHttp、MongoDB支持、Sa-Token集成等。
基础模块(nflg-wms-starter)
- 职责：封装基础控制器基类、统一异常处理、注解、过滤器与配置，为业务服务提供统一入口与横切能力。
- 关键点：继承自BaseController，提供二维码内容生成等通用逻辑；集成Sa-Token、Redis、Nacos、OSS/S3等。
数据访问模块(nflg-wms-repository)
- 职责：封装数据库访问，基于MyBatis-Plus与PostgreSQL，提供Mapper与实体映射。
- 关键点：引入Redisson、Spring Retry等增强能力，支持分布式锁与重试策略。
业务服务模块
- 管理后台(nflg-wms-admin)：集中式管理界面，集成LDAP、邮件、PDF、MongoDB、EasyExcel、PowerJob等。
- 认证(nflg-wms-auth)：统一认证中心，基于SSO与LDAP。
- 发货(nflg-wms-shipment)：发货相关流程与报表生成。
- 定时任务(nflg-wms-scheduled)：计划任务执行器，集成PowerJob与SAP JCo。
- SRM集成(nflg-wms-srm-receive)：接收SRM订单并对接SAP。
- 网关(nflg-wms-gateway)：路由与安全控制，结合Nacos与Sa-Token。

章节来源

架构总览

系统采用微服务分层架构：通用层提供公共能力，基础设施层提供横切与通用Web能力，业务服务层承载具体业务，网关层统一入口与安全控制。模块间通过Spring Cloud Alibaba生态(Nacos注册发现、配置)与Sa-Token进行统一鉴权与SSO集成。

graph TB
CLIENT["客户端/前端"] --> GW["网关(nflg-wms-gateway)"]
GW --> AUTH["认证(nflg-wms-auth)"]
GW --> ADMIN["管理后台(nflg-wms-admin)"]
GW --> SHIP["发货(nflg-wms-shipment)"]
GW --> SCH["定时任务(nflg-wms-scheduled)"]
GW --> SRM["SRM接收(nflg-wms-srm-receive)"]
subgraph "共享能力"
COMMON["通用(nflg-wms-common)"]
STARTER["基础(nflg-wms-starter)"]
REPO["数据访问(nflg-wms-repository)"]
end
ADMIN --> STARTER
ADMIN --> REPO
AUTH --> STARTER
AUTH --> REPO
SHIP --> STARTER
SHIP --> REPO
SCH --> STARTER
SCH --> REPO
SRM --> STARTER
SRM --> REPO
COMMON --> STARTER
COMMON --> REPO

图表来源

详细组件分析

通用模块(nflg-wms-common)

功能职责
- 提供全局常量(如语言代码、追踪ID头、字典项、角色与类型等)。
- 统一封装异常类型与通用工具类，降低重复代码。
- 提供大量DTO/QO/VO模型，支撑上层业务。
技术实现
- 依赖Hutool、Jackson、OkHttp、Sa-Token、MyBatis-Plus、MongoDB等。
- 通过Maven坐标在其他模块中被直接依赖。
使用场景
- 所有业务服务与基础设施模块均会复用该模块中的常量与工具。
配置与最佳实践
- 常量集中管理，避免散落定义；新增常量需同步更新文档。
- 工具类尽量无副作用，避免跨模块耦合。

章节来源

基础模块(nflg-wms-starter)

功能职责
- 提供基础控制器基类(BaseController)，封装通用二维码内容生成等逻辑。
- 提供统一异常处理、注解、过滤器与配置，减少重复开发。
技术实现
- 集成Sa-Token、Redis、Nacos、OSS/S3等；面向Web开发提供开箱即用能力。
使用场景
- 各业务服务控制器继承BaseController，统一处理通用逻辑。
配置与最佳实践
- 控制器层只做参数校验与调用服务层，不直接操作数据层。
- 异常处理统一收敛，便于日志与监控。

章节来源

数据访问模块(nflg-wms-repository)

功能职责
- 封装数据库访问，基于MyBatis-Plus与PostgreSQL，提供Mapper与实体映射。
技术实现
- 引入Redisson、Spring Retry，支持分布式锁与重试策略。
使用场景
- 业务服务通过Repository层进行数据持久化与查询。
配置与最佳实践
- Mapper命名规范与SQL复杂度控制；合理使用分页与索引。
- 对高并发写入场景启用重试与幂等设计。

章节来源

nflg-wms-repository/pom.xml:14-63

管理后台模块(nflg-wms-admin)

功能职责
- 集中式管理界面，集成LDAP、邮件、PDF、MongoDB、EasyExcel、PowerJob等。
技术实现
- 启用调度与重试；集成Actuator、Loki日志、Redisson等。
- 应用入口扫描多个包路径，确保组件被正确注册。
使用场景
- 企业内部管理后台，支持多环境配置与打包。
配置与最佳实践
- 多环境配置文件分离；生产环境开启Actuator与可观测性。
- PDF生成与Excel导入导出需关注内存与超时控制。

章节来源

认证模块(nflg-wms-auth)

功能职责
- 统一认证中心，支持SSO与LDAP。
技术实现
- 基于Sa-Token与Redis；集成Actuator与Redisson。
- 应用入口启用注册发现。
使用场景
- 作为单点登录与权限控制中心，为其他服务提供鉴权。
配置与最佳实践
- SSO配置需与业务服务保持一致；Redis缓存与JWT结合使用。

章节来源

网关模块(nflg-wms-gateway)

功能职责
- 统一路由与安全控制，结合Nacos与Sa-Token。
技术实现
- 基于Spring Cloud Gateway与负载均衡；集成Sa-Token与Redisson。
使用场景
- 统一入口，屏蔽后端服务差异，提供鉴权与限流能力。
配置与最佳实践
- 路由规则与断言需结合业务域名与路径；安全策略集中管理。

章节来源

定时任务模块(nflg-wms-scheduled)

功能职责
- 计划任务执行器，集成PowerJob与SAP JCo。
技术实现
- 以非Web方式启动，专注任务执行；集成Actuator与Redisson。
使用场景
- 与SAP或外部系统对账、数据同步等周期性任务。
配置与最佳实践
- 任务幂等与失败重试策略；监控任务执行状态。

章节来源

发货模块(nflg-wms-shipment)

功能职责
- 发货相关流程与报表生成，集成二维码、PDF、邮件等。
技术实现
- 启用调度与重试；集成Actuator、Loki日志、Redisson等。
使用场景
- 支持发货单据打印、包裹管理与物流对接。
配置与最佳实践
- PDF生成与二维码渲染需关注性能与资源占用。

章节来源

SRM集成模块(nflg-wms-srm-receive)

功能职责
- 接收SRM订单并对接SAP，完成入库与质检流程。
技术实现
- 集成SAP JCo与Redisson；支持Actuator与日志采集。
使用场景
- 供应链协同，自动接收SRM订单并触发WMS流程。
配置与最佳实践
- SAP连接参数与凭证需严格保密；网络与超时策略需优化。

章节来源

依赖分析

模块依赖关系
- common为所有模块的公共依赖。
- starter依赖common与repository，向上为业务服务提供基础能力。
- admin/auth/shipment/scheduled/srm-receive均依赖starter与repository。
- gateway依赖common与repository，作为统一入口。
外部依赖
- Sa-Token用于统一认证与SSO。
- Nacos用于注册发现与配置中心。
- Redisson用于分布式锁与Redis集成。
- MyBatis-Plus与PostgreSQL用于数据持久化。
- PowerJob用于计划任务执行。
- SAP JCo用于与SAP系统集成。

graph LR
COMMON["common"] --> STARTER["starter"]
COMMON --> REPO["repository"]
STARTER --> ADMIN["admin"]
STARTER --> AUTH["auth"]
STARTER --> SHIP["shipment"]
STARTER --> SCH["scheduled"]
STARTER --> SRM["srm-receive"]
REPO --> ADMIN
REPO --> AUTH
REPO --> SHIP
REPO --> SCH
REPO --> SRM
GATEWAY["gateway"] --> ADMIN
GATEWAY --> AUTH
GATEWAY --> SHIP
GATEWAY --> SCH
GATEWAY --> SRM

图表来源

章节来源

性能考虑

缓存与锁
- 使用Redisson进行分布式锁与缓存，避免热点竞争。
数据库
- MyBatis-Plus分页与索引优化，批量操作与连接池配置。
网关与路由
- 合理设置路由断言与过滤器链，避免不必要的序列化与转换。
日志与可观测性
- Loki日志采集与Micrometer+OTLP链路追踪，定位性能瓶颈。
文件与报表
- PDF与Excel生成需控制并发与内存占用，必要时异步处理。

故障排查指南

认证与SSO
- 检查Sa-Token配置与Redis连通性；确认SSO模式与客户端配置一致。
注册发现
- 确认Nacos地址与服务名；检查健康检查与实例列表。
数据库
- 查看慢查询与连接池状态；核对Mapper SQL与索引。
网关
- 检查路由规则与过滤器顺序；验证鉴权中间件是否生效。
定时任务
- 核查任务幂等与重试策略；查看任务执行日志。
文件与报表
- PDF渲染失败时检查字体与页面大小；Excel导入导出检查格式与编码。

结论

本系统通过“通用-基础-数据访问-业务服务-网关”的分层设计，实现了高内聚、低耦合的微服务体系。通用模块提供统一能力，基础模块抽象横切逻辑，业务服务按领域拆分，网关统一入口与安全控制。配合Sa-Token、Nacos、Redisson、MyBatis-Plus、PowerJob等技术栈，满足了WMS在认证、路由、数据持久化、任务调度与SRM集成等方面的复杂需求。建议在后续迭代中持续完善可观测性、安全加固与性能优化。

附录

配置要点
- 多环境配置文件分离；敏感信息通过密文或环境变量注入。
- Actuator与日志采集开启，便于问题定位。
使用示例
- 控制器继承BaseController，统一处理二维码生成与参数校验。
- 服务层通过Repository进行数据访问，保证事务与幂等。
最佳实践
- 保持模块职责单一；避免循环依赖；统一异常与日志规范。
- 对外接口版本化，保证兼容性；对内接口契约化，提升可测试性。

20 KiB Raw Blame History Unescape Escape

核心模块

目录

简介

项目结构

核心组件

架构总览

详细组件分析

通用模块(nflg-wms-common)

基础模块(nflg-wms-starter)

数据访问模块(nflg-wms-repository)

管理后台模块(nflg-wms-admin)

认证模块(nflg-wms-auth)

网关模块(nflg-wms-gateway)

定时任务模块(nflg-wms-scheduled)

发货模块(nflg-wms-shipment)

SRM集成模块(nflg-wms-srm-receive)

依赖分析

性能考虑

故障排查指南

结论

附录

20 KiB

Raw Blame History