어노테이션 레퍼런스

엔티티 어노테이션

@QfEntity

클래스를 Q-Framework 엔티티로 선언합니다. 도메인 엔티티 클래스에 선언합니다.

java

@QfEntity(
    appKey = "app",
    name = @QfI18n(
        defaultMessage = "Product",
        texts = { @QfI18nText(locale = "ko", message = "상품") }
    ),
    autoHistoryEnabled = false,
    deletePolicy = @QfCrudPolicy(enabled = true),
    capabilityKey = "product-management"
)
public class ProductEntity { }

속성	타입	설명	기본값
`appKey`	String	소속 클라이언트 앱 키	`""` (선언된 앱 사용)
`name`	@QfI18n	다국어 표시명	`@QfI18n(texts = {})`
`autoHistoryEnabled`	boolean	자동 변경 이력 활성화	`false`
`deletePolicy`	@QfCrudPolicy	삭제 작업 정책	`@QfCrudPolicy(enabled = false)`
`treePolicy`	@QfTreePolicy	트리/계층 구조 설정	`@QfTreePolicy` (비활성)
`organizationPolicy`	@QfOrganizationPolicy	조직 기반 데이터 필터링	`@QfOrganizationPolicy(enabled = false)`
`masterRelation`	@QfMasterRelation	마스터-디테일 관계	`@QfMasterRelation(enabled = false)`
`capabilityKey`	String	연결된 Capability 키	`""` (클래스명에서 도출)
`excelDownloadable`	boolean	Excel 내보내기 엔드포인트 활성화	`true`
`excelUploadable`	boolean	Excel 가져오기 엔드포인트 활성화	`true`

@QfClientApp

클라이언트 앱을 선언합니다. 설정 클래스에 선언합니다.

java

@QfClientApp(
    key = "app",
    name = @QfI18n(
        defaultMessage = "App",
        texts = { @QfI18nText(locale = "ko", message = "일반 앱") }
    )
)
public class AppConfig { }

속성	타입	필수	설명
`key`	String	✅	클라이언트 앱 고유 키
`name`	@QfI18n		다국어 표시명

Capability / 권한 어노테이션

@QfCapability

업무 기능 영역(Capability)을 선언합니다. 전용 클래스에 선언합니다.

java

@QfCapability(
    key = "product-management",
    name = @QfI18n(defaultMessage = "Product Management", texts = {}),
    entities = { ProductEntity.class },
    privileges = {
        @QfPrivilege(key = "product-management__create"),
        @QfPrivilege(key = "product-management__delete")
    }
)
public final class ProductManagementCapability { }

속성	타입	필수	설명
`key`	String	✅	고유 Capability 키
`name`	@QfI18n		다국어 표시명
`entities`	Class[]		관리하는 주요 엔티티 클래스 목록
`privileges`	@QfPrivilege[]		이 Capability에서 정의하는 권한 목록

엔티티는 엔티티 클래스에 @QfCapability를 선언하는 것이 아니라, @QfEntity(capabilityKey = "...")를 통해 Capability에 연결됩니다.

@QfPrivilege

@QfCapability 내에서 권한 단위를 선언합니다.

java

@QfPrivilege(
    key = "product-management__create",
    name = @QfI18n(defaultMessage = "Create Product", texts = {})
)

속성	타입	필수	설명
`key`	String	✅	고유 키 (Capability 내 유니크)
`name`	@QfI18n		다국어 표시명

보안 어노테이션

@QfCrypto

필드를 자동 암호화/복호화 처리합니다. 필드에 선언합니다.

java

@QfCrypto
private String email;

제약

@QfSearch와 함께 사용 불가 (컴파일 오류)

@QfOrganizationPolicy (요소 어노테이션)

조직 기반 데이터 필터링을 설정합니다. @QfEntity 안에서 요소로 사용합니다:

java

@QfEntity(
    organizationPolicy = @QfOrganizationPolicy(
        enabled = true,
        attribute = "orgId"   // 조직 ID를 담고 있는 필드명
    )
)

속성	타입	설명	기본값
`enabled`	boolean	조직 필터링 활성화	`true`
`attribute`	String	조직 ID를 담는 필드명	`""`
`include`	QfOrganizationInclude	탐색 방향	`ANCHOR_ONLY`

검증 어노테이션

@QfValidationRule

필드에 검증 규칙을 선언합니다. 반복 선언 가능.

java

