Scaffolding 탭 - 🌲 Sonamu

Scaffolding 탭에서는 Entity를 기반으로 Model과 테스트 코드를 자동 생성할 수 있습니다. CLI의 pnpm scaffold 명령어를 시각적 인터페이스로 제공합니다.

Scaffolding 탭 구조

Scaffolding 탭은 두 가지 주요 영역으로 구성됩니다:

왼쪽 Sidebar: Entity 목록과 선택 체크박스
오른쪽 Content: 코드 생성 옵션 (Model Class, Model Test, View)

생성 가능한 코드

코드 타입	설명	상태	CLI 명령어
Model Class	Entity를 위한 Model 클래스	✅ 사용 가능	`pnpm scaffold model`
Model Test	Model 테스트 파일	✅ 사용 가능	`pnpm scaffold model_test`
View List	목록 View 컴포넌트	🚧 개발 중	-
View Form	폼 View 컴포넌트	🚧 개발 중	-

View 컴포넌트 생성 기능은 현재 개발 중입니다. Sonamu UI의 다른 기능을 통해 React 컴포넌트를 생성할 수 있습니다.

Model 클래스 생성

1. Entity 선택

왼쪽 Entity 목록에서 Model을 생성할 Entity를 선택합니다. 단일 선택:

☑ User
□ Post
□ Comment

다중 선택:

☑ User
☑ Post
☑ Comment

2. 생성 옵션 선택

☑ Model Class 체크박스를 선택합니다.

3. Generate 실행

[Generate] 버튼을 클릭하면 다음 파일이 생성됩니다:

생성된 코드

src/application/user/user.model.ts

import {
  api,
  asArray,
  BadRequestException,
  BaseModelClass,
  exhaustive,
  NotFoundException,
  type ListResult,
} from "sonamu";

import { SD } from "../../i18n/sd.generated";
import { UserSubsetKey, UserSubsetMapping } from "../sonamu.generated";
import { userLoaderQueries, userSubsetQueries } from "../sonamu.generated.sso";
import { UserListParams, UserSaveParams } from "./user.types";

class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  // findById / findOne / findMany / save / del 이 @api 데코레이터와 함께 생성됩니다
}

export const UserModel = new UserModelClass();

자동 생성되는 기능:

✅ TypeScript 타입 정의
✅ Entity 연결
✅ BaseModel 상속
✅ 기본 CRUD 메서드

Model 테스트 생성

1. Entity 선택

Model과 동일하게 Entity를 선택합니다.

2. 생성 옵션 선택

☑ Model Test 체크박스를 선택합니다.

Model과 Test 동시 생성: Model Class와 Model Test를 동시에 선택하여 한 번에 생성할 수 있습니다.

3. Generate 실행

[Generate] 버튼을 클릭하면 다음 파일이 생성됩니다:

생성된 코드

src/application/user/user.model.test.ts

import { bootstrap, test } from "sonamu/test";
import { describe, expect, vi } from "vitest";

bootstrap(vi);
describe.skip("UserModelTest", () => {
  test("Query", async () => {
    expect(true).toBe(true);
  });
});

생성된 테스트는 describe.skip으로 시작합니다. 실제 테스트를 작성한 뒤 .skip을 제거해야 실행됩니다.

자동 생성되는 것:

✅ bootstrap(vi) 호출 (Sonamu 초기화 + 테스트별 트랜잭션 래핑)
✅ 비어 있는 describe.skip 블록 (테스트 케이스는 직접 작성)

일괄 생성

모든 Entity에 대해 생성

[Select All] 버튼 클릭
생성 옵션 선택
[Generate] 클릭

결과:

✓ user.model.ts created
✓ user.model.test.ts created
✓ post.model.ts created
✓ post.model.test.ts created
✓ comment.model.ts created
✓ comment.model.test.ts created

6 files generated successfully!

특정 Entity만 선택

프로젝트 초기 설정 시 모든 Entity에 대해:

☑ User
☑ Post
☑ Comment
☑ Category
☑ Tag

[Generate] → 10개 파일 생성

새 Entity 추가 시 해당 Entity만:

□ User (이미 생성됨)
□ Post (이미 생성됨)
☑ Product (신규)

[Generate] → 2개 파일 생성

생성 결과 확인

성공 메시지

✅ Code Generation Complete

Generated files:
  ✓ src/application/user/user.model.ts
  ✓ src/application/user/user.model.test.ts
  ✓ src/application/post/post.model.ts
  ✓ src/application/post/post.model.test.ts

Total: 4 files

파일 충돌

이미 존재하는 파일을 생성하려고 하면 확인 모달이 표시됩니다:

⚠️ Files Already Exist

The following files will be overwritten:
  • src/application/user/user.model.ts
  • src/application/user/user.model.test.ts

[Cancel] [Backup & Overwrite] [Overwrite]

