> ## 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 사용에 관한 일반적인 질문

## 시작하기

<AccordionGroup>
  <Accordion title="Sonamu를 사용하여 새 프로젝트를 시작하려면 어떻게 해야 하나요?">
    다음 명령어로 새 프로젝트를 생성합니다:

    ```bash theme={null}
    pnpm create sonamu
    ```

    대화형 프롬프트에 따라 프로젝트 설정:

    ```bash theme={null}
    ? Project name: my-app
    ? Would you like to set up pnpm? Yes
    ? Would you like to set up a database using Docker? Yes
    ? Enter the Docker project name: my-app-container
    ? Enter the database user: postgres
    ? Enter the container name: my-app-pg
    ? Enter the database name: my-app
    ? Enter the database password: ****
    ```

    프로젝트 실행:

    ```bash theme={null}
    # 1. 데이터베이스 시작
    cd my-app/api
    pnpm db:up

    # 2. API 서버 시작 (Sonamu UI 포함)
    pnpm dev

    # 3. 새 터미널에서 Web 서버 시작
    cd my-app/web
    pnpm dev
    ```

    접속 가능한 URL:

    ```
    API: http://localhost:34900
    Sonamu UI: http://localhost:34900/sonamu-ui
    Web: http://localhost:5173
    ```

    요구사항: `Node.js >= 18`, `pnpm >= 10`, `Docker`
  </Accordion>

  <Accordion title="Sonamu는 어떤 기술 스택을 사용하나요?">
    ```
    백엔드: TypeScript, Node.js, Fastify, Knex.js, PostgreSQL, Zod
    프론트엔드: React, TanStack Query, Axios, Tailwind CSS
    개발 도구: pnpm, Docker
    자동 생성: 마이그레이션 파일, TypeScript 타입, API 엔드포인트, React hooks
    ```
  </Accordion>
</AccordionGroup>

***

## 개발 환경

<AccordionGroup>
  <Accordion title="pnpm dev 명령어를 실행하면 정확히 어떤 일이 일어나나요?">
    1. **TypeScript 파일 즉시 실행**
       * `@sonamu-kit/ts-loader`로 TypeScript 파일을 런타임에 즉시 변환
       * Node.js의 `--import` 플래그로 등록

    2. **Sonamu 초기화 (`Sonamu.init`)**
       * DB 설정 로드
       * Entity 파일 로드
       * Syncer 생성 및 Types/Models/APIs 자동 로드
       * 초기 싱크 실행 (`syncer.sync()`)
       * 파일 감시 시작 (`startWatcher()`)

    3. **Fastify 서버 생성 및 설정**
       * 플러그인 등록 (`formbody`, `multipart`, `session` 등)
       * Auth 설정 (필요시)
       * `@api` 데코레이터가 붙은 메서드들을 API 엔드포인트로 등록

    4. **서버 리스닝 시작**
       * 설정된 포트에서 Fastify 서버 시작

    5. **HMR 활성화**
       * 파일 변경 감지 시 자동으로 타입 재생성 및 모듈 리로드
  </Accordion>

  <Accordion title="pnpm dev를 실행했는데 &#x22;Port 34900 is already in use&#x22; 에러가 발생합니다">
    **방법 1: 포트 변경**

    ```typescript theme={null}
    // api/src/sonamu.config.ts
    export default {
      server: {
        listen: {
          port: 2028, // 원하는 포트로 변경
        },
      },
    } satisfies SonamuConfig;
    ```

    **방법 2: 기존 프로세스 종료 (macOS/Linux)**

    ```bash theme={null}
    lsof -ti:34900 | xargs kill -9
    ```
  </Accordion>
</AccordionGroup>

***

## 파일 생성

