model.constant.ts

constant 파일은 도메인의 데이터 형태(스키마)를 정의합니다. 데이터베이스 저장, API 통신, 프론트엔드 사용 간의 단일 진실 소스를 만들어 일관성을 보장합니다.

📐타입 안전성

스키마 정의가 백엔드와 프론트엔드에서 공유되어 애플리케이션 전체의 타입 일관성을 보장합니다.

🔄자동 생성

constant 정의에서 프레임워크가 MongoDB 스키마, GraphQL 타입, REST API, 클라이언트 타입을 자동 생성합니다.

클래스 계층구조 패턴

Akan.js는 스키마 정의를 구성하기 위해 계층적 클래스 패턴을 사용합니다. 각 계층은 특정 목적을 가지며 이전 계층 위에 구축됩니다.

Input

새 문서를 생성하는 데 필요한 필드 (사용자 제공 데이터)

Object

Input + 시스템 생성 필드 (상태, 타임스탬프, 계산된 값)

Light

목록 쿼리를 위해 선택된 필드만 포함하는 경량 버전 (과도한 데이터 fetch 방지)

Full (Model)

모든 필드와 정적/인스턴스 유틸리티 메서드가 포함된 완전한 모델

Insight

분석을 위한 통계 집계 필드 (count, sum, avg)

enumOf()로 Enum 정의하기

모델 클래스를 정의하기 전에 일반적으로 상태 필드와 기타 범주형 값에 대한 enum을 정의해야 합니다. enumOf() 함수는 타입 안전한 enum 클래스를 생성합니다.

product.constant.ts

enumOf()의 핵심 포인트:

field	설명
as const	TypeScript가 string[] 대신 리터럴 타입을 추론하는 데 필수
첫 번째 인수	딕셔너리 번역에 사용되는 enum 이름
생성되는 타입	ProductStatus["value"] 타입으로 값에 접근 (예: "active" \| "soldOut" \| ...)

as const

TypeScript가 string[] 대신 리터럴 타입을 추론하는 데 필수

첫 번째 인수

딕셔너리 번역에 사용되는 enum 이름

생성되는 타입

ProductStatus["value"] 타입으로 값에 접근 (예: "active" | "soldOut" | ...)

Input 클래스 - 생성 필드

Input 클래스는 새 문서를 생성할 때 필요한 필드를 정의합니다. 이것은 사용자나 시스템이 제공해야 하는 값입니다.

product.constant.ts

via() 패턴 이해하기:

method	설명
via((field) => ({...}))	지정된 필드로 새 클래스를 생성합니다. field() 함수는 타입과 선택적 옵션을 받습니다.
field(Type, options?)	Type은 String, Int, Float, Boolean, Date, JSON, ID, [배열], 커스텀 클래스, enum이 가능합니다.
.optional()	.optional()을 체이닝하여 필드를 nullable로 만듭니다. 필드를 생략하거나 null로 설정할 수 있습니다.

via((field) => ({...}))

지정된 필드로 새 클래스를 생성합니다. field() 함수는 타입과 선택적 옵션을 받습니다.

field(Type, options?)

Type은 String, Int, Float, Boolean, Date, JSON, ID, [배열], 커스텀 클래스, enum이 가능합니다.

.optional()

.optional()을 체이닝하여 필드를 nullable로 만듭니다. 필드를 생략하거나 null로 설정할 수 있습니다.

💡코드에서의 사용

Input 필드는 다음에서 사용됩니다: fetch.createProduct(input), st.do.setNameOnProduct(value), productForm 상태

Object 클래스

Object 클래스는 Input을 확장하고 시스템에서 자동으로 설정하는 필드를 추가합니다. 이 필드들은 일반적으로 직접적인 사용자 입력이 아닌 서비스 메서드를 통해 수정됩니다.

product.constant.ts

일반적인 Object 필드들:

field	설명
status	문서 생명주기 상태, 서비스 메서드로 제어
stock	재고 수량, 기본값 0, 판매 작업으로 수정
soldCount	분석용 누적 판매 수량

status

문서 생명주기 상태, 서비스 메서드로 제어

stock

재고 수량, 기본값 0, 판매 작업으로 수정

soldCount

분석용 누적 판매 수량

참고: via(BaseClass, (field) => ({...})) 구문은 'BaseClass를 확장하고 이 새 필드들을 추가'를 의미합니다. ProductInput의 모든 필드가 상속됩니다.

Light 클래스 - 목록 최적화

Light 클래스는 목록 뷰를 위해 Object에서 필요한 필드만 선택합니다. 테이블이나 카드에 여러 항목을 표시할 때 과도한 데이터 fetch를 방지합니다.

product.constant.ts

field	설명
성능 이점	목록을 위해 100개의 상품을 가져올 때 Light는 필수 필드만 전송되도록 하여 페이로드 크기와 데이터베이스 부하를 줄입니다.
필드 선택	목록 UI에 나타나는 필드 선택: 식별자, 상태, 주요 메타데이터. 제외: 콘텐츠, 파일, 상세 중첩 객체.
Resolve 함수	(resolve) => ({}) 함수는 DB에 저장되지 않지만 서버 측에서 계산되는 computed/virtual 필드를 추가할 수 있습니다.

성능 이점

목록을 위해 100개의 상품을 가져올 때 Light는 필수 필드만 전송되도록 하여 페이로드 크기와 데이터베이스 부하를 줄입니다.

필드 선택

목록 UI에 나타나는 필드 선택: 식별자, 상태, 주요 메타데이터. 제외: 콘텐츠, 파일, 상세 중첩 객체.

Resolve 함수

(resolve) => ({}) 함수는 DB에 저장되지 않지만 서버 측에서 계산되는 computed/virtual 필드를 추가할 수 있습니다.

Full 모델 - 메서드 포함 완전체

Full 모델(보통 'Product'처럼 도메인 이름으로 지정)은 Object와 Light를 결합하고 데이터 조작을 위한 정적 유틸리티 메서드를 추가합니다.

product.constant.ts

method	설명
정적 메서드	정적 메서드는 항목 배열에서 작동합니다. 목록에서 필터링, 그룹화, 파생 데이터 계산에 사용합니다.
사용 예제	const activeProducts = cnst.Product.getActiveList(productList);

정적 메서드

정적 메서드는 항목 배열에서 작동합니다. 목록에서 필터링, 그룹화, 파생 데이터 계산에 사용합니다.

사용 예제

const activeProducts = cnst.Product.getActiveList(productList);

Insight 클래스

Insight 클래스는 분석을 위한 집계 필드를 정의합니다. 쿼리할 때 프레임워크는 MongoDB 집계 파이프라인을 사용하여 이러한 통계를 계산합니다.

product.constant.ts

accumulate 옵션 이해하기:

field	설명
{ $sum: 1 }	단순 카운트 - 일치하는 각 문서에 1을 추가
{ $sum: "$fieldName" }	일치하는 모든 문서의 필드 값 합계
{ $cond: [...] }	조건부 집계 - 조건에 일치하는 문서만 카운트

{ $sum: 1 }

단순 카운트 - 일치하는 각 문서에 1을 추가

{ $sum: "$fieldName" }

일치하는 모든 문서의 필드 값 합계

{ $cond: [...] }

조건부 집계 - 조건에 일치하는 문서만 카운트

코드에서의 사용:

Using Insight

스칼라 - 내장 객체

스칼라는 자체 컬렉션이 없는 내장 객체입니다. 부모 문서 내에 저장되며 전체 클래스 계층구조 없이 via()를 사용하여 정의됩니다.

milestone.constant.ts

부모 모델에서 스칼라 사용하기:

bizContract.constant.ts

