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

# nflg-wms-shipment - 发货服务

## 模块职责

发货管理服务，独立于 WMS 管理后台运行，专注于：
- 发运单管理
- 物料码管理（创建/查询/二维码生成/导入导出）
- 包装码管理
- 箱单管理
- 现场库存管理
- CRM 系统对接（发货信息推送）
- H5 移动端发货接口
- PDF 发运单据生成

## 入口与启动

| 项 | 值 |
|----|-----|
| 入口类 | `com.nflg.wms.shipment.ShipmentApplication` |
| 端口 | 8103 |
| 服务名 | shipment-local |

## 关键依赖

- nflg-wms-common
- nflg-wms-starter
- Spring Boot Web / AOP / Validation / Thymeleaf
- ZXing (二维码生成)
- EasyExcel (Excel 导入导出)
- iText7 / Flying Saucer PDF (PDF 生成)
- PowerJob Client (任务调度)
- Redisson (分布式锁)
- OpenTelemetry (链路追踪)
- Hypersistence TSID (ID 生成)

## 对外接口 (Controller)

| Controller | 说明 |
|-----------|------|
| `DeliveryController` | 发运单管理（创建/查询/修改/删除/发运） |
| `MaterialController` | 发货物料管理 |
| `MaterialCodeController` | 物料码管理（创建/查询/二维码/导入/导出/转发） |
| `PackagingCodeController` | 包装码管理 |
| `BoxListController` | 箱单管理（打印/导出/PDF 生成） |
| `SiteStockController` | 现场库存管理 |
| `H5Controller` | H5 移动端发货接口 |

## 关键业务 Service

| Service | 说明 |
|---------|------|
| `ShipmentMaterialControllerService` | 发货物料业务逻辑 |
| `CRMService` | CRM 系统对接服务（Token 获取/发货推送） |
| `BasdeSerialNumberControllerService` | 流水号生成 |

## 关键工具类

| 类 | 说明 |
|----|------|
| `QRCodeUtil` | 二维码生成工具 |
| `PdfGeneratorUtil` | PDF 生成工具 |
| `HtmlToImageUtil` | HTML 转图片工具 |
| `ThymeleafUtil` | Thymeleaf 模板渲染工具 |
| `PathUtils` | 路径工具 |
| `KeyUtil` | 键值生成工具 |

## 配置

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

## 测试

- `DeployDevTest.java` - 开发环境部署测试
- `DeploySitTest.java` - SIT 环境部署测试
- `MaterialImageUploadTest.java` - 物料图片上传测试

## 相关文件清单

- `src/main/java/com/nflg/wms/shipment/controller/` - 7 个 Controller
- `src/main/java/com/nflg/wms/shipment/service/` - 3 个 Service
- `src/main/java/com/nflg/wms/shipment/util/` - 5 个工具类
- `src/main/java/com/nflg/wms/shipment/pojo/` - DTO/QO/VO
- `src/main/java/com/nflg/wms/shipment/config/` - Thymeleaf/PowerJob 配置
- `src/main/resources/` - 配置文件
- `pom.xml` - 模块依赖定义

## 变更记录 (Changelog)

| 时间 | 操作 | 说明 |
|------|------|------|
| 2026-05-23 14:16:58 | 初始化 | 首次生成模块文档 |