용어 및 상태값 정리

Adit 서비스에서 사용하는 용어, 데이터 구조, 상태값을 정리했습니다.

참여자

참여자	설명	시스템
광고주 (Advertiser)	캠페인을 의뢰하고 비용을 지불	광고주 프론트
파트너 (Partner)	콘텐츠를 제작/업로드하고 정산금 수령	파트너 콘솔
대행사 (Agency)	정산을 중개하는 주체 (Adit, 미드나잇웨이브 등)	어드민
채널 (Channel)	파트너가 운영하는 SNS 계정	파트너 콘솔

데이터 관계도

전체 구조

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│  Advertiser │         │   Partner   │         │   Agency    │
│   (광고주)   │         │   (파트너)   │         │   (대행사)   │
└──────┬──────┘         └──────┬──────┘         └──────┬──────┘
       │                       │                       │
       │                       ▼                       │
       │               ┌─────────────┐                 │
       │               │   Channel   │                 │
       │               │   (채널)    │                 │
       │               └──────┬──────┘                 │
       │                      │                        │
       ▼                      ▼                        ▼
┌────────────────────────────────────────────────────────────┐
│                         Campaign                            │
│                          (캠페인)                           │
│  • advertiserId, partnerId, channelId                       │
│  • agencyId (정산 주체)                                      │
│  • settlementType (ADIT_SETTLEMENT / DIRECT_INVOICE)        │
└─────────────────────────────┬──────────────────────────────┘
                              │
                              │ 1:1 (업로드 완료 시 자동 생성)
                              ▼
┌────────────────────────────────────────────────────────────┐
│                        Settlement                           │
│                          (정산)                             │
│  • campaignId (1:1)                                         │
│  • advertiserInvoiceId (N:1) - 청구서 연결                   │
│  • partnerPayoutId (N:1) - 지급 연결                         │
└────────────┬───────────────────────────────┬───────────────┘
             │                               │
             ▼                               ▼
┌────────────────────────┐       ┌────────────────────────┐
│   AdvertiserInvoice    │       │     PartnerPayout      │
│    (광고주 청구서)      │       │     (파트너 지급)       │
│  • 건별 또는 월별 합산  │       │  • 건별 또는 월별 합산   │
└────────────────────────┘       └────────────────────────┘

정산 3계층 구조

계층	모델	설명	관계
1계층	Settlement	캠페인 단위 정산 레코드	캠페인 1건 = 정산 1건
2계층-A	AdvertiserInvoice	광고주에게 발행하는 청구서	건별: 1:1 / 월별: N:1
2계층-B	PartnerPayout	파트너에게 지급하는 배치	건별: 1:1 / 월별: N:1

캠페인 상태 (CampaignStatus)

상태	코드	설명
🟠 광고주 대기	`PENDING_ADVERTISER`	광고주가 등록, 파트너 검토 전
🟡 대기	`PENDING`	파트너/어드민 확정 대기
🟢 확정	`CONFIRMED`	캠페인 확정, 진행 예정
🔵 진행 중	`IN_PROGRESS`	콘텐츠 제작/업로드 기간
✅ 업로드 완료	`UPLOADED`	콘텐츠 업로드됨, 정산 대기
💰 완료	`COMPLETED`	정산까지 모두 완료
⛔ 거절	`REJECTED`	파트너가 거절
🔴 취소	`CANCELLED`	캠페인 취소

상태 전이 다이어그램

PENDING_ADVERTISER ──→ PENDING ──┬──→ CONFIRMED ──→ IN_PROGRESS ──→ UPLOADED ──→ COMPLETED
                                 │         │              │
                                 │         ▼              ▼
                                 │    CANCELLED      CANCELLED
                                 │
                                 └──→ REJECTED

사용자별 상태 변경 권한

현재 상태	가능한 액션
PENDING	취소 (삭제)
그 외	액션 없음 (조회만)

광고주는 PENDING 상태에서만 캠페인을 취소(삭제)할 수 있습니다.

정산 상태 (SettlementStatus)

상태	코드	설명
🕐 정산 대기	`SETTLEMENT_PENDING`	파트너 정산 요청 전
📤 결제 대기	`AWAITING_ADVERTISER_PAYMENT`	파트너가 정산 요청함, 광고주 입금 대기
✅ 결제 완료	`ADVERTISER_PAID`	광고주 입금 확인됨
🔄 지급 처리 중	`PARTNER_PAYOUT_PROCESSING`	파트너 지급 처리 중
💰 정산 완료	`SETTLEMENT_COMPLETED`	파트너 송금 완료
❌ 정산 취소	`SETTLEMENT_CANCELLED`	정산 취소

정산 방식별 플로우

ADIT_SETTLEMENT - Adit/대행사가 중개

