어드민 (대행사) 가이드

Adit 어드민 콘솔에서 플랫폼 전반을 관리하는 종합 가이드입니다. 캠페인, 정산, 조직, 사용자, 상품, 대행사, 세금계산서 발행까지 모든 어드민 기능을 상세하게 안내합니다.

1. 어드민 개요

Adit 어드민은 플랫폼의 핵심 관리 도구입니다. 캠페인 라이프사이클, 정산 처리, 조직 관리, 사용자 권한 등 모든 운영 업무를 어드민 콘솔에서 수행합니다.

1-1. 슈퍼어드민 vs 대행사 어드민

어드민 계정은 두 가지 역할로 구분됩니다.

1-2. 접근 가능한 메뉴 비교

2. 어드민 대시보드

경로: /admin/dashboard

대시보드는 플랫폼 전반의 현황을 한눈에 파악할 수 있는 요약 페이지입니다.

2-1. KPI 카드 (4개)

화면 상단에 4개의 핵심 지표 카드가 표시됩니다.

• 수익은 만원 단위로 반올림 표시됩니다 (예: ₩150만)
• 모든 카드에 트렌드 아이콘(TrendingUp)이 표시됩니다

2-2. 최근 파트너 테이블

가장 최근 등록된 파트너 5건이 표시됩니다.

• "전체 보기" 링크 클릭 시 /admin/organizations/partners로 이동

2-3. 최근 캠페인 테이블

가장 최근 등록된 캠페인 5건이 표시됩니다.

• "전체 보기" 링크 클릭 시 /admin/campaigns로 이동

2-4. 정산 현황 테이블

최근 정산 5건이 전체 너비로 표시됩니다.

• "전체 보기" 링크 클릭 시 /admin/settlements로 이동

3. 조직 관리

조직 관리는 파트너(매체사)와 광고주를 관리하는 메뉴입니다. 탭 또는 하위 경로로 구분됩니다.

3-1. 파트너 관리

경로: /admin/organizations/partners

파트너(인플루언서, 크리에이터, 매체사)를 등록하고 관리합니다.

통계 카드 (4개)

검색 및 필터

테이블 컬럼

상태 뱃지 색상

인증 뱃지 색상

액션 드롭다운

파트너 수정 가능 필드

파트너 수정 모달에서 변경할 수 있는 필드입니다.

파트너 생성 모달

"파트너 추가" 버튼을 클릭하면 PartnerCreateModal이 열립니다. 필수 정보를 입력하여 새 파트너를 등록할 수 있습니다.

3-2. 광고주 관리

경로: /admin/organizations/advertisers

광고를 집행하는 브랜드/기업을 등록하고 관리합니다.

통계 카드 (4개)

• 총 집행액은 자동으로 단위 변환됩니다: 1억 이상 = N.N억, 1만 이상 = N만

검색 및 필터

테이블 컬럼

액션 드롭다운

광고주 생성 모달

"광고주 추가" 버튼을 클릭하면 AdvertiserCreateModal이 열립니다. 회사명, 업종, 담당자 정보, 청구 정보 등을 입력하여 새 광고주를 등록합니다.

4. 캠페인 관리

경로: /admin/campaigns

모든 광고 캠페인을 통합 관리합니다. 검색, 필터링, 상태 변경, 수정, 삭제 등의 기능을 제공합니다.

4-1. 검색 및 필터

캠페인 상태 필터 옵션:

4-2. 테이블 컬럼

4-3. 캠페인 상태 뱃지 색상

4-4. 어드민 캠페인 상태 전이 테이블

어드민은 종료 상태(COMPLETED, CANCELLED, REJECTED)를 제외한 모든 상태 전이가 가능합니다.

4-5. 액션 드롭다운

4-6. 캠페인 상세 모달 (CampaignDetailModal)

캠페인을 클릭하면 상세 모달이 열립니다. 조회 모드와 편집 모드를 지원합니다.

조회 모드에서 확인 가능한 정보:

• 캠페인 기본 정보 (이름, ID, 상태)
• 광고주 정보
• 파트너/채널 정보
• 업로드 일정 및 시간
• 가격 및 수수료
• 정산 방식 및 담당 대행사
• 콘텐츠 가이드 (요청사항, 해시태그, 참고자료)
• 계약 정보 (특별 조항)

편집 모드에서 수정 가능한 필드:

4-7. 정산 주체(대행사) 변경

ADIT_SETTLEMENT 방식인 캠페인에서 담당 대행사를 변경할 수 있습니다. 대행사가 변경되면 광고주에게 안내하는 입금 계좌도 함께 변경됩니다.

4-8. 광고주 매칭

파트너가 직접 생성한 캠페인에는 광고주가 연결되어 있지 않을 수 있습니다. 어드민에서 해당 캠페인에 적절한 광고주를 매칭(연결)할 수 있습니다.

