실행 생명주기

Q-Framework는 3단계 생명주기를 통해 선언에서 실행까지 처리합니다.

전체 흐름

작성 시점          컴파일 시점          실행환경
(Authoring)   →  (Compile-time)  →   (Runtime)

개발자 선언        APT 처리             메타데이터 로딩
어노테이션 작성     계약 검증             레지스트리 구성
                  메타데이터 생성        요청 처리 자동화

---

1단계: 작성 시점 (Authoring Time)

개발자가 어노테이션으로 도메인 계약을 선언하는 단계입니다.

// 이것이 전부입니다 — 개발자가 선언해야 할 내용
@QfEntity(
    appKey = "app",
    name = @QfI18n(defaultMessage = "Product", texts = { @QfI18nText(locale = "ko", message = "상품") }),
    autoHistoryEnabled = true
)
@QfCapability(key = "product_management")
public class ProductEntity {

    @QfListAttribute(sortable = true)
    @QfDetailAttribute
    @QfCreateAttribute(requiredOn = @QfRequiredOn(always = true))
    @QfUpdateAttribute
    @QfSearch
    @QfDisplayLabel(text = "Product Name")
    private String name;

    @QfListAttribute(sortable = true)
    @QfDetailAttribute
    @QfCreateAttribute
    @QfUpdateAttribute
    @QfDisplayLabel(text = "Price")
    private Integer price;
}

Q-Framework의 역할 (작성 시점):

• 어노테이션 정의 제공
• IDE 코드 완성 및 문서 제공
• 어노테이션 작성 시 즉각적인 오류 표시 (IDE 플러그인)

---

2단계: 컴파일 시점 (Compile-time)

Java APT(Annotation Processing Tool, JSR-269)가 동작하는 단계입니다.

처리 순서

1. 소스 파일 파싱
       ↓
2. @QfEntity 탐색
       ↓
3. 각 어노테이션 핸들러 실행
       ↓
4. 계약 검증 (Fail-Fast)
   - 어노테이션 조합 규칙 검사
   - 타입 호환성 검사
   - 필수 속성 누락 검사
       ↓
   검증 실패 → 컴파일 오류 발생 → 빌드 중단
       ↓
5. 메타데이터 JSON 생성
       ↓
6. 레지스트리 인덱스 생성
       ↓
7. 결과 코드 상수 클래스 생성

생성되는 산출물

META-INF/
  qframework/
    entities/
      app.product.json          ← 엔티티 메타데이터
    capabilities/
      app.product_management.json  ← Capability 메타데이터
    index/
      entity-index.json         ← 엔티티 레지스트리 인덱스
      capability-index.json     ← Capability 레지스트리 인덱스

메타데이터 JSON 예시

{
  "schemaVersion": "1.0",
  "appKey": "app",
  "name": "product",
  "i18n": {
    "defaultMessage": "Product",
    "texts": [{ "locale": "ko", "message": "상품" }]
  },
  "autoHistoryEnabled": true,
  "fields": [
    {
      "name": "name",
      "type": "STRING",
      "label": "Product Name",
      "validations": [
        { "type": "REQUIRED" }
      ],
      "display": {
        "list": { "sortable": true },
        "detail": true,
        "create": true,
        "update": true,
        "search": true
      }
    }
  ]
}

이 파일은 수동으로 수정하면 안 됩니다. SSOT(어노테이션)에서 결정론적으로 생성되는 복사본입니다.

---

3단계: 실행환경 (Runtime)

컴파일된 메타데이터를 기반으로 실제 서비스를 제공하는 단계입니다.

초기화 흐름

애플리케이션 시작
      ↓
META-INF/qframework/index/*.json 로딩
      ↓
엔티티 레지스트리 구성
      ↓
Capability / Privilege 레지스트리 구성
      ↓
SPI 구현체 탐색 및 등록
  - QfUserProvider
  - QfOrganizationProvider
  - QfRuntimeInitializationHook
      ↓
API 라우팅 자동 등록
  - /api/{appKey}/{entityName}/**
      ↓
QfRuntimeInitializationHook.onAfterInitialize() 실행
      ↓
서비스 준비 완료

요청 처리 파이프라인

HTTP 요청 수신
      ↓
[1] 라우팅
    엔티티명 + 액션 파악
      ↓
[2] 인증 / 인가
    QfUserProvider.getCurrentUser()
    Privilege 확인
      ↓
[3] 입력 검증
    메타데이터 기반 검증 규칙 적용
    (@QfCreateAttribute requiredOn, @QfValidationRule 등)
      ↓
[4] Before 훅 실행
    @QfOn(event = BEFORE_CREATE) 등
      ↓
[5] 조직 범위 적용
    조직 정책 기반 필터/자동 설정
      ↓
[6] 데이터 처리
    저장 시: @QfCrypto 암호화
    조회 시: @QfCrypto 복호화
    자동 기록: @QfCreatedBy, @QfCreatedAt 등
      ↓
[7] After 훅 실행
    @QfOn(event = AFTER_CREATE) 등
      ↓
[8] 응답 반환
    표준 QfApiResponse 형식

표준 응답 형식

{
  "success": true,
  "code": "SUCCESS",
  "data": { ... },
  "pagination": {
    "page": 1,
    "size": 20,
    "totalElements": 150,
    "totalPages": 8
  }
}

---

3단계 요약

단계	Q-Framework 역할	개발자 역할
작성 시점	어노테이션 정의 제공	도메인 선언
컴파일 시점	계약 검증 + 메타데이터 생성	(없음)
실행환경	메타데이터 기반 자동 처리	SPI 구현 (필요 시)

---

다음 단계

• 어노테이션 레퍼런스 — 전체 어노테이션 목록
• SPI 확장 — 런타임 확장 포인트