Sonamu UI 사용하기

Sonamu UI는 Entity를 시각적으로 정의하고 관리할 수 있는 웹 기반 인터페이스입니다. 자동 완성, 유효성 검사, 실시간 미리보기 등 강력한 기능을 제공합니다.

Sonamu UI 접속하기

서버 실행

cd api
pnpm dev

UI 접속

API 서버가 실행되면 자동으로 Sonamu UI도 함께 제공됩니다:

http://localhost:1028/sonamu-ui

Sonamu UI는 별도의 포트 없이 API 서버의 /sonamu-ui 경로에서 제공됩니다.

📸 필요: Sonamu UI 메인 화면 - Entities 탭이 열린 상태

주요 탭 구성

Sonamu UI는 4개의 주요 탭으로 구성됩니다:

Entities
Migrations
Scaffolding
Fixture

Entity 정의와 관리

Entity 생성, 수정, 삭제
Props, Indexes, Subsets, Enums 설정

Entity 생성하기

1. Entity 목록 페이지

Entities 탭을 클릭하면 프로젝트의 모든 Entity 목록이 표시됩니다.

📸 필요: Entity 목록 화면 - 여러 Entity가 카드 형태로 나열

표시 정보:

Entity ID와 Title
테이블명
Props 개수
Relation 개수

2. 새 Entity 생성

Create Entity 버튼 클릭

우측 상단의 “Create Entity” 버튼을 클릭합니다.

기본 정보 입력

Entity 생성 폼에서 다음 정보를 입력합니다:

Entity ID: PascalCase (예: User, BlogPost)
Table Name: snake_case (예: users, blog_posts)
Title: 한글 또는 표시명 (예: “사용자”, “블로그 글”)
Parent ID: 선택 사항 - 다른 Entity를 상속할 때 사용

Entity ID는 생성 후 변경할 수 없으므로 신중하게 입력하세요.

저장

“Create” 버튼을 클릭하면:

{entity}.entity.json 파일 생성
Entity 상세 페이지로 자동 이동

📸 필요: Entity 생성 다이얼로그 - 입력 폼 화면

Entity 편집하기

Entity를 클릭하면 상세 편집 페이지가 열립니다. 4개의 시트로 구성됩니다:

Props 시트

Entity의 속성(컬럼)을 관리하는 메인 시트입니다.

📸 필요: Props 시트 화면 - 속성 목록이 표 형태로 표시

Props 추가하기

Add Property 버튼 클릭

우측 상단의 “Add Property” 버튼 클릭 또는 단축키 Ctrl+Cmd+Shift+N 사용

속성 정보 입력

기본 필드:

name: 속성명 (snake_case)
type: 데이터 타입 (드롭다운에서 선택)
desc: 설명 (선택 사항)
nullable: NULL 허용 여부 (체크박스)
dbDefault: 데이터베이스 기본값

타입별 추가 옵션:

string / string[]

length: 문자열 길이 (기본값: TEXT)
예: length: 255 → VARCHAR(255)

number / number[]

precision: 전체 자릿수
scale: 소수점 자릿수
numberType: real | double precision | numeric (기본값: numeric)
예: precision: 10, scale: 2 → NUMERIC(10, 2)

numeric / numeric[]

precision: 전체 자릿수
scale: 소수점 자릿수
주의: TypeScript에서 string 타입으로 처리됨 (정밀도 유지)

enum / enum[]

id: Enum 타입 ID (예: UserRole)
Enum은 별도의 Enums 섹션에서 정의

json

id: JSON 스키마 타입 ID
TypeScript 타입을 {entity}.types.ts에서 정의

vector / vector[]

dimensions: 벡터 차원 (예: 1536)
pgvector 확장 필요

virtual

id: Virtual 타입 ID
virtualType: code | query
- code: TypeScript 코드로 계산 (기본값)
- query: SQL 쿼리로 계산
데이터베이스에 저장되지 않는 계산된 필드

relation

Relation 타입 선택 및 설정
자세한 내용은 Relations 참조

저장

입력 완료 후 “Save” 버튼 클릭

Props 수정 및 삭제

수정
삭제
순서 변경

Props 목록에서 수정할 행을 더블클릭 또는 Enter 키
또는 행 선택 후 우측의 “Edit” 버튼 클릭
폼에서 값 수정 후 저장

