원화 오프램프 출금 기획·기술설계서 v0.9

출금팀은 partners 테이블의 내부 파트너로 등록한다 — 원장 적립과 인출이 기존 구조를 그대로 재사용한다.

원화 신청액 ÷ 빗썸 시세 = 락업 USDT　·　유저는 1,000,000원 전액 수령
올림 이유 — 내림하면 정산 분배 시 극소량이 모자라 실패한다. 파트너가 아주 조금 더 부담하지만 절대 부족하지 않다. 남는 dust는 정산 시 파트너에게 원복한다.
락업 총액은 저장하지 않는다 — usdt_amount + fee_amount 로 유도 (“저장하지 않고 유도” 원칙).

금액 구간

이 시스템에는 잔액 컬럼이 없다

settlement_balances.frozen_amount 는 2026-07-02 운영에서 DROP 됐다 (교차간섭 · 드리프트). freeze() 는 DB 쓰기가 없는 검증 전용이고 unfreeze() 는 no-op 이다. hold 는 매번 레코드 status 에서 파생된다.

-- 파트너 USDT 가용잔액 (SettlementService.getAvailableBreakdown)
available = computeBalance(ledger_entries)        -- CREDIT+ADJUSTMENT − DEBIT−FEE
          − sumPendingGeneralWithdrawals          -- 기존: withdrawals 파생
          − sumPendingCollection                  -- 기존: collection_queue 파생
          − sumPendingKrwOrderHold                  -- 신규 ← 이 한 항만 추가

-- KrwWithdrawOrderMapper.sumPendingHold
SELECT COALESCE(SUM(usdt_amount + fee_amount), 0)
FROM krw_withdraw_orders
WHERE partner_id = #{partnerId}
  AND currency_id = #{currencyId}
  AND network_id  = #{networkId}
  AND status IN ('REQUESTED', 'APPROVED');

축은 (partner_id, currency_id, network_id) 3키다. USDT는 체인마다 다른 currency_id 를 갖는다 (BSC=1 / POLYGON=2 / TRON=3) — “단일 체인 락업”이 기존 구조와 정확히 맞는다. BSC 부족 시 TRON 으로 폴백하되 한 오더는 한 체인만 쓴다.

☠️ 이중차감 방지 계약

-- 정산 트랜잭션 안에서 반드시 함께 일어나야 한다
① status : APPROVED → COMPLETED    -- hold 집계에서 빠짐
② ledger DEBIT 기록                -- 실감소 반영

-- 둘이 갈라지면
①만 반영 → 유령잔액 (묶이지도 차감되지도 않음)
②만 반영 → 이중차감 (hold + DEBIT 양쪽)

P2P 가 이 지점에서 두 번 사고를 냈다 — getSystemUnrealizedFeeBySource(2026-07-02 제거), p2p_partner_locks.locked_balance(2026-08-27 제거). 신규 항 추가 시 기존 3항과 이중차감이 없는지 반드시 검증할 것.

책임 경계 — 우리는 어디까지 하는가

구조는 단순하다 — 우리는 출금 요청 API 를 받고, 상태별로 API 를 반환한다. 그 앞단(유저가 무엇을 보는지)은 파트너사 영역이다.

☠️ 잔액 부족 = 오더를 만들지 않는다

락업이 접수 트랜잭션의 일부이므로, 락업이 실패하면 INSERT 자체가 롤백된다. 오더 레코드가 남지 않고, 오더 코드도 발급되지 않는다.

POST /api/v1/krw-withdrawals
   ↓
 ... 검증 · 환율 각인 · 체인 선택 ...
   ↓
 🔒 파트너 × 체인 FOR UPDATE
   ↓
 가용액 검증 → 부족
   ↓
 트랜잭션 롤백 — 오더 생성 안 됨
   ↓
 HTTP 409  KRW_PARTNER_BALANCE_SHORT (1117)

