메인 콘텐츠로 건너뛰기
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개의 주요 탭으로 구성됩니다:
Entity 정의와 관리
  • Entity 생성, 수정, 삭제
  • Props, Indexes, Subsets, Enums 설정

​
Entity 생성하기

​
1. Entity 목록 페이지

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

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

표시 정보:
  • Entity ID와 Title
  • 테이블명
  • Props 개수
  • Relation 개수

​
2. 새 Entity 생성

1

Create Entity 버튼 클릭

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

기본 정보 입력

Entity 생성 폼에서 다음 정보를 입력합니다:
  • Entity ID: PascalCase (예: User, BlogPost)
  • Table Name: snake_case (예: users, blog_posts)
  • Title: 한글 또는 표시명 (예: “사용자”, “블로그 글”)
  • Parent ID: 선택 사항 - 다른 Entity를 상속할 때 사용
Entity ID는 생성 후 변경할 수 없으므로 신중하게 입력하세요.
3

저장

“Create” 버튼을 클릭하면:
  • {entity}.entity.json 파일 생성
  • Entity 상세 페이지로 자동 이동

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

​
Entity 편집하기

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

​
Props 시트

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

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

​
Props 추가하기

1

Add Property 버튼 클릭

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

속성 정보 입력

기본 필드:
  • name: 속성명 (snake_case)
  • type: 데이터 타입 (드롭다운에서 선택)
  • desc: 설명 (선택 사항)
  • nullable: NULL 허용 여부 (체크박스)
  • dbDefault: 데이터베이스 기본값
타입별 추가 옵션:
  • length: 문자열 길이 (기본값: TEXT)
  • 예: length: 255 → VARCHAR(255)
  • precision: 전체 자릿수
  • scale: 소수점 자릿수
  • numberType: real | double precision | numeric (기본값: numeric)
  • 예: precision: 10, scale: 2 → NUMERIC(10, 2)
  • precision: 전체 자릿수
  • scale: 소수점 자릿수
  • 주의: TypeScript에서 string 타입으로 처리됨 (정밀도 유지)
  • id: Enum 타입 ID (예: UserRole)
  • Enum은 별도의 Enums 섹션에서 정의
  • id: JSON 스키마 타입 ID
  • TypeScript 타입을 {entity}.types.ts에서 정의
  • dimensions: 벡터 차원 (예: 1536)
  • pgvector 확장 필요
  • id: Virtual 타입 ID
  • virtualType: code | query
    • code: TypeScript 코드로 계산 (기본값)
    • query: SQL 쿼리로 계산
  • 데이터베이스에 저장되지 않는 계산된 필드
  • Relation 타입 선택 및 설정
  • 자세한 내용은 Relations 참조
3

저장

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

​
Props 수정 및 삭제

  • Props 목록에서 수정할 행을 더블클릭 또는 Enter 키
  • 또는 행 선택 후 우측의 “Edit” 버튼 클릭
  • 폼에서 값 수정 후 저장
Props를 삭제하면 해당 컬럼이 모든 Subset에서도 자동으로 제거됩니다. 복구할 수 없으므로 주의하세요.

​
Indexes 시트

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

📸 필요: Indexes 시트 화면

​
Index 추가하기

1

Add Index 버튼 클릭

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

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 키 추가

1

Add Subset 버튼 클릭

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

Subset 키 입력

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

​
필드 선택

  • 체크박스를 클릭하여 필드 포함/제외
  • 여러 subset에서 동일 필드 선택 가능
부모 Relation을 선택하면 하위 필드를 개별 선택할 수 없습니다. 전체 또는 특정 필드만 선택하세요.

​
Enums 섹션

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

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

​
Enum 추가

1

Add Enum 버튼 클릭

“Add Enum” 버튼을 클릭
2

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 삭제는 되돌릴 수 없습니다. 반드시 백업 후 진행하세요.
1

Entity 선택

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

Delete Entity 버튼 클릭

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

확인

확인 다이얼로그에서 Entity ID를 정확히 입력하여 삭제 확인
삭제 시 영향:
  • {entity}.entity.json 파일 삭제
  • 관련된 Model, Types 파일은 수동으로 삭제 필요
  • 데이터베이스 테이블은 마이그레이션을 통해 별도로 삭제

​
파일 구조

Entity를 저장하면 다음 파일들이 생성됩니다:
하이라이트된 파일들은 Sonamu가 자동으로 생성하는 파일입니다.

​
실시간 유효성 검사

Sonamu UI는 입력 즉시 유효성을 검사합니다:
  • 예약어 체크 (JavaScript/TypeScript 키워드)
  • 타입별 필수 옵션 체크
  • 중복 이름 체크
오류가 있으면 빨간색 테두리와 함께 오류 메시지가 표시됩니다.

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

​
자동 완성 기능

Sonamu UI는 컨텍스트에 맞는 자동 완성을 제공합니다:
  • 기존 Entity 목록 제안
  • 타이핑에 따라 필터링
  • with 필드에서 사용 가능한 Entity 목록 자동 완성
  • JSON, Virtual 타입의 id 필드에서 타입 제안
  • 정의된 Enum 목록 제안
  • 새 Enum 생성 옵션 제공

​
다음 단계

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

Field Types

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

Relations

Entity 간 관계 정의하는 방법

Migrations

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

Scaffolding

Model과 Types 파일 자동 생성