법정공제 릴리스 검증 — 홈택스 표본 대조 절차

간이세액표(소득세)와 법정 요율(4대보험)을 상용 조직에 릴리스하기 전에, 시스템 계산값을 공식 계산기(홈택스·공단 모의계산)와 표본 대조하는 절차. 설계 문서 design-statutory-deduction-phase1.md §3 Layer 3(golden 대조)과 §5 릴리스 워크플로의 [검증] 단계를 실행 가능한 형태로 구체화한 것이다.

상태: v1 (2026-08-20). 실행 도구: packages/api/src/scripts/verify-tax-samples.ts · 표본 템플릿: packages/database/data/tax-validation-samples.template.csv.

---

1. 왜 이 절차가 있나

golden test(statutory-formula.golden.test.ts)는 산식·절사·게이트 로직을 검증하지만, 그 기준값은 우리가 만든 것이다. 이 절차는 마지막 남은 두 오류 유형을 잡는다:

1. 변환·적재 오류 — 공식 문서(HWPX/Excel) → CSV → DB로 옮기는 과정에서 값이 틀어지거나 구간이 밀리는 경우. 구조 검증(연속성·단조성)은 통과하면서도 값 자체가 틀릴 수 있다.
2. 규칙 해석 오류 — 절사 방식·소액부징수·자녀 차감 순서 같은 규칙을 우리가 잘못 이해한 경우. 공식 계산기와의 대조만이 이를 드러낸다.

전건 일치가 릴리스 조건이다. 한 건이라도 불일치하면 릴리스하지 않는다 (§7 결정 4의 법적 책임 구조와 직결 — "주의의무 이행 증빙"이기도 하다).

2. 언제 수행하나 (트리거)

트리거	대조 범위
간이세액표 새 버전 적재 (import-simplified-tax-table.ts)	소득세 전 표본
자녀 차감액 등 statutory.income_tax.* 파라미터 개정 릴리스	자녀 관련 표본 + 대표 표본
4대보험 요율/상하한 개정 릴리스 (update-statutory-parameter.ts)	4대보험 표본 (§6)
세액 계산 로직 변경 (tax 모듈·loader)	소득세 전 표본
신규 상용 조직에 최초 적재	대표 표본 5건 이상 (스모크)

3. 공식 대조 도구

항목	도구	경로
소득세·지방소득세	홈택스 근로소득 간이세액표 자동 조회	hometax.go.kr → 세금신고 → 원천세 신고 → 근로소득 간이세액표(조견표) → "월 급여액에서 한 달간 납부하는 세금(간이세액)" 조회
국민연금	국민연금공단 보험료 모의계산	nps.or.kr → 자주 찾는 민원서비스 → 4대보험료 계산
건강보험·장기요양	건보공단 보험료 모의계산	nhis.or.kr → 민원여기요 → 보험료 계산기
고용보험	근로복지공단 / 4대사회보험 정보연계센터 계산기	4insure.or.kr

⚠ 입력 기준을 맞출 것: 홈택스 조회기의 "월급여액"은 비과세 소득을 제외한 금액이다 — 시스템의 과세보수(수당 합산 − 비과세 인정액)와 같은 기준이다. 조회기에 전체(gross)를 넣으면 대조가 어긋난다. 공제대상 가족 수는 본인 포함, 자녀 수 필드는 8세 이상 20세 이하만 센다.

4. 소득세 표본 대조 절차

4-1. 표본 설계 원칙

표본은 "무작위 몇 건"이 아니라 오류가 숨는 경계에 배치한다. 템플릿(23건)의 축:

• 구간 경계: 최저구간 미만(세액 0) · 첫 과세 구간 · 20천원 스텝 경계 직전/직후 · 표 마지막 구간 · 정확히 1,000만 원(전용 행) · 초과 산식 6개 구간 각각 (특히 1,400만 경계 — 가산식이 다음 구간 상수로 이어지는 지점)
• 가족수 축: 1 · 4 · 11(최대)
• 자녀 차감: 자녀 2명을 2026-03 이후 귀속(개정액 45,830)과 2026-02 귀속(구액 29,160) 양쪽으로 — 시행일 버전 선택 검증. 자녀 4명(차감 후 음수 → 0 클램프)
• 비율 선택: 80% · 100% · 120%
• 소액부징수: 세액 1,000원 미만 → 0 경계 부근

4-2. 단계

