Admin Finance API

관리자가 기업·캠페인 단위로 크레딧 잔액, 캠페인 예산(LOCK 금액), 카드결제를 통합 조회하고 어드민 권한으로 크레딧/예산을 조정할 수 있는 API입니다.

모델 개요

엔드포인트 목록

조회

변경 (ledger 패턴)

변경 (원장 = 가계부 패턴)

Ledger 규약 (기존 credit-tx 경로)

수정/삭제는 원본을 변경하지 않고 reverse 행을 추가합니다.

• 원본 CreditTransaction(id=X, amount=A) 를 삭제하면:
  • 새 행 CreditTransaction(transactionType=동일, amount=-A, reverseOfTxId=X) 추가
  • BUDGET_ADJUST 가 아니면 Business.remainCredit 도 같이 보정
• 수정은 위 reverse + 새 본 행 = 두 row 추가 (트랜잭션 1개로 묶임)
• 이미 reverse 된 원본 또는 reverse 행 자체 는 재수정·재삭제 불가 (IllegalStateException)
• UI 에서는 reversed=true 인 row 를 strike-through 처리

원장 규약 (ledger 경로)

행을 그 자리에서 고치고 이후 행의 balanceAfter 를 재계산합니다. 가계부와 같은 방식입니다.

• 시간축은 createdAt(DB 기록 시각)이 아니라 occurredAt(발생일) — 어드민이 과거 시점 지정 가능
• 정렬·재계산 순서는 (occurredAt, id)
• 기입/수정/삭제 시 앵커 이후 행만 다시 계산하고, 앵커 이전 행은 한 줄도 건드리지 않음
• 삭제는 물리 삭제가 아니라 deletedAt 소프트 삭제
• 변경 전/후 스냅샷은 TB_CREDIT_TRANSACTION_AUDIT 에 append-only 로 기록
• Business.remainCredit 은 델타만 이동. 원장 합계와 어긋나면 응답의 balanceMismatch=true 로 드러냄
• 레거시 reverse 쌍은 이 경로에서 거부 (409) — 기존 credit-tx 경로를 사용

두 경로는 공존합니다. 기존 데이터에 이미 만들어진 reverse 쌍은 그대로 두고, 신규 정정 작업만 원장 경로로 처리하면 됩니다.

CreditTransactionReason (어드민 수동 거래 사유)

시스템 자동 거래(결제 충전·캠페인 자동 입금 등)는 reason=null 로 남습니다.

CreditTransactionType ↔ Timeline Type 매핑

CampaignBudget 의 LOCK/UNLOCK 은 entity 그대로(createdAt, updatedAt) timeline 에 합쳐집니다.