wms/.qoder/repowiki/zh/content/开发指南/开发指南.md

# 开发指南

<cite>
**本文引用的文件**
- [pom.xml](file://pom.xml)
- [readme.md](file://readme.md)
- [lombok.config](file://lombok.config)
- [nflg-wms-common/pom.xml](file://nflg-wms-common/pom.xml)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java](file://nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java)
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java)
- [nflg-wms-admin/pom.xml](file://nflg-wms-admin/pom.xml)
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java)
- [nflg-wms-admin/src/main/resources/application.yml](file://nflg-wms-admin/src/main/resources/application.yml)
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java)
- [nflg-wms-repository/pom.xml](file://nflg-wms-repository/pom.xml)
- [nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java](file://nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向新加入的开发者，系统性介绍NFLG WMS系统的开发环境搭建、代码规范、项目结构、编码与注释规范、代码生成与模板使用、单元与集成测试策略、调试与问题定位方法、Git工作流与代码评审流程、第三方库集成与插件开发方法，并提供学习路径与常见问题解决方案。文档中的所有技术细节均以仓库现有文件为依据。

## 项目结构
本项目采用多模块Maven聚合工程组织，核心模块包括通用模块、基础启动器、数据访问层、网关、各业务服务（如管理后台、认证、定时任务、SRM收货、运输等），以及一个独立的QMS管理端。模块间通过公共依赖与版本管理统一约束。

- 聚合根：顶层pom.xml定义了模块清单、Java版本、编码、依赖与插件管理。
- 公共模块：nflg-wms-common 提供常量、异常、工具类与通用DTO/QO/VO等。
- 基础启动器：nflg-wms-starter 提供统一控制器基类、拦截器、切面与配置骨架。
- 数据访问层：nflg-wms-repository 封装MyBatis-Plus与数据库交互，内置代码生成器测试用例。
- 业务服务：nflg-wms-admin、nflg-wms-auth、nflg-wms-scheduled、nflg-wms-srm-receive、nflg-wms-shipment 等。
- 网关：nflg-wms-gateway。
- 独立管理端：nflg-qms-admin。

```mermaid
graph TB
Root["聚合根<br/>nflg-wms(pom.xml)"]
Common["公共模块<br/>nflg-wms-common"]
Starter["基础启动器<br/>nflg-wms-starter"]
Repo["数据访问层<br/>nflg-wms-repository"]
Gateway["网关<br/>nflg-wms-gateway"]
Admin["管理后台<br/>nflg-wms-admin"]
Auth["认证服务<br/>nflg-wms-auth"]
Scheduled["定时任务<br/>nflg-wms-scheduled"]
Srm["SRM收货<br/>nflg-wms-srm-receive"]
Shipment["运输模块<br/>nflg-wms-shipment"]
Qms["QMS管理端<br/>nflg-qms-admin"]
Root --> Common
Root --> Starter
Root --> Repo
Root --> Gateway
Root --> Admin
Root --> Auth
Root --> Scheduled
Root --> Srm
Root --> Shipment
Root --> Qms
Admin --> Common
Admin --> Starter
Admin --> Repo
Auth --> Common
Auth --> Starter
Scheduled --> Common
Srm --> Common
Shipment --> Common
Gateway --> Common
```

图表来源
- [pom.xml:17-27](file://pom.xml#L17-L27)
- [nflg-wms-admin/pom.xml:14-18](file://nflg-wms-admin/pom.xml#L14-L18)
- [nflg-wms-repository/pom.xml:14-18](file://nflg-wms-repository/pom.xml#L14-L18)

章节来源
- [pom.xml:1-260](file://pom.xml#L1-L260)

## 核心组件
- 通用常量与异常
  - 常量集中定义在公共模块中，便于跨模块共享。
  - 统一业务异常类型，配合状态码与消息返回。
- 工具类
  - BeanUtil提供对象与JSON、Map之间的转换能力，封装Jackson与Hutool。
- 基础控制器
  - BaseController提供二维码内容生成等通用逻辑，作为各业务Controller的父类。

章节来源
- [nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java:1-43](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37](file://nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java#L1-L37)
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)

## 架构总览
系统基于Spring Boot 3与Spring Cloud生态，采用Nacos作为配置与注册中心，Actuator暴露监控指标，支持链路追踪与健康检查。管理后台服务负责业务编排与对外接口，数据访问层通过MyBatis-Plus与PostgreSQL交互，部分模块集成Redisson、PowerJob、Loki日志采集等。

```mermaid
graph TB
subgraph "客户端"
Browser["浏览器/移动端"]
end
subgraph "边缘与网关"
Gateway["Spring Cloud Gateway"]
end
subgraph "服务发现与配置"
Nacos["Nacos(配置/注册)"]
end
subgraph "业务服务"
Admin["管理后台服务"]
Auth["认证服务"]
Scheduled["定时任务服务"]
Srm["SRM收货服务"]
Shipment["运输服务"]
end
subgraph "基础设施"
DB["PostgreSQL"]
Redis["Redis"]
Loki["Loki 日志"]
Act["Spring Boot Actuator"]
end
Browser --> Gateway
Gateway --> Admin
Gateway --> Auth
Admin --> DB
Auth --> DB
Scheduled --> DB
Srm --> DB
Shipment --> DB
Admin --> Redis
Auth --> Redis
Admin --> Loki
Auth --> Loki
Admin --> Act
Auth --> Act
Admin --> Nacos
Auth --> Nacos
Scheduled --> Nacos
Srm --> Nacos
Shipment --> Nacos
```

图表来源
- [nflg-wms-admin/src/main/resources/application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [nflg-wms-admin/pom.xml:14-189](file://nflg-wms-admin/pom.xml#L14-L189)
- [pom.xml:54-193](file://pom.xml#L54-L193)

## 详细组件分析

### 通用模块（nflg-wms-common）
- 职责
  - 定义系统级常量、通用异常类型、通用工具类与DTO/QO/VO集合。
- 关键点
  - 常量集中管理，便于统一维护与跨模块共享。
  - 异常体系以统一状态码与消息返回，便于前端与调用方处理。
  - 工具类封装常用转换逻辑，降低重复代码。

```mermaid
classDiagram
class Constant {
+String DEFAULT_LANGUAGE_CODE
+String TRACE_ID_HEADER
+String TRACE_ID
+... 多个常量
}
class NflgException {
+STATE state
+String msg
+NflgException(state, msg)
}
class BeanUtil {
+copy(source, clazz) T
+toJson(source) String
+toBean(map, clazz) T
+toMap(source) Map
}
```

图表来源
- [nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java:1-43](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37](file://nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java#L1-L37)

章节来源
- [nflg-wms-common/pom.xml:1-84](file://nflg-wms-common/pom.xml#L1-L84)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java:1-43](file://nflg-wms-common/src/main/java/com/nflg/wms/common/constant/Constant.java#L1-L43)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
- [nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java:1-37](file://nflg-wms-common/src/main/java/com/nflg/wms/common/util/BeanUtil.java#L1-L37)

### 基础启动器（nflg-wms-starter）
- 职责
  - 提供统一的控制器基类BaseController，封装通用逻辑（如二维码内容生成）。
- 关键点
  - 使用Lombok简化样板代码。
  - 作为其他服务的公共依赖，确保行为一致性。

```mermaid
classDiagram
class BaseController {
+generateQRContent(order) String
}
```

图表来源
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)

章节来源
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)

### 管理后台服务（nflg-wms-admin）
- 职责
  - 对外提供管理后台接口，集成LDAP、邮件、PDF生成、二维码、MongoDB、SAP JCo等能力。
- 关键点
  - 应用入口启用组件扫描、调度与重试。
  - 配置文件启用Nacos配置导入、Actuator端点、链路追踪采样。
  - 包含测试控制器，演示异常抛出与序列号生成等场景。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Admin as "AdminApplication"
participant Ctl as "TestController"
participant Svc as "相关服务"
Client->>Admin : 启动应用
Admin->>Admin : 组件扫描/调度/重试启用
Client->>Ctl : GET /test/add
Ctl->>Svc : 调用业务服务
Ctl-->>Client : 返回结果
Client->>Ctl : GET /test/businessError
Ctl-->>Client : 抛出业务异常
```

图表来源
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:1-27](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L1-L27)
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java:1-87](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java#L1-L87)

章节来源
- [nflg-wms-admin/pom.xml:1-281](file://nflg-wms-admin/pom.xml#L1-L281)
- [nflg-wms-admin/src/main/resources/application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java:1-27](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L1-L27)
- [nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java:1-87](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/controller/TestController.java#L1-L87)

### 数据访问层（nflg-wms-repository）
- 职责
  - 封装数据库访问，基于MyBatis-Plus与PostgreSQL，提供实体、Mapper、Service生成模板与测试。
- 关键点
  - 内置代码生成器测试用例，演示如何生成Entity、Mapper、Service与XML。
  - 支持Freemarker模板引擎与Lombok链式模型。

```mermaid
flowchart TD
Start(["执行代码生成测试"]) --> JDBC["连接PostgreSQL"]
JDBC --> Include["选择表集"]
Include --> Builder["配置实体/包结构/模板引擎"]
Builder --> Override["启用覆盖/链式模型/Lombok"]
Override --> Execute["执行生成"]
Execute --> End(["生成完成"])
```

图表来源
- [nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java:1-46](file://nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java#L1-L46)

章节来源
- [nflg-wms-repository/pom.xml:1-76](file://nflg-wms-repository/pom.xml#L1-L76)
- [nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java:1-46](file://nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java#L1-L46)

## 依赖分析
- 版本与依赖管理
  - 顶层pom集中管理Spring Boot、Spring Cloud、Spring Cloud Alibaba、MyBatis-Plus、Sa-Token、PostgreSQL、MinIO、Loki、Redisson、PowerJob、ZXing等版本。
- 模块依赖
  - 管理后台依赖公共模块、启动器与Web、LDAP、邮件、PDF、MongoDB、EasyExcel、Redisson、Actuator、OpenTelemetry等。
  - 数据访问层依赖公共模块与MyBatis-Plus、PostgreSQL、Redisson、测试依赖。

```mermaid
graph LR
POM["顶层pom.xml"]
Common["nflg-wms-common"]
Starter["nflg-wms-starter"]
Repo["nflg-wms-repository"]
Admin["nflg-wms-admin"]
Auth["nflg-wms-auth"]
Gateway["nflg-wms-gateway"]
POM --> Common
POM --> Starter
POM --> Repo
POM --> Admin
POM --> Auth
POM --> Gateway
Admin --> Common
Admin --> Starter
Admin --> Repo
```

图表来源
- [pom.xml:54-193](file://pom.xml#L54-L193)
- [nflg-wms-admin/pom.xml:14-18](file://nflg-wms-admin/pom.xml#L14-L18)
- [nflg-wms-repository/pom.xml:14-18](file://nflg-wms-repository/pom.xml#L14-L18)

章节来源
- [pom.xml:1-260](file://pom.xml#L1-L260)
- [nflg-wms-admin/pom.xml:1-281](file://nflg-wms-admin/pom.xml#L1-L281)
- [nflg-wms-repository/pom.xml:1-76](file://nflg-wms-repository/pom.xml#L1-L76)

## 性能考虑
- 链路追踪与指标
  - 启用Actuator与OpenTelemetry导出，建议在生产环境合理设置采样率，避免高噪声。
- 缓存与分布式锁
  - Redisson提供分布式能力，建议对热点查询与并发写入场景进行缓存与互斥控制。
- 数据库与分页
  - MyBatis-Plus分页与SQL解析器提升查询效率，建议结合索引与查询条件优化。
- 日志与可观测性
  - Loki日志采集用于集中化日志检索，建议按环境配置日志级别与过滤规则。

## 故障排查指南
- 异常处理
  - 统一使用NflgException返回业务状态与消息，便于前端与调用方识别与处理。
- 日志分析
  - 应用日志与Loki结合，按traceId快速定位请求链路。
- 常见问题
  - PDF生成与标签打印依赖wkhtmltoimage，需按readme安装对应依赖。
  - SAP JCo依赖需放置在指定目录，确保运行时可加载。

章节来源
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
- [readme.md:1-10](file://readme.md#L1-L10)

## 结论
本指南从环境搭建、项目结构、编码规范、代码生成、测试策略、调试与运维到Git工作流与第三方集成进行了系统阐述。建议新开发者先从公共模块与启动器入手，理解通用常量、异常与工具类的使用方式，再逐步深入到具体业务模块与数据访问层。

## 附录

### 开发环境搭建与IDE配置
- JDK与Maven
  - Java版本：17；Maven版本：3.6+。
- IDE推荐
  - IntelliJ IDEA：启用Lombok插件与Annotation Processing；配置Maven自动导入与编译器参数。
- 依赖安装
  - 按readme安装wkhtmltoimage，满足PDF与标签打印需求。
- Nacos与数据库
  - 确保Nacos地址与命名空间配置正确；数据库使用PostgreSQL，账号密码在代码生成测试中可见。

章节来源
- [pom.xml:29-35](file://pom.xml#L29-L35)
- [readme.md:1-10](file://readme.md#L1-L10)

### 代码规范与注释规范
- 包命名约定
  - 采用反向域名+模块+子域的层级结构，如com.nflg.wms.admin.controller。
- 类设计原则
  - 使用Lombok减少样板代码；异常类统一继承NflgException；工具类集中于common模块。
- 注释规范
  - 控制器与方法添加简要注释，说明用途与关键参数；复杂逻辑补充流程说明。

章节来源
- [nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java:1-18](file://nflg-wms-common/src/main/java/com/nflg/wms/common/exception/NflgException.java#L1-L18)
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)

### 代码生成与模板使用
- 生成范围
  - 通过代码生成器测试用例选择表集，生成Entity、Mapper、Service与XML。
- 模板引擎
  - 使用Freemarker模板引擎，支持链式模型与Lombok注解。
- 输出位置
  - 实体、Mapper、Service与XML分别输出到指定包路径，便于后续扩展。

章节来源
- [nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java:1-46](file://nflg-wms-repository/src/test/java/com/nflg/wms/repository/CodeGeneratorTest.java#L1-L46)

### 单元测试与集成测试策略
- 测试框架
  - 使用JUnit Jupiter；Surefire插件配置包含所有测试类。
- 测试覆盖率
  - 建议在CI中引入JaCoCo或类似工具统计覆盖率，目标不低于80%。
- 集成测试
  - 通过Deploy*Test类在不同环境（dev/sit/prod）验证部署与配置。

章节来源
- [pom.xml:246-254](file://pom.xml#L246-L254)
- [nflg-wms-admin/pom.xml:38-41](file://nflg-wms-admin/pom.xml#L38-L41)

### 调试技巧与问题定位
- 日志
  - 使用SLF4J与Loki日志采集，按环境调整日志级别；结合traceId快速定位。
- 性能分析
  - 启用Actuator与OpenTelemetry，导出指标与链路数据，定位慢调用与异常。
- 常见问题
  - PDF生成失败：确认wkhtmltoimage安装与路径；SAP JCo报错：检查JAR路径与权限。

章节来源
- [nflg-wms-admin/src/main/resources/application.yml:28-48](file://nflg-wms-admin/src/main/resources/application.yml#L28-L48)
- [readme.md:1-10](file://readme.md#L1-L10)

### Git工作流与代码审查流程
- 分支管理
  - 主干：main（受保护）；特性分支：feature/*；修复分支：fix/*；发布分支：release/*。
- 提交规范
  - 类型：feat/fix/docs/style/refactor/test/build/ci；格式：type(scope): subject。
- 代码审查
  - PR需至少一名Reviewer通过；合并前确保通过CI与测试。

### 第三方库集成指南与插件开发方法
- 常用库
  - Sa-Token：认证与会话；MyBatis-Plus：ORM；Redisson：分布式能力；PowerJob：定时任务；Loki：日志采集；OpenTelemetry：链路追踪。
- 插件开发
  - 在starter模块扩展通用能力（如拦截器、切面、注解），由各业务模块复用。

章节来源
- [pom.xml:54-193](file://pom.xml#L54-L193)
- [nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java:1-77](file://nflg-wms-starter/src/main/java/com/nflg/wms/starter/BaseController.java#L1-L77)

### 学习路径与技能要求
- 必备技能
  - Java 17、Spring Boot/Spring Cloud、MyBatis-Plus、PostgreSQL、Nacos、Docker/Kubernetes（可选）。
- 进阶方向
  - 链路追踪与可观测性、分布式缓存与限流、安全与认证、自动化测试与CI/CD。

### 常见开发问题与最佳实践
- 问题：PDF生成失败
  - 解决：安装wkhtmltoimage并确保系统可用。
- 问题：SAP JCo无法加载
  - 解决：将JAR放入lib目录并在构建阶段复制到输出目录。
- 最佳实践：统一异常处理、日志分级、参数校验、幂等与重试策略。

章节来源
- [readme.md:1-10](file://readme.md#L1-L10)
- [nflg-wms-admin/pom.xml:115-121](file://nflg-wms-admin/pom.xml#L115-L121)