ga-commission-system/ga-common/src/main/java/com/ga/common/annotation/ExcelColumn.java

package com.ga.common.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * 엑셀 컬럼 매핑 어노테이션. VO(데이터 클래스)의 필드에 붙여서 엑셀의 어느 열에 어떤 형식으로
 * 출력/입력될지를 선언한다.
 *
 * <p>왜 필요한가: 정산 데이터는 엑셀 내려받기/올리기가 잦다. 필드마다 헤더명·순서·서식을 코드로
 * 일일이 다루면 번거롭고 실수가 많으므로, 필드 위에 이 어노테이션만 달면 ExcelService(엑셀 처리기)가
 * 리플렉션으로 읽어 자동으로 엑셀을 생성/파싱한다.
 *
 * <p>어떻게 쓰이나: {@code ExcelColumnParser}가 VO의 각 필드에서 이 어노테이션을 읽어
 * {@code ExcelColumnInfo} 목록으로 변환하고, {@code ExcelService}가 그 목록으로 엑셀을 만든다.
 */
// @Target(FIELD): VO의 멤버 필드에만 붙인다.   @Retention(RUNTIME): 실행 중 리플렉션으로 읽으므로 필수.
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ExcelColumn {
    /** 엑셀 첫 행에 표시될 헤더(컬럼 제목). */
    String header();
    /** 컬럼 표시 순서(작을수록 왼쪽). */
    int order();
    /** 컬럼 너비(엑셀 단위). 기본 15. */
    int width() default 15;
    /** 셀 표시 서식(예: 날짜/숫자 포맷). 비우면 기본 서식. */
    String format() default "";
    /** 공통코드 그룹. 코드값을 사람이 읽는 코드명으로 변환해 표시할 때 사용. */
    String codeGroup() default "";
    /** true면 민감정보(주민번호 등)를 마스킹하여 출력. */
    boolean masked() default false;
    /** 값이 비어있을 때 채울 기본값. */
    String defaultValue() default "";
    /** true면 엑셀 업로드(임포트) 시 필수 입력 컬럼으로 검증. */
    boolean required() default false;
}