> ## 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를 더 효율적으로 사용하기 위한 **실용적인 팁과 모범 사례**를 소개합니다.

## 키보드 단축키

빠른 작업을 위한 필수 단축키:

| 단축키             | 기능    | 설명               |
| --------------- | ----- | ---------------- |
| `⌘K` / `Ctrl+K` | 검색    | 전체 검색 모달 열기      |
| `Esc`           | 닫기    | 열린 모달 닫기         |
| `⌘S` / `Ctrl+S` | 저장    | 현재 편집 내용 저장      |
| `Tab`           | 다음 필드 | 폼 입력 시 다음 필드로 이동 |
| `Enter`         | 확인    | 폼 제출 또는 편집 완료    |

<Tip>**검색 활용**: `⌘K`로 검색을 열고 Entity 이름, 필드명 등을 빠르게 찾을 수 있습니다.</Tip>

## Entity 관리 팁

### 1. 부모-자식 Entity 구조화

관련된 Entity들은 부모-자식 관계로 구조화하세요:

```
Order (부모)
├── OrderItem (자식)
├── OrderPayment (자식)
└── OrderShipment (자식)
```

**장점**:

* 사이드바에서 계층 구조로 표시
* 관련 Entity를 쉽게 찾을 수 있음
* 논리적 그룹핑

### 2. 명명 규칙 일관성

| 구분        | 규칙          | 예시                        |
| --------- | ----------- | ------------------------- |
| Entity ID | PascalCase  | `User`, `OrderItem`       |
| 필드명       | snake\_case | `created_at`, `user_id`   |
| Enum      | PascalCase  | `UserRole`, `OrderStatus` |
| Subset ID | 대문자         | `A`, `B`, `C`             |

### 3. AI 채팅 활용

**효과적인 프롬프트 작성**:

```
❌ 나쁜 예:
"사용자 만들어줘"

✅ 좋은 예:
"이커머스 사용자 Entity를 만들어줘.
필드: 이메일(unique), 이름, 전화번호(nullable),
역할(enum: admin, user, guest),
생성일, 마지막 로그인"
```

**구체적으로 요청**:

* 필드 타입과 제약조건 명시
* 관계 설정 설명
* 인덱스 필요 여부 언급

### 4. Property 순서 정리

의미 있는 순서로 필드를 배치하세요:

```typescript theme={null}
{
  properties: [
    // 1. Primary Key
    { name: "id", ... },

    // 2. 핵심 정보
    { name: "title", ... },
    { name: "content", ... },

    // 3. 외래키
    { name: "user_id", ... },
    { name: "category_id", ... },

    // 4. 상태/플래그
    { name: "status", ... },
    { name: "is_active", ... },

    // 5. 타임스탬프
    { name: "created_at", ... },
    { name: "updated_at", ... },
  ]
}
```

## Migration 팁

### 1. 작은 단위로 자주 실행

```
❌ 나쁜 예:
- 10개 Entity 한번에 수정
- 1주일에 한 번 마이그레이션

✅ 좋은 예:
- 1-2개 Entity씩 수정
- 하루에 여러 번 마이그레이션
- 각 마이그레이션 후 테스트
```

### 2. Migration Preview 활용

실행 전 반드시 Preview를 확인하세요:

**확인 사항**:

* ✅ 추가되는 컬럼이 맞는가?
* ⚠️ 삭제되는 컬럼은 없는가?
* 🔄 타입 변경이 의도한 것인가?

### 3. 프로덕션 마이그레이션 체크리스트

```
□ Development DB에서 테스트 완료
□ Testing DB에서 검증 완료
□ 데이터 백업 완료
□ 마이그레이션 Preview 확인
□ 롤백 계획 수립
□ 팀원에게 공지
□ Production DB 마이그레이션 실행
□ 애플리케이션 재시작 및 확인
```

## Scaffolding 팁

### 1. 일괄 생성 전략

**프로젝트 초기**:

```
1. 모든 Entity 정의
2. [Select All] → Model + Test 일괄 생성
3. 각 Model에 비즈니스 로직 추가
```

**개발 중**:

```
1. 새 Entity 하나만 추가
2. 해당 Entity만 선택하여 생성
3. 즉시 개발 시작
```

### 2. 파일 백업 습관

중요한 비즈니스 로직이 있는 Model은 재생성 전 백업:

```bash theme={null}
# 백업
cp src/models/User.model.ts src/models/User.model.ts.bak

# 재생성
[UI에서 Overwrite]

# 필요한 로직 복원
```

### 3. Git 활용

생성된 파일을 바로 커밋하여 변경 이력 관리:

```bash theme={null}
git add src/models/
git commit -m "Generate models for User, Post, Comment"
```