Props 목록에서 삭제할 행 선택
Cmd+Backspace 단축키 사용
또는 우측의 “Delete” 버튼 클릭
확인 다이얼로그에서 삭제 확인

Props를 삭제하면 해당 컬럼이 모든 Subset에서도 자동으로 제거됩니다. 복구할 수 없으므로 주의하세요.

Indexes 시트

데이터베이스 인덱스를 관리합니다.

📸 필요: Indexes 시트 화면

Index 추가하기

Add Index 버튼 클릭

“Add Index” 버튼 클릭 또는 Indexes 시트에서 Ctrl+Cmd+Shift+N

Index 설정

Index 옵션:

type: 인덱스 타입
- index: 일반 인덱스
- unique: 유니크 인덱스 (중복 방지)
- hnsw: Vector HNSW 인덱스
- ivfflat: Vector IVFFlat 인덱스
name: 인덱스명 (자동 생성 가능)
columns: 인덱스에 포함할 컬럼 선택
- 다중 컬럼 선택 가능
- 컬럼 순서 중요 (복합 인덱스)
using: 인덱스 방법 (선택 사항)
- btree (기본값)
- hash
- gin
- gist

Vector 인덱스 추가 옵션:

vectorOps: 거리 연산자
- vector_cosine_ops: 코사인 거리 (권장)
- vector_ip_ops: 내적 거리
- vector_l2_ops: 유클리드 거리
m: HNSW 그래프 연결 수 (기본값: 16)
efConstruction: HNSW 구성 품질 (기본값: 64)
lists: IVFFlat 클러스터 수 (기본값: 100)

인덱스 네이밍 규칙:

일반 인덱스: {table}_{columns}_idx
유니크 인덱스: {table}_{columns}_unique
예: users_email_unique, posts_created_at_idx

Subsets 시트

API 응답을 위한 필드 조합을 정의합니다.

📸 필요: Subsets 시트 화면 - 트리 구조로 필드 선택

Subset 키 추가

Add Subset 버튼 클릭

“Add Subset” 버튼을 클릭하여 새 subset 키 추가

Subset 키 입력

대문자로 시작하는 짧은 키 권장 (예: A, P, SS)
일반적으로 사용되는 키:
- A: All - 모든 필드
- P: Public - 공개 API용
- SS: Simple Short - 간단한 정보만

필드 선택

일반 필드
Relation 필드
Internal 필드

체크박스를 클릭하여 필드 포함/제외
여러 subset에서 동일 필드 선택 가능

Relation 필드는 트리 구조로 표시됨
화살표 아이콘을 클릭하여 펼치기/접기
하위 Entity의 필드도 선택 가능
예: employee.department.name

Relation 필드를 선택하면 Sonamu가 자동으로 JOIN 쿼리를 생성합니다.

부모 Relation을 선택하면 하위 필드를 개별 선택할 수 없습니다. 전체 또는 특정 필드만 선택하세요.

Enums 섹션

Enum 타입의 키와 레이블을 정의합니다.

📸 필요: Enums 섹션 화면 - 여러 Enum이 탭으로 구분

Enum 추가

Add Enum 버튼 클릭

“Add Enum” 버튼을 클릭

Enum ID 입력

PascalCase로 입력 (예: UserRole, PostStatus)
Entity ID와 연결하려면 {EntityId} 패턴 사용
- 예: $ModelRole → UserRole (자동 변환)

Enum 값 추가

각 Enum은 별도의 탭으로 표시되며, 키-레이블 쌍으로 구성됩니다.

{
  "UserRole": {
    "normal": "일반 사용자",
    "admin": "관리자",
    "superadmin": "최고 관리자"
  }
}

Enum 값 추가 방법:

“Add Row” 버튼 클릭
또는 Enum 탭에서 Ctrl+Cmd+Shift+N
Key와 Label 입력
- Key: 영문 소문자, 숫자, 언더스코어만 허용
- Label: 한글 또는 표시용 텍스트

자주 사용되는 Enum 패턴:

{Entity}OrderBy: 정렬 옵션 (예: id-desc, created_at-desc)
{Entity}SearchField: 검색 필드 (예: email, username)
{Entity}Status: 상태 (예: active, inactive, deleted)

키보드 단축키

Sonamu UI는 효율적인 작업을 위한 다양한 단축키를 제공합니다.