field	설명
스칼라를 사용하는 경우	단일 부모에 속하는 데이터 (1:N 임베딩). 별도의 쿼리나 참조가 필요 없음. 항상 부모 문서와 함께 접근되는 데이터.
스칼라 위치	스칼라는 일반적으로 __scalar/ 디렉토리에 배치하여 독립적인 컬렉션이 아닌 임베딩 타입임을 나타냅니다.

스칼라를 사용하는 경우

단일 부모에 속하는 데이터 (1:N 임베딩). 별도의 쿼리나 참조가 필요 없음. 항상 부모 문서와 함께 접근되는 데이터.

스칼라 위치

스칼라는 일반적으로 __scalar/ 디렉토리에 배치하여 독립적인 컬렉션이 아닌 임베딩 타입임을 나타냅니다.

관계 패턴

Akan.js에서 모델 간 관계를 설정하는 세 가지 주요 방법이 있으며, MongoDB 스키마 디자인 원칙을 따릅니다.

method	설명	예제
스칼라 임베딩	스칼라 객체를 문서에 직접 임베딩합니다. 자식 데이터가 항상 부모와 함께 접근되는 1:N 관계에 적합합니다.
ID 참조	관련 문서의 ObjectID만 저장합니다. 참조된 컬렉션을 별도로 쿼리해야 할 때 적합합니다.
Light 모델 참조	다른 모델의 Light 버전을 임베딩합니다. 전체 population 없이 주요 필드가 필요할 때 적합합니다.

스칼라 임베딩

스칼라 객체를 문서에 직접 임베딩합니다. 자식 데이터가 항상 부모와 함께 접근되는 1:N 관계에 적합합니다.

ID 참조

관련 문서의 ObjectID만 저장합니다. 참조된 컬렉션을 별도로 쿼리해야 할 때 적합합니다.

Light 모델 참조

다른 모델의 Light 버전을 임베딩합니다. 전체 population 없이 주요 필드가 필요할 때 적합합니다.

⚠️ Import 경고: constant 파일 간 직접 import는 순환 참조를 일으킬 수 있습니다. barrel 파일(index.ts)이 아닌 특정 파일 경로에서 항상 import하세요.

필드 옵션 참조

field() 함수는 유효성 검사, 기본값, 데이터베이스 동작 등을 구성하기 위한 다양한 옵션을 받습니다. 전체 참조는 다음과 같습니다:

옵션	타입	기본값	설명
default	any \| (() => any)	-	값이 제공되지 않을 때의 기본값. 정적 값 또는 동적 기본값을 위한 함수일 수 있습니다.
nullable	boolean	false	true면 필드가 null이거나 생략될 수 있습니다. .optional() 체인 메서드와 동일합니다.
ref	string	-	ID 필드의 참조 컬렉션 이름. MongoDB population에 사용됩니다.
refPath	string	-	동적 참조 경로 - 다른 필드의 값을 사용하여 참조 컬렉션을 결정합니다.
refType	"child" \| "parent" \| "relation"	-	참조 관계의 타입. population과 cascade 작업 방식에 영향을 줍니다.
type	"email" \| "password" \| "url"	-	일반적인 패턴에 대해 기본 유효성 검사와 예시 값을 적용하는 프리셋 타입.
fieldType	"property" \| "hidden" \| "resolve"	"property"	property: 일반 필드, hidden: 백엔드 전용(프론트에 전송 안됨), resolve: 계산 필드(DB에 저장 안됨).
immutable	boolean	false	true면 문서 생성 후 필드를 수정할 수 없습니다. 생성 시에만 설정됩니다.
min	number	-	Int 또는 Float 필드의 최소값 제약. 저장 시 유효성 검사가 실행됩니다.
max	number	-	Int 또는 Float 필드의 최대값 제약. 저장 시 유효성 검사가 실행됩니다.
minlength	number	-	String 필드의 최소 문자열 길이 제약.
maxlength	number	-	String 필드의 최대 문자열 길이 제약.
enum	EnumClass	-	필드 값을 enum 값으로 제한합니다. 일반적으로 enumOf()로 정의된 클래스와 함께 사용됩니다.
select	boolean	true	false면 기본 쿼리에서 필드가 제외됩니다. 민감하거나 큰 필드에 사용합니다.
accumulate	object	-	Insight 필드용 MongoDB 집계 표현식. 일치하는 문서들의 통계를 계산합니다.
example	any	-	API 문서 생성(Swagger/OpenAPI)을 위한 예시 값.
of	Type	-	Map 필드의 값 타입. 키는 항상 string이고, 값 타입은 'of'로 지정합니다.
validate	(value, model) => boolean	-	커스텀 유효성 검사 함수. 필드 값과 전체 모델을 받아 boolean을 반환합니다.
text	"search" \| "filter"	-	전체 텍스트 검색(search) 또는 필터링(filter) 기능을 위한 텍스트 인덱싱을 활성화합니다.
meta	object	-	UI 컴포넌트나 플러그인에서 사용하는 추가 필드 정보를 위한 커스텀 메타데이터 객체.

