Q-Framework 소개

Q-Framework는 도메인 메타데이터 기반 개발 프레임워크입니다. 어노테이션으로 도메인을 선언하면 CRUD API, UI, 검증, 권한 제어, 조직 기반 데이터 격리까지 자동으로 처리됩니다.

Human이 선언, AI가 구현, System이 강제 — 이것이 Q-Framework의 핵심 철학입니다.

Q-Framework가 해결하는 문제

전통적인 엔터프라이즈 개발에서는 동일한 패턴이 무한히 반복됩니다.

CRUD 보일러플레이트 폭발

하나의 엔티티를 위해 작성해야 하는 코드 목록:

• Entity 클래스
• Repository 인터페이스
• Service 클래스 (CRUD 메서드 × 4~6개)
• Controller 클래스 (API 엔드포인트 × 6개 이상)
• Request/Response DTO 다수
• 검증 로직 (Service 레이어 + Bean Validation)
• 프론트엔드 목록/상세/등록/수정 화면 × 4개
• API 연동 코드

이 중 실제 비즈니스 가치를 담은 코드는 10%도 되지 않습니다.

일관성 없는 검증

팀마다 다른 검증 방식, API마다 다른 오류 응답 형식, 서버-클라이언트 간 이중 검증의 비효율이 발생합니다.

중복된 권한 처리

화면, API, 데이터 필터링에 각각 별도로 구현되는 권한 로직은 수정 시 누락이 발생하기 쉽습니다.

개발자가 얻는 이점

기존 방식	Q-Framework
엔티티당 수백 줄 반복 코드	어노테이션 선언 하나
런타임에서야 발견되는 오류	컴파일 시점 Fail-Fast
팀마다 다른 구현 패턴	프레임워크가 강제하는 일관성
수동으로 관리하는 권한 규칙	선언 기반 자동 적용
AI가 만든 코드의 품질 보장 불가	동일한 계약 강제

Just 1 Entity — 자동으로 처리되는 것들

엔티티 하나를 선언하면 다음이 자동으로 처리됩니다.

@QfEntity(
    appKey = "app",
    name = @QfI18n(
        defaultMessage = "User",
        texts = { @QfI18nText(locale = "ko", message = "사용자") }
    ),
    organizationPolicy = @QfOrganizationPolicy(enabled = true, attribute = "organizationId"),
    capabilityKey = "user-management"
)
public class UserEntity {

    private String organizationId;   // 조직 필터 대상 (organizationPolicy.attribute에 선언)

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

    @QfDetailAttribute
    @QfCreateAttribute
    @QfCrypto
    @QfControlType(QfControlType.Type.email)
    @QfDisplayLabel(text = "Email")
    private String email;
}

백엔드 자동 처리:

• GET /api/app/users — 목록 조회 (페이지네이션, 검색 포함)
• GET /api/app/users/{id} — 상세 조회
• POST /api/app/users — 등록
• PUT /api/app/users/{id} — 수정
• DELETE /api/app/users/{id} — 삭제
• GET /api/app/users/history — 이력 조회
• GET /api/app/users/excel/download — Excel 다운로드
• POST /api/app/users/excel/upload — Excel 업로드
• 컴파일 시점 검증 규칙 강제
• 조직 범위 데이터 자동 필터링
• email 필드 자동 암호화/복호화

프론트엔드 자동 처리:

• 목록 화면 (검색, 정렬, 페이지네이션)
• 상세 화면
• 등록/수정 폼 (검증 포함)
• Excel 업로드/다운로드 UI

AI와의 협력 관계

Q-Framework는 AI 시대에 더욱 강력해집니다.

Human  →  "사용자 엔티티에 이메일 필드 추가, 암호화 필요"
  ↓
AI     →  @QfDetailAttribute @QfCrypto @QfControlType(Type.email) private String email; 코드 생성
  ↓
System →  컴파일 시점: @QfCrypto + @QfSearch 충돌 검사, 타입 검증
          런타임: 암호화 자동 적용

Q-Framework의 역할:

• Human의 의도를 어노테이션 계약으로 표현할 수 있게 함
• AI가 생성한 코드도 동일한 품질 게이트를 통과하도록 강제
• 어노테이션 위반, 정책 충돌은 컴파일 시점에 차단

AI가 틀린 코드를 생성해도, Q-Framework가 컴파일을 거부합니다.

Java 구현과 언어 독립성

현재 Q-Framework는 Java 기반으로 첫 번째 구현을 검증하고 있습니다.

핵심 패턴은 특정 언어에 종속되지 않습니다:

선언적 메타데이터 → 컴파일 시점 검증 → 런타임 자동화

구현 언어	선언 방식	컴파일 시점
Java	어노테이션 (APT/JSR-269)	Annotation Processor
TypeScript	데코레이터	tsc 플러그인
Kotlin	어노테이션 (KSP)	KSP Processor
Python	데코레이터	mypy 플러그인
Rust	매크로	매크로 확장

설계 원칙만 이식되면 됩니다 — 특정 언어 API가 아닙니다.

다음 단계

• 빠른 시작 — 5분 안에 첫 엔티티 실행하기
• 핵심 개념 — SSOT, 메타데이터 계약, 생명주기 이해하기
• 아키텍처 개요 — 내부 구조 깊게 이해하기