Adit 정산 시스템 설계 문서

campaignPrice        = Campaign.price (캠페인 가격)
commissionRate       = Campaign.commissionRate ?? Partner.commissionRate (기본 20%)
commissionAmount     = Math.round(campaignPrice × commissionRate / 100)
settlementAmount     = campaignPrice - commissionAmount
withholdingTaxRate   = (INDIVIDUAL + ADIT_SETTLEMENT) ? 3.3 : 0
withholdingTaxAmount = Math.round(settlementAmount × withholdingTaxRate / 100)
payoutAmount         = settlementAmount - withholdingTaxAmount

model BoltaReverseIssuance {
  id               BigInt   @id @default(autoincrement())
  settlementId     String   @unique  // SET{NNN}
  issuanceKey      String   // Bolta 발행 키
  status           String   // PENDING, SUCCESS, FAILURE, CANCELLED
  grantUrl         String?  // 역발행 승인 URL (10분 유효)
  failureCode      String?
  failureMessage   String?
}

model Settlement {
  id                      String    @id  // "SET001"
  campaignId              BigInt    @unique
  partnerId               BigInt
  agencyId                BigInt?   // null = Adit 기본
 
  // 금액 계산
  campaignPrice           Decimal(15,2)
  commissionRate          Decimal(5,2)   // 수수료율 (기본 20%)
  commissionAmount        Decimal(15,2)  // 수수료 금액
  settlementAmount        Decimal(15,2)  // 정산금 (price - commission)
  withholdingTaxRate      Decimal(5,2)   // 원천징수율 (0 or 3.3)
  withholdingTaxAmount    Decimal(15,2)  // 원천징수 금액
  payoutAmount            Decimal(15,2)  // 실지급액 (settlement - withholding)
 
  // 상태
  status                  SettlementStatus
  settlementType          SettlementType
 
  // 2계층 연결
  advertiserInvoiceId     BigInt?   // N:1 → AdvertiserInvoice
  partnerPayoutId         BigInt?   // N:1 → PartnerPayout
 
  // 직정산 전용
  invoiceIssuedAt         DateTime?
  invoicePaidAt           DateTime?
 
  // Bolta 역발행 수령 확인
  partnerInvoiceReceivedAt DateTime?
 
  // 파트너 계좌 스냅샷
  bankName                String?
  accountNumber           String?
  accountHolder           String?
 
  // 타임스탬프
  requestedAt             DateTime?
  processedAt             DateTime?
  completedAt             DateTime?
  adminNotes              String?   @db.Text
}

model Agency {
  id                    BigInt    @id @default(autoincrement())
  name                  String    // "르도드코퍼레이션"
  code                  String    @unique  // "ADIT"
  businessName          String    // 사업자등록증상 상호
  businessNumber        String    // 사업자번호
  representativeName    String    // 대표자명
  bankName              String    // "신한은행"
  accountNumber         String    // "100-038-478766"
  accountHolder         String    // "르도드코퍼레이션 주식회사"
  email                 String
  isActive              Boolean   @default(true)
}

model AdvertiserInvoice {
  id                    BigInt    @id @default(autoincrement())
  invoiceNumber         String    @unique  // "INV-2026-01-001"
  advertiserId          BigInt
  advertiserName        String
  agencyId              BigInt?   // 정산 주체 (null이면 Adit 기본값)
 
  // 유형
  invoiceType           String    // PER_CAMPAIGN | MONTHLY
  periodStart           DateTime? // 월별 정산 시
  periodEnd             DateTime? // 월별 정산 시
 
  // 금액
  subtotal              Decimal   // 공급가액
  taxAmount             Decimal   // 부가세 (10%)
  totalAmount           Decimal   // 합계
 
  // 세금계산서
  taxInvoiceNumber      String?
  taxInvoiceFileKey     String?
  taxInvoiceIssuedAt    DateTime?
 
  // 입금
  status                InvoiceStatus  // DRAFT, ISSUED, PAID, OVERDUE, CANCELLED
  dueDate               DateTime?
  paidAt                DateTime?
 
  // 입금 계좌 스냅샷
  bankName              String?
  accountNumber         String?
  accountHolder         String?
 
  // Relations
  settlements           Settlement[]
}

model PartnerPayout {
  id                    BigInt    @id @default(autoincrement())
  payoutNumber          String    @unique  // "PAY-2026-01-001"
  partnerId             BigInt
  partnerName           String
 
  // 유형
  payoutType            String    // PER_CAMPAIGN | MONTHLY
  periodStart           DateTime? // 월별 정산 시
  periodEnd             DateTime? // 월별 정산 시
 
  // 금액
  subtotal              Decimal   // 정산금 합계
  taxAmount             Decimal   // 원천징수 금액
  totalAmount           Decimal   // 실지급액 (정산금 - 원천징수)
 
  // 파트너 세금계산서
  partnerInvoiceNumber  String?
  partnerInvoiceFileKey String?
  partnerInvoiceReceivedAt DateTime?
 
  // 지급
  status                PayoutStatus  // PENDING, INVOICE_RECEIVED, PROCESSING, COMPLETED, CANCELLED
  paidAt                DateTime?
  transactionId         String?
 
  // 계좌 스냅샷
  bankName              String?
  accountNumber         String?
  accountHolder         String?
 
  // Relations
  settlements           Settlement[]
}

adit-backend/
├── prisma/schema.prisma                          # DB 스키마
├── src/utils/settlement-state-machine.ts          # 상태 전이 규칙
├── src/modules/
│   ├── admin/settlements/                         # 어드민 정산 서비스
│   │   ├── settlement.service.ts                  # 핵심 비즈니스 로직
│   │   ├── settlement.routes.ts                   # API 라우트
│   │   └── settlement.types.ts                    # Zod 스키마
│   ├── partner/settlements/                       # 파트너 정산 서비스
│   │   └── settlement.service.ts                  # 정산 요청, 역발행
│   ├── partner/campaigns/
│   │   └── campaign-settlement.service.ts         # 정산 레코드 자동 생성
│   ├── admin/invoices/                            # 광고주 청구서
│   ├── admin/payouts/                             # 파트너 지급
│   ├── admin/agencies/                            # 대행사 관리
│   ├── bolta/                                     # Bolta API 연동
│   └── notification/                              # 알림 서비스
└── src/templates/email/                           # 이메일 템플릿