오더가 없으므로 조회해도 나오지 않고(404), webhook 도 발송되지 않는다. 파트너는 동기 응답만으로 실패를 알 수 있다 — 비동기 대기가 필요 없다.

응답 스펙 — 접수 거절

HTTP 409 Conflict
{
  "code": "1117",
  "reasonCode": "TEMPORARILY_UNAVAILABLE",
  "retryable": true,
  "retryAfterSeconds": 300,
  "userMessage": "현재 출금 신청이 일시 중단되었습니다. 잠시 후 다시 시도해 주세요."
}
// orderCode 없음 — 오더가 생성되지 않았다

userMessage 를 우리가 내려주는 이유 — 파트너마다 제각각 번역하다 “테더 잔액 부족” 같은 내부 사정이 유저에게 새는 것을 막는다. 파트너는 이 문자열을 그대로 쓰면 되고, 쓸지 말지는 파트너 선택이다.

거절을 줄이는 장치 — 우리가 제공하는 것

-- ═══════════════════════════════════════════════════════════════════
-- │  SECTION 10: 원화 오프램프 출금 (KRW Off-ramp Withdrawal)        │
-- │  v2.20 추가 (2026-09-17)                                        │
-- ═══════════════════════════════════════════════════════════════════

-- 10-1. 원화 출금 오더
-- ★ 락업은 접수 시점에 이뤄진다. 접수 트랜잭션이 곧 락업 트랜잭션이다.
-- ☠️ 잔액/락업 컬럼을 두지 않는다. frozen_amount 는 2026-07-02 DROP 됐다.
--    hold 는 status IN ('REQUESTED','APPROVED') 파생이며, 상태가 바뀌면
--    자동으로 빠진다. "원복" 이라는 별도 동작은 존재하지 않는다.
CREATE TABLE krw_withdraw_orders (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_code VARCHAR(30) NOT NULL          COMMENT '오더 코드 — kwo_{nanoid}',
    partner_id      BIGINT NOT NULL          COMMENT 'partners.id',
    partner_user_id VARCHAR(255) NOT NULL     COMMENT '파트너 회원 ID',

    -- 금액 (KRW 원 단위 정수)
    krw_amount BIGINT NOT NULL               COMMENT '신청 원화액 = 유저 수령액',

    -- 환율 각인 (접수 순간 고정)
    rate_krw DECIMAL(20,4) NOT NULL          COMMENT '빗썸 USDT 시세',
    rate_at  DATETIME(6)   NOT NULL          COMMENT '조회 시각 — 분쟁 근거',

    -- USDT 환산 (6자리 올림)
    usdt_amount DECIMAL(36,18) NOT NULL       COMMENT '환산 원금 (krw ÷ rate, 올림)',
    fee_rate    DECIMAL(10,6)  NOT NULL       COMMENT '적용 요율 — 퍼센트 (1.0 = 1%)',
    fee_amount  DECIMAL(36,18) NOT NULL       COMMENT '수수료 확정액 (파트너 부담)',
    -- ※ 락업 총액은 저장하지 않는다 — usdt_amount + fee_amount 로 유도

    -- ★ 락업 대상 — 접수 시 확정
    currency_id BIGINT NOT NULL              COMMENT 'BSC=1 / POLYGON=2 / TRON=3',
    network_id  BIGINT NOT NULL              COMMENT '회수도 동일 체인',

    -- 수취 계좌 (개인정보 — 목록 마스킹)
    bank_code      VARCHAR(20)  NOT NULL,
    account_no     VARCHAR(50)  NOT NULL,
    account_holder VARCHAR(100) NOT NULL     COMMENT '예금주 — 화면 강조, 육안 대조',

    partner_reference VARCHAR(255)           COMMENT '파트너 주문번호 — 멱등키 원본',
    partner_metadata  JSON                   COMMENT 'pass-through',

    -- 상태 6종
    status VARCHAR(20) NOT NULL DEFAULT 'REQUESTED'
        COMMENT 'REQUESTED(요청) → APPROVED(승인) → COMPLETED(완료)
                 COMPLETED → REVERSED(회수)
                 분기: REJECTED(반려) / FAILED(실패)
                 ★ hold 대상 = REQUESTED, APPROVED',

    -- 처리자 (감사)
    approved_by VARCHAR(255),  approved_at DATETIME(6),

    -- 지급 보고 (상태 아님 — 승인 구간의 시각 기록)
    reported_by        VARCHAR(255),  reported_at DATETIME(6),
    proof_type         VARCHAR(20)   COMMENT 'IMAGE / TXNO',
    proof_ref          VARCHAR(500)  COMMENT '이체확인증 경로 또는 거래번호',
    paid_account_last4 VARCHAR(4)    COMMENT '실제 송금 계좌 뒷4자리 — 대조 근거',
    report_id          VARCHAR(64)   COMMENT '보고 멱등키',

    -- 정산
    settled_at DATETIME(6),
    settle_retry_count INT NOT NULL DEFAULT 0
                                        COMMENT '★정산 재시도 횟수 (최대 5회)',

    -- 회수 (완료 이후 사후)
    reversed_at DATETIME(6),  reverse_reason VARCHAR(500),

    -- 종결
    closed_at    DATETIME(6),
    close_reason VARCHAR(50)
        COMMENT 'AGENT_REJECTED / EXPIRED / CANCELLED_BY_PARTNER /
                 CANCELLED_BY_ADMIN / PAYMENT_MISMATCH / SETTLE_FAILED / REVERSED',
    incident_note TEXT                  COMMENT '사고 메모 — 회수는 시스템 밖 트랙',

    expire_at  DATETIME(6) NOT NULL         COMMENT '접수 + TTL',
    extend_count INT NOT NULL DEFAULT 0     COMMENT 'TTL 연장 횟수',

    created_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6),
    updated_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),

    -- 멱등키 — withdrawals.idem_key 패턴 그대로
    -- ★ 종결 상태 목록을 애플리케이션에서 다시 열거하지 말 것. 이 CASE 가 유일한 정의다.
    idem_key VARCHAR(255) GENERATED ALWAYS AS (
        CASE WHEN status IN ('REJECTED','FAILED','REVERSED')
             THEN NULL ELSE partner_reference END
    ) STORED,

    UNIQUE KEY uk_kwo_code (order_code),
    UNIQUE KEY uk_kwo_partner_idem (partner_id, idem_key),
    KEY idx_kwo_hold (partner_id, currency_id, network_id, status),  -- hold 집계 전용
    KEY idx_kwo_status_created (status, created_at),
    KEY idx_kwo_expire (status, expire_at),
    KEY idx_kwo_settle_pending (status, reported_at, settled_at),  -- ★정산 대기 조회
    KEY idx_kwo_partner_user (partner_id, partner_user_id, created_at)
) COMMENT '원화 오프램프 출금 오더 — 락업은 접수 시점, hold 는 status 파생';


