ga-commission-system/docs/DOMAIN_GAP_P9_환수채권이월.md

P9 — 환수채권 이월/미수금 관리 (Clawback Receivable Carry-forward)

작성: PL, 2026-06-04. 사용자 지시 "수수료 빠진 업무 찾아서 기획·설계 후 적용". 근거: incar CMS 메뉴(환수이월관리/환수계약리스트/환수리스트/위촉중환수) ↔ GA 부재 + 코드 갭 (AggregateStep.java:197-199 — net<0 시 경고 로그만, 미회수 환수 채권화·차월상계·대손 생애주기 전무).

범위: 풀스택(DB→Core→API→Batch→Frontend). 패턴 100% 준수(template = 정착지원금 V90 / SettlingSupport*). Flyway: V110이 최신 → V111부터. 금액 NUMERIC(15,2), HALF_UP.

확정 FK: agent(agent_id), settle_master(agent_id, settle_month).

---

1. 업무 정의 (표준 한국 GA 관행 — 데이터로 외부화)

조기해지 차등환수(chargeback)·공제가 당월 지급수수료(gross)를 초과하면 net < 0. 이 미회수분은 설계사가 GA에 갚아야 할 미수채권(환수채권) 이다. 표준 처리:

1. 이월(carryover): 당월 net<0 → 음수분(|net|)을 환수채권으로 신규 등록, 당월 실지급(payable)=0.
2. 상계 회수(recovery): 차월 이후 net>0이면 미결 채권을 FIFO(오래된 origin월 우선) 로 상계 회수. payable = net − 회수액.
3. 대손/직접상환(write-off / direct settle): 장기 미회수 채권은 관리자가 대손(WRITTEN_OFF) 또는 외부 직접상환(CLEARED) 처리.

표준 가정(회사 정책 다르면 데이터/룰만 수정, 코드 불변):

• 상계 우선순위 = origin_settle_month ASC (FIFO).
• 회수는 당월 양수 net 한도 내에서만(설계사를 음수로 만들지 않음).
• 이자·연체료 없음(필요 시 후속).

---

2. 스키마 (V111)

2-1. clawback_receivable (환수채권 마스터)

