모듈 구조

Q-Framework는 계층별로 모듈이 분리되어 있습니다. 각 계층은 단방향 의존성 원칙을 따릅니다.

아키텍처 계층

┌─────────────────────────────────────────────────────────┐
│                  응용 계층 (Application Layer)            │
│       (개발자가 작성하는 엔티티, Capability, 훅)           │
├─────────────────────────────────────────────────────────┤
│              Q-Framework 계층 (Q-Framework Layer)        │
│         (q-apt-*, q-context, q-runtime, q-util)         │
├─────────────────────────────────────────────────────────┤
│               Q-어댑터 계층 (Q-Adapter Layer)            │
│         (q-spring-jpa, q-spring-boot, q-spring-webmvc)  │
├─────────────────────────────────────────────────────────┤
│         호스트 프레임워크 계층 (Host Framework Layer)      │
│              (Spring Boot, Spring MVC, JPA)             │
├─────────────────────────────────────────────────────────┤
│                  인프라 계층 (Infrastructure Layer)       │
│                  (DB, 파일 시스템, 메시지 큐)             │
└─────────────────────────────────────────────────────────┘

의존성 방향: 위 → 아래 (단방향)

Q-Framework 계층은 호스트 프레임워크에 의존하지 않습니다. 어댑터 계층이 그 연결을 담당합니다.

---

백엔드 모듈 목록

Q-Framework 핵심 계층

모듈	역할
q-apt-entity	@QfEntity 및 엔티티 필드 어노테이션 처리 (APT)
q-apt-capability	@QfCapability, @QfPrivilege 처리 (APT)
q-apt-result-code	@QfResultCode 처리 및 코드 상수 생성 (APT)
q-context	요청 컨텍스트, 사용자 정보, 조직 정보 관리
q-runtime	메타데이터 로딩, 레지스트리, CRUD 파이프라인
q-util	공통 유틸리티, 암호화, 직렬화
q-management	CLI, 운영 도구 서버

Q-어댑터 계층

모듈	역할
q-spring-boot	Spring Boot Auto-configuration 제공
q-spring-webmvc	Spring MVC 기반 API 엔드포인트 자동 등록
q-spring-jpa	JPA 기반 데이터 접근 구현

의존성 다이어그램 (백엔드)

애플리케이션 코드
    │
    ├── q-apt-entity (annotationProcessor)
    ├── q-apt-capability (annotationProcessor)
    │
    ├── q-context
    ├── q-runtime
    │       └── q-util
    │
    ├── q-spring-boot
    │       ├── q-runtime
    │       └── spring-boot-autoconfigure
    │
    ├── q-spring-webmvc
    │       └── spring-webmvc
    │
    └── q-spring-jpa
            └── spring-data-jpa

---

프론트엔드 모듈

프론트엔드 모듈은 npm 패키지로 제공됩니다 (@softminds 스코프).

모듈	역할
@softminds/q-ui-runtime	백엔드 메타데이터 API 연동, UI 렌더링 엔진
@softminds/q-coreui	UI 공통 컴포넌트 (특정 프레임워크 비의존)
@softminds/q-vue	Vue 3 어댑터
@softminds/q-nuxt	Nuxt 3 어댑터

프론트엔드 의존성 원칙

@softminds/q-coreui
    ← (의존하지 않음) @softminds/q-nuxt
    ← (의존하지 않음) @softminds/q-vue

q-coreui는 특정 UI 프레임워크에 의존하지 않습니다. q-vue와 q-nuxt가 각각 어댑터 역할을 담당합니다.

Vue 3 사용 예시

<script setup>
import { QfEntityView, QfEntityForm } from '@softminds/q-vue'
</script>

<template>
  <!-- 목록/상세/등록/수정 화면 자동 렌더링 -->
  <QfEntityView client-app="app" entity="product" />
</template>

Nuxt 3 사용 예시

<!-- pages/products/index.vue -->
<script setup>
// Nuxt 자동 임포트
</script>

<template>
  <QfEntityView client-app="app" entity="product" />
</template>

---

의존성 방향 규칙

허용:     위 계층 → 아래 계층
금지:     아래 계층 → 위 계층
금지:     Q-Framework 계층 → 호스트 프레임워크 계층 (직접)
허용:     Q-Framework 계층 → 호스트 프레임워크 계층 (어댑터 경유)

이 규칙은 컴파일 시점 의존성 검사로 강제됩니다.

---

다음 단계

• 실행 생명주기 — 컴파일~런타임 처리 흐름
• SPI 확장 — 어댑터 계층 커스터마이징