-- 10-2. 파트너별 원화 출금 설정
CREATE TABLE partner_krw_withdraw_configs (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    partner_id BIGINT NOT NULL,
    is_enabled TINYINT(1) NOT NULL DEFAULT 0,
    fee_rate        DECIMAL(10,6) NOT NULL DEFAULT 1.000000  COMMENT '총 요율 %',
    system_fee_rate DECIMAL(10,6) NOT NULL DEFAULT 0.500000  COMMENT '크립토먼츠 몫 %',
    min_amount_krw         BIGINT NULL   COMMENT 'NULL = 전역 설정',
    max_amount_krw         BIGINT NULL,
    daily_limit_krw        BIGINT NULL,
    user_daily_limit_krw   BIGINT NULL,
    user_daily_limit_count INT    NULL,
    concurrent_limit_krw   BIGINT NULL   COMMENT '★동시 진행(hold) 상한 — 락업 폭주 방지',
    low_balance_alert_usdt DECIMAL(36,18) NULL COMMENT '★가용액 임계 — 이하면 사전 경고',
    created_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6),
    updated_at DATETIME(6) DEFAULT CURRENT_TIMESTAMP(6) ON UPDATE CURRENT_TIMESTAMP(6),
    UNIQUE KEY uk_pkwc_partner (partner_id)
) COMMENT '파트너별 원화 출금 설정 — 요율·한도·임계';

