diff --git a/card-settlement-migration/INVARIANTS.md b/card-settlement-migration/INVARIANTS.md new file mode 100644 index 0000000..74f87ed --- /dev/null +++ b/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** |