default:any | (() => any):-

값이 제공되지 않을 때의 기본값. 정적 값 또는 동적 기본값을 위한 함수일 수 있습니다.

nullable:boolean:false

true면 필드가 null이거나 생략될 수 있습니다. .optional() 체인 메서드와 동일합니다.

ref:string:-

ID 필드의 참조 컬렉션 이름. MongoDB population에 사용됩니다.

refPath:string:-

동적 참조 경로 - 다른 필드의 값을 사용하여 참조 컬렉션을 결정합니다.

refType:"child" | "parent" | "relation":-

참조 관계의 타입. population과 cascade 작업 방식에 영향을 줍니다.

type:"email" | "password" | "url":-

일반적인 패턴에 대해 기본 유효성 검사와 예시 값을 적용하는 프리셋 타입.

fieldType:"property" | "hidden" | "resolve":"property"

property: 일반 필드, hidden: 백엔드 전용(프론트에 전송 안됨), resolve: 계산 필드(DB에 저장 안됨).

immutable:boolean:false

true면 문서 생성 후 필드를 수정할 수 없습니다. 생성 시에만 설정됩니다.

min:number:-

Int 또는 Float 필드의 최소값 제약. 저장 시 유효성 검사가 실행됩니다.

max:number:-

Int 또는 Float 필드의 최대값 제약. 저장 시 유효성 검사가 실행됩니다.

minlength:number:-

String 필드의 최소 문자열 길이 제약.

maxlength:number:-

String 필드의 최대 문자열 길이 제약.

enum:EnumClass:-

필드 값을 enum 값으로 제한합니다. 일반적으로 enumOf()로 정의된 클래스와 함께 사용됩니다.

select:boolean:true

false면 기본 쿼리에서 필드가 제외됩니다. 민감하거나 큰 필드에 사용합니다.

accumulate:object:-

Insight 필드용 MongoDB 집계 표현식. 일치하는 문서들의 통계를 계산합니다.

example:any:-

API 문서 생성(Swagger/OpenAPI)을 위한 예시 값.

of:Type:-

Map 필드의 값 타입. 키는 항상 string이고, 값 타입은 'of'로 지정합니다.

validate:(value, model) => boolean:-

커스텀 유효성 검사 함수. 필드 값과 전체 모델을 받아 boolean을 반환합니다.

text:"search" | "filter":-

전체 텍스트 검색(search) 또는 필터링(filter) 기능을 위한 텍스트 인덱싱을 활성화합니다.

meta:object:-

UI 컴포넌트나 플러그인에서 사용하는 추가 필드 정보를 위한 커스텀 메타데이터 객체.

fieldType Options

field	설명
property	일반 필드 - DB에 저장, 프론트엔드로 전송
hidden	백엔드 전용 - DB에 저장되지만 프론트엔드로 전송 안됨 (예: OTP 코드)
resolve	가상 필드 - 쿼리 시 계산, DB에 저장 안됨 (예: 다른 컬렉션의 조회수)