SETTLEMENT_PENDING (정산 대기)
      │
      │ [파트너] 정산 요청
      ▼
AWAITING_ADVERTISER_PAYMENT (결제 대기)
      │
      │ [어드민] 세금계산서 발급 → 광고주에게 발송
      │ [어드민] 입금 확인
      ▼
ADVERTISER_PAID (결제 완료)
      │
      │ [어드민] 파트너 지급 시작
      ▼
PARTNER_PAYOUT_PROCESSING (지급 처리 중)
      │
      │ [어드민] 정산 완료
      ▼
SETTLEMENT_COMPLETED (정산 완료)
      │
      └─→ 캠페인 상태도 COMPLETED로 변경

청구서 상태 (InvoiceStatus)

광고주에게 발행하는 청구서 상태입니다.

상태	코드	설명
📝 초안	`DRAFT`	청구서 생성됨, 세금계산서 미발행
📤 발행됨	`ISSUED`	세금계산서 발행됨, 입금 대기
✅ 입금 완료	`PAID`	광고주 입금 확인됨
⚠️ 연체	`OVERDUE`	납기일 초과
❌ 취소	`CANCELLED`	청구서 취소

지급 상태 (PayoutStatus)

파트너에게 송금하는 지급 상태입니다.

상태	코드	설명
🕐 대기	`PENDING`	지급 배치 생성됨, 세금계산서 미수령
📥 세금계산서 수령	`INVOICE_RECEIVED`	파트너 세금계산서 수령 확인
🔄 처리 중	`PROCESSING`	송금 처리 중
✅ 완료	`COMPLETED`	송금 완료
❌ 취소	`CANCELLED`	지급 취소

정산 유형 (SettlementType)

유형	코드	설명	수수료
Adit 정산	`ADIT_SETTLEMENT`	광고주 → 대행사 → 파트너	있음
매체사 직정산	`DIRECT_INVOICE`	광고주 → 파트너 직접	없음 (0%)

청구/지급 유형

유형	코드	설명
건별	`PER_CAMPAIGN`	캠페인 1건 = 청구서/지급 1건
월별	`MONTHLY`	여러 캠페인 합산하여 청구/지급

💡

현재는 건별 정산만 지원됩니다. 월별 정산은 추후 지원 예정입니다.

슬롯 (PartnerSlot)

파트너의 날짜별 캠페인 예약 가능 여부를 관리합니다.

필드	설명	기본값
`date`	날짜	-
`isAvailable`	예약 가능 여부	true
`maxCampaigns`	최대 캠페인 수 (0=무제한)	0
`currentCampaigns`	현재 예약된 캠페인 수	0

슬롯 카운트 변화

시점	변화
캠페인 생성	+1
캠페인 업로드 완료	-1
캠페인 완료	-1
캠페인 취소	-1
캠페인 거절	-1

슬롯 반환은 최초 1회만 발생합니다 (중복 반환 방지).

금액 계산

정산금 계산 (ADIT 정산)

수수료 금액 = 캠페인 가격 × 수수료율
정산금 (공급가액) = 캠페인 가격 - 수수료 금액
파트너 수령액 = 정산금 + VAT(10%)

예시 (캠페인 100만원, 수수료 10%):

항목	금액
캠페인 가격	1,000,000원
수수료 (10%)	100,000원
정산금	900,000원
VAT	90,000원
파트너 수령액	990,000원

매체사 직정산

수수료가 0%이므로 캠페인 가격 전액 + VAT가 파트너 수령액입니다.

주요 필드 설명

Campaign

필드	설명
`settlementType`	정산 유형 (ADIT_SETTLEMENT / DIRECT_INVOICE)
`commissionRate`	캠페인별 수수료율 (null이면 파트너 기본값)
`agencyId`	담당 대행사 ID (ADIT 정산 시 정산 주체)
`uploadDate`	업로드 예정일
`status`	캠페인 상태

Settlement

필드	설명
`campaignPrice`	캠페인 가격 (스냅샷)
`commissionRate`	수수료율
`commissionAmount`	수수료 금액
`settlementAmount`	정산금 (파트너 수령액)
`requestedAt`	정산 요청 일시
`completedAt`	정산 완료 일시
`invoiceIssuedAt`	세금계산서 발급일 (DIRECT_INVOICE)
`invoicePaidAt`	입금 확인일 (DIRECT_INVOICE)

상태 이모지 빠른 참조

캠페인

🟠	🟡	🟢	🔵	✅	💰	⛔	🔴
광고주대기	대기	확정	진행중	업로드완료	완료	거절	취소

정산

🕐	📤	✅	🔄	💰	❌
정산대기	결제대기	결제완료	지급처리중	정산완료	취소

홈 캠페인 진행 흐름