rakor
/
wms
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
wms/.qoder/repowiki/zh/content/外部系统集成/外部系统集成.md

552 lines
28 KiB
Markdown
Raw Normal View History

docs(api): 新增完整API接口文档 - 覆盖仓储管理、物料管理、订单处理等业务域接口设计与规范 - 介绍统一返回体、状态码体系、认证授权机制及错误处理策略 - 详细描述接口清单管理及二维码内容生成机制 - 提供架构总览、依赖分析和性能考虑建议 - 包含故障排查指南及Postman集合和curl示例说明 docs(biz): 新增业务功能文档详解 - 系统化梳理仓储、物料、订单、生产、采购销售和质量管理业务流程 - 按功能划分控制层模块，明确数据模型和持久化结构 - 详细描述核心业务组件及关键操作流程图和时序图 - 分析业务依赖与耦合点，强调事务一致性和并发锁机制 - 提供故障排查和性能优化建议，支持批量操作分批处理
2026-04-14 08:26:07 +08:00
# 外部系统集成
<cite>
**本文引用的文件**
- [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)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向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
```mermaid
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
```
图表来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [SAPConfig.java:1-120](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L1-L120)
- [SAPConfig.java:1-120](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java#L1-L120)
- [SAPException.java:1-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/SAPException.java#L1-L17)
- [SRMOrderReceiveDTO.java:1-54](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMOrderReceiveDTO.java#L1-L54)
- [SRMQualityInspectionResultDTO.java:1-82](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMQualityInspectionResultDTO.java#L1-L82)
- [LdapConfig.java:1-42](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L1-L42)
- [LDAPSyncProcessor.java:35-179](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/LDAPSyncProcessor.java#L35-L179)
- [LdapUserDTO.java:1-28](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/LdapUserDTO.java#L1-L28)
- [AliyunOSSConfig.java:1-56](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L1-L56)
- [OSSFileUploadServiceImpl.java:1-44](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/OSSFileUploadServiceImpl.java#L1-L44)
- [RustFSConfig.java:1-40](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L1-L40)
- [RustFSServiceImpl.java:1-38](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/RustFSServiceImpl.java#L1-L38)
- [EmailService.java:1-68](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L1-L68)
- [EmailConfigDTO.java:1-21](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/EmailConfigDTO.java#L1-L21)
- [Constant.java:1-43](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
章节来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application-dev.yml:1-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L1-L34)
- [application-prod.yml:1-30](file://nflg-wms-admin/src/main/resources/application-prod.yml#L1-L30)
## 核心组件
- SAP RFC集成
- 通过自定义DestinationDataProvider注册JCo目的地，支持连接池容量与峰值校验，提供JCoRepository以供RFC调用
- 异常封装为SAPException，便于统一处理
- SRM对接
- 使用SRMOrderReceiveDTO与SRMQualityInspectionResultDTO承载采购订单接收与质量检验结果的数据结构
- LDAP集成
- LdapConfig提供上下文源配置；LDAPSyncProcessor负责周期性拉取组织树与用户信息并落库
- 文件存储
- OSS与RustFS（兼容S3）双实现，基于条件注解按配置选择具体实现
- 邮件服务
- EmailService读取参数配置表，构建SMTP会话并发送HTML邮件
章节来源
- [SAPConfig.java:1-120](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L1-L120)
- [SAPConfig.java:1-120](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java#L1-L120)
- [SAPException.java:1-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/SAPException.java#L1-L17)
- [SRMOrderReceiveDTO.java:1-54](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMOrderReceiveDTO.java#L1-L54)
- [SRMQualityInspectionResultDTO.java:1-82](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMQualityInspectionResultDTO.java#L1-L82)
- [LdapConfig.java:1-42](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L1-L42)
- [LDAPSyncProcessor.java:35-179](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/LDAPSyncProcessor.java#L35-L179)
- [LdapUserDTO.java:1-28](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/LdapUserDTO.java#L1-L28)
- [AliyunOSSConfig.java:1-56](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L1-L56)
- [OSSFileUploadServiceImpl.java:1-44](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/OSSFileUploadServiceImpl.java#L1-L44)
- [RustFSConfig.java:1-40](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L1-L40)
- [RustFSServiceImpl.java:1-38](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/RustFSServiceImpl.java#L1-L38)
- [EmailService.java:1-68](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L1-L68)
- [EmailConfigDTO.java:1-21](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/EmailConfigDTO.java#L1-L21)
## 架构总览
下图展示WMS与外部系统的主要交互路径：SAP（RFC）、SRM（订单/质检数据）、LDAP（目录服务）、文件存储（OSS/RustFS）、邮件服务。
```mermaid
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
```
图表来源
- [SAPConfig.java:1-120](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L1-L120)
- [SAPConfig.java:1-120](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java#L1-L120)
- [SRMOrderReceiveDTO.java:1-54](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMOrderReceiveDTO.java#L1-L54)
- [SRMQualityInspectionResultDTO.java:1-82](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMQualityInspectionResultDTO.java#L1-L82)
- [LdapConfig.java:1-42](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L1-L42)
- [AliyunOSSConfig.java:1-56](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L1-L56)
- [RustFSConfig.java:1-40](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L1-L40)
- [EmailService.java:1-68](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L1-L68)
## 详细组件分析
### SAP系统集成方案
- 配置要点
- 通过Environment注册DestinationDataProvider，避免文件IO，直接在内存中提供JCo属性
- 属性包括：主机、系统号、客户端、用户名、密码、语言、连接池容量、峰值限制
- 初始化时进行峰值与池容量的数值校验，确保峰值不小于池容量
- 提供JCoDestination与JCoRepository Bean，供后续RFC调用使用
- 错误处理
- 初始化失败抛出IllegalStateException
- 业务异常封装为SAPException，便于上层捕获与统一处理
- 数据同步机制
- 通过JCoRepository加载RFC函数元数据，结合JCoDestination执行RFC调用
- 建议在调用层对RFC执行进行重试与超时控制，避免阻塞线程池
```mermaid
classDiagram
class SAPConfig {
+initDestination()
+jcoDestination()
+getJCoRepository()
-validatePoolConfig()
-buildConnectionProperties()
}
class SimpleDestinationDataProvider {
+getDestinationProperties()
+supportsEvents()
}
class SAPException {
+state
+msg
}
SAPConfig --> SimpleDestinationDataProvider : "注册目的地"
SAPConfig --> SAPException : "异常封装"
```
图表来源
- [SAPConfig.java:1-120](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L1-L120)
- [SAPConfig.java:1-120](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java#L1-L120)
- [SAPException.java:1-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/SAPException.java#L1-L17)
章节来源
- [SAPConfig.java:1-120](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L1-L120)
- [SAPConfig.java:1-120](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java#L1-L120)
- [SAPException.java:1-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/SAPException.java#L1-L17)
### SRM系统对接功能
- 采购订单处理
- 使用SRMOrderReceiveDTO承载订单头与明细集合，字段包含公司、工厂、采购组、发货时间、运单号、供应商信息等
- 建议在接收后进行幂等校验（如订单号唯一性）与基础字段校验
- 质量检验数据交换
- 使用SRMQualityInspectionResultDTO承载检验单号、工厂、送货数量、检验结果、物料号、供应商代码、检验类型、行号、检验数量、物料描述、单位、收货库存地、不合格原因、采购订单号、物料凭证等
- 建议在入库或质检流程中，依据检验结果与不合格原因进行后续处置（如拒收、挑选、让步接收）
```mermaid
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
}
```
图表来源
- [SRMOrderReceiveDTO.java:1-54](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMOrderReceiveDTO.java#L1-L54)
- [SRMQualityInspectionResultDTO.java:1-82](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMQualityInspectionResultDTO.java#L1-L82)
章节来源
- [SRMOrderReceiveDTO.java:1-54](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMOrderReceiveDTO.java#L1-L54)
- [SRMQualityInspectionResultDTO.java:1-82](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMQualityInspectionResultDTO.java#L1-L82)
### LDAP集成方案
- 用户认证与目录访问
- LdapConfig提供LdapContextSource，设置URL、Base DN、用户DN与密码，并开启二进制属性支持
- 组织架构与用户同步
- LDAPSyncProcessor周期性拉取组织树与用户列表，根据配置决定映射策略（全量或增量）
- 将LDAP用户与部门信息写入本地数据库，建立来源标识与映射关系
- 权限与角色
- 可结合用户与部门来源ID在权限体系中进行授权映射（需配合权限模块）
```mermaid
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 : 同步完成
```
图表来源
- [LDAPSyncProcessor.java:35-179](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/LDAPSyncProcessor.java#L35-L179)
- [LdapConfig.java:1-42](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L1-L42)
- [LdapUserDTO.java:1-28](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/LdapUserDTO.java#L1-L28)
章节来源
- [LdapConfig.java:1-42](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L1-L42)
- [LDAPSyncProcessor.java:35-179](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/LDAPSyncProcessor.java#L35-L179)
- [LdapUserDTO.java:1-28](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/LdapUserDTO.java#L1-L28)
### 文件存储集成
- OSS（阿里云）
- AliyunOSSConfig按配置构建OSSClient，设置连接/读取超时与区域
- OSSFileUploadServiceImpl基于PutObjectRequest上传文件，返回访问域名+路径
- RustFS（S3兼容）
- RustFSConfig基于S3Client，支持endpoint override与path-style访问
- RustFSServiceImpl上传文件并返回访问地址
- 配置选择
- 通过file.upload.type切换实现（oss/rustfs），确保仅启用一种实现
```mermaid
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
```
图表来源
- [AliyunOSSConfig.java:1-56](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L1-L56)
- [OSSFileUploadServiceImpl.java:1-44](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/OSSFileUploadServiceImpl.java#L1-L44)
- [RustFSConfig.java:1-40](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L1-L40)
- [RustFSServiceImpl.java:1-38](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/RustFSServiceImpl.java#L1-L38)
章节来源
- [AliyunOSSConfig.java:1-56](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L1-L56)
- [OSSFileUploadServiceImpl.java:1-44](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/OSSFileUploadServiceImpl.java#L1-L44)
- [RustFSConfig.java:1-40](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L1-L40)
- [RustFSServiceImpl.java:1-38](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/RustFSServiceImpl.java#L1-L38)
### 邮件服务集成
- 参数配置
- 从参数配置表读取EmailSet分组的host/port/username/password
- 发送流程
- 构建SMTP属性（SSL、超时），使用Authenticator认证
- 创建MimeMessage并发送HTML内容
- 通知与报告
- 可用于密码重置通知、业务事件提醒、报告生成后的通知等场景
```mermaid
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 : 返回结果
```
图表来源
- [EmailService.java:1-68](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L1-L68)
- [EmailConfigDTO.java:1-21](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/EmailConfigDTO.java#L1-L21)
- [Constant.java:1-43](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
章节来源
- [EmailService.java:1-68](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L1-L68)
- [EmailConfigDTO.java:1-21](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/EmailConfigDTO.java#L1-L21)
- [Constant.java:1-43](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
## 依赖分析
- 组件耦合
- SAPConfig在admin与srm-receive模块重复出现，职责一致，建议抽取公共模块或共享配置
- LDAPSyncProcessor依赖LdapConfig与多个业务服务（部门/用户/内部用户），关注跨模块调用边界
- 文件存储实现通过条件注解隔离，避免多实现冲突
- 外部依赖
- SAP JCo、Spring LDAP、JavaMail、OSS SDK、AWS S3 SDK
- 循环依赖
- 当前未发现明显循环依赖；注意在新增服务时避免互相注入
```mermaid
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"]
```
图表来源
- [SAPConfig.java:1-120](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L1-L120)
- [SAPConfig.java:1-120](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java#L1-L120)
- [SAPException.java:1-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/SAPException.java#L1-L17)
- [LDAPSyncProcessor.java:35-179](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/LDAPSyncProcessor.java#L35-L179)
- [LdapConfig.java:1-42](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L1-L42)
- [OSSFileUploadServiceImpl.java:1-44](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/OSSFileUploadServiceImpl.java#L1-L44)
- [AliyunOSSConfig.java:1-56](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L1-L56)
- [RustFSServiceImpl.java:1-38](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/RustFSServiceImpl.java#L1-L38)
- [RustFSConfig.java:1-40](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L1-L40)
- [EmailService.java:1-68](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L1-L68)
- [EmailConfigDTO.java:1-21](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/EmailConfigDTO.java#L1-L21)
章节来源
- [SAPConfig.java:1-120](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L1-L120)
- [SAPConfig.java:1-120](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java#L1-L120)
- [SAPException.java:1-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/SAPException.java#L1-L17)
- [LDAPSyncProcessor.java:35-179](file://nflg-wms-scheduled/src/main/java/com/nflg/wms/scheduled/processor/LDAPSyncProcessor.java#L35-L179)
- [LdapConfig.java:1-42](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L1-L42)
- [OSSFileUploadServiceImpl.java:1-44](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/OSSFileUploadServiceImpl.java#L1-L44)
- [AliyunOSSConfig.java:1-56](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L1-L56)
- [RustFSServiceImpl.java:1-38](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/RustFSServiceImpl.java#L1-L38)
- [RustFSConfig.java:1-40](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L1-L40)
- [EmailService.java:1-68](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L1-L68)
- [EmailConfigDTO.java:1-21](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/EmailConfigDTO.java#L1-L21)
## 性能考虑
- 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与超时设置
章节来源
- [SAPConfig.java:79-91](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L79-L91)
- [SAPException.java:1-17](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/SAPException.java#L1-L17)
- [LdapConfig.java:27-41](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L27-L41)
- [AliyunOSSConfig.java:34-47](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L34-L47)
- [RustFSConfig.java:30-39](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L30-L39)
- [EmailService.java:27-67](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L27-L67)
## 结论
本集成方案以模块化方式实现了与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
章节来源
- [SAPConfig.java:34-51](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/SAPConfig.java#L34-L51)
- [SAPConfig.java:34-51](file://nflg-wms-srm-receive/src/main/java/com/nflg/wms/srm/receive/config/SAPConfig.java#L34-L51)
- [EmailService.java:27-44](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/service/EmailService.java#L27-L44)
- [LdapConfig.java:15-25](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L15-L25)
- [AliyunOSSConfig.java:19-29](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/AliyunOSSConfig.java#L19-L29)
- [OSSFileUploadServiceImpl.java:26-30](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/OSSFileUploadServiceImpl.java#L26-L30)
- [RustFSConfig.java:21-28](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/config/RustFSConfig.java#L21-L28)
- [RustFSServiceImpl.java:25-29](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/service/impl/RustFSServiceImpl.java#L25-L29)
### 接口规范与数据格式
- SRM订单接收
- 头字段：送货单号、公司、工厂、采购组、发货时间、运单号、供应商编号、供应商名称
- 明细字段：ResultSet（由SRMOrderReceiveItemQO定义）
- SRM质量检验结果
- 字段：检验单号、工厂、送货数量、检验结果、物料号、供应商代码、检验类型、行号、检验数量、物料描述、单位、收货库存地、不合格原因、采购订单号、物料凭证
章节来源
- [SRMOrderReceiveDTO.java:10-53](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMOrderReceiveDTO.java#L10-L53)
- [SRMQualityInspectionResultDTO.java:8-82](file://nflg-wms-common/src/main/java/com/nflg/wms/common/vo/SRMQualityInspectionResultDTO.java#L8-L82)
### 部署与监控指南
- 部署
- 使用Nacos作为配置中心，按环境激活对应配置组
- 启动时加载application.yml，按profiles.active选择配置
- 监控
- 开启Actuator端点与健康检查
- 配置OTLP链路追踪与Loki日志推送
- 关注SAP连接池、LDAP查询延迟、文件上传耗时与邮件发送成功率
章节来源
- [application.yml:13-19](file://nflg-wms-admin/src/main/resources/application.yml#L13-L19)
- [application-dev.yml:21-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L21-L34)
- [application-prod.yml:27-30](file://nflg-wms-admin/src/main/resources/application-prod.yml#L27-L30)