<AccordionGroup>
  <Accordion title="Sonamu가 생성하는 코드에는 어떤 것들이 있나요?">
    ```
    타입 파일: {entity}.types.ts, sonamu.generated.ts
    마이그레이션: migrations/{timestamp}_{entity}_create.ts
    Model 클래스: {entity}.model.ts (Scaffolding)
    테스트 파일: {entity}.model.test.ts
    View 파일: React 컴포넌트 (목록, 상세, 편집)
    클라이언트 코드: Axios 클라이언트, TanStack Query hooks
    ```
  </Accordion>

  <Accordion title="Sonamu가 생성하는 각 파일은 무엇이고 언제 생성되나요?">
    **1. 자동 생성 (Entity 생성/수정 시)**

    * `{entity}.entity.json`
      * Entity의 테이블 구조, 필드, 관계, 인덱스, Subset 정의
      * 생성: Sonamu UI에서 Entity 생성 시

    * `{entity}.types.ts`
      * Entity의 커스텀 타입 정의
      * 생성: Entity 생성 시 (초기 템플릿만, 이후 개발자가 수정)

    * `sonamu.generated.ts`
      * 모든 Entity의 `BaseSchema`, `Enum`, `Subset` 타입 자동 생성
      * 생성: Entity 또는 타입 파일 변경 시마다 자동 재생성

    * `sonamu.generated.sso.ts`
      * Subset별 쿼리 빌더와 서버 전용 타입
      * 생성: Entity 변경 시마다 자동 재생성

    **2. 수동 생성 (Sonamu UI에서 Generate 클릭)**

    * `migrations/{timestamp}_{action}.ts`
      * 데이터베이스 스키마 변경을 위한 마이그레이션 파일
      * 생성: DB Migration 탭에서 Generate 클릭 시

    * `{entity}.model.ts`
      * Entity의 비즈니스 로직과 `@api` 데코레이터로 API 정의
      * 생성: Scaffolding 탭에서 Model 템플릿 Generate 시 (1회만)

    * `{entity}.model.test.ts`
      * Model 메서드의 단위 테스트 파일
      * 생성: Scaffolding 탭에서 Test 템플릿 Generate 시

    * `*.view.tsx`
      * React 기반 백오피스 UI 컴포넌트
      * 생성: Scaffolding 탭에서 View 템플릿 Generate 시

    **3. 자동 생성 (API 서버 실행 중)**

    * `{entity}.service.ts`
      * 백엔드 API를 호출하는 프론트엔드 클라이언트 코드
      * 생성: Model 파일 변경 감지 시

    * `sonamu.generated.http`
      * VSCode REST Client용 API 테스트 템플릿
      * 생성: `@api` 데코레이터가 있는 메서드 추가/변경 시

    * 프론트엔드 파일 복사
      * `types.ts`, `generated.ts` 등이 `web/src/services/`로 자동 복사
      * 생성: 백엔드 파일 변경 시 sync.targets에 정의된 경로로 자동 복사

    * `sonamu.lock`
      * 파일 변경 추적을 위한 체크섬 파일
      * 생성: 파일 변경 추적을 위해 자동 갱신
  </Accordion>

  <Accordion title="Sonamu에 의해 생성된 코드를 직접 수정하면 어떻게 되나요?">
    **항상 덮어쓰기 (overwrite: true)**

    다음 파일들은 재생성 시 항상 덮어쓰기되므로 **수정하지 마세요**:

    * `sonamu.generated.ts` - Entity 변경 시 항상 재생성
    * `sonamu.generated.sso.ts` - Entity 변경 시 항상 재생성
    * `{entity}.service.ts` - Model 변경 시 항상 재생성
    * `sonamu.generated.http` - `@api` 메서드 변경 시 항상 재생성

    **재생성 시 보호 (overwrite: false, 기본값)**

    다음 파일들은 재생성해도 덮어쓰이지 않으므로 **자유롭게 수정 가능**:

    * `{entity}.types.ts` - 커스텀 타입 추가 가능
    * `{entity}.model.ts` - 비즈니스 로직 추가/수정 가능
    * `{entity}.model.test.ts` - 테스트 케이스 추가/수정 가능
    * `*.view.tsx` - UI 커스터마이징 가능

    **Best Practice:**

    * 커스텀 타입은 `{entity}.types.ts`에 추가
    * 비즈니스 로직은 `{entity}.model.ts`에 구현
    * Entity 정의는 Sonamu UI 사용
  </Accordion>

  <Accordion title="Sonamu가 관리하는 lock 파일과 생성 코드는 버전 컨트롤의 대상인가요?">
    **반드시 커밋해야 하는 파일:**

    * `sonamu.lock` - Entity 스키마 변경 추적, 팀 동기화
    * `sonamu.generated.ts` - 타입 동기화, 프론트엔드에서 즉시 사용 가능
    * `{entity}.types.ts` - 커스텀 타입 정의
    * `migrations/*.ts` - DB 스키마 변경 이력
    * `{entity}.model.ts` - 비즈니스 로직

    **이유:**

    * 타입 동기화로 프론트엔드 개발자가 즉시 사용 가능
    * 빌드 시간 단축
    * 코드 리뷰 용이
  </Accordion>
</AccordionGroup>

***

## 스캐폴딩

<AccordionGroup>
  <Accordion title="스캐폴딩이란 무엇이고, 왜 필요한가요?">
    템플릿 기반으로 반복적인 기본 코드(보일러플레이트)를 자동 생성하는 기능입니다.

    **생성 가능한 것:**

    * Model 클래스 (`{entity}.model.ts`)
    * Test 파일 (`{entity}.model.test.ts`)
    * View 컴포넌트 (`*.view.tsx`)

    **실행 방법:**

    1. Sonamu UI 접속
    2. Scaffolding 탭 이동
    3. Entity 선택
    4. Template 선택 (model/model\_test/view\_list/view\_form)
    5. Generate 클릭

    **필요한 이유:**

    * 반복적인 CRUD 코드 자동 생성으로 개발 시간 단축
    * 일관된 코드 구조 유지
    * 오타나 누락 방지
    * 초보자도 표준 패턴 학습 가능

    **overwrite 옵션:**

    * `overwrite: false` (기본값): 파일이 이미 존재하면 생성하지 않음 (model, test, view 템플릿)
    * `overwrite: true`: 파일이 존재해도 항상 덮어쓰기 (generated, service 템플릿)
  </Accordion>
</AccordionGroup>

***

## 관련 문서

* [프로젝트 시작하기](/ko/getting-started/quick-start)
* [Entity 정의하기](/ko/core-concepts/entities/defining-entities)
* [스캐폴딩 사용하기](/ko/tools-and-cli/scaffolding)
* [마이그레이션 관리](/ko/database/migrations/migration-basics)