model.constant.ts

constant 파일은 model의 비즈니스 형태를 정의합니다. field, enum, embedded scalar 값, generated view, 데이터 타입과 함께 다녀야 하는 작은 helper 동작을 선언합니다.

현재 Akan 패턴은 via()를 중심으로 구성됩니다. 각 class는 같은 비즈니스 model의 서로 다른 view를 만들고, 이후 document, service, signal, store, UI 코드가 이 generated type을 재사용합니다.

Model 계층 패턴

대부분의 document model은 Input, Object, Light, full Model, Insight의 다섯 계층을 사용합니다. 작은 embedded scalar가 아니라면 이 형태를 기본값으로 생각하세요.

Input

model을 생성하거나 수정할 때 받는 field입니다.

Object

Input에 system 또는 service가 관리하는 저장 field를 더합니다.

Light

list, relation, card 형태 query에 쓰는 작은 view입니다.

Model

Object와 Light를 결합한 full model이며 static helper를 둘 수 있습니다.

Insight

분석을 위한 aggregation 또는 reporting field입니다.

ticket.constant.ts

Field와 enumOf

field()로 값을 설명하고 enumOf()로 범주형 값을 정의합니다. field option은 default, optional, reference, hidden 또는 secret field, example, aggregation처럼 비즈니스에 필요한 내용 중심으로 둡니다.

status enum

practical field options

field.hidden과 field.secret

field.hidden()과 field.secret()은 일반 public property처럼 다루면 안 되는 field를 위한 helper입니다. 둘 다 hidden, nullable field를 만들고, field.secret()은 추가로 select: false를 설정해서 document load 시 기본 선택 대상에서 빠지게 합니다.

field.hidden()

document에는 존재할 수 있지만 일반적으로 보이는 field처럼 다루면 안 되는 내부 상태에 사용합니다.

field.secret()

password, phone, token, account id, wallet, notification 설정처럼 기본 조회에서 빠져야 하는 민감 값에 사용합니다.

user.constant.ts

Generated model 확장

일부 앱은 app 또는 library template에서 생성된 model hook을 확장합니다. generated inputs, objects, lights, models, insights를 via()에 spread해서 custom field와 generated field가 함께 유지되도록 합니다.

user.constant.ts

Light와 Full model helper

동작이 데이터 타입 자체에 속한다면 constant class에 작은 helper method를 둘 수 있습니다. instance helper는 Light class에 어울리고, list 또는 lookup helper는 full Model class의 static method에 어울립니다.

LightBoard helper

Board static helper

Resolve field

Light와 full model은 resolve helper로 resolved field를 선언할 수 있습니다. resolved field는 document에 직접 저장되는 값이 아닙니다. constant는 field 이름과 타입을 선언하고, internal signal이 client fetch 시 해당 값을 어떻게 계산해서 붙일지 정의합니다.

현재 사용자가 story에 like를 눌렀는지, 이 사용자의 read count, permission flag처럼 request context에 따라 달라지는 값을 붙일 때 유용합니다.

story.constant.ts

story.signal.ts

Scalar constant와 static utility

Scalar는 자체 collection이 없는 embedded value입니다. 그래도 값 자체에 속하는 계산이나 변환이라면 유용한 static helper를 노출할 수 있습니다.

coordinate.constant.ts

Insight constant

Insight constant는 집계 또는 reporting 지향 값을 설명합니다. dashboard count, summary, grouped statistic을 일반 model shape에 섞지 말고 Insight에 둡니다.

ticket.constant.ts

실전 규칙

작은 embedded scalar가 아니라면 document model에는 Input, Object, Light, Model, Insight 계층을 사용합니다.

비즈니스 category에는 enumOf를 사용하고 union이 필요하면 해당 enum의 value type을 참조합니다.

app template이 inputs, objects, lights, models, insights를 제공한다면 generated extension spread를 사용합니다.

숨겨진 내부 값에는 field.hidden을, 기본 조회에서 빠져야 하는 민감 값에는 field.secret을 사용합니다.

viewer별로 달라지는 값을 model에 직접 저장하지 말고 signal context로 계산되는 resolve field를 사용합니다.

helper 동작은 데이터 타입에 명확히 속할 때만 constant에 둡니다.

순환 barrel reference를 피하기 위해 다른 constant는 직접 파일 경로에서 import합니다.