513 lines
23 KiB
Markdown
513 lines
23 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
# NFLG-WMS 南方路机仓库管理系统
|
||
|
||
## 项目愿景
|
||
|
||
南方路机仓库管理系统 (NFLG WMS) 是一套面向制造业的仓库管理平台，涵盖入库、出库、库存盘点、质检、发货、SRM 对接、SAP 集成等完整仓储生命周期管理。系统采用 Spring Cloud 微服务架构，通过 API 网关统一对外提供服务。
|
||
|
||
## 技术栈
|
||
|
||
| 类别 | 技术 | 版本 |
|
||
|------|------|------|
|
||
| 语言 | Java | 17 |
|
||
| 框架 | Spring Boot | 3.2.4 |
|
||
| 微服务 | Spring Cloud | 2023.0.1 |
|
||
| 微服务 | Spring Cloud Alibaba | 2023.0.1.0 |
|
||
| 注册/配置中心 | Nacos | - |
|
||
| 网关 | Spring Cloud Gateway | - |
|
||
| ORM | MyBatis-Plus | 3.5.12 |
|
||
| 数据库 | PostgreSQL | 42.7.7 |
|
||
| 缓存 | Redis (Redisson) | 3.52.0 |
|
||
| 文档数据库 | MongoDB | - |
|
||
| 认证 | Sa-Token + JWT + SSO | 1.42.0 |
|
||
| 对象存储 | 阿里云 OSS / AWS S3 (RustFS) / MinIO | - |
|
||
| 定时任务 | PowerJob | 5.1.1 |
|
||
| 日志采集 | Loki (logback-appender) | 2.0.0 |
|
||
| 链路追踪 | OpenTelemetry + Micrometer | - |
|
||
| ERP 集成 | SAP JCo3 | 3.1.12 |
|
||
| Excel | EasyExcel / EEC | - |
|
||
| PDF | iText7 / Flying Saucer / Thymeleaf / Apache PDFBox | - |
|
||
| 二维码 | ZXing | 3.5.3 |
|
||
| LDAP | spring-boot-starter-data-ldap | - |
|
||
| 构建 | Maven | - |
|
||
| ID 生成 | Hypersistence TSID | 2.1.4 |
|
||
|
||
## 架构总览
|
||
|
||
系统采用 Maven 多模块结构，分为 **4 个基础模块** 和 **7 个可部署服务**。
|
||
|
||
```mermaid
|
||
graph TD
|
||
A["nflg-wms (根 POM)"] --> B["nflg-wms-common<br/>公共模块"]
|
||
A --> C["nflg-wms-repository<br/>数据层"]
|
||
A --> D["nflg-wms-starter<br/>启动器"]
|
||
A --> E["nflg-wms-gateway<br/>API 网关<br/>:8100"]
|
||
A --> F["nflg-wms-auth<br/>认证服务<br/>:8101"]
|
||
A --> G["nflg-wms-admin<br/>WMS 管理后台<br/>:8102"]
|
||
A --> H["nflg-wms-shipment<br/>发货服务<br/>:8103"]
|
||
A --> I["nflg-wms-scheduled<br/>定时任务<br/>:8103"]
|
||
A --> J["nflg-wms-srm-receive<br/>SRM 接收<br/>:8104"]
|
||
A --> K["nflg-qms-admin<br/>QMS 管理后台<br/>:8105"]
|
||
A --> L["nflg-qms-pdf-extract<br/>PDF 数据提取"]
|
||
|
||
B --> C
|
||
C --> D
|
||
B --> D
|
||
D --> G
|
||
D --> F
|
||
D --> H
|
||
D --> I
|
||
D --> J
|
||
D --> K
|
||
B --> E
|
||
C --> E
|
||
L --> K
|
||
|
||
click B "./nflg-wms-common/CLAUDE.md" "查看 common 模块文档"
|
||
click C "./nflg-wms-repository/CLAUDE.md" "查看 repository 模块文档"
|
||
click D "./nflg-wms-starter/CLAUDE.md" "查看 starter 模块文档"
|
||
click E "./nflg-wms-gateway/CLAUDE.md" "查看 gateway 模块文档"
|
||
click F "./nflg-wms-auth/CLAUDE.md" "查看 auth 模块文档"
|
||
click G "./nflg-wms-admin/CLAUDE.md" "查看 admin 模块文档"
|
||
click H "./nflg-wms-shipment/CLAUDE.md" "查看 shipment 模块文档"
|
||
click I "./nflg-wms-scheduled/CLAUDE.md" "查看 scheduled 模块文档"
|
||
click J "./nflg-wms-srm-receive/CLAUDE.md" "查看 srm-receive 模块文档"
|
||
click K "./nflg-qms-admin/CLAUDE.md" "查看 qms-admin 模块文档"
|
||
click L "./nflg-qms-pdf-extract/CLAUDE.md" "查看 qms-pdf-extract 模块文档"
|
||
```
|
||
|
||
### 依赖关系
|
||
|
||
```
|
||
nflg-wms-common (基础 POJO / 工具 / 异常)
|
||
└── nflg-wms-repository (Entity / Mapper / Service 接口及实现)
|
||
└── nflg-wms-starter (统一配置：Sa-Token / Redis / Nacos / OSS / 全局异常处理)
|
||
├── nflg-wms-admin (WMS 管理后台服务)
|
||
├── nflg-wms-auth (SSO 认证服务)
|
||
├── nflg-wms-shipment (发货服务)
|
||
├── nflg-wms-scheduled (定时任务执行器)
|
||
├── nflg-wms-srm-receive(SRM 订单接收服务)
|
||
└── nflg-qms-admin (QMS 质量管理后台)
|
||
└── nflg-qms-pdf-extract (PDF 数据提取库)
|
||
|
||
nflg-wms-gateway (API 网关，依赖 common + repository，不依赖 starter)
|
||
```
|
||
|
||
## 模块索引
|
||
|
||
| 模块 | 类型 | 端口 | 描述 | 入口类 |
|
||
|------|------|------|------|--------|
|
||
| nflg-wms-common | 基础库 | - | 公共 POJO (QO/VO/DTO)、常量、异常、工具类（12 个） | - |
|
||
| nflg-wms-repository | 基础库 | - | 数据访问层：Entity、Mapper、Service 接口与实现、MyBatis XML、TypeHandler（3 个）、拦截器 | - |
|
||
| nflg-wms-starter | 基础库 | - | 统一启动配置：Sa-Token、Redis、Nacos、OSS、全局异常处理 | - |
|
||
| nflg-qms-pdf-extract | 基础库 | - | PDF 工程图纸尺寸数据提取（PDFBox 3.0.4） | - |
|
||
| nflg-wms-gateway | 服务 | 8100 | API 网关，路由转发 + Sa-Token 鉴权 + CORS + 链路追踪 | GateWayApplication |
|
||
| nflg-wms-auth | 服务 | 8101 | SSO 单点登录认证服务 + LDAP 集成 | AuthApplication |
|
||
| nflg-wms-admin | 服务 | 8102 | WMS 核心管理后台：53 个 Controller，覆盖入库/出库/库存/盘点/质检/物料/BOM/权限 | AdminApplication |
|
||
| nflg-wms-shipment | 服务 | 8103 | 发货管理：发运单/物料码/包装码/箱单/现场库存 + CRM 对接 | ShipmentApplication |
|
||
| nflg-wms-scheduled | 服务 | 8103 | PowerJob 定时任务执行器：SAP 库存同步/LDAP 同步/物料图片导入 | ScheduledApplication |
|
||
| nflg-wms-srm-receive | 服务 | 8104 | SRM 供应商订单接收，SAP 集成 | SrmReceiveApplication |
|
||
| nflg-qms-admin | 服务 | 8105 | QMS 质量管理后台：37 个 Controller，覆盖来料检验/检验标准/问题工单/PDI/COA/文件管理 | QmsApplication |
|
||
|
||
## 开发快速入门
|
||
|
||
### 常用命令
|
||
|
||
**编译与构建**
|
||
```bash
|
||
# 全量编译（跳过测试）
|
||
mvn clean compile -DskipTests
|
||
|
||
# 编译特定模块
|
||
mvn -pl nflg-wms-admin clean compile -DskipTests
|
||
|
||
# 全量打包（跳过测试）
|
||
mvn clean package -DskipTests
|
||
|
||
# 单模块打包及其依赖
|
||
mvn -pl nflg-wms-admin -am clean package -DskipTests
|
||
```
|
||
|
||
**运行测试**
|
||
```bash
|
||
# 运行全部测试
|
||
mvn clean test
|
||
|
||
# 运行单个模块的测试
|
||
mvn -pl nflg-wms-admin test
|
||
|
||
# 运行单个测试类
|
||
mvn -pl nflg-wms-admin test -Dtest=ApiStorageTest
|
||
|
||
# 运行特定测试方法
|
||
mvn -pl nflg-wms-admin test -Dtest=ApiStorageTest#methodName
|
||
```
|
||
|
||
**代码生成**
|
||
- nflg-wms-repository 模块含 MyBatis-Plus 代码生成器：运行 `CodeGeneratorTest` 可根据数据库表生成 Entity/Mapper/Service 代码
|
||
|
||
**IDE 启动**
|
||
- 各服务 Application 类位于 `src/main/java/{module}/` 下，直接以 Java Application 运行或调试
|
||
- 推荐启动前确保 Nacos/PostgreSQL/Redis/MongoDB 已启动
|
||
|
||
### 环境要求
|
||
- JDK 17+
|
||
- Maven 3.8+
|
||
- PostgreSQL（数据库）
|
||
- Redis（缓存、Session、分布式锁）
|
||
- Nacos（服务注册、配置中心）
|
||
- MongoDB（文档存储：扫码记录等）
|
||
|
||
### 启动顺序建议
|
||
1. 基础设施：Nacos -> PostgreSQL -> Redis -> MongoDB
|
||
2. API 网关：nflg-wms-gateway (:8100)
|
||
3. 认证服务：nflg-wms-auth (:8101)
|
||
4. 业务服务：nflg-wms-admin (:8102) 或其他业务服务
|
||
5. 定时任务（可选）：nflg-wms-scheduled (:8103)
|
||
|
||
### 配置管理
|
||
- 所有服务通过 Nacos 拉取共享配置 `shared.properties`
|
||
- 环境区分：`dev` / `sit` / `prod`
|
||
- 每个服务有独立的 `application-{env}.yml` 做环境特定配置
|
||
- 本地开发通常使用 `application-dev.yml`
|
||
|
||
### 打包方式
|
||
服务采用 maven-shade-plugin + maven-jar-plugin 组合打包，依赖 JAR 分离到 `lib/` 目录：
|
||
```bash
|
||
java -jar nflg-wms-admin-1.0.0-SNAPSHOT.jar
|
||
```
|
||
|
||
## 运行与部署
|
||
|
||
### 环境要求
|
||
- JDK 17+
|
||
- Maven 3.8+
|
||
- PostgreSQL
|
||
- Redis
|
||
- Nacos（注册/配置中心）
|
||
- MongoDB（扫码记录等文档型数据存储）
|
||
|
||
### 构建命令
|
||
```bash
|
||
# 全量构建
|
||
mvn clean package -DskipTests
|
||
|
||
# 单模块构建（以 admin 为例）
|
||
mvn clean package -pl nflg-wms-admin -am -DskipTests
|
||
```
|
||
|
||
### 启动顺序建议
|
||
1. 基础设施：Nacos -> PostgreSQL -> Redis -> MongoDB
|
||
2. 网关：nflg-wms-gateway (:8100)
|
||
3. 认证：nflg-wms-auth (:8101)
|
||
4. 业务服务：nflg-wms-admin (:8102) / nflg-wms-shipment (:8103) / nflg-wms-srm-receive (:8104) / nflg-qms-admin (:8105)
|
||
5. 定时任务：nflg-wms-scheduled (:8103)
|
||
|
||
### 配置管理
|
||
- 所有服务通过 Nacos 拉取共享配置 `shared.properties`
|
||
- 环境区分：`dev` / `sit` / `prod`
|
||
- 每个服务有独立的 `application-{env}.yml` 做环境特定配置
|
||
|
||
### 打包方式
|
||
服务采用 maven-shade-plugin + maven-jar-plugin 组合打包，依赖 JAR 分离到 `lib/` 目录，启动示例：
|
||
```bash
|
||
java -jar nflg-wms-admin-1.0.0-SNAPSHOT.jar
|
||
```
|
||
|
||
## 代码探索与导航
|
||
|
||
### 快速找到关键代码
|
||
|
||
**按功能模块查找**
|
||
- 仓库管理 (WMS)：`nflg-wms-admin` 模块，53 个 Controller 覆盖全业务
|
||
- 质量管理 (QMS)：`nflg-qms-admin` 模块，37 个 Controller，来料检验/检验标准/问题工单/PDI/COA
|
||
- 发货管理：`nflg-wms-shipment` 模块
|
||
- 认证/权限：`nflg-wms-auth` 模块（Sa-Token + JWT + SSO）
|
||
- API 网关：`nflg-wms-gateway` 模块（路由转发 + 权限检查）
|
||
- 定时任务：`nflg-wms-scheduled` 模块（PowerJob 执行器）
|
||
|
||
**按数据表找实体**
|
||
- 所有 Entity 在 `nflg-wms-repository/entity/` 下，Mapper 在 `mapper/` 下
|
||
- Mapper XML 文件在 `src/main/resources/mapper/` 下，与 Entity 名称对应
|
||
|
||
**按业务流程找 Controller Service**
|
||
- 入库流程：`InProduceOrderControllerService`、`POReceiptControllerService` 等（`nflg-wms-admin`）
|
||
- 出库流程：`OutProduceControllerService`、`OutCostCenterControllerService` 等（`nflg-wms-admin`）
|
||
- SAP 集成：`SapService`、`SAPCommonService`（各模块独立实现或在 `nflg-wms-admin`）
|
||
- 质检流程：`NormalQMControllerService`（`nflg-wms-admin`）
|
||
|
||
**按权限查找 API**
|
||
- 权限定义：`@ApiMark` 注解标注在 Controller 方法上
|
||
- 权限检查由 Sa-Token 在网关 + 各服务中进行
|
||
- 菜单和权限数据库表：`sys_menu` 和权限相关表
|
||
|
||
### 常见开发任务
|
||
|
||
**新增 API 端点**
|
||
1. 在相应 Controller 中添加方法，标注 `@PostMapping/@GetMapping` 等
|
||
2. 添加请求参数类（QO）和响应类（VO）
|
||
3. 在 Service 中实现业务逻辑
|
||
4. 如涉及数据库，先在 Service 层调用 Repository 的方法或直接通过 Mapper 调用
|
||
|
||
**修改数据库表结构**
|
||
1. 在 PostgreSQL 中执行 DDL（或创建迁移脚本）
|
||
2. 运行 `CodeGeneratorTest` 重新生成 Entity/Mapper/Service
|
||
3. 更新 Mapper XML 中的复杂查询或自定义 SQL
|
||
|
||
**集成 SAP 业务**
|
||
1. 在对应模块的 `SAPConfig` 中配置 JCo 连接参数
|
||
2. 调用 `JCoUtil` 或 `SAPCommonService` 执行 RFC 函数
|
||
3. 处理返回结构，同步结果到本地数据库
|
||
|
||
**添加定时任务**
|
||
1. 在 `nflg-wms-scheduled` 模块中添加类，继承 PowerJob 的任务接口
|
||
2. 通过 PowerJob 服务端界面或 API 配置任务周期和参数
|
||
|
||
**处理文件操作**
|
||
1. 上传：通过 `FileControllerService`
|
||
2. 下载：通过 `FileController` 中的下载接口
|
||
3. Excel：使用 EasyExcel 或 EEC 库（已在依赖中）
|
||
4. PDF 生成：使用 `PdfGeneratorUtil` 或 `ThymeleafUtil`
|
||
|
||
## 测试策略
|
||
|
||
- 测试文件主要为部署测试 (DeployDevTest / DeploySitTest) 和功能验证测试
|
||
- 代码生成：`nflg-wms-repository` 含 MyBatis-Plus 代码生成器 (CodeGeneratorTest)
|
||
- 测试框架：JUnit 5 (junit-jupiter) + Spring Boot Test
|
||
- 各模块测试分布：admin (6)、auth (2)、gateway (2)、scheduled (1)、shipment (3)、srm-receive (3)、qms (1)、starter (1)、repository (1)
|
||
|
||
## 编码规范
|
||
|
||
### 包结构约定
|
||
```
|
||
com.nflg.wms.{module}
|
||
├── controller/ # REST API 接口
|
||
├── service/ # 业务逻辑层
|
||
├── config/ # 配置类
|
||
├── pojo/
|
||
│ ├── qo/ # 查询/请求对象 (Query Object)
|
||
│ ├── vo/ # 视图对象 (View Object)
|
||
│ └── dto/ # 数据传输对象 (Data Transfer Object)
|
||
└── util/ # 工具类
|
||
```
|
||
|
||
### 数据层约定 (nflg-wms-repository)
|
||
```
|
||
com.nflg.wms.repository
|
||
├── entity/ # 数据库实体 (MyBatis-Plus)
|
||
├── mapper/ # Mapper 接口 (继承 BaseMapper)
|
||
├── service/ # Service 接口 (I{Entity}Service)
|
||
├── service/impl/ # Service 实现 ({Entity}ServiceImpl)
|
||
├── handler/ # 类型处理器 (TypeHandler): UTCLocalDate/UTCLocalDateTime/Ltree
|
||
└── interceptor/ # MyBatis 拦截器 (AuditInnerInterceptor)
|
||
```
|
||
|
||
### 命名规范
|
||
- Entity：对应数据库表名（驼峰转换）
|
||
- Mapper：`{Entity}Mapper.java` + `{Entity}Mapper.xml`
|
||
- Service 接口：`I{Entity}Service`
|
||
- Service 实现：`{Entity}ServiceImpl`
|
||
- Controller Service：`{Feature}ControllerService`（admin/shipment/qms 模块的业务逻辑层）
|
||
- QO：`{Feature}{Action}QO`（请求参数）
|
||
- VO：`{Feature}VO`（响应数据）
|
||
- DTO：`{Feature}DTO`（数据传输）
|
||
|
||
### API 响应格式
|
||
统一使用 `ApiResult<T>` 包装，分页使用 `ApiPageResult` / `PageData`。
|
||
|
||
### 异常处理
|
||
- `NflgException`：通用业务异常
|
||
- `DataAlertException`：数据告警异常
|
||
- `SAPException`：SAP 集成异常
|
||
- 全局异常处理：`GlobalRestControllerAdvice`
|
||
|
||
### SAP 集成
|
||
- 使用 SAP JCo3 进行 RFC 调用
|
||
- 配置类：`SAPConfig`（各服务独立配置）
|
||
- 工具类：`JCoUtil`
|
||
- 涉及模块：admin、scheduled、srm-receive
|
||
|
||
### 常见数据模型模式
|
||
|
||
**主子表模式** — 大量业务单据采用主表 + 明细表的结构
|
||
- 例：`WmsPoReceipt` (主) + `WmsPoReceiptItem` (明细)
|
||
- Entity 中一般不包含导航字段，通过 Mapper 查询获取完整数据
|
||
- Service 中通常先保存主表，再批量保存明细表
|
||
- 注意主外键关系和 Mapper XML 中的 JOIN 复杂性
|
||
|
||
**字典与常量** — 系统字典表 (`sys_dictionary`) 存储枚举值
|
||
- 各业务模块大量使用字典值作为状态/类型标记
|
||
- 修改字典时需同步更新内存缓存（Redis）
|
||
|
||
**权限数据模型** — Sa-Token + 数据库权限表的组合
|
||
- 菜单权限：`sys_menu` 表和权限标记 (`@ApiMark` 注解)
|
||
- 数据权限：`sys_data_permission` 等表，支持按部门/人员过滤
|
||
- 新增 API 时需要在数据库插入对应的菜单和权限记录
|
||
|
||
**多语言支持** — 通过 `t_multilingual` 及相关表
|
||
- 主要业务对象（物料、仓库、库位等）都支持多语言描述
|
||
- 查询时需要根据当前语言环境 JOIN 多语言表
|
||
|
||
**审计字段** — 大多数业务表包含 create_by/create_time/update_by/update_time
|
||
- MyBatis 拦截器 `AuditInnerInterceptor` 自动填充这些字段
|
||
|
||
### SAP 集成详解
|
||
|
||
**常见 RFC 函数模式**
|
||
- 库存移动：涉及 MIGO（Material Issue/Goods Receipt）相关 RFC
|
||
- 过账操作：涉及财务凭证生成（FI）相关 RFC
|
||
- 物料主数据查询：通过 RFC 查询 SAP 物料信息
|
||
- 注意错误码处理：SAP RFC 返回的错误码与本系统业务异常的映射
|
||
|
||
**处理 JCo 连接池**
|
||
- SAP JCo 连接是有限资源，长连接需要管理
|
||
- 异常情况下需要显式关闭连接避免连接泄漏
|
||
- 大批量操作建议分批处理
|
||
|
||
**SAP 数据同步**
|
||
- 定时任务（PowerJob）定期与 SAP 同步库存数据
|
||
- 关键数据（库存变化）需要实时反馈给 SAP
|
||
- 同步失败时需记录日志和异常信息便于问题诊断
|
||
|
||
## AI 使用指引
|
||
|
||
### 重要上下文
|
||
1. **业务领域** — 制造业仓储管理系统，术语包含大量仓储/物流/质量领域专有名词（例：库位、SN 码、质检任务、工装台账等）
|
||
2. **SAP 深度集成** — 许多业务操作必须同步到 SAP ERP，如库存移动、物料收发、财务过账等，SAP 集成失败会导致系统与 ERP 数据不一致
|
||
3. **多端支持** — 系统同时服务 PC Web 端（浏览器）和 H5 移动端（扫码收货等物流场景）
|
||
4. **数据模型** — 大量采用"单据 + 明细"的主子表模式（如 WmsPoReceipt + WmsPoReceiptItem），修改时需同时考虑主表和明细的一致性
|
||
5. **术语约定**
|
||
- **Wms** = 仓储管理（库存、入库、出库、盘点）
|
||
- **Srm** = 供应商关系管理（供应商订单接收）
|
||
- **Qms** = 质量管理（来料检验、检验标准、问题工单、PDI、COA）
|
||
- **In/Out** = 入库/出库操作的前缀
|
||
- **ControllerService** = 控制层的业务逻辑层（区别于 Repository Service）
|
||
6. **QMS 功能** — 已发展为完整的质量管理系统：来料检验、检验标准批管理、问题工单全流程、整车 PDI 检测、COA 证书管理
|
||
|
||
### 代码修改建议
|
||
|
||
**修改 Entity 时**
|
||
- 同步检查 Mapper XML 中是否有对应的字段映射
|
||
- 如果添加新字段，通常需要更新查询 SQL 中的 SELECT 列表
|
||
- 考虑审计字段的影响（create_by/create_time/update_by/update_time）
|
||
|
||
**修改 API 接口时**
|
||
- 新增接口需要添加 `@ApiMark` 注解，指定权限标记（需同时在数据库 sys_menu 等表中创建菜单记录）
|
||
- 修改现有接口参数时，检查是否有其他服务或前端正在调用该接口（通过 grep 查找调用者）
|
||
- 权限检查在两处进行：API 网关 (nflg-wms-gateway) 和各服务中，确保一致
|
||
|
||
**SAP 相关修改**
|
||
- 理解待调用的 RFC 函数的参数结构（导入表、导出表、返回码等）
|
||
- 处理 JCo 异常时要区分网络异常、认证异常、业务异常等
|
||
- 大批量 SAP 操作建议分批处理，避免超时和连接耗尽
|
||
|
||
**新增 Controller 时**
|
||
- 创建对应的 ControllerService 承载业务逻辑
|
||
- 在 Controller 方法上标注权限（@ApiMark）
|
||
- 需要在 Nacos 配置或数据库中注册 API 信息（供前端权限菜单使用）
|
||
- 遵循包结构约定：controller/service/pojo/{qo,vo,dto}
|
||
|
||
**修改权限或菜单**
|
||
- 权限标记与数据库菜单表 (sys_menu) 必须对应
|
||
- 数据权限涉及 sys_data_permission 表，新增权限时检查是否需要添加数据权限规则
|
||
|
||
### 关键业务流程
|
||
|
||
**入库流程**
|
||
PO 收货 -> 质检（可选，看配置）-> 入库上架（生成库位分配）-> SAP 过账（MIGO）-> 库存可用
|
||
|
||
**出库流程**
|
||
生产领料/成本中心领用/外协出库 -> 拣货（扫码确认）-> 库存扣减 -> SAP 过账
|
||
|
||
**SRM 流程**
|
||
SRM 发货通知（外系统推送）-> WMS 收货（生成 PO 单）-> 质检 -> 入库 -> SAP 同步
|
||
|
||
**发货流程**
|
||
发运单创建 -> 物料码/包装码管理 -> 箱单与装箱 -> 发运（物流单）
|
||
|
||
**盘点流程**
|
||
创建盘点任务 -> 分配库位 -> H5 扫码盘点 -> 差异处理（调整库存）-> SAP 同步
|
||
|
||
**QMS 来料检验**
|
||
来料到货（收货单）-> 自动/手动创建检验任务 -> 按抽样方案抽样 -> 检验员记录结果 -> 回调 WMS 更新收货单状态
|
||
|
||
**QMS 问题工单**
|
||
创建工单（问题类型/严重度） -> 分配处理人 -> 整改措施 -> 验证/关闭 -> 整个生命周期有待办和催办机制
|
||
|
||
### 修改时的常见陷阱
|
||
|
||
- **忘记更新 Mapper XML** — Entity 字段变更后 XML 中的映射可能不一致
|
||
- **SAP 同步失败但本地继续执行** — 需要正确处理异常和事务回滚
|
||
- **权限管理不一致** — 网关权限检查与服务端不统一导致用户权限混乱
|
||
- **多语言数据不完整** — 新增业务对象时忘记插入多语言记录
|
||
- **分布式锁泄漏** — SAP/Redis 操作中异常导致锁未释放，后续请求被永久阻塞
|
||
- **主子表数据不一致** — 保存主表成功但明细保存失败，导致数据不完整
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
nflg-wms/
|
||
├── pom.xml # 根 POM（模块聚合 + 依赖管理）
|
||
├── nflg-wms-common/ # 公共模块
|
||
├── nflg-wms-repository/ # 数据层
|
||
├── nflg-wms-starter/ # 统一启动器
|
||
├── nflg-wms-gateway/ # API 网关服务
|
||
├── nflg-wms-auth/ # 认证服务
|
||
├── nflg-wms-admin/ # WMS 管理后台
|
||
├── nflg-wms-shipment/ # 发货服务
|
||
├── nflg-wms-scheduled/ # 定时任务
|
||
├── nflg-wms-srm-receive/ # SRM 接收服务
|
||
├── nflg-qms-admin/ # QMS 管理后台
|
||
└── nflg-qms-pdf-extract/ # QMS PDF 数据提取
|
||
```
|
||
|
||
## 模块间依赖与隔离说明
|
||
|
||
### 清晰的依赖链路
|
||
```
|
||
nflg-wms-common (最底层：POJO/常量/异常)
|
||
└── nflg-wms-repository (数据访问层：Entity/Mapper/Service)
|
||
└── nflg-wms-starter (启动器：统一配置中心)
|
||
└── 业务服务模块 (admin/auth/shipment/scheduled/srm-receive/qms-admin)
|
||
|
||
nflg-wms-gateway (特殊：仅依赖 common+repository，不依赖 starter)
|
||
```
|
||
|
||
### 模块选择指南
|
||
- **修改数据库模型或 ORM** → `nflg-wms-repository`
|
||
- **修改全局配置或异常处理** → `nflg-wms-starter`
|
||
- **修改公共 POJO/常量** → `nflg-wms-common`
|
||
- **修改权限/认证流程** → `nflg-wms-auth` 和 `nflg-wms-gateway`
|
||
- **修改业务逻辑** → 具体业务模块 (`nflg-wms-admin`/`nflg-qms-admin` 等)
|
||
|
||
### 避免的做法
|
||
- **不要在 admin 模块中添加与其他业务模块紧耦合的代码** — 这会导致部署时互相依赖
|
||
- **不要在 starter 中添加业务逻辑** — starter 只做全局配置，避免变更影响所有依赖者
|
||
- **不要跨模块访问 private Service** — 通过 REST API 或消息队列通信
|
||
|
||
## 快速参考：按模块查找代码
|
||
|
||
| 需求 | 查找位置 |
|
||
|------|--------|
|
||
| 查看所有 Entity 定义 | `nflg-wms-repository/entity/` |
|
||
| 查看数据库 SQL 映射 | `nflg-wms-repository/src/main/resources/mapper/` |
|
||
| 查看 API 端点定义 | 各业务模块的 `controller/` |
|
||
| 查看业务逻辑 | 各业务模块的 `service/` 或 `controller/` 下的 `ControllerService` |
|
||
| 查看 SAP 集成 | `SAPConfig`/`SapService`/`JCoUtil`（主要在 admin 和其他模块） |
|
||
| 查看权限和菜单 | 数据库 `sys_menu` 表，代码中的 `@ApiMark` 注解 |
|
||
| 查看多语言配置 | `nflg-wms-admin` 中的 `MultilingualController` 和 `t_multilingual` 表 |
|
||
| 查看定时任务 | `nflg-wms-scheduled/` 或各模块的 `schedule/` 目录 |
|
||
| 查看 Redis 缓存配置 | `nflg-wms-starter/config/` 中的缓存配置 |
|
||
| 查看数据库连接池 | `nflg-wms-starter/config/` 中的 DataSource 配置 |
|
||
|
||
## 变更记录 (Changelog)
|
||
|
||
| 时间 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| 2026-06-13 | 大幅增强 | 1) 添加"开发快速入门"章节，含常用 Maven 命令（编译/测试/代码生成）；2) 新增"代码探索与导航"章节，含按功能模块查找、常见开发任务（新增 API/修改表结构/SAP 集成等）；3) 补充"常见数据模型模式"，详解主子表、字典、权限、多语言、审计字段等；4) 深化"SAP 集成详解"，含 RFC 函数、连接池管理、数据同步；5) 大幅重写"AI 使用指引"，增加业务上下文、修改建议（Entity/API/SAP）、常见陷阱；6) 新增"模块间依赖与隔离说明"和"快速参考表"；7) 增加英文 CLAUDE.md 前缀说明 |
|
||
| 2026-05-23 14:28:57 | 增量更新 | 1) 新增 nflg-qms-pdf-extract 模块文档（首次遗漏）；2) 重写 nflg-qms-admin 文档（3 文件->80 文件，0->37 Controller）；3) 修正 nflg-wms-admin Controller 数量 54->53（移除不存在的 AdvertisementController），补充全部 REST 路由前缀；4) 补充 nflg-wms-common 工具类 3->12 个；5) 补充 nflg-wms-repository LtreeTypeHandler；6) 更新 Mermaid 架构图和模块索引 |
|
||
| 2026-05-23 14:16:58 | 初始化 | 首次生成项目 AI 上下文文档，覆盖全部 10 个模块 |
|