# 지침서 #32 — GAS_COST 원장 타입 + 출금 수수료 제거

**날짜**: 2026-03-22
**대상**: Spring Boot (IntelliJ) + DDL
**난이도**: ★☆☆ (단순 삭제)
**예상 시간**: 15분

---

## 배경

### GAS_COST 제거 이유
- 가스비는 `gas_cost_records` → `gas_invoices` 별도 청구 체계로 운영
- `ledger_entries`에 GAS_COST 엔트리를 INSERT하는 코드가 **어디에도 없음**
- `computeBalance` SQL에만 방어적으로 포함 → 실제 데이터 0건
- 원장과 가스비 이중 차감 구조는 불필요

### withdrawal_fee_fixed 제거 이유
- 출금 수수료 부과 로직이 미구현이며, 부과하지 않기로 결정
- `WithdrawalService.onTxConfirmed()`에서 `debit(amount)` — 원금만 차감
- DDL/Entity/DTO에 컬럼만 존재하고 비즈니스 로직에서 사용하지 않음

---

## 변경 1: GAS_COST 원장 타입 제거 (5개 파일)

### 1-1. `common/.../enums/LedgerEntryType.java`

```java
// ❌ 삭제
GAS_COST,

// ✅ 결과 (3개만 남음)
public enum LedgerEntryType {
    /** 입금 / 자산 증가 */
    CREDIT,
    /** 출금 / 자산 감소 */
    DEBIT,
    /** 수수료 */
    FEE,
    /** 수동 조정 */
    ADJUSTMENT;
}
```

### 1-2. `common/.../enums/LedgerReferenceType.java`

```java
// ❌ 삭제
GAS_COST;

// ✅ 결과
public enum LedgerReferenceType {
    DEPOSIT,
    WITHDRAWAL,
    COLLECTION;
}
```

### 1-3. `common/.../mapper/LedgerMapper.java`

```java
// ❌ 기존
/**
 * CREDIT + ADJUSTMENT - DEBIT - FEE - GAS_COST
 */
+ "  - SUM(CASE WHEN entry_type IN ('DEBIT','FEE','GAS_COST') THEN amount ELSE 0 END)"

// ✅ 변경
/**
 * CREDIT + ADJUSTMENT - DEBIT - FEE
 */
+ "  - SUM(CASE WHEN entry_type IN ('DEBIT','FEE') THEN amount ELSE 0 END)"
```

### 1-4. `admin-api/.../dto/response/TxSearchResponse.java`

JavaDoc 주석 2곳 수정:

```java
// L113 부근
// ❌ /** 원장 항목 타입 (CREDIT / DEBIT / FEE / GAS_COST / ADJUSTMENT) */
// ✅ /** 원장 항목 타입 (CREDIT / DEBIT / FEE / ADJUSTMENT) */

// L122 부근
// ❌ /** 참조 타입 (DEPOSIT / WITHDRAWAL / COLLECTION / GAS_COST) */
// ✅ /** 참조 타입 (DEPOSIT / WITHDRAWAL / COLLECTION) */
```

### 1-5. `common/.../entity/LedgerEntry.java`

JavaDoc 주석 2곳 수정:

```java
// L30 부근
// ❌ /** CREDIT / DEBIT / FEE / GAS_COST / ADJUSTMENT */
// ✅ /** CREDIT / DEBIT / FEE / ADJUSTMENT */

// L39 부근
// ❌ /** DEPOSIT, WITHDRAWAL, COLLECTION, GAS_COST */
// ✅ /** DEPOSIT, WITHDRAWAL, COLLECTION */
```

> **참고**: `AuditAction.WAIVE_GAS_COST`와 `ResultEntityType.GAS_COST`는
> gas_cost_records 테이블 관련 감사 로그용이므로 **삭제하지 않음** (원장과 무관).

---

## 변경 2: withdrawal_fee_fixed 제거 (5개 파일 + DDL)

### 2-1. `common/.../entity/Partner.java`

```java
// ❌ 삭제 (L53 부근)
/** 출금 고정 수수료 */
private BigDecimal withdrawalFeeFixed;
```

### 2-2. `admin-api/.../dto/request/PartnerCreateRequest.java`

```java
// ❌ 삭제 (L71 부근)
/** 출금 고정 수수료 */
@DecimalMin("0")
private BigDecimal withdrawalFeeFixed;
```

### 2-3. `admin-api/.../dto/request/PartnerFeeUpdateRequest.java`

```java
// ❌ 삭제 (L34 부근)
/** 출금 고정 수수료 */
@DecimalMin("0")
private BigDecimal withdrawalFeeFixed;
```