## Subset 활용 팁

### 1. 표준 Subset 정의

모든 Entity에 일관된 Subset을 정의하세요:

```typescript theme={null}
// 모든 Entity에 공통 적용

Subset A: 목록용
- id
- title (또는 name)
- 핵심 1-2개 필드
- created_at

Subset B: 상세용
- 모든 일반 필드
- 민감 정보 제외
- 타임스탬프 포함

Subset C: 관계 포함
- Subset B 기반
- 필요한 관계 추가
```

### 2. 성능 최적화

**필요한 필드만 포함**:

```typescript theme={null}
// ❌ 과도한 필드
{
  ...모든필드,
  author: "User.C",  // User의 모든 관계까지
  category: "Category.B",
  tags: "Tag.C",
}

// ✅ 최적화
{
  id: true,
  title: true,
  content: true,
  author: "User.A",  // 최소 정보만
  category_id: true,
  created_at: true,
}
```

### 3. API별 Subset 선택

| API     | 추천 Subset | 이유     |
| ------- | --------- | ------ |
| 목록 조회   | A         | 빠른 응답  |
| 상세 조회   | B 또는 C    | 전체 정보  |
| 자동완성    | A (최소화)   | 초고속 응답 |
| 관리자 페이지 | C         | 모든 정보  |

## 검색 활용

### 빠른 탐색

검색(`⌘K`)으로 다음을 찾을 수 있습니다:

* **Entity**: `User`, `Post`
* **필드**: `email`, `created_at`
* **Migration**: 파일명 검색
* **Subset**: `User.Subset A`

**검색 팁**:

```
user email       → User Entity의 email 필드
post migration   → Post 관련 마이그레이션
subset A         → 모든 Subset A
```

## 워크플로우 최적화

### 신규 기능 개발 플로우

```
1. Entity 정의 (Entity 탭)
   - AI 채팅으로 빠른 생성
   - 필드와 관계 설정
   ↓
2. Subset 정의 (Entity 탭 내)
   - A, B, C 표준 Subset 생성
   ↓
3. Migration 실행 (Migration 탭)
   - Preview 확인
   - Development → Testing 순서로 실행
   ↓
4. Scaffolding (Scaffolding 탭)
   - Model + Test 생성
   ↓
5. 개발 (코드 에디터)
   - Model 메서드 추가
   - API 엔드포인트 구현
   - 테스트 작성
   ↓
6. Fixture 등록 (Fixture 탭)
   - 테스트 데이터 준비
```

### Entity 수정 플로우

```
1. Entity 수정 (Entity 탭)
   - 필드 추가/수정/삭제
   ↓
2. Migration 생성 확인 (Migration 탭)
   - 자동 생성된 마이그레이션 확인
   ↓
3. Preview 검토
   - 의도한 변경사항인지 확인
   - 데이터 손실 위험 체크
   ↓
4. Migration 실행
   - Development → Testing 순서
   ↓
5. Model 수정 (필요 시)
   - 타입 자동 동기화 확인
   - 새 필드 활용 로직 추가
```

## 브라우저 개발자 도구 활용

### Network 탭

API 호출을 확인하여 디버깅:

```
F12 → Network 탭

- 마이그레이션 실행 → /api/migrate/run 확인
- Entity 저장 → /api/entity/save 확인
- 에러 발생 시 응답 내용 확인
```

### Console 탭

에러 메시지 확인:

```
F12 → Console 탭

- JavaScript 에러 확인
- API 응답 에러 로그
- 네트워크 요청 실패 원인
```

## 문제 해결

### UI가 느릴 때

**원인**: 너무 많은 Entity나 큰 데이터
**해결**:

* 브라우저 캐시 삭제
* 불필요한 브라우저 탭 닫기
* Sonamu UI 재시작

### 변경사항이 반영되지 않을 때

**해결**:

1. 브라우저 새로고침 (`F5`)
2. 하드 리로드 (`⌘⇧R` / `Ctrl+Shift+R`)
3. API 서버 재시작
4. Sonamu UI 재시작

### Entity 저장 실패

**확인 사항**:

* API 서버가 실행 중인가?
* 파일 쓰기 권한이 있는가?
* 필드명이 유효한가? (예약어 체크)
* 외래키 참조가 올바른가?

## 다음 단계

<CardGroup cols={2}>
  <Card title="Entity 관리" icon="cube" href="/ko/tools-and-cli/sonamu-ui/entity-management">
    Entity 관리 자세히 보기
  </Card>

  <Card title="Sonamu CLI" icon="terminal" href="/ko/tools-and-cli/sonamu-cli">
    CLI로 고급 작업하기
  </Card>
</CardGroup>