crm-backend-matt/.qoder/repowiki/knowledge/zh/Maven 多模块聚合构建体系/Maven 多模块聚合构建体系.md

kind	name	category	scope	source_files
build_system	Maven 多模块聚合构建体系	build_system	[**]	[pom.xml crm-app/pom.xml crm-base/pom.xml crm-auth/pom.xml crm-file/pom.xml]

本项目采用 Maven 聚合工程（父 POM + 多子模块）作为唯一的构建系统，基于 Spring Boot 3.3.5 的 spring-boot-starter-parent 管理依赖与插件。核心设计如下：

1. 构建工具与版本策略

• 根 pom.xml 声明 <packaging>pom</packaging>，通过 <modules> 聚合 crm-base、crm-auth、crm-file、crm-app 四个子模块。
• Java 版本固定为 17（java.version、maven.compiler.source/target），编码 UTF-8。
• 所有第三方依赖版本集中在父 POM 的 <properties> 与 <dependencyManagement> 中统一管理，子模块引用时不指定版本号，由注释明确约束“不允许自行指定版本”。
• 内部模块间依赖通过 ${project.version} 引用，保证版本一致。

2. 模块职责与构建产物

• crm-base：基础公共库（jar），提供通用实体、统一响应体、异常处理、MyBatis-Plus/Redis/Jackson/Spring Security Core 等配置，被其他业务模块依赖。
• crm-auth：认证能力库（jar），包含 Spring Security + JWT、RBAC、三方登录，可独立运行但默认不做 repackage，开发时在 IDE 直接运行 AuthApplication。
• crm-file：文件服务库（jar），封装 MinIO 上传/下载/预览能力，对外暴露 FileApi 门面。
• crm-app：唯一可执行 jar 启动入口，聚合所有业务模块并配置运行时依赖（MySQL 驱动 scope=runtime），通过 spring-boot-maven-plugin 执行 repackage 生成可部署包。

3. 插件与打包约定

• 父 POM 在 <pluginManagement> 中集中声明 spring-boot-maven-plugin，并通过 <excludes> 排除 lombok 避免打入最终 jar。
• 仅 crm-app 的 pom.xml 显式启用该插件进行 repackage；其他模块因会被依赖，故不打包为可执行 jar。
• 测试依赖统一使用 spring-boot-starter-test（JUnit 5 + Mockito + AssertJ），部分模块额外引入 H2（内存数据库）用于单元测试。

4. 构建约束与规范

• 新增业务模块命名遵循 crm-{业务域}（如 crm-customer / crm-order），并在父 POM 的 <modules> 与 crm-app 的依赖列表中追加。
• Lombok 在所有模块中标记为 optional=true 或 scope=provided，确保不传递到依赖方。
• 运行时依赖（如 MySQL 驱动）统一标记 scope=runtime，编译期不污染依赖图。
• 当前仓库未包含 Dockerfile、CI 流水线或 Makefile，构建完全依赖 mvn clean package 标准流程。