5. 정산 관리

경로: /admin/settlements

정산 관리 페이지는 정산 목록 탭과 세금계산서 발행 현황 탭, 두 개의 탭으로 구성됩니다.

5-1. 정산 목록 탭

통계 카드 (4개)

통계 카드 상태 구분:

• 대기: SETTLEMENT_PENDING 상태
• 처리 중: AWAITING_ADVERTISER_PAYMENT + ADVERTISER_PAID + PARTNER_PAYOUT_PROCESSING 상태
• 완료: SETTLEMENT_COMPLETED 상태

필터

정산 상태 옵션 (6개):

테이블 컬럼 상세

유형 뱃지 스타일

정산 금액 컬럼 상세

• 기본 표시: ₩N 형식 (굵은 글씨)
• 원천징수 대상인 경우: 금액 옆에 원천징수 뱃지 (회색 배경, 10px 크기)가 추가 표시
• 원천징수 대상(withholdingTaxRate > 0)일 때는 payoutAmount(실지급액)을, 아닐 때는 settlementAmount(정산금)을 표시
• 수수료: DIRECT_INVOICE는 항상 -, ADIT_SETTLEMENT는 ₩N 형식

경과일 표시 색상 코딩

요청일 옆에 (N일) 형식으로 경과일이 표시되며, 기간에 따라 색상이 달라집니다.

행 배경색

정산 테이블의 각 행은 현재 처리 단계에 따라 배경색이 달라집니다.

상태 컬럼 부가 정보

상태 뱃지 아래에 추가 정보가 표시됩니다.

ADIT_SETTLEMENT인 경우:

• 다음 액션 가이드 메시지 (예: Adit → 광고주 세금계산서 발행 (수동))
• 원천징수 대상이면: 개인 · 원천징수 N%
• 정발행 완료 시: 체크 아이콘 + 정발행 완료
• 역발행 대기 시: 시계 아이콘 + 역발행 대기
• 역발행 완료 시: 체크 아이콘 + 역발행 완료
• 입금 확인 완료 시: 지폐 아이콘 + 입금 확인 완료
• 진행도 바: SETTLEMENT_PENDING과 종료 상태 제외, 3단계 진행도 표시 (파란색/회색)

DIRECT_INVOICE인 경우:

• 파트너 발급 완료 시: 체크 아이콘 + 파트너 발급 완료
• 파트너 입금 확인 완료 시: 지폐 아이콘 + 파트너 입금 확인 완료
• 미발급 시: 파트너 처리 대기 중

5-2. ADIT 정산 워크플로우 액션 버튼 (상태별)

5-3. DIRECT_INVOICE (직접 정산) 어드민 동작

DIRECT_INVOICE 유형의 정산에서 어드민은 읽기 전용입니다. 파트너가 직접 처리하는 상태만 모니터링합니다.

표시되는 정보:

• 파트너 발급 완료 여부 (invoiceIssuedAt)
• 파트너 입금 확인 완료 여부 (invoicePaidAt)
• 미발급 시 "파트너 처리 대기 중" 안내

5-4. 드롭다운 액션 (정산 목록)

모든 정산 항목에 공통으로 드롭다운 메뉴가 제공됩니다.

5-5. 주요 모달 상세

세금계산서 발행 모달 (InvoiceIssueModal)

"광고주 세금계산서 발행 (수동)" 버튼 클릭 시 열립니다.

표시 정보:

• 정산 기본 정보 (캠페인명, 파트너, 광고주)
• 광고주 사업자 정보
• 발행 금액 (공급가액, 부가세, 합계)
• 대행사 정보 (발행 주체)

확인 버튼: "세금계산서 발행 확인" -- 클릭 시 invoiceIssuedAt이 기록됩니다.

입금 확인 모달 (PaymentConfirmationModal)

"광고주 입금 확인" 버튼 클릭 시 열립니다.

표시 정보:

• 캠페인명, 광고주 정보
• 예상 입금 금액 (캠페인 가격)
• 실제 입금 금액 입력 필드 (필수)

처리 로직:

• 실제 입금 금액과 예상 금액의 차액을 계산
• adminNotes에 기록: 실제 입금 금액: N원 (예상: N원, 차액: +/-N원)
• 확인 시 정산 상태가 ADVERTISER_PAID로 변경

파트너 지급 모달 (PartnerPayoutModal)

"지급 시작" 또는 "파트너 세금계산서 수령" 버튼 클릭 시 열립니다.

표시 정보:

• 파트너 정보 (이름, 사업자 유형)
• 파트너 계좌 정보 (은행명, 계좌번호, 예금주)
• 정산금액 상세 (캠페인가격, 수수료, 정산금, 원천징수, 실지급액)
• 파트너 세금계산서 수령 상태
• 역발행 상태 (Bolta 역발행 사용 시)

