[根目录](../CLAUDE.md) > **nflg-wms-admin**

# nflg-wms-admin - WMS 管理后台服务

## 模块职责

WMS 核心管理后台，是系统中最大的业务服务，覆盖：
- 系统管理（用户/角色/菜单/权限/部门/岗位/字典/参数配置）
- 入库管理（PO 收货/质检收货/生产退货/成本中心退货/生产订单入库/剩余入库）
- 出库管理（生产领料/成本中心出库/外协出库/采购退货）
- 库存管理（库存查询/盘点/条码打印/库位转移）
- 物料管理（物料/BOM/型号/仓库/库位）
- 数据权限管理
- SAP 集成（过账/库存同步）
- LDAP 域同步
- 文件管理（上传/下载）
- 多语言管理
- 工装台账
- 工具物料
- 钢构包管理
- 零部件包装/出库
- 发货通知单 (NormalPGI)
- 普通单据/质检
- 采购退货
- 公司间/工厂间调拨
- 使用指南
- 工作台
- 扫码记录
- 操作记录

## 入口与启动

| 项 | 值 |
|----|-----|
| 入口类 | `com.nflg.wms.admin.AdminApplication` |
| 端口 | 8102 |
| 服务名 | admin-local |

## 关键依赖

- nflg-wms-common
- nflg-wms-starter
- Spring Boot Web / AOP / Validation / Mail / Thymeleaf / LDAP / MongoDB
- SAP JCo3 (ERP 集成)
- ZXing (二维码)
- EasyExcel (Excel 处理)
- iText7 / Flying Saucer PDF (PDF 生成)
- PowerJob Client (任务调度)
- Redisson (分布式锁)
- OpenTelemetry (链路追踪)
- Spring Retry (重试)
- Hypersistence TSID (ID 生成)

## 对外接口 (Controller) -- 53 个

| Controller | 路由前缀 | 说明 |
|-----------|---------|------|
| `UserController` | `/user` | 用户管理 |
| `RoleController` | `/role` | 角色管理 |
| `MenuController` | `/menu` | 菜单管理 |
| `DepartmentController` | `/department` | 部门管理 |
| `PositionController` | `/position` | 岗位管理 |
| `DictionaryController` | `/dictionary` | 字典管理 |
| `ParamConfigController` | `/paramconfig` | 参数配置 |
| `DataPermissionController` | `/permissionRole` | 数据权限管理 |
| `POReceiptController` | `/po` | PO 收货 |
| `QCReceiptController` | `/qc` | 质检收货 |
| `InProduceBackController` | `/in/produce/back` | 生产退货入库 |
| `InCostCenterBackController` | `/in/costcenter` | 成本中心退货入库 |
| `InProduceOrderController` | `/in/produce` | 生产订单入库 |
| `InProduceOrderSurplusController` | `/in/produce/surplus` | 生产剩余入库 |
| `OutProduceController` | `/out/produce` | 生产领料出库 |
| `OutCostCenterController` | `/out/costcenter` | 成本中心出库 |
| `OutAssistanceController` | `/out/assistance` | 外协出库 |
| `OutPurchaseController` | `/out/purchase` | 采购退货出库 |
| `InventoryController` | `/inventory` | 库存管理 |
| `LocationTransferController` | `/localtiontransfer` | 库位转移 |
| `StorageController` | `/storage` | 仓库管理 |
| `WarehouseController` | `/warehouse` | 仓库配置 |
| `BinController` | `/bin` | 库位管理 |
| `MaterialController` | `/material` | 物料管理 |
| `BomController` | `/bom` | BOM 管理 |
| `ModelController` | `/model` | 型号管理 |
| `QrCodeMasterController` | `/qrcodemaster` | 二维码主数据 |
| `BarcodePrintingController` | `/barcode` | 条码打印 |
| `NormalOrderController` | `/deliver/order/normal` | 普通单据 |
| `NormalQMController` | `/qm/normal` | 普通质检 |
| `NormalPGIController` | `/pgi/normal` | 发货通知单 |
| `PackingController` | `/packing` | 包装管理 |
| `PurchaseReturnController` | `/purchaseReturn` | 采购退货 |
| `TransferCompanyController` | `/transfer/company` | 公司间调拨 |
| `TransferFactoryController` | `/transfer/factory` | 工厂间调拨 |
| `ComponentPackingController` | `/component/packing` | 零部件包装 |
| `ComponentOutboundController` | `/component/outbound` | 零部件出库 |
| `StructuralPackageController` | `/package` | 钢构包管理 |
| `StructuralPackageOrderController` | `/deliver/order/package` | 钢构包订单 |
| `GongZhuangTaiZhangController` | `/gongzhuang/taizhang` | 工装台账 |
| `ToolMaterialController` | `/tool/material` | 工具物料 |
| `FileController` | `/file` | 文件管理 |
| `MultilingualController` | `/multilingual` | 多语言管理 |
| `LDAPController` | `/ldap` | LDAP 同步 |
| `FormController` | `/form` | 表单管理 |
| `UsageGuideController` | `/usageguide` | 使用指南 |
| `WorkbenchController` | `/workbench` | 工作台 |
| `ScanRecordController` | `/scan/record` | 扫码记录 |
| `OptRecordController` | `/operation/record` | 操作记录 |
| `SupplierController` | `/supplier` | 供应商管理 |
| `SsoClientController` | `/sso` | SSO 客户端 |
| `BaseController` | (无路由前缀) | 基础接口 |
| `TestController` | `/test` | 测试接口 |

