Admin Finance API

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

모델 개요

엔드포인트 목록

조회

변경 (입금 · 예산 · 레거시 정정)

변경 (원장 경로 — 현재 표준)

어느 API 를 써야 하나

같은 "크레딧을 고친다" 라도 목적에 따라 경로가 다릅니다. 잘못 고르면 원장이 어긋납니다.

레거시 reverse 규약 (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 쌍은 credit-tx 로만 다룰 수 있고(원장 경로는 409 로 거부), 그 외 모든 신규 작업은 원장 경로입니다.

잔액 계산에서 빠지는 행

원장 합계를 낼 때 아래 두 종류는 제외합니다. 프론트에서 합계를 직접 계산한다면 같은 기준을 쓰셔야 화면과 서버 값이 맞습니다.

임시충전을 빼면 결제분만 남아 잔액이 내려가고, 그 마이너스가 곧 미수 금액입니다. 어드민 화면도 이 행을 감추므로 화면과 계산 기준이 같습니다. 실입금이 확인돼 임시 표시를 끈 행(provisional: false)은 그대로 셉니다.

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

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

CreditTransactionType ↔ Timeline Type 매핑

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