선택 옵션:

Cancel: 생성 취소
Backup & Overwrite: 기존 파일을 .bak로 백업 후 덮어쓰기
Overwrite: 바로 덮어쓰기 (주의!)

코드 손실 주의: 기존 파일을 덮어쓰면 작성한 비즈니스 로직이 삭제될 수 있습니다. 커스터마이징한 Model은 백업하거나 덮어쓰기를 피하세요.

View 생성

Scaffolding 탭의 TemplateKey 목록에는 Model 외에 View 템플릿도 포함되어 있습니다.

TemplateKey	생성 위치
`view_list`	`web/src/routes/admin/{entities}/index.tsx`
`view_form`	`web/src/routes/admin/{entities}/form.tsx`
`view_search_input`	목록 화면에서 사용하는 검색 입력 컴포넌트

동일한 템플릿을 CLI에서도 사용할 수 있습니다: pnpm scaffold view_list, pnpm scaffold view_form.

생성 후 워크플로우

1. Model 메서드 추가

생성된 Model에 비즈니스 로직을 추가합니다:

src/application/user/user.model.ts

class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  // 이메일로 사용자 찾기
  async findByEmail(email: string): Promise<User | null> {
    return this.getPuri("r").table("users").where("email", email).first();
  }

  // 활성 사용자만 조회
  async findActiveUsers() {
    return this.getPuri("r").table("users").where("is_active", true).where("deleted_at", null);
  }
}

2. 테스트 추가

생성된 테스트 파일에 추가 테스트를 작성합니다:

src/application/user/user.model.test.ts

describe("User Model - Extended", () => {
  test("findByEmail", async () => {
    const user = await UserModel.findByEmail("user@example.com");
    expect(user).toBeDefined();
    expect(user?.email).toBe("user@example.com");
  });

  test("findActiveUsers", async () => {
    const users = await UserModel.findActiveUsers();
    users.forEach((user) => {
      expect(user.is_active).toBe(true);
    });
  });
});

3. API 추가

Model에 @api 데코레이터를 사용하여 API 엔드포인트를 추가합니다:

class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  @api({ httpMethod: "GET" })
  async findActiveUsers() {
    const { qb } = this.getSubsetQueries("A");
    qb.where("is_active", true);

    return this.executeSubsetQuery({
      subset: "A",
      qb,
      params: { num: 20, page: 1 },
    });
  }
}

실전 팁

1. 프로젝트 초기 설정

1. 모든 Entity 정의
   ↓
2. Scaffolding 탭에서 일괄 생성
   - [Select All]
   - Model Class ☑
   - Model Test ☑
   - [Generate]
   ↓
3. 각 Model에 비즈니스 로직 추가

2. 새 Entity 추가 시

1. Entity 탭에서 Entity 생성
   ↓
2. Migration 탭에서 마이그레이션 실행
   ↓
3. Scaffolding 탭에서 해당 Entity만 생성
   ↓
4. 비즈니스 로직 및 테스트 작성

3. 재생성이 필요한 경우

Entity 구조가 크게 변경되어 Model을 재생성해야 하는 경우:

# 기존 파일 백업
cp src/application/user/user.model.ts src/application/user/user.model.ts.bak

# UI에서 재생성
[Backup & Overwrite]

# 백업 파일에서 커스텀 로직 복원

​Scaffolding 탭 구조

​생성 가능한 코드

​Model 클래스 생성

​1. Entity 선택

​2. 생성 옵션 선택

​3. Generate 실행

​생성된 코드

​Model 테스트 생성

​1. Entity 선택

​2. 생성 옵션 선택

​3. Generate 실행

​생성된 코드

​일괄 생성

​모든 Entity에 대해 생성

​특정 Entity만 선택

​생성 결과 확인

​성공 메시지

​파일 충돌

​View 생성

​생성 후 워크플로우

​1. Model 메서드 추가

​2. 테스트 추가

​3. API 추가

​실전 팁

​1. 프로젝트 초기 설정

​2. 새 Entity 추가 시

​3. 재생성이 필요한 경우

​다음 단계

Model

scaffold CLI

Scaffolding 탭 구조

생성 가능한 코드

Model 클래스 생성

1. Entity 선택

2. 생성 옵션 선택

3. Generate 실행

생성된 코드

Model 테스트 생성

1. Entity 선택

2. 생성 옵션 선택

3. Generate 실행

생성된 코드

일괄 생성

모든 Entity에 대해 생성

특정 Entity만 선택

생성 결과 확인

성공 메시지

파일 충돌

View 생성

생성 후 워크플로우

1. Model 메서드 추가

2. 테스트 추가

3. API 추가

실전 팁

1. 프로젝트 초기 설정

2. 새 Entity 추가 시

3. 재생성이 필요한 경우

다음 단계