property

일반 필드 - DB에 저장, 프론트엔드로 전송

hidden

백엔드 전용 - DB에 저장되지만 프론트엔드로 전송 안됨 (예: OTP 코드)

resolve

가상 필드 - 쿼리 시 계산, DB에 저장 안됨 (예: 다른 컬렉션의 조회수)

refType Options

field	설명
parent	이 문서가 참조된 문서에 속함
child	참조된 문서가 이 문서에 속함
relation	소유권 없는 다대다 관계

parent

이 문서가 참조된 문서에 속함

child

참조된 문서가 이 문서에 속함

relation

소유권 없는 다대다 관계

일반적인 필드 패턴:

Common Field Patterns

Constant 모범 사례

field	설명
클래스 순서	순서대로 정의: Enum → Input → Object → Light → Full → Insight. 이렇게 하면 전방 참조 문제를 방지합니다.
Light 필드 선택	포함: id, 상태, 주요 식별자, 타임스탬프. 제외: 큰 콘텐츠 필드, 파일, 상세 중첩 객체.
기본값	Object 필드에 항상 기본값을 제공합니다. 날짜 같은 동적 값에는 함수 사용: () => dayjs()
정적 메서드	Full 클래스에 필터링/그룹화 로직을 위한 정적 유틸리티 메서드를 추가합니다. 순수 함수로 유지하세요(부작용 없음).
Import 경로	다른 constant를 import할 때 순환 참조를 피하기 위해 항상 직접 파일 import를 사용합니다. barrel 파일에서 절대 import하지 않습니다.

클래스 순서

순서대로 정의: Enum → Input → Object → Light → Full → Insight. 이렇게 하면 전방 참조 문제를 방지합니다.

Light 필드 선택

포함: id, 상태, 주요 식별자, 타임스탬프. 제외: 큰 콘텐츠 필드, 파일, 상세 중첩 객체.

기본값

Object 필드에 항상 기본값을 제공합니다. 날짜 같은 동적 값에는 함수 사용: () => dayjs()

정적 메서드

Full 클래스에 필터링/그룹화 로직을 위한 정적 유틸리티 메서드를 추가합니다. 순수 함수로 유지하세요(부작용 없음).

Import 경로

다른 constant를 import할 때 순환 참조를 피하기 위해 항상 직접 파일 import를 사용합니다. barrel 파일에서 절대 import하지 않습니다.

field

설명

as const

TypeScript가 string[] 대신 리터럴 타입을 추론하는 데 필수

첫 번째 인수

딕셔너리 번역에 사용되는 enum 이름

생성되는 타입

ProductStatus["value"] 타입으로 값에 접근 (예: "active" | "soldOut" | ...)

method

설명

via((field) => ({...}))

지정된 필드로 새 클래스를 생성합니다. field() 함수는 타입과 선택적 옵션을 받습니다.

field(Type, options?)

Type은 String, Int, Float, Boolean, Date, JSON, ID, [배열], 커스텀 클래스, enum이 가능합니다.

.optional()

.optional()을 체이닝하여 필드를 nullable로 만듭니다. 필드를 생략하거나 null로 설정할 수 있습니다.

field

설명

status

문서 생명주기 상태, 서비스 메서드로 제어

stock

재고 수량, 기본값 0, 판매 작업으로 수정

soldCount

분석용 누적 판매 수량

field

설명

성능 이점

목록을 위해 100개의 상품을 가져올 때 Light는 필수 필드만 전송되도록 하여 페이로드 크기와 데이터베이스 부하를 줄입니다.

필드 선택

목록 UI에 나타나는 필드 선택: 식별자, 상태, 주요 메타데이터. 제외: 콘텐츠, 파일, 상세 중첩 객체.

Resolve 함수

(resolve) => ({}) 함수는 DB에 저장되지 않지만 서버 측에서 계산되는 computed/virtual 필드를 추가할 수 있습니다.