1. 표본 파일 준비 — 템플릿을 복사한다: cp packages/database/data/tax-validation-samples.template.csv /tmp/tax-samples-$(date +%Y%m%d).csv. 릴리스 대상에 맞게 귀속월·표본을 조정한다.
2. 기대값 기입 (사람) — 각 행을 홈택스 조회기로 조회해 expectedIncomeTax(소득세)와 expectedLocalTax(지방소득세)를 기입한다. 지방소득세를 조회기가 함께 보여주지 않으면 소득세의 10%에서 10원 미만 절사한 값을 기입한다.
   • 홈택스 조회기가 지원하지 않는 케이스(월 1,000만 원 초과 구간 등)는 별표2 하단 산식을 수기로 계산해 기입하고 note에 "수기 산식"을 남긴다.
3. 대조 실행 — 프로덕션과 동일한 조회·계산 경로로 전 표본을 재계산해 비교한다:

   cd packages/api
   npx ts-node -r tsconfig-paths/register --project tsconfig.dev.json \
     src/scripts/verify-tax-samples.ts --org=<조직코드> --file=/tmp/tax-samples-YYYYMMDD.csv

   기대값이 빈 행은 PENDING으로 표시되고(시스템 계산값을 함께 출력하므로 홈택스 조회 시 참고), 전건 일치가 아니면 종료 코드 1이다.
4. 판정 — PASS 23 / FAIL 0 / PENDING 0이면 릴리스 조건 충족. 불일치는 §5의 분류를 따른다.
5. 기록 — 결과 출력과 표본 CSV를 릴리스 기록에 남긴다: 파라미터 릴리스면 해당 버전의 reason에 "표본 대조 N건 통과(YYYY-MM-DD, 수행자)"를 덧붙이고, CSV는 docs/internal/release-validations/ 아래에 날짜 파일명으로 커밋한다. 이것이 §3 Layer 5 audit 패키지의 "검증 이력"이 된다.

5. 불일치가 나오면 — 원인 분류

분류	증상 패턴	조치
변환 오류 (적재 데이터)	특정 구간/가족수에서만 불일치, 인접 구간은 정상	해당 버전 soft-delete → 원본 문서 재파싱 → 재적재 → 전 표본 재대조
산식 오류 (로직)	전 표본이 일정한 방향으로 어긋남 (절사·비율·차감 순서)	tax 모듈 수정 + golden test에 그 케이스 추가 후 재대조
개정 시차	특정 귀속월 이후만 불일치	새 시행일 버전 미적재 여부 확인 — 표/파라미터의 최신 개정을 확인해 적재
입력 기준 불일치	비과세가 큰 표본에서만 어긋남	홈택스 입력이 비과세 제외 금액이었는지 재확인 (시스템 결함 아님)

불일치를 "허용 오차"로 넘기지 않는다 — 원 단위까지 일치해야 한다. 절사 규칙이 다르면 그것이 곧 산식 오류다.

6. 4대보험 표본 대조

요율·상하한 개정 릴리스 시 최소 4건을 공단 계산기와 대조한다 (정률 계산 모드의 검증 — 고지 기반 모드는 §3 Layer 4 고지액 대사가 담당):

표본	검증 포인트
보수월액 300만	대표값 — 4보험 전부
하한 미만 (예: 30만)	국민연금 하한(기준소득월액) 클램프
상한 초과 (예: 700만)	국민연금 상한 클램프
개정 시행일 직전/직후 귀속월 각 1건	시행일 버전 선택

시스템 값은 법정공제 시트에서 읽거나 golden test의 산식으로 재계산한다. 공단 계산기와 절사 단위가 다르게 나오면 §5와 동일하게 산식 오류로 취급한다.

7. 한 장 요약 (체크리스트)

• [ ] 템플릿 복사 → 릴리스 대상에 맞게 표본 조정
• [ ] 홈택스/수기 산식으로 기대값 전 행 기입 (입력 = 비과세 제외 월급여, 가족수 = 본인 포함, 자녀 = 8~20세)
• [ ] verify-tax-samples.ts 실행 → PASS 전건 / 종료 코드 0
• [ ] (요율 개정 시) 4대보험 4표본 공단 계산기 대조
• [ ] 결과 CSV를 docs/internal/release-validations/에 커밋 + 파라미터 릴리스 reason에 대조 이력 기록
• [ ] 불일치 발생 시 릴리스 중단 → §5 분류 → 수정 → 전 표본 재대조