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

---
name: "add-enum-field"
description: "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/`

```java
@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

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

## 枚举设计规范

### 基本结构
```java
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;
}
```

### 实用方法（可选）

```java
/**
 * 根据类型值获取枚举
 */
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 模块**：

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

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

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

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

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