> ## Documentation Index
> Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 시작하기

> Sonamu UI 실행 및 접속하기

Sonamu UI는 **Entity, Migration, Scaffolding, Fixture 관리를 위한 웹 기반 개발 도구**입니다. CLI로 수행하던 작업들을 시각적인 인터페이스로 더 쉽게 할 수 있으며, 테스트 결과 확인과 CDD 계약 관리 기능도 제공합니다.

## Sonamu UI란?

Sonamu UI는 다음 기능을 제공합니다:

| 기능               | 설명                                   | CLI 대체             |
| ---------------- | ------------------------------------ | ------------------ |
| **Entity 관리**    | Entity 생성, 수정, 삭제                    | `pnpm stub entity` |
| **DB Migration** | 마이그레이션 생성 및 실행                       | `pnpm migrate`     |
| **Scaffolding**  | Model, 테스트 자동 생성                     | `pnpm scaffold`    |
| **Fixture**      | 테스트 데이터 관리                           | `pnpm fixture`     |
| **i18n**         | 국제화 문자열 관리                           | 수동 편집              |
| **Tasks**        | 워크플로우 실행 모니터링                        | -                  |
| **Test Results** | 테스트 실행 결과 확인                         | -                  |
| **CDD**          | Contract-Driven Development 계약/스펙 관리 | -                  |

## 실행 방법

### 개발 환경에서 실행

Sonamu UI는 **API 서버에 내장**되어 있습니다. 별도의 명령어가 필요 없습니다.

```bash theme={null}
# API 서버 실행
cd api
pnpm dev
```

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

**기본 URL**: `http://localhost:34900/sonamu-ui`

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

### 일반적인 개발 워크플로우

```bash theme={null}
# API 서버 실행 (Sonamu UI 포함)
cd api
pnpm dev

# 브라우저에서 접속
# http://localhost:34900/sonamu-ui
```

## 인터페이스 구조

<Frame caption="Sonamu UI 전체 화면">
  <img src="https://mintcdn.com/cartanova-7788888c/wk-O_9zBoKGthXNV/images/sonamuUI-created-entity.png?fit=max&auto=format&n=wk-O_9zBoKGthXNV&q=85&s=8a0bfe09c51843f4ca9fad863996edc5" alt="Sonamu UI 전체 화면" width="2872" height="1916" data-path="images/sonamuUI-created-entity.png" />
</Frame>

Sonamu UI는 크게 세 가지 영역으로 구성됩니다:

### 1. Global Navigation Bar (GNB)

화면 상단에 위치하며 주요 기능에 빠르게 접근할 수 있습니다.

| 메뉴                | 기능               |
| ----------------- | ---------------- |
| **Entities**      | Entity 생성 및 편집   |
| **DB Migration**  | 마이그레이션 관리        |
| **Scaffolding**   | Model/Test 코드 생성 |
| **Fixture**       | 테스트 데이터 관리       |
| **i18n**          | 국제화 문자열 관리       |
| **Tasks**         | 워크플로우 실행 모니터링    |
| **Test Results**  | 테스트 실행 결과 확인     |
| **CDD**           | CDD 계약/스펙 관리     |
| **Search** (`⌘K`) | 전체 검색            |

### 2. Sidebar

화면 왼쪽에 위치하며 현재 선택한 메뉴의 항목 목록을 표시합니다.

* **Entities 탭**: 모든 Entity 목록 표시
* **Migrations 탭**: 마이그레이션 파일 목록
* **하단 버튼**: 새 항목 추가 버튼 (예: New Entity)

### 3. Main Content Area

화면 중앙의 넓은 영역으로 선택한 항목의 상세 정보를 표시하고 편집합니다.

* Entity 속성 편집
* 마이그레이션 미리보기
* 코드 생성 옵션 등

## 키보드 단축키

| 단축키                             | 기능       |
| ------------------------------- | -------- |
| `⌘K` (Mac) / `Ctrl+K` (Windows) | 검색 모달 열기 |
| `Esc`                           | 모달 닫기    |

## 다음 단계

<CardGroup cols={2}>
  <Card title="Entity 관리" icon="cube" href="/ko/tools-and-cli/sonamu-ui/entity-management">
    Entity 생성 및 편집하기
  </Card>

  <Card title="Scaffolding" icon="wand-magic-sparkles" href="/ko/tools-and-cli/sonamu-ui/scaffolding-tab">
    코드 자동 생성하기
  </Card>

  <Card title="Tasks" icon="list-check" href="/ko/tools-and-cli/sonamu-ui/tasks-tab">
    워크플로우 모니터링하기
  </Card>
</CardGroup>