컨벤션 준수 — ENUM 미사용(VARCHAR+COMMENT) · FK 없음 · DATETIME(6) · KRW=BIGINT / USDT=DECIMAL(36,18) / 환율=DECIMAL(20,4) / 요율=DECIMAL(10,6) 퍼센트 · 코드 {prefix}_{nanoid} · 인덱스 uk_/idx_ 테이블 약어 접두.
원장 참조는 단일 축으로 고정 — reference_type='KRW_WITHDRAW' + reference_id=krw_withdraw_orders.id. p2p_settlements 는 두 ID 공간을 섞어 파트너 경계를 넘는 조인 사고를 냈다.

① 접수 = 락업 — 기존 requestWithdrawal 프로토콜 재사용

[락 밖]
 ① 멱등 검사 (partner_reference)            ← 최우선. 뒤에 두면 중복이 다른 오류로 먼저 실패
 ② 서비스 게이트 (점검시간 · 접수중지 · 사전차단 버퍼)
 ③ 금액 범위 (파트너 설정 > 전역 설정) · 일일/유저 한도
 ④ 시세 조회 → ±5% 이상치 필터 → 각인      ← 캐시 5분, 초과 시 거절. 임의 추정 금지
 ⑤ 체인 후보 스캔 (BSC 우선, 읽기 전용)       ← I/O 를 락 안에 넣으면 전 파트너가 직렬 대기

[락 안 — 선택된 1개 체인만]
 ⑥ 🔒 lockPartnerBalanceForWithdrawal(partner, currency, network)  FOR UPDATE
 ⑦ 연타 차단 (60초 창)                       ← 반드시 락 이후. 앞에 두면 동시 요청이 전부 통과
 ⑧ 동시 진행 상한 검사 (concurrent_limit_krw)                      (2026-05-21 사고: 1초 53건)
 ⑨ 가용액 검증 (자기 미포함) → 부족 시 409
 ⑩ INSERT (REQUESTED)                       ← save 를 재검증보다 먼저 (자기 레코드가 hold 에 포함되도록)
 ⑪ 저장 후 재검증 (자기 포함) → 음수면 롤백
 ⑫ 상태 이력 + 출금팀 텔레그램

④ 정산 → 완료 (원자적)

@Transactional  // 전부 or 전무
 ① 상태 가드 (APPROVED + reported_at NOT NULL)
 ② settlementService.debit (파트너,  usdt + fee,     KRW_WITHDRAW, order.id)
 ③ settlementService.credit(출금팀,  usdt + 팀몫,     KRW_WITHDRAW, order.id)
 ④ settlementService.recordFee(     시스템몫,        KRW_WITHDRAW, order.id)
 ⑤ UPDATE status=COMPLETED, settled_at        ← 팀 인출은 즉시 가능
 ⑥ (트랜잭션 밖) webhook + 텔레그램          ← 알림 실패가 자금 트랜잭션을 깨지 않게 try/catch

⚠ 정산 실패 시 — 트랜잭션이 롤백되어 상태는 APPROVED 로 남는다. 지급은 이미 끝났으므로 KrwSettleRetryJob 이 status='APPROVED' AND reported_at IS NOT NULL AND settled_at IS NULL 을 주워 재시도한다.

A. open-api — 파트너 서버 연동 (HMAC 3헤더)