확인 버튼: 클릭 시 정산 상태가 PARTNER_PAYOUT_PROCESSING으로 변경

새로고침 버튼: 역발행 상태를 최신으로 갱신

5-6. 세금계산서 발행 현황 탭

정산 관리 페이지의 두 번째 탭입니다. ADIT_SETTLEMENT 유형만 표시됩니다.

필터

• "수동 발행 대기만" 선택 시: invoiceIssuedAt이 없는 항목만 필터링

테이블 컬럼

발행 상태 뱃지

실패 사유 컬럼

액션 컬럼

6. 사용자 관리

경로: /admin/users

6-1. 검색 및 필터

6-2. 테이블 컬럼

6-3. 역할 뱃지

6-4. 상태 뱃지

6-5. 액션 드롭다운

6-6. 역할 변경 모달

사용자의 역할을 변경합니다.

선택 가능한 역할:

대행사 관리자 선택 시:

• 소속 대행사 선택 필드가 추가로 표시됩니다 (필수)
• 활성 상태인 대행사만 드롭다운에 표시됩니다
• 형식: 대행사명 (코드) (예: 르도드코퍼레이션 (ADIT))
• 대행사를 선택하지 않으면 저장 시 알림이 표시됩니다

7. 상품 관리

경로: /admin/products

파트너가 판매하는 광고 상품을 생성하고 관리합니다.

7-1. 통계 카드 (3개)

7-2. 검색 및 필터

7-3. 테이블 컬럼

7-4. 상품 유형

7-5. 액션 드롭다운

7-6. 상품 생성 모달 (ProductCreateModal)

"상품 추가" 버튼 클릭 시 열립니다. 상품명, 유형, 가격, 설명, 기간, 산출물 등을 입력합니다.

7-7. 상품 상세/수정 모달 (ProductDetailModal)

조회 모드와 편집 모드를 지원합니다.

수정 가능 필드: 상품명, 유형, 가격, 설명, 기간, 산출물, 활성/비활성

8. 콘텐츠 관리

경로: /admin/content/

광고주 프론트에 표시되는 콘텐츠를 관리합니다. 두 가지 유형이 있습니다.

8-1. 성공 사례 (Success Stories)

경로: /admin/content/success-stories

성공적인 캠페인 사례를 등록하고 관리합니다.

• 콘텐츠 유형: SUCCESS_STORY
• 액션: 생성, 수정, 삭제, 발행(Publish), 아카이브(Archive)
• 상태: DRAFT(초안), PUBLISHED(발행됨), ARCHIVED(아카이브)

8-2. 혜택 정보 (Benefits)

경로: /admin/content/benefits

광고주를 위한 혜택 정보를 등록하고 관리합니다.

• 콘텐츠 유형: BENEFIT_INFO
• 액션: 성공 사례와 동일 (생성, 수정, 삭제, 발행, 아카이브)

8-3. 공통 기능

9. 대행사 관리

경로: /admin/agencies

정산 주체가 되는 대행사를 관리합니다. 대행사 계좌로 광고주가 입금하고, 대행사가 파트너에게 정산금을 지급합니다.

9-1. 대행사 목록 테이블

9-2. 액션 드롭다운

9-3. 대행사 정보 필드

9-4. 대행사 용도

• ADIT_SETTLEMENT 캠페인의 정산 주체
• 대행사 계좌로 광고주 입금 → 대행사가 파트너에게 지급
• 캠페인 생성 시 또는 어드민에서 담당 대행사 배정

9-5. 기본 대행사

10. Bolta 세금계산서 설정

경로: /admin/settings/bolta

전자세금계산서 발행을 위한 Bolta(볼타) 연동을 관리합니다.

10-1. 볼타 고객 등록

발행 주체(Adit 본사 또는 대행사)별로 볼타 고객을 등록합니다.

등록 모달 필드:

10-2. 공동인증서 등록

각 볼타 고객에 대해 공동인증서(사업자 공인인증서)를 등록합니다.

콜백 핸들러: /admin/settings/bolta/certificate-callback

• Bolta가 인증 완료 후 이 URL로 리다이렉트합니다
• 인증 성공/실패 메시지를 표시합니다

10-3. 등록된 발행 주체 목록

각 항목에 표시되는 정보:

• 상호명
• 소속 (대행사명 또는 "Adit 본사")
• 사업자등록번호
• 인증서 만료일 (있는 경우)

액션:

10-4. 세금계산서 발행 프로세스

10-5. 웹훅 수신

Bolta에서 세금계산서 발행 결과를 웹훅으로 전송합니다.

