28 KiB

Raw Blame History

外部系统集成

**本文引用的文件** - [application.yml](file://nflg-wms-admin/src/main/resources/application.yml) - [application-dev.yml](file://nflg-wms-admin/src/main/resources/application-dev.yml) - [application-prod.yml](file://nflg-wms-admin/src/main/resources/application-prod.yml) - [SAPConfig.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java) - [SAPConfig.java](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java) - [SAPException.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/SAPException.java) - [EmailService.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java) - [EmailConfigDTO.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/pojo/dto/EmailConfigDTO.java) - [LdapConfig.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java) - [LdapUserDTO.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/LdapUserDTO.java) - [LDAPSyncProcessor.java](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/LDAPSyncProcessor.java) - [AliyunOSSConfig.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java) - [OSSFileUploadServiceImpl.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/OSSFileUploadServiceImpl.java) - [RustFSConfig.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java) - [RustFSServiceImpl.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/RustFSServiceImpl.java) - [SRMQualityInspectionResultDTO.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMQualityInspectionResultDTO.java) - [SRMOrderReceiveDTO.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMOrderReceiveDTO.java) - [Constant.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java)

简介

本文件面向NFLG WMS系统与外部系统集成的综合文档，覆盖以下方面：

SAP系统集成：RFC调用配置、连接池与仓库缓存、异常处理策略
SRM系统对接：采购订单接收、质量检验结果数据交换
LDAP集成：用户认证、权限同步、组织架构管理
文件存储集成：OSS、RustFS（兼容S3）等对象存储配置与使用
邮件服务集成：通知发送、报告生成的自动化能力
配置参数、接口规范与数据格式说明
常见问题与解决方案
系统管理员部署与监控指南

项目结构

围绕外部系统集成的关键模块与文件分布如下：

配置与启动
- 应用配置：application.yml、application-dev.yml、application-prod.yml
SAP集成
- 配置类：nflg-wms-admin与nflg-wms-srm-receive下的SAPConfig
- 异常定义：SAPException
SRM对接
- DTO模型：SRMOrderReceiveDTO、SRMQualityInspectionResultDTO
LDAP集成
- 配置类：LdapConfig
- 同步处理器：LDAPSyncProcessor
- DTO模型：LdapUserDTO
文件存储
- OSS配置与上传：AliyunOSSConfig、OSSFileUploadServiceImpl
- RustFS配置与上传：RustFSConfig、RustFSServiceImpl
邮件服务
- 邮件发送：EmailService
- 配置模型：EmailConfigDTO
通用常量
- 字典项与常量：Constant

graph TB
subgraph "应用配置"
A1["application.yml"]
A2["application-dev.yml"]
A3["application-prod.yml"]
end
subgraph "SAP集成"
S1["admin/SAPConfig.java"]
S2["srm-receive/SAPConfig.java"]
S3["SAPException.java"]
end
subgraph "SRM对接"
R1["SRMOrderReceiveDTO.java"]
R2["SRMQualityInspectionResultDTO.java"]
end
subgraph "LDAP集成"
L1["LdapConfig.java"]
L2["LDAPSyncProcessor.java"]
L3["LdapUserDTO.java"]
end
subgraph "文件存储"
F1["AliyunOSSConfig.java"]
F2["OSSFileUploadServiceImpl.java"]
F3["RustFSConfig.java"]
F4["RustFSServiceImpl.java"]
end
subgraph "邮件服务"
E1["EmailService.java"]
E2["EmailConfigDTO.java"]
end
subgraph "通用"
U1["Constant.java"]
end
A1 --> S1
A1 --> S2
A1 --> L1
A1 --> F1
A1 --> F3
A1 --> E1
S1 --> S3
S2 --> S3
L2 --> L1
L2 --> L3
F2 --> F1
F4 --> F3
E1 --> E2
A1 --> U1

图表来源

章节来源

核心组件

SAP RFC集成
- 通过自定义DestinationDataProvider注册JCo目的地，支持连接池容量与峰值校验，提供JCoRepository以供RFC调用
- 异常封装为SAPException，便于统一处理
SRM对接
- 使用SRMOrderReceiveDTO与SRMQualityInspectionResultDTO承载采购订单接收与质量检验结果的数据结构
LDAP集成
- LdapConfig提供上下文源配置；LDAPSyncProcessor负责周期性拉取组织树与用户信息并落库
文件存储
- OSS与RustFS（兼容S3）双实现，基于条件注解按配置选择具体实现
邮件服务
- EmailService读取参数配置表，构建SMTP会话并发送HTML邮件

章节来源

架构总览

下图展示WMS与外部系统的主要交互路径：SAP（RFC）、SRM（订单/质检数据）、LDAP（目录服务）、文件存储（OSS/RustFS）、邮件服务。

graph TB
WMS["WMS应用"]
SAP["SAP系统"]
SRM["SRM系统"]
LDAP["LDAP目录服务"]
OSS["阿里云OSS"]
RFS["RustFS(S3兼容)"]
MAIL["邮件服务"]
WMS --> |RFC调用| SAP
WMS --> |订单/质检| SRM
WMS --> |组织/用户| LDAP
WMS --> |文件上传| OSS
WMS --> |文件上传| RFS
WMS --> |通知/报告| MAIL

图表来源

详细组件分析

SAP系统集成方案

配置要点
- 通过Environment注册DestinationDataProvider，避免文件IO，直接在内存中提供JCo属性
- 属性包括：主机、系统号、客户端、用户名、密码、语言、连接池容量、峰值限制
- 初始化时进行峰值与池容量的数值校验，确保峰值不小于池容量
- 提供JCoDestination与JCoRepository Bean，供后续RFC调用使用
错误处理
- 初始化失败抛出IllegalStateException
- 业务异常封装为SAPException，便于上层捕获与统一处理
数据同步机制
- 通过JCoRepository加载RFC函数元数据，结合JCoDestination执行RFC调用
- 建议在调用层对RFC执行进行重试与超时控制，避免阻塞线程池

classDiagram
class SAPConfig {
+initDestination()
+jcoDestination()
+getJCoRepository()
-validatePoolConfig()
-buildConnectionProperties()
}
class SimpleDestinationDataProvider {
+getDestinationProperties()
+supportsEvents()
}
class SAPException {
+state
+msg
}
SAPConfig --> SimpleDestinationDataProvider : "注册目的地"
SAPConfig --> SAPException : "异常封装"

图表来源

章节来源

SRM系统对接功能

采购订单处理
- 使用SRMOrderReceiveDTO承载订单头与明细集合，字段包含公司、工厂、采购组、发货时间、运单号、供应商信息等
- 建议在接收后进行幂等校验（如订单号唯一性）与基础字段校验
质量检验数据交换
- 使用SRMQualityInspectionResultDTO承载检验单号、工厂、送货数量、检验结果、物料号、供应商代码、检验类型、行号、检验数量、物料描述、单位、收货库存地、不合格原因、采购订单号、物料凭证等
- 建议在入库或质检流程中，依据检验结果与不合格原因进行后续处置（如拒收、挑选、让步接收）

classDiagram
class SRMOrderReceiveDTO {
+noteNum
+ouCode
+iuCode
+purchaseGroup
+deliveryNoteDate
+waybillNum
+supplierNum
+supplierName
+ResultSet
}
class SRMQualityInspectionResultDTO {
+inspectionNum
+factory
+deliveryQty
+inspectionResult
+itemCode
+supplierNum
+inspectionType
+poLineNumber
+inspectionQty
+itemName
+unit
+receivedWarehouse
+unqualifiedReason
+poNum
+materialDocument
}

图表来源

章节来源

LDAP集成方案

用户认证与目录访问
- LdapConfig提供LdapContextSource，设置URL、Base DN、用户DN与密码，并开启二进制属性支持
组织架构与用户同步
- LDAPSyncProcessor周期性拉取组织树与用户列表，根据配置决定映射策略（全量或增量）
- 将LDAP用户与部门信息写入本地数据库，建立来源标识与映射关系
权限与角色
- 可结合用户与部门来源ID在权限体系中进行授权映射（需配合权限模块）

sequenceDiagram
participant Sch as "调度器"
participant Proc as "LDAPSyncProcessor"
participant Ldap as "LDAP服务"
participant Dept as "部门服务"
participant User as "用户服务"
Sch->>Proc : 触发同步任务
Proc->>Ldap : 获取组织树/用户列表
Ldap-->>Proc : 返回组织与用户数据
Proc->>Dept : 保存/更新部门
Proc->>User : 保存/更新用户
Proc-->>Sch : 同步完成

图表来源

章节来源

文件存储集成

OSS（阿里云）
- AliyunOSSConfig按配置构建OSSClient，设置连接/读取超时与区域
- OSSFileUploadServiceImpl基于PutObjectRequest上传文件，返回访问域名+路径
RustFS（S3兼容）
- RustFSConfig基于S3Client，支持endpoint override与path-style访问
- RustFSServiceImpl上传文件并返回访问地址
配置选择
- 通过file.upload.type切换实现（oss/rustfs），确保仅启用一种实现

flowchart TD
Start(["开始"]) --> Choose["读取file.upload.type"]
Choose --> |oss| OSS["AliyunOSSConfig构建OSSClient"]
Choose --> |rustfs| S3["RustFSConfig构建S3Client"]
OSS --> UploadOSS["OSSFileUploadServiceImpl上传"]
S3 --> UploadS3["RustFSServiceImpl上传"]
UploadOSS --> Done(["结束"])
UploadS3 --> Done

图表来源

章节来源

邮件服务集成

参数配置
- 从参数配置表读取EmailSet分组的host/port/username/password
发送流程
- 构建SMTP属性（SSL、超时），使用Authenticator认证
- 创建MimeMessage并发送HTML内容
通知与报告
- 可用于密码重置通知、业务事件提醒、报告生成后的通知等场景

sequenceDiagram
participant Caller as "调用方"
participant Mail as "EmailService"
participant Store as "参数配置存储"
participant SMTP as "SMTP服务器"
Caller->>Mail : 发送邮件(收件人, 主题, HTML内容)
Mail->>Store : 查询EmailSet配置
Store-->>Mail : 返回host/port/username/password
Mail->>SMTP : 建立会话并发送
SMTP-->>Mail : 发送成功
Mail-->>Caller : 返回结果

图表来源

章节来源

依赖分析

组件耦合
- SAPConfig在admin与srm-receive模块重复出现，职责一致，建议抽取公共模块或共享配置
- LDAPSyncProcessor依赖LdapConfig与多个业务服务（部门/用户/内部用户），关注跨模块调用边界
- 文件存储实现通过条件注解隔离，避免多实现冲突
外部依赖
- SAP JCo、Spring LDAP、JavaMail、OSS SDK、AWS S3 SDK
循环依赖
- 当前未发现明显循环依赖；注意在新增服务时避免互相注入

graph LR
AdminSAP["admin/SAPConfig"] --> CommonSAPEx["SAPException"]
SRMSAP["srm-receive/SAPConfig"] --> CommonSAPEx
LDAPProc["LDAPSyncProcessor"] --> LdapCfg["LdapConfig"]
OSSUp["OSSFileUploadServiceImpl"] --> OSSCfg["AliyunOSSConfig"]
S3Up["RustFSServiceImpl"] --> S3Cfg["RustFSConfig"]
Mail["EmailService"] --> MailDTO["EmailConfigDTO"]

图表来源

章节来源

性能考虑

SAP连接池
- 确保峰值与池容量合理配置，避免频繁创建销毁连接
- 对RFC调用增加超时与重试策略，防止阻塞线程池
LDAP同步
- 控制同步频率与批量大小，避免对LDAP服务器造成压力
- 对大部门树采用分页/分批处理
文件存储
- OSS/RustFS上传设置合理的超时与断点续传策略（如需要）
- 控制并发度，避免带宽与连接数瓶颈
邮件服务
- SMTP连接复用，避免频繁建立/关闭会话
- 批量发送时注意队列与速率限制

故障排查指南

SAP初始化失败
- 检查连接池配置是否为数字且峰值不小于池容量
- 核对主机、系统号、客户端、用户名、密码、语言等属性是否正确
RFC调用异常
- 捕获SAPException，查看状态码与消息，结合SAP日志定位问题
LDAP同步失败
- 检查LdapConfig的URL、Base DN、用户DN与密码
- 确认LDAP服务器可达与网络策略放行
文件上传失败
- OSS：检查endpoint、region、access key与bucket权限
- RustFS：确认endpoint、access-key/secret-key与path-style配置
邮件发送失败
- 核对参数配置表中EmailSet的host/port/username/password
- 检查SMTP SSL与超时设置

章节来源

结论

本集成方案以模块化方式实现了与SAP、SRM、LDAP、文件存储与邮件服务的对接。通过集中配置与条件装配，系统具备良好的可扩展性与可维护性。建议在生产环境中完善监控与告警，持续优化连接池与同步策略，确保高可用与高性能。

附录

配置参数清单

SAP（admin/srm-receive）
- custom.sap.host
- custom.sap.sysnr
- custom.sap.client
- custom.sap.username
- custom.sap.password
- custom.sap.lang
- custom.sap.pool
- custom.sap.peak
邮件（EmailService）
- 参数配置表分组：EmailSet
- 字段：host、port、username、password
LDAP（LdapConfig）
- spring.ldap.urls[0]
- spring.ldap.base
- spring.ldap.username
- spring.ldap.password
文件存储（OSS）
- file.upload.type=oss
- aliyun.oss.endpoint
- aliyun.oss.region
- aliyun.oss.accessKeyId
- aliyun.oss.accessKeySecret
- aliyun.oss.bucketName
- aliyun.oss.domain
文件存储（RustFS）
- file.upload.type=rustfs
- rustfs.endpoint
- rustfs.access-key
- rustfs.secret-key
- rustfs.bucket-name
- rustfs.domain

章节来源

接口规范与数据格式

SRM订单接收
- 头字段：送货单号、公司、工厂、采购组、发货时间、运单号、供应商编号、供应商名称
- 明细字段：ResultSet（由SRMOrderReceiveItemQO定义）
SRM质量检验结果
- 字段：检验单号、工厂、送货数量、检验结果、物料号、供应商代码、检验类型、行号、检验数量、物料描述、单位、收货库存地、不合格原因、采购订单号、物料凭证

章节来源

部署与监控指南

部署
- 使用Nacos作为配置中心，按环境激活对应配置组
- 启动时加载application.yml，按profiles.active选择配置
监控
- 开启Actuator端点与健康检查
- 配置OTLP链路追踪与Loki日志推送
- 关注SAP连接池、LDAP查询延迟、文件上传耗时与邮件发送成功率

章节来源

28 KiB Raw Blame History Unescape Escape

外部系统集成

目录

简介

项目结构

核心组件

架构总览

详细组件分析

SAP系统集成方案

SRM系统对接功能

LDAP集成方案

文件存储集成

邮件服务集成

依赖分析

性能考虑

故障排查指南

结论

附录

配置参数清单

接口规范与数据格式

部署与监控指南

28 KiB

Raw Blame History