도메인 모듈

도메인 모듈은 하나의 도메인(예: User, Product, Order)과 관련된 모든 코드를 캡슐화하는 표준화된 폴더 구조입니다. 기술적 관심사가 아닌 비즈니스 도메인을 중심으로 코드를 구성하는 도메인 주도 설계 원칙을 따릅니다.

Domain Module Structure

🎯목표

Nest.js 백엔드 모듈과 Next.js 프론트엔드 페이지에서 사용할 수 있는 재사용 가능한 UI 컴포넌트와 비즈니스 로직을 생산하는 것이 목표입니다.

모듈 아키텍처

도메인 모듈은 공통 파일(공유), 백엔드 파일, 프론트엔드 파일의 세 가지 카테고리로 나뉩니다. 이러한 분리는 중복 코드 선언을 제거합니다.

데이터 흐름

Common + Backend → MongoDB Model, Service Logic, Endpoint → Nest.js Module

Common + Frontend → Fetch Client, Flux Store, UI Components → Next.js Component

카테고리	파일	결과물
Common	constant, dictionary, signal	타입 정의, 번역, API 계약
Backend	document, service	MongoDB 모델, 비즈니스 로직
Frontend	store, Template, Unit, View, Zone, Util	상태 관리, UI 컴포넌트

공통 파일은 백엔드와 프론트엔드 간에 공유됩니다. 플랫폼별 의존성 없이 순수 JavaScript/TypeScript로 작성되어야 합니다.

파일	설명
`constant.ts`	via() 빌더 패턴을 사용하여 데이터 스키마(Input, Object, Light, Full, Insight)와 enum을 정의합니다.
`dictionary.ts`	모델 이름, 필드 레이블, enum 값, API 설명, 에러 메시지에 대한 다국어 번역을 제공합니다.
`signal.ts`	API 엔드포인트(쿼리, 뮤테이션, 구독)와 프론트엔드-백엔드 간의 타입 계약을 정의합니다.

공통 파일은 백엔드 전용(mongoose, fs) 또는 프론트엔드 전용(window, document) 의존성을 import할 수 없습니다. @akanjs/base와 @akanjs/common만 허용됩니다. 타입 import는 트랜스파일 시 사라지므로 안전합니다.

백엔드 파일은 MongoDB 모델을 생성하고, 비즈니스 로직을 구현하며, Nest.js 모듈을 만들기 위해 결합됩니다.

파일	설명
`document.ts`	constant 스키마로부터 MongoDB Document/Model을 생성합니다. 데이터베이스 쿼리, 필터, 데이터 처리 로직(Redis 캐시, 텍스트 검색 등)을 정의합니다.
`service.ts`	도메인별 비즈니스 로직을 구현합니다. 복잡한 작업, 검증, 다른 서비스와의 상호작용을 처리합니다.

Backend Data Flow

프론트엔드 파일은 도메인에 대한 상태 관리, 데이터 페칭, UI 컴포넌트를 정의합니다.

파일	타입	설명
`store.ts`	Client	Zustand를 사용한 글로벌 상태 관리. 도메인 관련 state와 action을 정의합니다.
`Template.tsx`	Client	상태 관리가 통합된 Create/Update 작업용 폼 컴포넌트.
`Unit.tsx`	Server	여러 항목 표시를 위한 카드/목록 아이템 컴포넌트. 효율적인 렌더링을 위해 LightModel을 사용합니다.
`View.tsx`	Server	단일 항목 상세 표시를 위한 뷰 컴포넌트. 모든 속성이 포함된 전체 Model을 사용합니다.
`Zone.tsx`	Client	Template, Unit, View를 완전한 UI 섹션으로 구성하는 페이지 컨테이너 컴포넌트.
`Util.tsx`	Client	도메인별 기능(버튼, 배지 등)을 위한 특수 유틸리티 컴포넌트.