### 2-4. `admin-api/.../dto/response/PartnerDetailResponse.java`

```java
// ❌ 삭제 (L65 부근)
private BigDecimal withdrawalFeeFixed;
```

### 2-5. `admin-api/.../service/PartnerManagementService.java`

4곳에서 `withdrawalFeeFixed` 참조 제거:

```java
// ❌ L199 (createPartner 빌더) — 삭제
.withdrawalFeeFixed(request.getWithdrawalFeeFixed())

// ❌ L291 (toDetailResponse 빌더) — 삭제
.withdrawalFeeFixed(partner.getWithdrawalFeeFixed())

// ❌ L402 (updateFees 변수) — 삭제
BigDecimal newWithdrawalFeeFixed = request.getWithdrawalFeeFixed() != null
    ? request.getWithdrawalFeeFixed() : partner.getWithdrawalFeeFixed();

// ❌ L429 (updateFees 빌더) — 삭제
.withdrawalFeeFixed(newWithdrawalFeeFixed)
```

---

## 변경 3: DDL 수정

### 3-1. `v2-docs/CRYPTOMENTS_V2_DDL.sql` — partners 테이블

```sql
-- ❌ L180 삭제
withdrawal_fee_fixed DECIMAL(10,4) DEFAULT 0 COMMENT '출금 고정 수수료 (USDT 단위)',
```

### 3-2. `v2-docs/CRYPTOMENTS_V2_DDL.sql` — ledger_entries 테이블

```sql
-- ❌ 기존 entry_type COMMENT (L1539 부근)
    entry_type VARCHAR(30) NOT NULL
        COMMENT 'CREDIT — 입금/자산 증가
                 DEBIT — 출금/자산 감소
                 FEE — 수수료
                 GAS_COST — 가스비
                 ADJUSTMENT — 수동 조정',

-- ✅ 변경
    entry_type VARCHAR(30) NOT NULL
        COMMENT 'CREDIT — 입금/자산 증가
                 DEBIT — 출금/자산 감소
                 FEE — 수수료
                 ADJUSTMENT — 수동 조정',
```

```sql
-- ❌ 기존 reference_type COMMENT
    reference_type VARCHAR(30) COMMENT 'DEPOSIT, WITHDRAWAL, COLLECTION, GAS_COST',

-- ✅ 변경
    reference_type VARCHAR(30) COMMENT 'DEPOSIT, WITHDRAWAL, COLLECTION',
```

### 3-3. DB 적용 (Cowork에서 실행)

```sql
-- partners 테이블에서 withdrawal_fee_fixed 컬럼 제거
ALTER TABLE partners DROP COLUMN withdrawal_fee_fixed;
```

> **참고**: ledger_entries의 entry_type은 VARCHAR이므로 DB 스키마 변경 없음.
> 기존 GAS_COST 데이터가 0건이므로 데이터 마이그레이션 불필요.

---

## 변경 요약

| # | 파일 | 변경 | 모듈 |
|---|------|------|------|
| 1-1 | `LedgerEntryType.java` | `GAS_COST` enum 삭제 | common |
| 1-2 | `LedgerReferenceType.java` | `GAS_COST` enum 삭제 | common |
| 1-3 | `LedgerMapper.java` | computeBalance SQL에서 `'GAS_COST'` 제거 | common |
| 1-4 | `TxSearchResponse.java` | JavaDoc 주석 2곳 | admin-api |
| 1-5 | `LedgerEntry.java` | JavaDoc 주석 2곳 | common |
| 2-1 | `Partner.java` | `withdrawalFeeFixed` 필드 삭제 | common |
| 2-2 | `PartnerCreateRequest.java` | `withdrawalFeeFixed` 필드 삭제 | admin-api |
| 2-3 | `PartnerFeeUpdateRequest.java` | `withdrawalFeeFixed` 필드 삭제 | admin-api |
| 2-4 | `PartnerDetailResponse.java` | `withdrawalFeeFixed` 필드 삭제 | admin-api |
| 2-5 | `PartnerManagementService.java` | `withdrawalFeeFixed` 참조 4곳 삭제 | admin-api |
| 3-1 | `CRYPTOMENTS_V2_DDL.sql` | partners 컬럼 삭제 + ledger COMMENT 정리 | DDL |
| 3-3 | DB | `ALTER TABLE partners DROP COLUMN` | DB |

**총 10개 Java 파일 수정 + DDL 1개 + DB ALTER 1건**

## 검증

```bash
./gradlew :common:compileJava :admin-api:compileJava :core:compileJava :open-api:compileJava
```

컴파일 통과하면 완료.