# 公共常量与枚举

<cite>
**本文引用的文件**   
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
</cite>

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

## 简介
本文件面向 CRM 后端项目的“公共常量与枚举”体系，聚焦 crm-base 模块中的系统级常量与通用枚举，并覆盖各业务模块（如认证、文件）的领域常量。目标包括：
- 解释 CommonConstants 的系统常量定义与使用场景
- 说明 HasValueEnum 与 StatusEnum 等枚举的设计原则与用法
- 明确常量的命名规范与枚举设计原则
- 提供扩展新常量与新枚举的最佳实践

## 项目结构
本项目采用多模块分层组织，公共常量与枚举集中在基础模块 crm-base 中，业务模块通过引用复用：
- crm-base：基础能力与通用定义（常量、枚举、异常、结果封装、工具类等）
- crm-auth：认证与权限相关领域常量与枚举
- crm-file：文件服务相关常量

```mermaid
graph TB
subgraph "基础模块 crm-base"
BASE_CONST["常量<br/>CommonConstants"]
BASE_ENUMS["通用枚举<br/>HasValueEnum / StatusEnum"]
RESULT_ENUM["结果码枚举<br/>ResultCodeEnum"]
end
subgraph "认证模块 crm-auth"
AUTH_CONST["领域常量<br/>AuthConstants"]
AUTH_ENUMS["领域枚举<br/>DataScopeEnum / IdentityTypeEnum / MenuTypeEnum"]
end
subgraph "文件模块 crm-file"
FILE_CONST["领域常量<br/>FileConstants"]
end
AUTH_CONST --> BASE_ENUMS
FILE_CONST --> BASE_ENUMS
AUTH_ENUMS --> BASE_ENUMS
```

图表来源 
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)

## 核心组件
- 系统常量 CommonConstants
  - 作用：集中存放跨模块复用的系统级常量（如分页默认值、时间格式、缓存键前缀、消息头名等），避免魔法字符串散落各处。
  - 典型类别：分页参数默认值、日期时间格式、Redis Key 前缀、HTTP 请求头名称、通用开关或阈值等。
  - 使用建议：所有跨模块共享的“硬编码值”应优先从该处引用，禁止在业务代码中直接写死。

- 通用枚举 HasValueEnum
  - 作用：为“有值/无值”或“启用/禁用”等二元状态提供统一抽象，便于在不同实体字段上复用一致的语义。
  - 设计要点：通常包含取值与显示文本映射，并提供按值查找、按显示文本查找等方法；保持枚举实例不可变且稳定。
  - 使用场景：布尔型字段的替代方案，利于前端展示与国际化扩展。

- 通用枚举 StatusEnum
  - 作用：统一表示对象生命周期或运行状态（如正常、停用、删除等），确保全链路状态一致。
  - 设计要点：每个枚举项需具备稳定的 code/value 与可读描述；提供按值查询、排序顺序等辅助方法。
  - 使用场景：数据表中的状态列、接口返回的状态字段、流程控制的条件判断。

- 结果码枚举 ResultCodeEnum
  - 作用：统一 API 响应码与消息，保证前后端对错误语义的一致性。
  - 设计要点：code 唯一且稳定，message 清晰可定位问题；必要时支持参数化消息模板。

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)

## 架构总览
下图展示了常量与枚举在各模块间的分布与复用关系。基础模块提供“最小可用”的通用定义，业务模块按需扩展领域常量与枚举，并通过引用实现解耦。

```mermaid
classDiagram
class CommonConstants {
+系统常量集合
}
class HasValueEnum {
+取值
+显示文本
+按值获取
}
class StatusEnum {
+状态码
+状态描述
+按值获取
}
class ResultCodeEnum {
+响应码
+响应消息
}
class AuthConstants {
+认证域常量
}
class FileConstants {
+文件域常量
}
class DataScopeEnum {
+数据范围
}
class IdentityTypeEnum {
+身份类型
}
class MenuTypeEnum {
+菜单类型
}
AuthConstants --> HasValueEnum : "可能复用"
AuthConstants --> StatusEnum : "可能复用"
FileConstants --> HasValueEnum : "可能复用"
FileConstants --> StatusEnum : "可能复用"
DataScopeEnum --> HasValueEnum : "可能复用"
IdentityTypeEnum --> HasValueEnum : "可能复用"
MenuTypeEnum --> HasValueEnum : "可能复用"
```

