Skip to main content

코디 모듈 개발 착수 계획 (MVP)

기준일: 2026-03-04

1. 적용 고정 사항 (결정 확정)​

  1. coordis와 outfits는 분리 테이블로 유지한다.
  2. outfits.coordiId는 필수(NOT NULL)다.
  3. 공유 적용은 원본 참조가 아니라 내 계정 복제 방식만 허용한다.
  4. 착장 생성 기본 배치는 4장(batch_size=4) 이다.
  5. Scene 생성에서 image_1은 항상 outfit이다.
  6. Scene 생성에서 image_2, image_3는 선택 참조 입력으로 허용한다.
  7. 코디 텍스트 프롬프트가 있으면 Scene 프롬프트 합성에 포함한다.
  8. MVP 범위에서 coordi_cards, persona_versions, coordi versioning은 도입하지 않는다.

2. 모듈 분해​

2.1 Backend 서브모듈​

  • coordis
    • CRUD
    • 공개 코디 복제(copy to my account)
  • outfits
    • 착장 생성 요청(배치 4)
    • 후보 선택 저장
    • CRUD
  • default-assets
    • 관리자용 기본 에셋 관리
    • USER/SYSTEM 출처 분리
    • 관리자 업로드 이미지/영상 저장소
    • 사용자 조회용 includeSystem 필터
  • generation-bridge
    • Persona/Coordi/Scene 입력 주입 규칙
    • creations.snapshot 및 projection 저장
    • creation_results 정렬/seed 저장

2.2 Frontend 서브모듈​

  • /personas/[id] 허브
    • 탭: 코디 | 착장
    • 코디 선택 -> 착장 생성 -> Scene 진입
  • 각 좌측 목록
    • 기본 에셋 포함 체크박스
    • 기본값은 포함
    • SYSTEM 에셋은 읽기 전용 렌더링
  • /personas/[id]/prepare/image|video
    • Scene 생성 전 공통 촬영 준비 단계
    • 현재는 착장 선택만 활성
    • 향후 헤어, 메이크업 등 외형 프리셋 카테고리로 확장
  • Scene 페이지(i2i/i2v)
    • 고정 컨텍스트: persona + outfit
    • 코디+Scene 프롬프트 합성 표시
    • 히스토리 배치 렌더링(4장)

2.3 Data/Persistence 서브모듈​

  • coordis 저장 계약
  • outfits 저장 계약 (coordiId FK)
  • default assets 저장 계약 (assetSource, 관리자 업로드 미디어)
  • creations/creation_results 저장 계약

3. 데이터 모델​

3.1 coordis​

  • 필수 필드
    • id, userId, name
    • assetSource (USER | SYSTEM)
    • positivePrompt, negativePrompt (빈 문자열 허용)
    • refImageS3Path, refImage2S3Path (nullable)
    • s3Path, thumbnailS3Path
    • visibility, createdAt, updatedAt

3.2 outfits​

  • 필수 필드
    • id, personaId, userId, name
    • assetSource (USER | SYSTEM)
    • coordiId (NOT NULL)
    • s3Path, thumbnailS3Path
    • outfitPrompt, outfitNegativePrompt (nullable)
    • visibility, createdAt, updatedAt

3.3 personas​

  • 필수 필드
    • id, userId, name
    • assetSource (USER | SYSTEM)
    • s3Path, thumbnailS3Path
    • basePrompt, identityPrompt
    • createdAt, updatedAt

3.4 persona_media_assets (신규)​

  • 목적
    • 관리자가 직접 업로드한 기본 이미지/영상 보관
  • 필수 필드
    • id, personaId
    • outfitId (nullable)
    • mediaType (IMAGE | VIDEO)
    • assetSource (SYSTEM)
    • s3Path, thumbnailS3Path
    • sortOrder, isActive
    • createdByUserId, createdAt, updatedAt
  • 비고
    • 생성 결과를 나타내는 creations와 분리한다.
    • 일반 유저가 수정/삭제하지 못하는 운영 카탈로그 자산으로 취급한다.

4. 생성 계약​

4.1 코디 생성 (PERSONA_COORDI_GEN)​

  • t2i/i2i 통합 기능
  • 입력: text_1, text_2, 선택 참조 이미지
  • 출력: 코디 이미지 + 프롬프트

4.2 착장 생성 (PERSONA_OUTFIT_GEN)​

  • 필수 입력: personaId, coordiId
  • 기본 배치: 4
  • 출력: 후보 4장, 선택 후 outfits 저장

