가이드라인 V4

V4는 세션 기반 단계별 AI 가이드라인 생성 시스템입니다. V2가 사용자 입력을 받아 한번에 저장하는 방식이었다면, V4는 컨셉 → 생성 → 재생성/추가 → 저장의 흐름으로 사용자가 AI 결과를 수정하면서 만들어갑니다.

사전 준비

V4 가이드라인을 시작하기 전에 빈 템플릿 요청을 version=4로 호출하여 guidelineVersion을 설정해야 합니다.

PUT /ai/business/contents/guideline/empty/{collabNo}?version=4

자세한 내용은 빈 템플릿 요청 문서를 참고하세요.

흐름

1. concepts         컨셉 3개 후보 생성 (Step 1)
2. generate         선택한 컨셉으로 전체 가이드라인 생성 (Step 2)
3. regenerate       개별 항목 재생성 (Step 3, optional)
4. add-item         항목 1개 추가 (Step 4, optional)
5. add-batch        항목 일괄 추가 (Step 5, optional)
6. save             상태 전이 + COMPLETED 부가작업 실행
   - GET /session   세션 상태 조회
   - DELETE /session 세션 삭제 (Gemini 파일 정리)

데이터 저장 위치

MongoDB guidelines 컬렉션 — GuidelineDocument 단일 도큐먼트, collabNo unique. V2와 컬렉션 공유 (v4 전용 필드: concepts, selectedConcept, geminiFileIds, pdfMetadata, referenceMetadata, expiresAt)
TB_COLLAB — guidelineStatus, campaignSubStep, guidelineVersion=4, keywords 등
TB_CAMPAIGN_ADDON_FEE — COMPLETED 저장 시 가이드라인의 추가금 항목과 자동 sync

샷 생성 정책

V4 샷 생성은 클라이언트가 직접 후보 목록을 보내는 방식이 아닙니다. Spring이 협업 정보의 카테고리/콘텐츠 타입을 기준으로 촬영 옵션을 구성하고, Python은 전달받은 후보 안에서만 샷을 생성합니다.

기본 구조는 beginning HOOK 1개, middle 샷 3개, ending CTA 1개입니다.
middle 샷 후보는 basicShots + additionalOptions입니다.
NARRATION은 촬영 샷이 아니므로 후보에서 제외합니다.
MongoDB 템플릿의 shootingOptions가 비어 있으면 Spring V4 fallback catalog를 사용합니다.
basicShots는 optionType=BASIC, additionalOptions는 optionType=ADDITIONAL로 내려갑니다.
HOOK/CTA는 촬영 옵션 후보와 별개로 고정 생성되며 optionType=BASIC입니다.
생성/추가/재생성 응답에는 price_tag를 내려주지 않습니다. 추가금 금액은 별도 저장 및 DB sync 흐름에서 처리합니다.

상태 흐름

`GuidelineDocument.status`	의미
(없음)	세션 미생성
`CONCEPTS_GENERATED`	컨셉 3개 후보 생성 완료
`GUIDELINE_GENERATED`	전체 가이드라인 생성 완료
`EDITING`	regenerate / add-item / add-batch 진행 중
`DRAFT`	초안 저장 (isFirst=true)
`COMPLETED`	완성본 저장 (모집 단계 전환)

COMPLETED 저장 시 부가작업

저장 API (PUT /ai/guideline/v4/{collabNo})가 isFirst=false로 호출되면 V2와 동일한 부가작업을 함께 실행합니다:

Collab.campaignSubStep = CREATOR_RECRUIT 전환
모집 마감일 자동 설정 (CampaignScheduleService.updateRecruitmentEndDate)
캠페인 벡터화 비동기 호출 (Python vectorizeCampaignAsync)
해시태그 자동 크롤 이벤트 발행 (HashtagCrawlRequestedEvent)
Collab.keywords 에 해시태그 저장
모집 콘텐츠(알리미/DM/한줄어필/스토리이미지) 비동기 생성
칸반 태스크 완료 (Node.js API 호출)
TB_CAMPAIGN_ADDON_FEE sync (가이드라인의 추가금 항목과 일치시키기)

세부 동작은 가이드라인 V4 저장 (save) 페이지를 참고하세요.

V2 와 차이점

항목	V2	V4
입력 방식	클라이언트가 전체 DTO 전송	단계별 호출, 결과는 MongoDB 세션에 누적
AI 생성 시점	캠페인 생성 직후 자동 / On-demand	명시적 호출 (`concepts` → `generate`)
재생성 단위	전체 또는 hooks/concept 단위	항목 단위 (`regenerate` with `itemType`, `targetIndex`)
항목 추가	DTO 에 포함해 PUT	`add-item` / `add-batch` 전용 endpoint
세션 만료	없음	`expiresAt` 필드 (기본 48시간)
Gemini 파일 관리	없음	`geminiFileIds` 추적, `DELETE /session` 으로 cleanup
addon-fee sync	없음	COMPLETED 저장 시 `TB_CAMPAIGN_ADDON_FEE` 자동 동기화

가이드라인 V4 개요