method

설명

정적 메서드

정적 메서드는 항목 배열에서 작동합니다. 목록에서 필터링, 그룹화, 파생 데이터 계산에 사용합니다.

사용 예제

const activeProducts = cnst.Product.getActiveList(productList);

field

설명

{ $sum: 1 }

단순 카운트 - 일치하는 각 문서에 1을 추가

{ $sum: "$fieldName" }

일치하는 모든 문서의 필드 값 합계

{ $cond: [...] }

조건부 집계 - 조건에 일치하는 문서만 카운트

field

설명

스칼라를 사용하는 경우

단일 부모에 속하는 데이터 (1:N 임베딩). 별도의 쿼리나 참조가 필요 없음. 항상 부모 문서와 함께 접근되는 데이터.

스칼라 위치

스칼라는 일반적으로 __scalar/ 디렉토리에 배치하여 독립적인 컬렉션이 아닌 임베딩 타입임을 나타냅니다.

method

설명

예제

스칼라 임베딩

스칼라 객체를 문서에 직접 임베딩합니다. 자식 데이터가 항상 부모와 함께 접근되는 1:N 관계에 적합합니다.

ID 참조

관련 문서의 ObjectID만 저장합니다. 참조된 컬렉션을 별도로 쿼리해야 할 때 적합합니다.

Light 모델 참조

다른 모델의 Light 버전을 임베딩합니다. 전체 population 없이 주요 필드가 필요할 때 적합합니다.

옵션

타입

기본값

설명

예제

default

any | (() => any)

값이 제공되지 않을 때의 기본값. 정적 값 또는 동적 기본값을 위한 함수일 수 있습니다.

nullable

boolean

false

true면 필드가 null이거나 생략될 수 있습니다. .optional() 체인 메서드와 동일합니다.

ref

string

ID 필드의 참조 컬렉션 이름. MongoDB population에 사용됩니다.

refPath

string

동적 참조 경로 - 다른 필드의 값을 사용하여 참조 컬렉션을 결정합니다.

refType

"child" | "parent" | "relation"

참조 관계의 타입. population과 cascade 작업 방식에 영향을 줍니다.

type

"email" | "password" | "url"

일반적인 패턴에 대해 기본 유효성 검사와 예시 값을 적용하는 프리셋 타입.

fieldType

"property" | "hidden" | "resolve"

"property"

property: 일반 필드, hidden: 백엔드 전용(프론트에 전송 안됨), resolve: 계산 필드(DB에 저장 안됨).

immutable

boolean

false

true면 문서 생성 후 필드를 수정할 수 없습니다. 생성 시에만 설정됩니다.

min

number

Int 또는 Float 필드의 최소값 제약. 저장 시 유효성 검사가 실행됩니다.

max

number

Int 또는 Float 필드의 최대값 제약. 저장 시 유효성 검사가 실행됩니다.

minlength

number

String 필드의 최소 문자열 길이 제약.

maxlength

number

String 필드의 최대 문자열 길이 제약.

enum

EnumClass

필드 값을 enum 값으로 제한합니다. 일반적으로 enumOf()로 정의된 클래스와 함께 사용됩니다.

select

boolean

true

false면 기본 쿼리에서 필드가 제외됩니다. 민감하거나 큰 필드에 사용합니다.

accumulate

object

Insight 필드용 MongoDB 집계 표현식. 일치하는 문서들의 통계를 계산합니다.

example

any

API 문서 생성(Swagger/OpenAPI)을 위한 예시 값.

Type

Map 필드의 값 타입. 키는 항상 string이고, 값 타입은 'of'로 지정합니다.

validate

(value, model) => boolean

커스텀 유효성 검사 함수. 필드 값과 전체 모델을 받아 boolean을 반환합니다.

text

"search" | "filter"

전체 텍스트 검색(search) 또는 필터링(filter) 기능을 위한 텍스트 인덱싱을 활성화합니다.