Serverpod Model Agent#

Serverpod .spy.yaml 모델 파일 생성 전문 에이전트

역할#

Serverpod 백엔드의 모델 파일(.spy.yaml)을 생성합니다. Entity, DTO, Enum 타입을 일관된 패턴으로 생성합니다.

실행 조건#

• /serverpod:model 커맨드 호출 시 활성화
• /feature:create 오케스트레이션의 Step 1에서 호출

Parameters#

생성 파일#

backend/petmedi_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 (필요 시)

핵심 패턴 요약#

Entity 정의#

### 엔티티 설명
class: EntityName
table: table_name

fields:
  ### 고유 식별자
  id: int?
  ### 필드 설명
  fieldName: Type
  ### 생성일시
  createdAt: DateTime
  ### 수정일시
  updatedAt: DateTime?

indexes:
  field_idx:
    fields: field

DTO 정의#

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

Enum 정의#

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

생성 후 필수 작업 ⚠️#

모델 파일(.spy.yaml) 생성 후 반드시 다음 명령어를 실행해야 합니다:

# 1. [필수] 코드 생성 - 새 모델을 Dart 코드로 변환
melos run backend:pod:generate

# 2. 커밋
git add .
git commit -m "chore(backend): 🔧 코드 생성"

# 3. (Entity 변경 시) 마이그레이션 생성
melos run backend:pod:create-migration

# 4. (Entity 변경 시) 마이그레이션 적용
melos run backend:pod:run-migration

⚠️ 중요#

backend:pod:generate를 생략하면:

• kobic_client에 새로운 모델이 반영되지 않음
• 프론트엔드에서 새 Entity/DTO를 사용할 수 없음
• 빌드 오류 발생

이 에이전트는 모델 파일 생성 후 자동으로 backend:pod:generate를 실행합니다.

체크리스트#

• 모든 필드에 한글 주석(###) 추가
• createdAt, updatedAt 필드 포함
• 필요한 인덱스 정의
• 외래키 관계 정의 (필요 시)
• 기본값 설정 (카운터, 상태 필드)
• DTO 파일 생성 (CRUD용)
• Enum 파일 생성 (필요 시)

관련 문서#

• Serverpod Endpoint Agent
• Repository 패턴