• 엔드포인트: /api/public/webhooks/bolta
• 이벤트: 정발행 성공/실패, 역발행 성공/실패
• 성공 시 해당 정산의 invoiceIssuedAt 또는 partnerInvoiceReceivedAt 자동 업데이트
• 실패 시 issuanceFailureMessage 업데이트

11. 정산 비즈니스 룰 상세

11-1. 수수료 계산

수수료율 = campaign.commissionRate ?? partner.commissionRate (기본 20%)
수수료 = 캠페인가격 × (수수료율 / 100)
정산금 = 캠페인가격 - 수수료

• 캠페인에 commissionRate가 설정되어 있으면 우선 적용
• 없으면 파트너의 기본 commissionRate 적용
• 둘 다 없으면 기본값 20% 적용

11-2. 원천징수

원천징수세 = 정산금 × (원천징수율 / 100)
실지급액(payoutAmount) = 정산금 - 원천징수세

11-3. 사업자 유형별 세금계산서 처리

11-4. 정산 금액 계산 예시

예시: 캠페인 가격 1,000,000원, 수수료율 20%, 법인사업자

수수료 = 1,000,000 × 20% = 200,000원
정산금 = 1,000,000 - 200,000 = 800,000원
원천징수 = 0원 (법인사업자)
실지급액 = 800,000원

예시: 캠페인 가격 1,000,000원, 수수료율 20%, 개인사업자(INDIVIDUAL)

수수료 = 1,000,000 × 20% = 200,000원
정산금 = 1,000,000 - 200,000 = 800,000원
원천징수 = 800,000 × 3.3% = 26,400원
실지급액 = 800,000 - 26,400 = 773,600원

11-5. 직접 정산(DIRECT_INVOICE) 제약

• 개인사업자(INDIVIDUAL)는 직접 정산 불가 (자동으로 allowDirectInvoice = false)
• 어드민에서 수동으로 변경 불가

12. 감사 로그

관리자가 수행한 모든 액션이 감사 로그에 기록됩니다.

12-1. 기록되는 정보

12-2. 조회 API

엔드포인트: GET /admin/audit-logs

쿼리 파라미터:

13. 알림 시스템 (어드민 관점)

13-1. Slack 알림

어드민이 받는 주요 Slack 알림입니다.

13-2. SlackCampaignThread

각 캠페인마다 Slack 대화 스레드가 생성됩니다. 캠페인과 관련된 모든 이벤트(상태 변경, 정산 요청, 입금 확인 등)가 해당 스레드에 기록됩니다.

13-3. 이메일 알림

정산 처리 과정에서 광고주와 파트너에게 자동으로 이메일이 발송됩니다.

광고주 대상:

파트너 대상:

14. 어드민 액션 전체 요약 테이블

캠페인 관련 액션

정산 관련 액션

조직 관련 액션

사용자 관련 액션 (슈퍼어드민 전용)

대행사 관련 액션 (슈퍼어드민 전용)

상품 관련 액션

볼타(세금계산서) 관련 액션

15. 자주 묻는 질문

Q. 세금계산서 발행 버튼이 보이지 않습니다.

A. invoiceIssuedAt이 이미 기록되어 있으면 (Bolta 자동 발행 성공) 수동 발행 버튼이 표시되지 않습니다. 세금계산서 발행 현황 탭에서 발행 상태를 확인하세요.

Q. DIRECT_INVOICE 정산에서 어드민이 할 수 있는 일이 없나요?

A. 맞습니다. 직접 정산은 파트너가 직접 처리합니다. 어드민은 상태 모니터링과 필요 시 취소만 가능합니다.

Q. 파트너 지급 버튼이 "파트너 세금계산서 수령"으로 표시됩니다.

A. 법인사업자 파트너의 경우, 역발행(세금계산서 수령)이 먼저 완료되어야 지급을 시작할 수 있습니다. Bolta 역발행이 완료되면 자동으로 "지급 시작"으로 변경됩니다.

Q. 개인사업자에게는 세금계산서를 받지 않나요?

A. 개인(INDIVIDUAL) 사업자는 원천징수 3.3%로 대체되므로 세금계산서 수령이 불필요합니다. 바로 "지급 시작"이 가능합니다.

Q. 대행사 어드민이 사용자를 관리하고 싶습니다.

A. 사용자 관리와 대행사 관리는 슈퍼어드민 전용 기능입니다. 슈퍼어드민에게 요청하세요.

Q. 정산을 취소하면 캠페인 상태도 변경되나요?

A. 정산 취소(SETTLEMENT_CANCELLED)는 정산 상태만 변경합니다. 캠페인 상태는 별도로 관리해야 합니다.

Q. 경과일이 14일 이상인 정산은 어떻게 하나요?

A. 빨간색으로 표시된 정산은 즉시 처리가 필요합니다. 광고주에게 입금 독촉 연락을 하거나, 파트너에게 세금계산서 발행을 요청하세요.