ERPTurbo_Server/.claude/skills/add-enum-field/SKILL.md

name	description
Add Enum Field	Add enum field to ERPTurbo project entities following DDD layered architecture. Automatically creates enum class, updates DO, VO, Cmd, and Domain Entity with proper type mapping and MyBatis annotations.

Add Enum Field

为 ERPTurbo 项目实体添加枚举字段，遵循 DDD 分层架构规范。

⚠️ 重要规则

仅操作 erp-turbo-business 模块，禁止修改 erp-turbo-svc 模块！

详见：.claude/PROJECT_RULES.md

工作流程

输入格式

Enum: EnumName | value1:description1, value2:description2, ... | fieldName | fieldComment

示例：

Enum: DealerAccountRecordTargetType | 1:产地采购发货单,2:市场采购发货单,3:市场调货发货单 | targetType | 变动类型

工作流程

1. 创建枚举类

路径：erp-turbo-api/src/main/java/com/xunhong/erp/turbo/api/biz/dto/enums/

@Getter
@RequiredArgsConstructor
public enum YourEnumName {
    VALUE1(1, "描述1"),
    VALUE2(2, "描述2");

    @EnumValue
    private final Integer type;

    private final String message;
}

2. 更新相关文件（仅限 erp-turbo-business 模块）

文件路径	类型	修改内容
erp-turbo-business/erp-turbo-biz/.../entity/*DO.java	Entity	添加枚举类型字段 + @TableField
erp-turbo-common/erp-turbo-api/.../vo/*VO.java	VO	添加枚举类型字段 + @Schema
erp-turbo-common/erp-turbo-api/.../cmd/*CreateCmd.java	CMD	添加枚举类型字段 + @Schema
erp-turbo-common/erp-turbo-api/.../cmd/*UpdateCmd.java	CMD	添加枚举类型字段 + @Schema
erp-turbo-business/erp-turbo-biz/.../domain/entity/*.java	Domain Entity	添加枚举类型字段

⚠️ 禁止修改 erp-turbo-svc/ 下的任何文件！

3. 生成 DDL

ALTER TABLE table_name
ADD COLUMN field_name TINYINT COMMENT 'field comment';

枚举设计规范

基本结构

package com.xunhong.erp.turbo.api.biz.dto.enums;

import com.baomidou.mybatisplus.annotation.EnumValue;
import lombok.Getter;
import lombok.RequiredArgsConstructor;

@Getter
@RequiredArgsConstructor
public enum YourEnum {
    /**
     * 枚举值1
     */
    VALUE1(1, "描述1"),

    /**
     * 枚举值2
     */
    VALUE2(2, "描述2");

    @EnumValue
    private final Integer type;

    private final String message;
}

实用方法（可选）

/**
 * 根据类型值获取枚举
 */
public static YourEnum fromType(Integer type) {
    if (type == null) {
        return null;
    }
    for (YourEnum value : values()) {
        if (value.type.equals(type)) {
            return value;
        }
    }
    return null;
}

/**
 * 根据其他枚举转换
 */
public static YourEnum fromOtherEnum(OtherEnum other) {
    if (other == null) {
        return null;
    }
    return switch (other) {
        case OTHER_VALUE1 -> VALUE1;
        case OTHER_VALUE2 -> VALUE2;
        default -> null;
    };
}

数据库类型映射

枚举值数量	数据库类型	Java 类型
1-10	TINYINT	Integer + 枚举
11-100	SMALLINT	Integer + 枚举
100+	INT	Integer + 枚举

使用示例

示例 1：简单状态枚举

Enum: AuditState | 1:待审核,2:审核中,3:审核成功,4:审核驳回,5:审核取消 | state | 审核状态

示例 2：带转换方法的枚举

Enum: DealerAccountRecordTargetType | 1:产地采购发货单,2:市场采购发货单,3:市场调货发货单 | targetType | 变动类型

注意事项

1. @EnumValue 注解：MyBatis-Plus 需要此注解来识别数据库存储的枚举值
2. Integer 类型：枚举的存储值使用 Integer 而非 int，避免空值问题
3. 命名规范：
   • 枚举类名：PascalCase + Enum 后缀（可选）
   • 枚举值：UPPER_SNAKE_CASE
4. null 处理：转换方法中正确处理 null 值
5. 业务逻辑：复杂转换逻辑放在枚举类的静态方法中，保持业务代码整洁

输出示例

✅ 已完成枚举字段添加
========================================
创建文件:
✅ api/.../enums/YourEnum.java (erp-turbo-common)

更新文件:
✅ biz/.../entity/YourEntityDO.java (erp-turbo-business)
✅ api/.../vo/YourEntityVO.java (erp-turbo-common)
✅ api/.../cmd/YourEntityCreateCmd.java (erp-turbo-common)
✅ api/.../cmd/YourEntityUpdateCmd.java (erp-turbo-common)
✅ biz/.../domain/entity/YourEntity.java (erp-turbo-business)

⚠️ 请执行数据库迁移:
ALTER TABLE your_table
ADD COLUMN your_field TINYINT COMMENT 'your comment';

文件搜索规则

使用 Glob 工具时，必须限制在 erp-turbo-business 模块：

# ✅ 正确：限定路径
erp-turbo-business/**/*.java
erp-turbo-common/**/*.java

# ❌ 错误：会匹配到 svc 模块
**/*OrderShip*.java

使用 Grep 工具时，排除 erp-turbo-svc 目录：

# ✅ 正确：指定路径
grep -r "pattern" erp-turbo-business/ erp-turbo-common/

# ❌ 错误：搜索所有目录
grep -r "pattern" .