// POST 요청
{ "orderId": "P20260917-001",   // 멱등키 (빈문자 → null 정규화)
  "userId": "user_12345",
  "krwAmount": 1000000,          // 원 단위 정수
  "bankCode": "004", "accountNo": "12345678901234", "accountHolder": "홍길동",
  "metadata": "{...}" }          // pass-through

// 응답 — ❌ 잔액 정보 없음
{ "orderCode": "kwo_a1b2c3d4", "status": "PROCESSING",
  "krwAmount": 1000000, "estimatedMinutes": 30 }

상태 매핑 (내부 6종 → 파트너 3종) — 요청·승인 → PROCESSING / 완료 → COMPLETED / 반려·실패·회수 → FAILED + reasonCode

모든 매핑에 한글 name = + Javadoc @group/@auth/@response/@header — 이게 없으면 Axim REST 문서 생성기가 파트너 문서를 만들지 못한다. 목록은 XPage<T> + @XPaginationDefault(column="id") XPagination + from/to/status/search.

// 실패 페이로드 — 유저 문구를 우리가 내려준다
{ "eventType": "KRW_WITHDRAWAL_FAILED",
  "eventId": "evt_kwo_a1b2c3d4_fail",      // ★ 멱등 처리용 — 기존 출금엔 없는 필드
  "reasonCode": "TEMPORARILY_UNAVAILABLE",
  "retryable": true, "retryAfterSeconds": 300,
  "userMessage": "현재 출금 신청이 일시 중단되었습니다. 잠시 후 다시 시도해 주세요." }

구현 규칙 — 페이로드는 WebhookPayloadBuilder 안에서만 생성한다(2026-08-07 통합 이력, 호출부 JSON 조립 금지) · 서명식 partnerId|txHash|amount|timestamp 불변(txHash는 "") · 발송은 notificationService.send(...) 한 줄 + try/catch · 재시도 30s/60s/300s/900s/3600s 5회는 기존 인프라 그대로.
텔레그램 — 발송은 Spring 전담(Node 봇은 수신만). TelegramMessageFormatter 에 krwOrderRequested / Approved / Rejected / Paid / Settled / Reversed / LowBalance 추가. 출금팀 단톡방 + partner_telegram_configs 파트너별 채널.

설정 키 — system_settings INSERT 블록에 함께 추가

⚠ 코드에서 조회하는데 DDL 씨드에 없는 키가 이미 7개 드리프트돼 있다. 신규 키는 반드시 DDL INSERT 블록에 함께 넣고, 코드에는 상수 + 폴백 기본값을 둔다.

화면은 cryptoments-admin repo 에 만든다 (본 repo 에는 추가하지 않는다). 설계서는 ADMIN_CONSOLE_UI_HANDOFF.md 의 “엔드포인트 표 / 목록 컬럼 표 / 액션 표” 3단 포맷을 따른다.

A. 출금팀 오더 페이지 — admin-ui 신규 메뉴 「원화 출금」

잔액부족 배지는 없다 — 접수 단계에서 이미 걸러진다. 대신 남은시간(TTL) 이 핵심 컬럼이다.
상세(SlideDrawer) : 계좌·금액 [복사] 버튼(수기 입력 제거) · 예금주명 강조 · 남은시간 · [승인] [반려] [시간 연장] · 지급완료 보고 폼(증빙 + 뒷4자리 입력·대조, 불일치 시 버튼 비활성)

UI 규칙 — 목록은 useDataTable composable 로만 · 공통 컴포넌트 (DataTable/StatusBadge/AmountDisplay/DateDisplay/EmptyState/LoadingSkeleton) 사용 · 서비스 레이어는 얇은 URL 매핑만(에러는 인터셉터 위임, catch 에서 mock 반환 금지) · 20건/페이지, XPagination 1-based, 기본 created_at DESC · 로딩은 스피너가 아니라 스켈레톤 · 위험 액션은 ConfirmDialog 필수 · 계좌·예금주는 목록 마스킹(상세에서만 전체).

제안 요약