@QfValidationRule(
    rule = QfValidationRule.Rule.regex,
    params = "^[A-Za-z0-9_]+$",
    invalidValueMessageKey = "validation.loginId.invalid"
)
private String loginId;

속성	타입	필수	설명
`rule`	Rule	✅	검증 규칙 타입
`params`	String[]		규칙 파라미터 (`regex`의 경우 패턴)
`invalidValueMessageKey`	String		오류 메시지 키
`invalidValueMessages`	@QfI18n		인라인 오류 메시지
`serverOnly`	boolean		서버 측 전용 검증
`applyOn`	@QfConditionExpr[]		규칙 적용 조건

Rule 열거값:

규칙	설명	params
`regex`	커스텀 정규식	`params[0]` = 패턴
`unique`	서버 중복 검사	`params[0]` = URL (선택)
`login_id`	로그인 ID 형식 (설정에서 가져옴)	—
`user_pwd`	비밀번호 정책 (설정에서 가져옴)	—

화면 노출 어노테이션

@QfListAttribute

목록 화면에 컬럼으로 표시합니다.

java

@QfListAttribute(sortable = true)
private String name;

속성	타입	기본값	설명
`sortable`	boolean	`false`	정렬 가능 여부
`isTreeNodeTitle`	boolean	`false`	트리 노드 제목으로 사용
`isTreeNodeSubTitle`	boolean	`false`	트리 노드 부제목으로 사용
`cannotHide`	boolean	`false`	사용자가 컬럼 숨김 방지
`buttons`	@QfButton[]	`{}`	행 단위 액션 버튼
`exposeOn`	@QfExposeOn[]	`{}`	앱/Capability 가시성 규칙

@QfDetailAttribute

상세 조회 화면에 표시합니다.

java

@QfDetailAttribute
private String name;

@QfCreateAttribute

등록 폼에 입력 필드로 표시합니다.

java

@QfCreateAttribute(
    requiredOn = @QfRequiredOn(always = true)
)
private String name;

속성	타입	설명
`requiredOn`	@QfRequiredOn	필수 규칙
`readonlyOn`	@QfReadonlyOn	읽기 전용 규칙
`initialValue`	String	정적 초기값
`showOn`	@QfConditionExpr[]	표시 조건
`disableOn`	@QfConditionExpr[]	비활성화 조건

@QfUpdateAttribute

수정 폼에 입력 필드로 표시합니다. @QfCreateAttribute와 동일한 속성을 가집니다.

@QfSearch

목록 화면의 검색 조건으로 활성화합니다.

java

@QfSearch(type = QfSearch.Type.text)
private String name;

@QfSearch(type = QfSearch.Type.select)
private String status;

타입	설명
`auto`	필드 타입 기반 자동 감지
`text`	일반 텍스트 입력
`select`	단일 선택 드롭다운
`true_or_false`	불리언 토글
`multiselect`	다중 선택
`period_date`	날짜 범위
`period_datetime`	날짜시간 범위

@QfDisplayLabel

필드의 표시 레이블을 설정합니다.

java

@QfDisplayLabel(text = "Product Name")
private String name;

@QfDisplayLabel(key = "label.product.name")   // 메시지 리소스에서 조회
private String name;

속성	설명
`key`	i18n 조회용 메시지 리소스 키
`text`	리터럴 레이블 텍스트 (대체값)

@QfControlType

필드의 UI 컨트롤 타입을 선언합니다.

java

@QfControlType(QfControlType.Type.email)
private String email;

@QfControlType(QfControlType.Type.textarea)
private String description;

구조 어노테이션

@QfMasterRelation (요소 어노테이션)

마스터-디테일 관계를 선언합니다. @QfEntity 안에서 요소로 사용합니다:

java

@QfEntity(
    masterRelation = @QfMasterRelation(
        enabled = true,
        masterEntityFqcn = "com.example.OrderEntity",
        masterKeyAttribute = "orderId",
        onMasterDelete = QfMasterRelation.OnMasterDelete.CASCADE_DELETE
    )
)
public class OrderItemEntity { }

`onMasterDelete`	설명
`CASCADE_DELETE`	마스터 삭제 시 디테일 레코드 자동 삭제
`RESTRICT`	디테일이 존재하면 마스터 삭제 거부
`IGNORE`	디테일 레코드를 고아 상태로 유지

@QfParent / @QfTreeDepth / @QfChildren

트리 구조 필드를 선언합니다.

java

@QfParent
private String parentId;

