/serverpod:model — 데이터 설계도 만들기 도우미#

한마디로#

새 기능에 필요한 "데이터 보관 양식(설계도)"을 자동으로 만들어 주는 도우미입니다. 물건을 넣을 서랍장을 짤 때 "이 칸엔 제목, 이 칸엔 작성자, 이 칸엔 작성 날짜"처럼 칸을 미리 정해 두는 일과 같아요.

누가·언제 쓰나요#

• 새 기능을 만들면서 어떤 정보를 저장할지 정의해야 하는 백엔드 개발자
• /serverpod:model 명령을 직접 실행할 때
• 전체 기능 생성(/feature:create)의 첫 단계에서 자동으로 호출될 때

무엇을 해주나요#

데이터 양식 파일(.spy.yaml)을 정해진 폴더에 자동으로 만들어 줍니다. 구체적으로는:

• Entity 파일 — 실제로 저장할 정보의 본체 양식 (예: {entity_name}.spy.yaml)
• DTO 파일 — 만들기/수정하기/목록 보기 같은 작업에 쓰는 요청·응답 양식 (생성·수정·목록 응답용)
• Enum 파일 — "상태값" 같은 정해진 선택지 목록 (필요한 경우에만)

만들어진 뒤에는 이 양식을 실제 코드로 바꾸는 작업(코드 생성)과, 데이터베이스 반영(마이그레이션)까지 이어집니다.

어떻게 쓰나요#

# 명령 실행 (별칭으로도 호출 가능)
/serverpod:model
/backend:model
/model:create

실행할 때는 아래 값을 함께 넘깁니다. (✅ 표시는 반드시 필요한 값)

• feature_name ✅ — 기능 모듈 이름 (snake_case, 예: community_post)
• entity_name ✅ — 저장할 정보의 이름 (PascalCase, 예: Post)
• fields ✅ — 어떤 칸(필드)들을 둘지 목록
• has_crud — 만들기/수정 같은 작업용 양식(CRUD DTO)을 자동 생성할지 (기본값: 켜짐)

안에서 무슨 일이 벌어지나요#

1. 정해진 폴더 구조에 맞춰 Entity, DTO, Enum 양식 파일(.spy.yaml)을 만듭니다.
2. 각 칸에는 한국어 설명, 작성·수정 날짜, 필요한 색인(index), 다른 데이터와의 연결 관계, 기본값(조회수·상태 등)을 빠짐없이 채웁니다.
3. 양식을 다 만든 뒤 코드 생성(backend:pod:generate)을 자동으로 실행합니다. 이 단계를 건너뛰면 새 양식이 프론트엔드에 반영되지 않아 빌드 오류가 납니다.
4. Entity가 바뀐 경우에는 데이터베이스 반영용 마이그레이션을 만들고 적용합니다.

backend/kobic_server/lib/src/feature/{feature_name}/model/
├── entities/
│   └── {entity_name}.spy.yaml
├── dto/
│   ├── {entity_name}_create_request.spy.yaml
│   ├── {entity_name}_update_request.spy.yaml
│   └── {entity_name}_list_response.spy.yaml
└── enum/
    └── {entity_name}_status.spy.yaml (if needed)

### Entity description
class: EntityName
table: table_name

fields:
  ### Unique identifier
  id: int?
  ### Field description
  fieldName: Type
  ### Created timestamp
  createdAt: DateTime
  ### Updated timestamp
  updatedAt: DateTime?

indexes:
  field_idx:
    fields: field

### Request DTO
class: EntityCreateRequest
fields:
  requiredField: Type
  optionalField: Type?

enum: EnumName
serialized: byName
values:
  - value1
  - value2

createdAt: DateTime
updatedAt: DateTime?

authorId: int
authorName: String
authorProfileUrl: String?

viewCount: int, default=0
likeCount: int, default=0

status: EntityStatus, default=active
isDeleted: bool, default=false

# 1. [Required] Code generation - Convert new models to Dart code
melos run backend:pod:generate

# 2. Commit
git add .
git commit -m  " chore(backend): code generation " 

 # 3. (For Entity changes) Create migration
melos run backend:pod:create-migration

# 4. (For Entity changes) Apply migration
melos run backend:pod:run-migration