카드 정산 업무 규칙과 전환 불변식 추출 (codex-bais-final3-20260713-192718-BAIS-SPRING-ANA-CARD-001)

card-settlement-migration/INVARIANTS.md

@@ -0,0 +1,94 @@
+# 카드 정산 불변식 표 (Card Settlement Invariants)
+
+**범위**: card-settlement-migration
+
+## 1. 브랜드 정산 (Brand Settlement) 불변식
+
+| ID | 설명 | 수식 | 영향 클래스 | 보존 주의사항 |
+|---|---|---|---|---|
+| BRAND_SETTLEMENT_NON_NEGATIVE | 브랜드 정산금은 0 이상 | settlementAmount >= 0 | SettlementCalculator | 음수 시 0 보정 |
+| BRAND_SETTLEMENT_FORMULA | 정산금 = 승인금액 - 취소금액 - 수수료 | settlementAmount = approved - cancelled - commission | SettlementCalculator | 계산 순서 준수 |
+| BRAND_COMMISSION_FORMULA | 수수료 = 승인금액 * 정산요율 | commission = approvedAmount * rate | SettlementCalculator | 2자리 반올림 |
+| BRAND_COMMISSION_RATE_DEFAULT | 미지정 시 기본값 0.02(2%) | rate = 0.02 when null | SettlementCalculator | DEFAULT_COMMISSION_RATE |
+
+## 2. IRD (Interchange Reimbursement Fee) 불변식
+
+| ID | 설명 | 수식 | 영향 클래스 | 보존 주의사항 |
+|---|---|---|---|---|
+| IRD_NON_NEGATIVE | IRD는 0 이상 | ird >= 0 | SettlementCalculator | 음수 시 0 보정 |
+| IRD_FORMULA | IRD = 승인금액 * IRD율 | ird = approvedAmount * rate | SettlementCalculator | 2자리 반올림 |
+| IRD_RATE_DEFAULT | 미지정 시 기본값 0.015(1.5%) | rate = 0.015 when null | SettlementCalculator | DEFAULT_IRD_RATE |
+
+## 3. 발급사 수수료 (Issuer Fee) 불변식
+
+| ID | 설명 | 수식 | 영향 클래스 | 보존 주의사항 |
+|---|---|---|---|---|
+| ISSUER_FEE_NON_NEGATIVE | 발급사 수수료는 0 이상 | issuerFee >= 0 | SettlementCalculator | 음수 시 0 보정 |
+| ISSUER_FEE_FORMULA | 발급사 수수료 = IRD * 발급사 수수료율 | issuerFee = ird * rate | SettlementCalculator | 2자리 반올림 |
+| ISSUER_FEE_RATE_DEFAULT | 미지정 시 기본값 0.005(0.5%) | rate = 0.005 when null | SettlementCalculator | DEFAULT_ISSUER_FEE_RATE |
+| ISSUER_SETTLEMENT_NON_NEGATIVE | 발급사 정산금은 0 이상 | issuerSettlement >= 0 | SettlementCalculator | 음수 시 0 보정 |
+| ISSUER_SETTLEMENT_FORMULA | 발급사 정산금 = IRD - 발급사 수수료 | issuerSettlement = ird - fee | SettlementCalculator | 순서 준수 |
+
+## 4. 공통 금액 검증 불변식
+
+| ID | 설명 | 수식 | 영향 클래스 | 보존 주의사항 |
+|---|---|---|---|---|
+| AMOUNT_NOT_NULL | 금액은 null 불가 | amount != null | SettlementCalculator | IllegalArgumentException |
+| AMOUNT_NON_NEGATIVE | 금액은 0 이상 | amount >= 0 | SettlementCalculator | IllegalArgumentException |
+| AMOUNT_MAX_LIMIT | 최대 한도 이하여야 함 | amount <= 999999999999.99 | SettlementCalculator | IllegalArgumentException |
+
+## 5. 금액 정밀도 불변식
+
+| ID | 설명 | 수식 | 영향 클래스 | 보존 주의사항 |
+|---|---|---|---|---|
+| AMOUNT_SCALE | 소수점 2자리 표현 | scale(amount) = 2 | SettlementCalculator | setScale(2, HALF_UP) |
+| ROUNDING_MODE | HALF_UP 반올림 | RoundingMode.HALF_UP | SettlementCalculator | 반올림 정책 준수 |
+
+## 6. 계산 흐름도
+
+```
+승인요청
+  │
+  ▼
+┌─────────────────────────────┐
+│  SettlementCalculator       │
+│  ─────────────────────────  │
+│  [브랜드 정산 계산]          │
+│  1. 승인금액 검증 (NOT_NULL, │
+│     NON_NEGATIVE, MAX_LIMIT)│
+│  2. 수수료 = 승인금액 * 요율 │
+│  3. IRD = 승인금액 * IRD율  │
+│  4. 정산금 = 승인 - 취소 - 수수료│
+│  5. 음수 보정 (>= 0)        │
+│  ─────────────────────────  │
+│  [발급사 수수료 계산]        │
+│  6. 발급사수수료 = IRD * 요율│
+│  7. 발급사정산 = IRD - 수수료│
+│  8. 음수 보정 (>= 0)        │
+└─────────────────────────────┘
+  │
+  ▼
+정산 결과 출력
+```
+
+## 7. Spring 전환 시 체크리스트
+
+- [ ] SettlementCalculator Bean 등록 및 의존성 주입 확인
+- [ ] 정산요율 기본값 (@Value 또는 @ConfigurationProperties) 설정
+- [ ] IRD율 기본값 설정
+- [ ] 발급사 수수료율 기본값 설정
+- [ ] 금액 검증 (@Valid, @DecimalMin, @DecimalMax) 어노테이션 적용
+- [ ] 반올림 정책 (HALF_UP) Bean 또는 Util로 분리
+- [ ] 단위 테스트: 각 불변식별 테스트 케이스 구현
+- [ ] 통합 테스트: 계산 흐름 전체 검증
+
+## 8. 불변식 요약
+
+| 카테고리 | 불변식 수 |
+|---|---|
+| 브랜드 정산 | 4 |
+| IRD | 3 |
+| 발급사 수수료 | 5 |
+| 공통 금액 검증 | 3 |
+| 금액 정밀도 | 2 |
+| **총계** | **17** |