4.3 Scene 생성 (PERSONA_TO_IMAGE_GEN, PERSONA_TO_VIDEO_GEN)​

  • 준비 단계:
    • /personas/[id]/prepare/image|video
    • 현재는 outfitId 선택만 활성
  • 필수 입력: outfitId
  • 주입
    • image_1 = outfit.s3Path
    • image_2, image_3 = 사용자 선택 참조
  • 프롬프트 합성
    • resolved_positive = join(coordi.positivePrompt, scene.text_1)
    • resolved_negative = join(coordi.negativePrompt, scene.text_2)
    • 빈 값 제외 후 최종 빈 문자열 허용

5. 저장 계약​

5.1 creations.snapshot (jsonb)​

필수 키:

  • text_1, text_2
  • personaId, featureKey, workflowGroupId, variantId

조건부 키:

  • coordiId (코디/착장/Scene 맥락)
  • outfitId (Scene 맥락)

비고:

  • 미래의 준비 단계 확장 카테고리(hairStyleId, makeupId)는 MVP 범위에서 snapshot 계약에 포함하지 않는다.

5.2 creations projection​

  • resolved_prompt, resolved_negative_prompt, ratio, refs

5.3 creation_results​

  • seed, resultIndex, s3Path, thumbnailS3Path
  • 정렬 규칙: Creation(1):CreationResult(N), 내부 resultIndex ASC

6. API 초안​

Coordis​

  • GET /api/v1/coordis?includeSystem=true|false
  • POST /api/v1/coordis
  • PATCH /api/v1/coordis/:coordiId
  • DELETE /api/v1/coordis/:coordiId
  • POST /api/v1/coordis/:coordiId/copy

Outfits​

  • GET /api/v1/personas/:personaId/outfits?includeSystem=true|false
  • POST /api/v1/personas/:personaId/outfits/generate
  • POST /api/v1/personas/:personaId/outfits (후보 선택 저장)
  • PATCH /api/v1/personas/:personaId/outfits/:outfitId
  • DELETE /api/v1/personas/:personaId/outfits/:outfitId

Personas​

  • GET /api/v1/personas?includeSystem=true|false
  • GET /api/v1/personas/:id
  • POST /api/v1/personas
  • PATCH /api/v1/personas/:id
  • DELETE /api/v1/personas/:id

Default Assets (Admin)​

  • GET /api/v1/admin/default-assets/personas
  • POST /api/v1/admin/default-assets/personas
  • GET /api/v1/admin/default-assets/coordis
  • POST /api/v1/admin/default-assets/coordis
  • GET /api/v1/admin/default-assets/outfits
  • POST /api/v1/admin/default-assets/outfits
  • GET /api/v1/admin/default-assets/media
  • POST /api/v1/admin/default-assets/media
  • PATCH /api/v1/admin/default-assets/:assetType/:id
  • DELETE /api/v1/admin/default-assets/:assetType/:id

7. 구현 단계 (MVP 우선순위)​

  1. DB 계약 확정
  • outfits.coordiId NOT NULL 강제
  • 인덱스/외래키 점검
  1. Backend 계약 고정
  • 코디 복제 API
  • 착장 생성(batch=4) + 저장 API
  • Scene 실행 시 outfitId 필수 검증
  1. Generation 주입/저장
  • image_1=outfit 고정 주입
  • 코디+Scene 프롬프트 합성 저장
  • snapshot/projection/result 저장 계약 적용
  1. Frontend 허브/Scene 연결
  • /personas/[id]에서 코디 -> 착장 -> 촬영 준비 -> Scene 흐름 연결
  • 준비 단계에서는 현재 착장만 선택 가능하도록 구현
  • 코디 미완성 시 Scene 진입 차단
  1. 히스토리/정렬 검증
  • 배치 4 pending/완료 렌더링
  • 새로고침 복구 및 순서 검증
  1. 기본 에셋 도입
  • personas, coordis, outfits에 assetSource 추가
  • 관리자용 기본 에셋 관리 메뉴 추가
  • 기본 이미지/영상 전용 테이블 및 CRUD 추가
  • 사용자 페이지의 기본 에셋 포함 필터 연결
  • SYSTEM 에셋 읽기 전용 정책 적용

8. 테스트 체크리스트​

  1. outfits.coordiId 없는 저장 차단
  2. 공개 코디 복제 시 새 userId로 생성 검증
  3. Scene 실행 시 outfitId 소유권/페르소나 일치 검증
  4. image_1=outfit, image_2/3 선택 주입 검증
  5. creation_results.resultIndex 정렬 및 seed 저장 검증
  6. includeSystem=true|false에 따른 목록 결과 차이 검증
  7. 일반 유저가 SYSTEM 에셋을 수정/삭제하지 못하는지 검증
  8. 관리자 업로드 기본 이미지/영상이 creations와 분리 조회되는지 검증

9. 참고​