도메인 모듈

도메인 모듈은 하나의 도메인(예: 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	도메인별 기능(버튼, 배지 등)을 위한 특수 유틸리티 컴포넌트.

상태 관리

store.ts가 클라이언트에서 도메인 상태와 비즈니스 로직을 처리합니다.

UI 컴포넌트

Template, Unit, View가 재사용 가능한 UI 패턴을 제공합니다.

컨테이너

Zone이 컴포넌트를 완전한 페이지로 구성합니다.

파일 명명 규칙

Akan.js는 다양한 파일 타입을 구분하기 위해 일관된 명명 규칙을 따릅니다:

패턴	예시	설명
`model.*.ts`	product.constant.ts	로직 파일 (소문자)
`Model.*.tsx`	Product.View.tsx	React 컴포넌트 (PascalCase)

Complete Module Example

도메인 모듈 모범 사례

1️⃣공통 파일을 순수하게 유지

constant.ts, dictionary.ts, signal.ts에서 플랫폼별 코드를 import하지 마세요. 이 파일들은 Node.js와 브라우저 환경 모두에서 동작해야 합니다.

2️⃣적절한 모델 타입 사용

Unit.tsx는 LightModel을 사용합니다 (적은 필드, 더 나은 성능). View.tsx는 전체 Model을 사용합니다 (상세 표시를 위한 모든 필드).

3️⃣서버 vs 클라이언트 컴포넌트

Unit.tsx와 View.tsx는 서버 컴포넌트입니다 ('use client' 없음). Template.tsx, Zone.tsx, Util.tsx는 클라이언트 컴포넌트입니다 ('use client' 포함).

4️⃣도메인별로 구성

관련된 모든 파일을 같은 폴더에 유지하세요. 이렇게 하면 도메인 전체를 이해하고 유지보수하기 쉬워집니다.

🎉 학습한 내용:

✓ 11개의 표준화된 파일로 구성된 도메인 모듈 구조
✓ 세 가지 카테고리: 공통(공유), 백엔드, 프론트엔드
✓ constant → document → service → signal 데이터 흐름
✓ 프론트엔드 컴포넌트 계층: Zone → Template/Unit/View
✓ 명명 규칙: 로직은 소문자.ts, 컴포넌트는 PascalCase.tsx

카테고리

파일

결과물

Common

constant, dictionary, signal

타입 정의, 번역, API 계약

Backend

document, service

MongoDB 모델, 비즈니스 로직

Frontend

store, Template, Unit, View, Zone, Util

상태 관리, UI 컴포넌트

파일

설명

constant.ts

via() 빌더 패턴을 사용하여 데이터 스키마(Input, Object, Light, Full, Insight)와 enum을 정의합니다.

dictionary.ts

모델 이름, 필드 레이블, enum 값, API 설명, 에러 메시지에 대한 다국어 번역을 제공합니다.

signal.ts

API 엔드포인트(쿼리, 뮤테이션, 구독)와 프론트엔드-백엔드 간의 타입 계약을 정의합니다.

파일

설명

document.ts

constant 스키마로부터 MongoDB Document/Model을 생성합니다. 데이터베이스 쿼리, 필터, 데이터 처리 로직(Redis 캐시, 텍스트 검색 등)을 정의합니다.

service.ts

도메인별 비즈니스 로직을 구현합니다. 복잡한 작업, 검증, 다른 서비스와의 상호작용을 처리합니다.

파일

타입

설명

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

도메인별 기능(버튼, 배지 등)을 위한 특수 유틸리티 컴포넌트.

패턴

예시

설명

model.*.ts

product.constant.ts

로직 파일 (소문자)

Model.*.tsx

Product.View.tsx

React 컴포넌트 (PascalCase)