图表来源 
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)

## 详细组件分析

### CommonConstants（系统常量）
- 职责边界
  - 集中管理跨模块共享的“不变量”，降低散落的魔法字符串与数字带来的维护成本。
  - 作为团队约定的一部分，约束输入输出、缓存键、日志标记、配置键等。
- 常见分类
  - 分页与排序：默认页大小、最大页大小、默认排序字段等
  - 时间与格式：日期时间格式、时区、序列化策略等
  - 缓存与键空间：Redis Key 前缀、过期时间默认值等
  - HTTP 与网关：请求头名称、跨域策略、限流键前缀等
  - 业务阈值：文件大小限制、重试次数、超时时间等
- 使用建议
  - 新增常量必须补充注释，说明用途与变更历史
  - 避免将易变的业务规则放入常量，必要时改为配置项
  - 对敏感信息（密钥、令牌）严禁以明文常量形式存在

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)

### HasValueEnum（有值/无值枚举）
- 设计原则
  - 语义清晰：用枚举表达“有值/无值”或“启用/禁用”，避免裸布尔值歧义
  - 可扩展性：预留 displayText、sortOrder 等字段，便于前端展示与排序
  - 稳定性：code/value 一旦发布不得随意变更，如需调整需兼容迁移
- 常用方法
  - 按值获取枚举实例
  - 校验值是否合法
  - 获取显示文本或国际化 key
- 使用场景
  - 实体类中的布尔型字段替代
  - 表单校验与下拉选项生成
  - 与前端字典联动

章节来源
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)

### StatusEnum（状态枚举）
- 设计原则
  - 状态机思维：明确初始态、流转规则与终态
  - 一致性：数据库、接口、日志、监控均使用同一套状态码
  - 可观测性：状态变化需可追踪，配合审计日志
- 常用方法
  - 按值获取枚举实例
  - 判断是否为有效状态
  - 获取状态描述用于展示
- 使用场景
  - 订单、审批、任务等业务流程状态
  - 资源的生命周期（启用/停用/删除）
  - 对外 API 的状态码映射

章节来源
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)

### ResultCodeEnum（结果码枚举）
- 设计原则
  - 全局唯一：code 不重复、不重用
  - 语义明确：message 能直接指导排错
  - 版本兼容：新增 code 不应破坏既有调用方
- 使用场景
  - 统一 API 响应体
  - 错误码与监控告警关联
  - 前端错误提示文案来源

章节来源
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)

### 领域常量与枚举（认证与文件）
- AuthConstants
  - 职责：认证域内的固定键名、令牌前缀、会话标识等
  - 使用：登录、鉴权、第三方接入等流程
- FileConstants
  - 职责：文件上传分片、存储路径、预览服务等固定配置
  - 使用：分片上传、断点续传、在线预览等流程
- DataScopeEnum / IdentityTypeEnum / MenuTypeEnum
  - 职责：数据权限范围、身份类型、菜单类型等
  - 使用：权限模型、菜单树构建、数据隔离

章节来源
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)

## 依赖关系分析
- 耦合度
  - 常量与枚举本身无运行时依赖，仅被其他模块引用
  - 业务逻辑通过引用常量/枚举减少硬编码，提升内聚性
- 扩展性
  - 新增枚举项不影响既有调用方（只要不改变既有 code/value）
  - 常量变更需评估影响面，必要时提供兼容层或迁移脚本