@QfTreeDepth
private Integer depth;

@QfChildren
private List<CategoryEntity> children;

@QfGroup

관련 필드를 UI에서 그룹으로 묶습니다.

java

@QfGroup(key = "address_info")
private String address;

@QfGroup(key = "address_info")
private String zipCode;

감사 추적 어노테이션

프레임워크가 쓰기 시점에 자동으로 채웁니다:

어노테이션	설명
`@QfRgsOperId`	등록자 ID 자동 기록
`@QfRgsOperDt`	등록일시 자동 기록
`@QfRgsOperIp`	등록자 IP 주소 자동 기록
`@QfUpdtOperId`	최종 수정자 ID 자동 기록
`@QfUpdtOperDt`	최종 수정일시 자동 기록
`@QfUpdtOperIp`	수정자 IP 주소 자동 기록
`@QfDeleteOperId`	삭제자 ID 자동 기록
`@QfDeleteOperDt`	삭제일시 자동 기록
`@QfDeleteFlag`	소프트 삭제 표시

결과 코드 어노테이션

@QfResultCode

결과 코드를 선언합니다. 인터페이스에 선언합니다.

java

@QfResultCode(
    code = "PRODUCT_NOT_FOUND",
    httpStatus = 404,
    message = "Product not found.",
    resolution = "Check the product ID and retry."
)
public interface ProductResultCode { }

자세한 내용은 결과 코드 레퍼런스를 참고하세요.

다국어 어노테이션

@QfI18n

다국어 메시지 번들을 선언합니다. 다른 어노테이션 안에서 요소로 사용합니다.

java

@QfI18n(
    defaultMessage = "Product Name",
    texts = {
        @QfI18nText(locale = "ko", message = "상품명"),
        @QfI18nText(locale = "ja", message = "商品名")
    },
    key = "entity.product.name.label",   // 선택 사항; 비어 있으면 자동 생성
    sync = false
)

속성	타입	설명
`defaultMessage`	String	로케일 불일치 시 대체 텍스트
`texts`	@QfI18nText[]	로케일별 메시지
`key`	String	메시지 조회 키 (비어 있으면 자동 생성)
`sync`	boolean	시작 시마다 소스와 동기화

@QfI18nText

@QfI18n 번들 내 하나의 로케일별 메시지입니다.

java

@QfI18nText(locale = "ko", message = "상품명")

@QfDisplayHint

필드의 힌트(툴팁 / 플레이스홀더)를 선언합니다.

java

@QfDisplayHint(
    i18n = @QfI18nText(locale = "en", message = "Enter the product name")
)
private String name;

어노테이션 레퍼런스 ​

엔티티 어노테이션 ​

@QfEntity ​

@QfClientApp ​

Capability / 권한 어노테이션 ​

@QfCapability ​

@QfPrivilege ​

보안 어노테이션 ​

@QfCrypto ​

@QfOrganizationPolicy (요소 어노테이션) ​

검증 어노테이션 ​

@QfValidationRule ​

화면 노출 어노테이션 ​

@QfListAttribute ​

@QfDetailAttribute ​

@QfCreateAttribute ​

@QfUpdateAttribute ​

@QfSearch ​

@QfDisplayLabel ​

@QfControlType ​

구조 어노테이션 ​

@QfMasterRelation (요소 어노테이션) ​

@QfParent / @QfTreeDepth / @QfChildren ​

@QfGroup ​

감사 추적 어노테이션 ​

결과 코드 어노테이션 ​

@QfResultCode ​

다국어 어노테이션 ​

@QfI18n ​

@QfI18nText ​

@QfDisplayHint ​

어노테이션 레퍼런스

엔티티 어노테이션

@QfEntity

@QfClientApp

Capability / 권한 어노테이션

@QfCapability

@QfPrivilege

보안 어노테이션

@QfCrypto

@QfOrganizationPolicy (요소 어노테이션)

검증 어노테이션

@QfValidationRule

화면 노출 어노테이션

@QfListAttribute

@QfDetailAttribute

@QfCreateAttribute

@QfUpdateAttribute

@QfSearch

@QfDisplayLabel

@QfControlType

구조 어노테이션

@QfMasterRelation (요소 어노테이션)

@QfParent / @QfTreeDepth / @QfChildren

@QfGroup

감사 추적 어노테이션

결과 코드 어노테이션

@QfResultCode

다국어 어노테이션

@QfI18n

@QfI18nText

@QfDisplayHint