전역 단축키

단축키	기능
`Cmd+S`	현재 Entity 저장
`Cmd+K`	검색 모드 진입
`Tab`	다음 시트로 이동
`Shift+Tab`	이전 시트로 이동
`Esc`	다이얼로그 닫기 / 선택 해제

Props/Indexes 시트

단축키	기능
`Ctrl+Cmd+Shift+N`	새 항목 추가
`Enter`	선택한 항목 수정
`Cmd+Backspace`	선택한 항목 삭제
`↑` `↓`	항목 선택 이동
`Cmd+↑` `Cmd+↓`	항목 순서 변경

검색 모드

단축키	기능
`Cmd+K`	검색 시작
타이핑	일치하는 항목으로 자동 이동
`Enter`	검색 완료
`Esc`	검색 취소

검색 모드에서는 타이핑하는 즉시 일치하는 항목으로 커서가 이동합니다. 빠른 네비게이션에 활용하세요!

Entity 삭제하기

Entity 삭제는 되돌릴 수 없습니다. 반드시 백업 후 진행하세요.

Entity 선택

삭제할 Entity의 상세 페이지로 이동

Delete Entity 버튼 클릭

우측 상단의 “Delete Entity” 버튼 클릭

확인

확인 다이얼로그에서 Entity ID를 정확히 입력하여 삭제 확인

삭제 시 영향:

{entity}.entity.json 파일 삭제
관련된 Model, Types 파일은 수동으로 삭제 필요
데이터베이스 테이블은 마이그레이션을 통해 별도로 삭제

파일 구조

Entity를 저장하면 다음 파일들이 생성됩니다:

하이라이트된 파일들은 Sonamu가 자동으로 생성하는 파일입니다.

실시간 유효성 검사

Sonamu UI는 입력 즉시 유효성을 검사합니다:

Props
Indexes
Subsets
Enums

예약어 체크 (JavaScript/TypeScript 키워드)
타입별 필수 옵션 체크
중복 이름 체크

오류가 있으면 빨간색 테두리와 함께 오류 메시지가 표시됩니다.

📸 필요: 유효성 검사 오류 표시 예제

자동 완성 기능

Sonamu UI는 컨텍스트에 맞는 자동 완성을 제공합니다:

Entity ID 입력 시

기존 Entity 목록 제안
타이핑에 따라 필터링

Relation 설정 시

with 필드에서 사용 가능한 Entity 목록 자동 완성

Type ID 입력 시

JSON, Virtual 타입의 id 필드에서 타입 제안

Enum ID 입력 시

정의된 Enum 목록 제안
새 Enum 생성 옵션 제공

다음 단계

Sonamu UI의 기본 사용법을 익혔다면, 다음 주제를 학습하세요:

Field Types

모든 필드 타입의 상세 옵션과 사용법

Relations

Entity 간 관계 정의하는 방법

Migrations

생성된 마이그레이션 실행하기

Scaffolding

Model과 Types 파일 자동 생성

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​Sonamu UI 접속하기

​서버 실행

​UI 접속

​주요 탭 구성

​Entity 생성하기

​1. Entity 목록 페이지

​2. 새 Entity 생성

​Entity 편집하기

​Props 시트

​Props 추가하기

​Props 수정 및 삭제

​Indexes 시트

​Index 추가하기

​Subsets 시트

​Subset 키 추가

​필드 선택

​Enums 섹션

​Enum 추가

​Enum 값 추가

​키보드 단축키

​전역 단축키

​Props/Indexes 시트

​검색 모드

​Entity 삭제하기

​파일 구조

​실시간 유효성 검사

​자동 완성 기능

​다음 단계

Field Types

Relations

Migrations

Scaffolding

Sonamu UI 접속하기

서버 실행

UI 접속

주요 탭 구성

Entity 생성하기

1. Entity 목록 페이지

2. 새 Entity 생성

Entity 편집하기

Props 시트

Props 추가하기

Props 수정 및 삭제

Indexes 시트

Index 추가하기

Subsets 시트

Subset 키 추가

필드 선택

Enums 섹션

Enum 추가

Enum 값 추가

키보드 단축키

전역 단축키

Props/Indexes 시트

검색 모드

Entity 삭제하기

파일 구조

실시간 유효성 검사

자동 완성 기능

다음 단계