docs: 수수료 레퍼런스에 갭보완 4종(§3-7) 반영 + 간이지급명세서 주민번호 화면 마스킹

- 수수료_계산공식_전체레퍼런스.md: §3-7 감사 보완 4종(A 지급보류/B 환수원천세역분개/
  C 환수채권연체이자/D 간이지급명세서) 추가, schema v126 표기
- SimplifiedPaymentReport: 화면 표시용 주민번호 마스킹(생년월일+성별구분 이후 *).
  엑셀 export는 국세청 제출용이라 원본 유지

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
GA Pro
2026-06-08 21:27:26 +09:00
parent fbbabf2d04
commit 711f3b5e16
3 changed files with 103 additions and 2 deletions
@@ -121,6 +121,47 @@ net = gross − 소득세 − 지방세 + 부가세 − 공제(deduction)
---
## 3-7. 2026-06 감사 보완 4종 (V124~V126)
설계사 지급성 수수료 종류는 사실상 완비된 상태에서, 감사로 발견한 **실제 결함·규제 갭**만 보완.
### 3-7-A. 지급보류(HOLD) 지급배치 제외 — **버그 수정**
```
지급배치 대상 = settle_master WHERE payable_amount>0 AND status NOT IN ('PAID','HOLD')
```
- 종전엔 `status != 'PAID'` 만 검사 → 운영자가 지급보류(HOLD)한 설계사도 펌뱅킹 이체에 포함되던 결함.
(`PaymentBatchItemMapper.insertFromSettleMaster`)
### 3-7-B. 환수 원천세 역분개 — 교차월 환수 시 기납부 원천세 보정
```
gross<0(상계되지 않은 환수분)인 월:
역분개 기준액 = |gross|
소득세 역분개 = −(|gross| × 소득세율) ← withholding_tax_adjustment (음수)
지방세 역분개 = −(소득세 역분개액 × 10%)
분기 원천세신고 = Σpayment(원천세) + Σadjustment(역분개, 음수) ← 과대신고 해소
```
- gross≥0(당월 환수가 양수분으로 상계)인 달은 당월 과세에 이미 반영 → **역분개 미발생**(이중계상 없음).
- settle_master gross/net/carryover/payable 흐름은 **불변**(역분개는 신고보정용 별도 레코드).
(`AggregateStep` gross<0 분기, `WithholdingTaxReportMapper.upsertQuarterlyAggregate`)
### 3-7-C. 환수채권 연체이자 — 미수채권 이월 시 월 단리 적립
```
당월 적립이자 = 채권잔액(balance) × 연체이자율(%) / 1200 (월 단리, scale 0)
적립조건 = origin_settle_month ≤ 당월 (거치기간+1)
balance += 적립이자 (→ 기존 FIFO 상계가 이자까지 회수)
```
- 이자율 `CLAWBACK_OVERDUE_INTEREST_RATE`(기본 0=미적립 안전폴백), 거치기간 `CLAWBACK_INTEREST_GRACE_MONTHS`(기본 0).
- 멱등: `clawback_interest` 이력으로 당월 적립분 reverse 후 재적립. (`AggregateStep.reverseAndAccrueClawbackInterest`)
### 3-7-D. 사업소득 간이지급명세서(월별) — 국세청 제출 대응
```
간이지급명세서 = commission_statement(MONTHLY) ⋈ agent
(소득자·주민/사업자번호·지급액·소득세·지방소득세·차인지급액)
```
- 신규 데이터테이블 없음(읽기전용 리포트). 조회 + 엑셀 export. (`ReportMapper.selectSimplifiedPayment`)
---
## 4. 실지급 흐름 한 장 요약
```
@@ -138,4 +179,4 @@ net = gross − 소득세 − 지방세 + 부가세 − 공제(deduction)
*기준 코드: CommissionCalculator, TaxCalculator, ChargebackCalculator, InstallmentPlanGenerator,
RegulatoryLimitChecker, CalcRecruit/Maintain/OverrideStep, AggregateStep, AccountingEntryGenerateStep,
P7/P8 12개 commission Service. schema v110. 2026-06 수수료 감사 수정 반영.*
P7/P8 12개 commission Service. schema v126. 2026-06 수수료 감사 수정 + 갭보완 4종(§3-7) 반영.*
@@ -27,9 +27,15 @@ function fetchReport(settleMonth: string) {
);
}
// 화면 표시용 주민번호 마스킹(생년월일+성별구분 이후 *). 엑셀 export(국세청 제출용)는 원본 유지.
function maskResidentNo(v?: string): string {
if (!v) return '-';
return v.length > 8 ? v.slice(0, 8) + '*'.repeat(v.length - 8) : v;
}
const columns: ProColumns<SimplifiedPaymentRow>[] = [
{ title: '소득자', dataIndex: 'agentName', width: 120, fixed: 'left' },
{ title: '주민등록번호', dataIndex: 'residentNo', width: 140 },
{ title: '주민등록번호', dataIndex: 'residentNo', width: 140, render: (_, r) => maskResidentNo(r.residentNo) },
{ title: '사업자번호', dataIndex: 'businessNo', width: 140 },
{ title: '소득구분', dataIndex: 'incomeTypeName', width: 90 },
{
+54
View File
@@ -0,0 +1,54 @@
{
"title": "보험 수수료 갭 보완 — 감사 발견 4종",
"stories": [
{
"id": "US-A",
"title": "지급보류(HOLD) 건이 지급배치에 포함되는 버그 수정",
"priority": 1,
"passes": true,
"acceptanceCriteria": [
"PaymentBatchItemMapper.insertFromSettleMaster 쿼리가 status='HOLD' 인 settle_master 를 지급배치 대상에서 제외한다",
"HOLD 건은 batch_item 에 포함되지 않고, CALCULATED/CONFIRMED 건은 그대로 포함됨을 검증하는 단위테스트 추가",
"./gradlew :ga-api:test 관련 테스트 통과(또는 mapper 단위검증), 전체 build 통과"
]
},
{
"id": "US-B",
"title": "환수(클로백) 발생 시 기납부 원천세 환급/조정 — 분기 원천세신고·연간소득 반영",
"priority": 2,
"passes": true,
"acceptanceCriteria": [
"클로백으로 gross<0 인 월에 원천세 역분개(음수 income_tax/local_tax)가 산출되어 withholding_tax_adjustment 에 멱등(agent_id,settle_month,reason UNIQUE) 기록된다",
"분기 원천세신고(withholding_tax_report) 집계가 해당 역분개를 차감 반영하여 과대신고가 해소된다",
"settle_master 금액 흐름(gross/net/carryover/payable)과 양수 정산 동작은 불변(회귀 없음) — 역분개는 별도 레코드로만 적재",
"단위테스트: BatchTaxCalculator 역분개액 + 양수월+클로백월 시퀀스 누적 원천세 net-off 검증",
"전체 build/test 통과"
]
},
{
"id": "US-C",
"title": "환수채권(미수) 이월 시 연체이자 자동 발생",
"priority": 3,
"passes": true,
"acceptanceCriteria": [
"환수채권 balance 가 이월될 때 연체일수 기준 연체이자가 산출된다(이자율은 common_config 로 정책화, 기본값 명시)",
"연체이자가 환수채권에 누적 기록되고 회수/상계 대상에 포함된다",
"이자율 0 또는 미설정 시 기존 동작(이자 미발생)과 동일하게 안전 폴백",
"단위테스트: 연체일수→이자액 계산 및 0율 폴백 검증",
"전체 build/test 통과"
]
},
{
"id": "US-D",
"title": "사업소득 간이지급명세서(월별) 생성 — 국세청 제출 법정의무 대응",
"priority": 4,
"passes": true,
"acceptanceCriteria": [
"월별(설계사×정산월) 사업소득 지급명세서 집계가 생성된다(소득액·원천세·지방소득세)",
"조회 API + 엑셀 export 제공(기존 report/statement 패턴 재사용)",
"기존 분기 원천세신고와 데이터 정합(동일 payment 소스 기준)",
"전체 build/test 통과"
]
}
]
}