45-tablegen-enumgen

Status: ACTIVE
AppliesTo: v10
SSOT: skills/devian-core/03-ssot/SKILL.md

Overview

DATA 테이블(예: XLSX)의 Options Row(3번째 줄)에서 gen:<EnumName> 옵션을 선언하면:

1. •해당 컬럼(gen 컬럼)이 PK 컬럼이 된다 (gen 컬럼 = PK 컬럼).
2. •해당 컬럼의 각 row 값이 enum 멤버 이름(name) 이 된다.
3. •enum 멤버 값(value)은 결정적 자동 할당 (이름 오름차순 정렬 후 0부터 순차).
4. •TB 캐시에 Find(<EnumName> key) / TryFind(<EnumName> key) 헬퍼가 자동 생성된다.

Terminology

Hard Rules (MUST)

1. Gen Column = PK Column

• •gen:<EnumName> 옵션이 붙은 컬럼은 반드시 pk여야 한다.
• •즉, gen 컬럼 = PK 컬럼 (같은 컬럼).
• •gen 컬럼에 pk가 없으면 빌드 FAIL.
• •gen 컬럼은 테이블당 딱 1개만 허용한다 (2개 이상 FAIL).

2. Enum Member Name = Gen/PK Column Value

• •gen/PK 컬럼의 각 row 값이 enum 멤버 이름이 된다.
• •멤버 이름은 유효한 식별자여야 한다 (^[A-Za-z_][A-Za-z0-9_]*$).

3. Enum Member Value = Deterministic Auto-Assignment

enum 멤버 값은 결정적 자동 할당으로 생성된다:

1. •모든 멤버 이름을 오름차순(ASCII) 정렬한다.
2. •정렬된 순서대로 0부터 1씩 증가하는 int 값을 할당한다.

예시:

테이블 데이터: CriRate, AttackPower, MaxHealth
정렬 후:       AttackPower, CriRate, MaxHealth
할당 결과:     AttackPower=0, CriRate=1, MaxHealth=2

4. 식별자 규칙 위반은 실패

• •gen 컬럼 값(enum 멤버 이름)이 C#/TS 식별자 규칙을 위반하면 빌드 실패한다.
• •정규식: ^[A-Za-z_][A-Za-z0-9_]*$
• •자동 치환(공백→_, 특수문자 제거) 같은 "추측 기반 보정"은 금지한다.

5. 중복은 실패

• •enum 멤버 이름(gen 컬럼 값) 중복: FAIL

6. 결정적 출력

• •enum 멤버 나열 순서는 이름 오름차순으로 고정한다.
• •동일 입력에서 동일 출력이 보장되어야 한다.

7. Find/TryFind 헬퍼

• •TB_<n>.Find(<EnumName> key) / TryFind(<EnumName> key) 헬퍼가 생성된다.
• •keyType이 이미 enum:<EnumName>인 경우, 중복 오버로드는 생성하지 않는다.
• •Find/TryFind는 gen 테이블에만 생성된다.

Table Authoring Spec

Required Columns

Example: TB_COMPLEX_POLICY

Row 1 (Header):    key                      | fallbackValue | minValue | maxValue
Row 2 (Type):      enum:ComplexPolicyType   | Variant       | Variant  | Variant
Row 3 (Options):   pk, gen:ComplexPolicyType |              |          |
Row 4 (Comment):   (ignored)
Row 5+ (Data):     AttackPower              | i:0           | i:0      | i:10000
                   CriRate                  | f:0           | f:0      | f:3.5
                   MaxHealth                | i:100         | i:1      | i:99999

여기서:

• •key 컬럼 = PK = gen 컬럼 (같은 컬럼, 옵션: pk, gen:ComplexPolicyType)
• •key 컬럼의 값이 enum 멤버 이름
• •enum 값은 자동 할당: AttackPower=0, CriRate=1, MaxHealth=2 (이름 정렬 순)
• •Variant 컬럼은 NDJSON에서 {k, i|f|s} 오브젝트로 저장되며, i/f/s는 Complex shape(CInt/CFloat/CString)이다.

Output Artifacts

C# Enum

namespace Devian.Domain.Common
{
    public enum ComplexPolicyType : int
    {
        AttackPower = 0,
        CriRate = 1,
        MaxHealth = 2,
    }
}

C# TB Cache Find/TryFind

public static class TB_COMPLEX_POLICY
{
    // 기존 Get/TryGet 유지...

    // Find/TryFind - keyType이 enum이므로 기본 버전만 생성
    public static Row Find(ComplexPolicyType key) { ... }
    public static bool TryFind(ComplexPolicyType key, out Row? row) { ... }
}

TypeScript Enum

export enum ComplexPolicyType {
    AttackPower = 0,
    CriRate = 1,
    MaxHealth = 2,
}

TypeScript TB Cache find/tryFind

export class TB_COMPLEX_POLICY {
    // 기존 get/tryGet 유지...

    // keyType이 enum이므로 기본 버전만
    static find(key: ComplexPolicyType): Row { ... }
    static tryFind(key: ComplexPolicyType): Row | undefined { ... }
}

Failure Conditions (Build MUST fail)

DoD (Definition of Done)

• • gen:<EnumName> 옵션이 Options Row에서 파싱된다
• • gen 컬럼은 반드시 pk여야 한다 (gen = PK)
• • gen/PK 컬럼 값이 enum 멤버 이름으로 사용된다
• • enum 멤버 값이 이름 정렬 + 0..N-1 자동 할당된다
• • enum 코드(C#/TS)가 생성된다
• • enum 멤버 순서가 이름 오름차순으로 결정적이다
• • TB 캐시에 Find/TryFind 헬퍼가 생성된다 (gen 테이블만)
• • keyType이 enum이면 중복 오버로드를 생성하지 않는다
• • 식별자 위반/중복 시 빌드가 실패한다
• • key:true 또는 key 옵션 사용 시 빌드가 실패한다
• • 기존 테이블(gen 미사용)은 영향 없다

Reference

• •Table Authoring Rules: skills/devian-data/30-table-authoring-rules/SKILL.md
• •TableGen Implementation: skills/devian-data/42-tablegen-implementation/SKILL.md
• •Variant Feature: skills/devian-common/11-feature-variant/SKILL.md