## 关键业务 Service (28 个)

| Service | 说明 |
|---------|------|
| `SapService` | SAP RFC 集成服务 |
| `SAPCommonService` | SAP 公共方法 |
| `LdapService` / `LDAPControllerService` | LDAP 域集成 |
| `UserControllerService` | 用户业务逻辑 |
| `RoleControllerService` | 角色业务逻辑 |
| `MenuControllerService` | 菜单业务逻辑 |
| `DepartmentControllerService` | 部门业务逻辑 |
| `StorageControllerService` | 仓库业务逻辑 |
| `WarehouseControllerService` | 仓库配置逻辑 |
| `BinControllerService` / `BinService` | 库位业务逻辑 |
| `MaterialControllerService` | 物料业务逻辑 |
| `BomControllerService` | BOM 业务逻辑 |
| `DictionaryControllerService` | 字典业务逻辑 |
| `FileControllerService` | 文件上传逻辑 |
| `TableInfoService` | 表信息服务 |
| `NormalQMControllerService` | 质检逻辑 |
| `NormalPGIControllerService` | PGI 发货通知逻辑 |
| `ComponentOutboundControllerService` | 零部件出库逻辑 |
| `ComponentPackingControllerService` | 零部件包装逻辑 |
| `StructuralPackageControllerService` | 钢构包逻辑 |
| `WorkbenchControllerService` | 工作台逻辑 |
| `MultilingualControllerService` | 多语言逻辑 |
| `ModelControllerService` | 型号逻辑 |
| `PositionControllerService` | 岗位逻辑 |
| `ParamConfigControllerServive` | 参数配置逻辑（注意类名拼写：Servive） |
| `BasdeSerialNumberControllerService` | 流水号生成 |

## 其他重要类

| 路径 | 类 | 说明 |
|------|-----|------|
| `config/` | `SAPConfig` | SAP JCo 连接池配置 |
| `config/` | `LdapConfig` | LDAP 连接配置 |
| `config/` | `PowerJobClientConfig` | PowerJob 客户端配置 |
| `config/` | `ThymeleafConfig` | Thymeleaf 模板配置 |
| `runner/` | `RedisDataInitRunner` | 启动时初始化 Redis 缓存（钢构包单号/托盘号序号） |
| `schedule/` | `LdapScheduledTask` | LDAP 定时同步任务 |
| `repository/` | 7 个 MongoDB Repository | MongoDB 扫码记录数据访问（入库/出库/盘点/包装/SRM 收货等） |
| `util/` | `JCoUtil` | SAP JCo 工具类 |
| `util/` | `QRCodeUtil` | 二维码生成工具 |
| `util/` | `PdfGeneratorUtil` | PDF 生成工具 |
| `util/` | `HtmlToImageUtil` | HTML 转图片工具 |
| `util/` | `ThymeleafUtil` | Thymeleaf 模板渲染工具 |
| `util/` | `PathUtils` | 路径工具 |
| `util/` | `KeyUtil` | 键值生成工具 |
| `util/` | `NoUtil` | 编号工具 |

## 配置

- 文件上传上限：200MB
- 支持 dev / sit / prod 环境
- 集成 Actuator 健康检查 + OpenTelemetry 链路追踪

## 测试

- `ApiStorageTest.java` - API 存储测试
- `ATest.java` - 通用测试
- `DataTest.java` - 数据测试
- `DeployDevTest.java` - 开发环境部署测试
- `DeploySitTest.java` - SIT 环境部署测试
- `SapMetaPrintTest.java` - SAP 元数据打印测试

## 特殊说明

- 包含 `lib/sapjco3.jar` 本地依赖（SAP JCo 连接器）
- 使用 maven-shade-plugin 打包，将内部模块合并到最终 JAR
- 外部依赖复制到 `target/lib/` 目录

## 相关文件清单

- `src/main/java/com/nflg/wms/admin/controller/` - 53 个 Controller
- `src/main/java/com/nflg/wms/admin/service/` - 28 个 Service
- `src/main/java/com/nflg/wms/admin/repository/` - 7 个 MongoDB Repository
- `src/main/java/com/nflg/wms/admin/config/` - 4 个配置类
- `src/main/java/com/nflg/wms/admin/util/` - 8 个工具类
- `src/main/java/com/nflg/wms/admin/runner/` - 启动初始化
- `src/main/java/com/nflg/wms/admin/schedule/` - 定时任务
- `src/main/java/com/nflg/wms/admin/pojo/` - DTO/VO/Request
- `src/main/resources/` - 配置文件和模板
- `lib/` - 本地 JAR 依赖
- `pom.xml` - 模块依赖定义

## 变更记录 (Changelog)

| 时间 | 操作 | 说明 |
|------|------|------|
| 2026-05-23 14:28:57 | 更新 | 修正 Controller 数量 54->53（移除不存在的 AdvertisementController）；补充全部 REST 路由前缀；补充 MongoDB Repository/runner/schedule/util 目录；补充工具类清单 |
| 2026-05-23 14:16:58 | 初始化 | 首次生成模块文档 |