---
kind: build_system
name: Maven 多模块聚合构建体系
category: build_system
scope:
    - '**'
source_files:
    - 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` 标准流程。