```mermaid
graph LR
COMMON["CommonConstants"] --> AUTH["AuthConstants"]
COMMON --> FILE["FileConstants"]
HAS["HasValueEnum"] --> AUTH_ENUMS["认证枚举"]
STATUS["StatusEnum"] --> AUTH_ENUMS
HAS --> FILE_ENUMS["文件枚举(如有)"]
STATUS --> FILE_ENUMS
```

图表来源 
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)

## 性能考虑
- 枚举与常量均为编译期常量或轻量运行时对象，开销极低
- 避免在热点路径频繁解析枚举显示文本，建议缓存或预取
- 对大体积常量集合（如字典表）建议使用懒加载或外部配置中心

## 故障排查指南
- 常见问题
  - 使用了未定义的枚举值导致空指针或分支遗漏
  - 常量拼写不一致导致缓存键冲突或请求头丢失
  - 修改了已有枚举 code/value 造成下游解析失败
- 排查步骤
  - 检查枚举按值获取方法的健壮性与空值处理
  - 核对常量引用位置，确认是否存在多处不一致
  - 查看日志中的状态码与消息，定位具体环节
- 修复建议
  - 增加单元测试覆盖枚举与常量的关键路径
  - 引入静态扫描或契约测试，防止破坏性变更

章节来源
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)

## 结论
- 统一的常量与枚举是系统可维护性的基石
- 通过 CommonConstants、HasValueEnum、StatusEnum 等基础构件，结合各领域的常量与枚举，形成清晰的层次与复用机制
- 遵循命名规范与设计原则，可有效降低沟通成本与回归风险

## 附录：扩展指南

### 新增系统常量（CommonConstants）
- 适用场景
  - 跨模块共享的固定值（如分页默认值、时间格式、缓存前缀、请求头名等）
- 步骤
  - 在 CommonConstants 中添加常量，给出清晰注释与用途说明
  - 在业务代码中替换原有硬编码引用
  - 更新相关文档与测试用例
- 注意事项
  - 避免将易变规则放入常量，必要时改为配置项
  - 对敏感信息严禁以明文常量形式存在

章节来源
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)

### 新增通用枚举（HasValueEnum / StatusEnum）
- 适用场景
  - 需要统一语义的二元或多值状态（如启用/停用、有值/无值）
- 步骤
  - 在对应枚举中新增枚举项，确保 code/value 唯一且稳定
  - 完善按值获取、校验、显示文本等方法
  - 在实体与接口中使用新枚举替代裸值
- 注意事项
  - 已发布枚举项不得随意变更 code/value
  - 新增枚举项需同步更新前端字典与测试用例

章节来源
- [HasValueEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/HasValueEnum.java)
- [StatusEnum.java](file://crm-base/src/main/java/com/crm/base/domain/enums/StatusEnum.java)

### 新增领域常量与枚举（认证/文件）
- 适用场景
  - 特定业务域的固定键名、类型、范围等
- 步骤
  - 在对应模块的 constant 或 enums 包下新增
  - 尽量复用基础枚举（HasValueEnum/StatusEnum）表达通用语义
  - 在控制器、服务层统一引用，避免散落
- 注意事项
  - 保持命名一致性与可读性
  - 与接口文档保持一致，避免前后端不一致

章节来源
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [FileConstants.java](file://crm-file/src/main/java/com/crm/file/constant/FileConstants.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)

### 命名规范与设计原则
- 命名规范
  - 常量：全大写+下划线分隔，语义明确（如 PAGE_DEFAULT_SIZE、DATE_TIME_FORMAT）
  - 枚举：名词短语，首字母大写（如 StatusEnum、HasValueEnum）
  - 枚举项：全大写+下划线（如 ENABLED、DISABLED、DELETED）
- 设计原则
  - 单一职责：一个枚举只表达一类语义
  - 稳定优先：code/value 一旦发布不得破坏性变更
  - 可观测性：枚举项需具备可读描述，便于日志与监控
  - 可扩展性：预留排序、显示文本、国际化 key 等扩展点

[本节为概念性内容，不直接分析具体文件]