---
kind: configuration_system
name: Spring Boot 配置体系与环境变量注入
category: configuration_system
scope:
    - '**'
source_files:
    - crm-app/src/main/resources/application.yml
    - crm-auth/src/main/resources/application.yml
    - crm-file/src/main/java/com/crm/file/config/FileProperties.java
    - crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java
    - crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java
    - crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java
---

本仓库采用 Spring Boot 标准的 YAML + `@ConfigurationProperties` 配置体系，通过多模块各自 `application.yml` 提供默认值，并以环境变量覆盖敏感参数，形成“默认配置 + 环境覆盖”的分层加载模式。

**1. 使用的框架与工具**
- Spring Boot `@ConfigurationProperties` 类型安全绑定：所有业务配置均通过带 `@Component` 的 POJO 类声明前缀（如 `crm.auth`、`crm.file`、`crm.snowflake`、`scheduled-task`），由 Spring 自动装配。
- YAML 配置文件：每个模块在 `src/main/resources/application.yml` 中定义完整配置结构，包括数据库、Redis、MyBatis-Plus、JWT、MinIO、kkFileView、定时任务等。
- 环境变量占位符 `${ENV_VAR:default}`：敏感信息（JWT secret、钉钉 Client ID/Secret、MinIO AK/SK）一律使用环境变量注入，默认值仅用于本地开发。

**2. 核心文件与位置**
- `crm-app/src/main/resources/application.yml`：聚合应用入口配置，集中声明 MySQL、Redis、multipart 上传限制、crm.* 命名空间下的全部业务配置。
- `crm-auth/src/main/resources/application.yml`：认证服务独立运行时的配置，端口 8081，包含 JWT、钉钉登录、雪花 ID 等。
- `crm-file/src/main/java/com/crm/file/config/FileProperties.java`：文件模块配置类，定义 MinIO、预览、分片上传、黑名单等参数及默认值。
- `crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java`：雪花 ID 生成器配置，要求多实例 worker-id/datacenter-id 互异。
- `crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java`：定时任务属主控制，支持多实例下按 owner 限定执行节点。
- `crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java`：认证模块配置，含 JWT 密钥、TTL、钉钉凭据及额外放行 URL 列表。

**3. 架构与设计约定**
- **统一命名空间**：所有业务配置集中在 `crm.*` 前缀下（auth、file、snowflake），跨模块共享；仅定时任务属主使用独立的 `scheduled-task` 前缀。
- **分层默认值策略**：`application.yml` 提供可运行的默认值（如 localhost 数据库、默认 secret），生产环境通过环境变量覆盖，避免硬编码敏感信息。
- **类型安全与单位约束**：文件大小使用 `DataSize`（MB/GB）、超时使用 `Duration`（m/h），由 Spring Boot 自动校验与转换，避免字符串解析错误。
- **配置联动约束**：multipart 的 `max-file-size` / `max-request-size` 必须 ≥ `crm.file.chunk-size` 与 `direct-upload-limit` 中的较大值，注释明确标注需同步调整。
- **多实例部署约定**：雪花 ID 的 `worker-id` 在多实例时必须互不相同；定时任务通过 `scheduled-task.owner` 指定唯一执行节点。

**4. 约束与规则**
- 生产环境的 JWT secret、钉钉 Client Secret、MinIO AK/SK 必须通过环境变量注入，不得写入代码或配置文件（多处注释明确要求“生产环境务必用环境变量覆盖”）。
- 分片上传的 `chunk-size` 不得低于 5MB（受 MinIO composeObject 非末片下限约束），且需与 multipart 上限联动调整。
- 逻辑删除字段统一为 `deleted`，未删=0、已删=1，全局生效于 MyBatis-Plus 配置。
- 驼峰映射 `map-underscore-to-camel-case=true` 在所有模块中保持一致。
- 日志输出格式统一包含 `%X{traceId}` 追踪标识，便于链路追踪。