사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
앱 & 라이브러리▾
도메인▾
스칼라▾
스칼라 개요
스칼라는 다른 모델 안에 들어가는 작은 필드 묶음에 이름을 붙인 것입니다. 한 번 정의해 두고, 같은 필드가 반복되는 곳마다 넣어 씁니다.
예를 들어 상품, 주문, 청구서에는 모두 가격이 필요합니다.
amount와 currency를 세 번 쓰는 대신 Price 스칼라를 한 번 정의해 세 곳에 모두 넣습니다.이 페이지에서 쓰는 말
용어설명
값 객체
가격이나 주소처럼 필드 값만으로 정해지고 자체
id가 없는 값입니다.임베드
스칼라를 다른 모델의 필드로 넣어 그 모델과 함께 저장하는 것입니다.
상위 모델
Price를 필드로 가진 Product처럼, 스칼라를 담고 있는 모델입니다.데이터베이스 모듈
lib/<model>/ 아래에서 자체 테이블, 서비스, 엔드포인트, 화면을 갖는 모델입니다.스칼라를 쓰는 경우
이 값이 다른 레코드 안에서만 쓰이는지 먼저 따져 봅니다. 그렇다면 스칼라이고, 자체 목록이나 권한, 수명 주기가 필요하다면 데이터베이스 모듈입니다.
이 값이…
스칼라
lib/__scalar/
데이터베이스 모듈
lib/<model>/
스칼라가 맞는 경우
다른 레코드 안에 있음
✓
자체
id나 createdAt 없이 상위 레코드와 함께 저장되고 불러와집니다.같은 필드가 반복됨
✓
상품과 주문의 가격처럼, 같은 필드 묶음이 여러 모델에 나옵니다.
엔드포인트의 입력이나 결과
✓
이 문서 앱이 돌려주는
DocPage 목록처럼, 뒤에 테이블이 없는 데이터 모양입니다.데이터베이스 모듈이 필요한 경우
자체 목록 페이지
✓
사람들이 레코드를 둘러보고, 검색하고, 페이지를 넘깁니다.
자체 권한
✓
가드가 레코드마다 누가 읽고 바꿀 수 있는지 정합니다.
자체 서비스 메서드
✓
approve()나 cancel() 같은 비즈니스 동작이 이 모델을 대상으로 실행됩니다.독립된 수명 주기
✓
상위 레코드와 함께가 아니라 따로 생성되고 삭제됩니다.
✓이쪽을 씁니다해당 없음
좋은 스칼라 예
Price · Address · ContactInfo · Coordinate · FileMetalibs/util의 Coordinate와 libs/shared의 FileMeta는 직접 열어 볼 수 있는 실제 스칼라입니다.좋은 데이터베이스 모듈 예
Product · Order · User · Post · Ticket각각 자체 목록, 권한, 수명 주기가 있으므로 모듈을 따로 둡니다.
넣는 방법은 다른 필드와 같습니다. 스칼라 클래스를 import해서
field()에 넘깁니다:apps/<app>/lib/product/product.constant.ts
- 상대 경로로 import합니다. constant 파일은 다른 모듈의 constant를
../__scalar/price/price.constant처럼 직접 import할 수 있습니다. - 기본값을 따로 적지 않아도 됩니다.
field(Price)는Price에 정해 둔 기본값으로 채워진 채 시작합니다. - 목록과 빈 값도 평소처럼 씁니다.
field([Price])는 여러 개를 담고,field(Price).optional()은null로 시작합니다. - 스칼라 안에 스칼라를 넣을 수도 있습니다.
libs/util의AccessLog는location필드에Coordinate를 넣습니다.
스칼라 파일
스칼라마다
lib/__scalar/<scalarName>/ 폴더를 하나씩 둡니다. akan create-scalar price가 기본 파일 네 개를 만들고, UI 파일은 여러 곳에서 같은 UI가 필요할 때만 추가합니다.apps/<app>/lib/
기본 파일 네 개
파일설명
값의 의미, 검증 의도, 재사용 규칙, 그리고 에이전트를 위한 메모를 적습니다.
필드와 enum, 그리고 서버와 클라이언트가 모두 부를 수 있는 helper 메서드를 담은 클래스 하나입니다.
scalarDictionary로 쓰는, 모든 필드와 enum 값의 라벨과 설명입니다.서버 쪽 클래스로 보통
by(cnst.Price) 한 줄이며, helper 메서드는 constant 클래스에 둡니다.선택: UI 파일
파일설명
상위 폼 안에서 값을 편집하는 에디터로, 첫 줄이 "use client"입니다.
상위 카드나 상세 화면 안에서 값을 보여 주는 서버 컴포넌트입니다.
- service, signal, store 파일은 없습니다. 스칼라에는 자체 엔드포인트나 클라이언트 상태가 없고, 불러오고 저장하는 일은 상위 모듈이 합니다.
- View, Zone, Util도 없습니다. 스칼라가 가질 수 있는 UI 역할은 Template과 Unit뿐입니다.
- .ts 파일 세 개를 모두 둡니다. document가
by(cnst.Price)한 줄뿐이어도 constant, dictionary와 함께 남겨 둡니다.
작은 예시
스칼라는 그 자체로 이해되어야 합니다. 값의 모양만 정하고, 저장하고 불러오고 그리는 방식은 상위 모듈에 맡깁니다.
constant는 클래스 하나입니다. 금액에는 소수점이 있으므로
amount는 Float를 씁니다:apps/<app>/lib/__scalar/price/price.constant.ts
dictionary는 각 필드에 라벨을 달고, document는 서버에서 쓸 수 있게 constant를 감쌉니다:
apps/<app>/lib/__scalar/price/price.dictionary.ts · price.document.ts
자주 하는 실수
Number를 쓰는 것. 필드 타입이 아닙니다. 소수에는Float, 개수에는Int를 씁니다.- 스칼라를 독립된 데이터처럼 다루는 것. 목록 페이지, 엔드포인트, 자체 권한이 필요하다면 데이터베이스 모듈로 만듭니다.
- 클래스를 다섯 개 쓰는 것. 스칼라는
via((field) => ({ … }))클래스 하나입니다. 데이터베이스 모델처럼 Input, Object, Light, full, Insight를 모두 쓰지 않습니다.