컬럼	타입	설명
receivable_id	BIGSERIAL PK
agent_id	BIGINT NN FK agent
origin_settle_month	CHAR(6) NN	미수 발생 정산월
original_amount	NUMERIC(15,2) NN	발생액(양수, =당월
recovered_amount	NUMERIC(15,2) NN DEFAULT 0	누적 상계 회수액
balance	NUMERIC(15,2) NN	= original_amount − recovered_amount
status	VARCHAR(20) NN DEFAULT 'OUTSTANDING'	OUTSTANDING/RECOVERING/CLEARED/WRITTEN_OFF
last_recovery_month	CHAR(6)	최근 회수 정산월
writeoff_reason	VARCHAR(300)	대손/직접상환 사유
written_off_at	TIMESTAMP
written_off_by	BIGINT
created_at	TIMESTAMP NN DEFAULT now()
created_by	BIGINT
updated_at	TIMESTAMP

• UNIQUE(agent_id, origin_settle_month) — 설계사·발생월당 1건(배치 upsert 멱등 키)
• CHECK status IN('OUTSTANDING','RECOVERING','CLEARED','WRITTEN_OFF')
• CHECK original_amount >= 0, balance >= 0
• idx: (agent_id, status), (status), (origin_settle_month)

2-2. clawback_recovery (상계 회수 이력)

컬럼	타입	설명
recovery_id	BIGSERIAL PK
receivable_id	BIGINT NN FK clawback_receivable
settle_month	CHAR(6) NN	회수(상계) 정산월
recovered_amount	NUMERIC(15,2) NN	이 월 이 채권에서 회수한 액
created_at	TIMESTAMP NN DEFAULT now()

• idx: (receivable_id), (settle_month)
• 멱등 키: 배치 재실행 시 동일 settle_month 회수분을 reverse(삭제+balance 복원) 후 재적용.

2-3. settle_master 컬럼 추가 (기존 의미 불변)

ALTER TABLE settle_master
  ADD COLUMN clawback_recovered NUMERIC(15,2) NOT NULL DEFAULT 0,  -- 당월 채권 상계 회수액
  ADD COLUMN clawback_carryover NUMERIC(15,2) NOT NULL DEFAULT 0,  -- 당월 발생→이월된 미수액
  ADD COLUMN payable_amount     NUMERIC(15,2) NOT NULL DEFAULT 0;  -- 실지급(이체대상) = max(0,net) − recovered

• net_amount(=gross−소득세−지방세+부가세−공제) 의미·계산 불변(무결성 Σ원장==Σsettle_master 보존).
• 실제 이체/출금 가용액은 payable_amount 사용(후속: withdraw 한도 검증을 payable_amount 기준으로 전환은 본 P9 범위 외, 문서화만).

2-4. 메뉴 / 권한 / 공통코드

• 메뉴 CLAWBACK_RECEIVABLE (환수채권관리), 상위 GRP_COMMISSION, path /commission/clawback-receivable, component commission/ClawbackReceivable.
• 권한 READ/UPDATE/EXPORT + 역할부여(SUPER_ADMIN·ADMIN 전체, MANAGER READ) — V54/V95 패턴.
• 공통코드 CLAWBACK_RCV_STATUS: OUTSTANDING=미회수/RECOVERING=회수중/CLEARED=상환완료/WRITTEN_OFF=대손.

---

3. 배치 통합 (AggregateStep, Step 8) — 핵심

설계사 루프에서 rawNet = tax.netAmount() − deductionTotal 계산 직후(현 196행), settle_master.upsert 이전에 삽입:

priorBalance = receivableMapper.outstandingBalance(agentId, settleMonth)
               // SUM(balance) WHERE agent_id=? AND status IN('OUTSTANDING','RECOVERING')
               //                AND origin_settle_month < settleMonth
recovered = 0; carryover = 0; payable = 0
if (rawNet.signum() >= 0) {
    recovered = min(rawNet, priorBalance)     // 양수 net에서 기존 채권 FIFO 상계
    payable   = rawNet - recovered
} else {
    payable   = 0
    carryover = rawNet.negate()               // 음수분 신규 채권화
}
vo.setNetAmount(rawNet)                        // 불변
vo.setClawbackRecovered(recovered)
vo.setClawbackCarryover(carryover)
vo.setPayableAmount(payable)
settleMapper.upsert(vo)

// settle_master upsert 가드(status NOT IN CONFIRMED/PAID)와 동일 행만 채권 부수효과 적용
if (settle_master 행이 갱신가능 상태였다면) {
    clawbackService.applyCarryoverAndRecovery(agentId, settleMonth, carryover, recovered)
}

applyCarryoverAndRecovery (배치 멱등 보장) — ga-batch 내 헬퍼 또는 Mapper 직접:

1. reverse: 이 settleMonth의 기존 clawback_recovery 행 조회 → 각 receivable.balance += recovered_amount, recovered_amount -= , status 재계산(CLEARED→RECOVERING/OUTSTANDING) → recovery 행 삭제. (재실행 안전)
2. carryover: carryover>0 → upsert clawback_receivable (agent_id, origin=settleMonth) {original_amount=carryover, balance=carryover, recovered_amount=0, status=OUTSTANDING}. (ON CONFLICT 갱신)
3. recovery: recovered>0 → outstanding 채권 origin_month ASC FIFO 순회:
   • take = min(recovered_remaining, rcv.balance); rcv.recovered_amount += take; rcv.balance -= take; status = balance==0 ? CLEARED : RECOVERING; last_recovery_month=settleMonth; INSERT clawback_recovery(receivable_id, settleMonth, take); recovered_remaining -= take;
   • recovered_remaining==0 종료.

reverse를 먼저 하므로 동일 월 재정산 시 회수 중복 없음. carryover는 UNIQUE upsert로 멱등. 주의: priorBalance 조회는 origin_settle_month < settleMonth 로 당월 발생분 자기상계 방지.

배치 Step 순서: AggregateStep(8) 내부에서 처리(별도 Step 불필요). 회계분개(8b)·세금은 net_amount 기준 불변.

---

4. API (ga-api)

ClawbackReceivableService + ClawbackReceivableController (/api/clawback-receivables):

• GET /api/clawback-receivables — 목록(agentId/status/originMonth 필터, PageHelper, @RequirePermission READ)
• GET /api/clawback-receivables/{id} — 상세 + 회수이력(clawback_recovery 리스트)
• GET /api/clawback-receivables/summary — 설계사별 미결 잔액 집계(status OUTSTANDING/RECOVERING)
• PUT /api/clawback-receivables/{id}/write-off — 대손/직접상환 처리(@RequirePermission UPDATE, @DataChangeLog). body {action: WRITTEN_OFF|CLEARED, reason}. balance→0, status 전이, writeoff_* 기록. OUTSTANDING/RECOVERING만 허용(CLEARED/WRITTEN_OFF 재처리 E411).
• GET /api/clawback-receivables/export — 엑셀(ExcelService, @Transactional).
• 표준 ApiResponse/PageResponse, MapStruct, BaseMapper 상속.

회수(recovery)는 배치만 생성(수동 회수 엔드포인트 없음 — 정산 상계로만 발생).

---

5. Frontend (ga-frontend)

• src/api/clawbackReceivable.ts — list/detail/summary/writeOff/export.
• src/pages/commission/ClawbackReceivable.tsx — AG Grid(목록 100건+ / status 컬러칩 / 합계행: original/recovered/balance) + 행 클릭 상세 Drawer(회수이력 타임라인) + 대손/상환 처리 버튼(PermissionButton UPDATE) + 엑셀 export.
• App.tsx 라우트 commission/clawback-receivable (lazy).

---

6. 검증 (PL 직접)

1. ./gradlew build(test 포함) SUCCESSFUL, ga-frontend npm run build PASS.
2. Flyway V111 success, schema v111. 테이블 2개·컬럼 3개·메뉴 1·권한·공통코드 확인.
3. GET 3종 + write-off PUT 실호출 5xx 0.
4. 배치 e2e (핵심): 단일 트랜잭션 롤백 시나리오로
   • (a) 특정 설계사에 chargeback>gross 인 net<0 상황 구성 → 202611 정산 → clawback_carryover 발생 + clawback_receivable OUTSTANDING 1건 + payable=0 확인.
   • (b) 익월 202612 정산(양수 net) → clawback_recovered 상계 + receivable balance 감소/CLEARED + clawback_recovery 행 + payable=net−recovered 확인.
   • (c) 동일월 재실행 → 회수 중복 없음(reverse 멱등) 확인.
   • 부산물 전부 롤백, pre-e2e 복원.

---

7. 후속 갭 (본 P9 범위 외, 기록)

• 시상/인정실적 환수 ledger (incar 인정실적수수료환수/신인도입유치자시상환수).
• 지급대상건 구성·수정(수동 포함/제외 워크플로우, incar 지급대상건구성/수정/조회).
• 환수 보험사자료 업로드(incar 환수보험사자료 업로드 — 보험사 통보 기반 환수 인입).
• withdraw 가용한도 검증을 net_amount→payable_amount 로 전환.