법정공제 계산과 반영 검증

제품 개발 기록 · 급여 시트 · 인사·근로계약 · 급여 확정·배포

템플릿·계산기·API를 연결한 공제 입력·계산·저장 안내입니다. 계산·법령 대조·상용 조직 반영은 실행 검증하지 않았습니다. 저장된 요율이나 개별 조직의 법정 신고 정확성을 검증한 자료는 아닙니다.

대상·준비와 진입

급여 담당자가 보험료와 소득세를 계산하고 급여대장에 공제로 반영하는 기능입니다. /admin/#embed/sheets 또는 HR 앱 /hr-system/sheets에서 귀속월을 고릅니다. 급여 읽기/관리 권한과 같은 조직의 직원·근로계약, 수당 원천, 급여대장, 조직별 상수 및 간이세액표가 필요합니다. 상수 목록은 설정 읽기, 변경은 설정 관리 계열 권한을 별도로 검사합니다.

1. 새 시트 만들기 > 추천 템플릿에서 법정공제 — 4대보험 (월별)을 적용합니다. 이름은 4대보험이지만 현재 템플릿에는 국민연금·건강보험·장기요양·고용보험·소득세·지방소득세가 포함됩니다. 산재보험의 사업주 부담을 직원 공제 열로 제공하는 템플릿은 아닙니다.
2. 귀속월과 급여대장 연결을 확인하고 설정 완료합니다. 직원 행은 원천 직원 정보로 구성됩니다. 해당 월 입사/퇴사 범위와 비활성 상태 필터가 있으므로 조직 전체 직원 수와 항상 같지 않습니다.
3. 계약급여내역, 연장근무·인센티브 등 수당 시트부터 급여대장에 반영합니다. 계약 화면의 기본급이 보이는 것만으로 이 월의 보험료 기초가 준비된 것은 아닙니다.

지원 작업과 입력

작업	입력·기본값	저장/영향
직원별 자동 판정 확인	생년월일, 입사일, 주 소정근로시간, 귀속월/퇴사일	판정 근거를 원천에서 읽어 계산
수동 판정	미선택=자동; 1 강제 적용 (자동 판정 무시), 2 제외 — 이중근로 부사업장, 3 제외 — 기타	해당 시트 셀에 수동 결정 저장; 사유 메모 필요
가족·자녀·원천징수비율 입력	부양가족수(본인포함), 8~20세 자녀수, 원천징수비율(%)	소득세 계산 입력 셀
계산 실행/재실행	데이터 > 계산 실행	서버 계산 셀, 입력 스냅샷
공제 반영	급여대장에 반영	공제 레코드와 적용 파라미터/제외 사유·잠정 상태
기초/미계산 오류 보정	원천 반영, 직원 정보·기준 자료 보완 후 재시도	기존 출력 삭제 전에 검사
경고 확인/취소/행 이동	이대로 반영·해당 행 보기·Esc	승인한 경고가 있는 반영 또는 취소
요율·단가 관리	수식 편집기 상수 > 관리	조직 상수와 버전 기록
결과·명세서 확인	급여대장·셀 상세·직원 앱	급여 확정·배포로 연결

자동 판단은 생년월일/입사일/주 소정근로시간으로 판정 불가, 연령, 초단시간, 60세 도달, 65세 이후 입사, 보험별 제외를 계산합니다. 수동 판정은 자동 사유보다 우선합니다. 기본급 (참고)는 설명용 원천이며 보험료 기초의 대체값이 아닙니다.

소득세 로더의 미입력 기본값은 부양가족 1명, 비율 100%, 자녀 0명입니다. 가족 수는 반올림 후 1~11 범위, 자녀 수는 반올림 후 0 이상으로 처리됩니다. UI의 숫자 입력과 실제 정규화가 다르므로 예를 들어 가족 수 1.5를 넣어도 “1.5명 그대로” 계산하지 않습니다. 정상 운영에서는 정수 인원과 선택 의도에 맞는 비율을 입력합니다. 현재 모듈은 80/100/120만 허용하는 선택값 검사를 하지 않고 입력 숫자를 사용하며 0은 100으로 대체합니다. 80/100/120 외 값과 0 입력의 실제 결과는 운영 전에 확인할 항목입니다.

월 계산과 기초의 연결

1. 급여대장에서 수당이 반영된 것을 확인합니다. 보험료 시트의 insurableBase는 [payroll_ledger:insurable_gross]를 읽습니다. 기초가 비거나 0 이하이면 반영을 막습니다. 기본급을 대신 사용하는 과거 fallback은 현재 템플릿에 없습니다.
2. 보험료 열의 기초/제외 표시를 확인합니다. 국민연금은 조직에 저장된 기준소득 하한·상한을 적용한 기초와 근로자 요율, 건강보험은 기초와 요율, 장기요양은 근로자 건강보험료와 추가 요율, 고용보험은 기초와 근로자 요율을 참조합니다. 반올림·절사 방식은 저장된 수식과 모듈에 따릅니다.
3. 소득세 입력을 채우고 데이터 > 계산 실행합니다. 소득세는 보험료 셀을 직접 읽지 않고 그 달 반영된 수당 금액에서 각 레코드의 비과세 인정액을 차감해 합산합니다. 가족 수와 귀속월 말 이전 최신 시행일의 간이세액표를 조회하고 고액 구간은 모듈 산식을 사용합니다.
4. 가족 수·자녀 수·비율 또는 수당을 바꿨다면 다시 계산하고 소득세·지방소득세의 값과 급여 기초를 확인합니다. 간이세액표 버전/구간이 없으면 빈 셀로 남을 수 있으며 0원과 구별해야 합니다. 자녀 차감 파라미터가 없을 때 로더는 경고를 남기고 차감 없이 계산하는 경로가 있어 “숫자가 나왔으니 기준 자료 완비”라고 판단할 수 없습니다.
5. 수식 값은 바뀌었지만 장부에는 이전 반영 출력이 남아 있을 수 있습니다. 금액을 장부에 기록하려면 다음 반영 절차를 수행합니다. 급여 확정은 그 이후 별도 작업입니다.

반영과 오류·경고 처리

1. 급여대장에 반영을 누르고 기존 레코드 교체 안내를 확인합니다.
2. 기초 누락이면 수당 시트를 먼저 반영합니다. 수동 판정 사유 누락이면 해당 판정 셀의 우클릭 메모에 사유를 적습니다. 예: “이중근로 확인 자료에 따라 이 조직에서는 제외 처리함.” 삭제되지 않은 그 셀의 메모가 필요하며 다른 열의 메모로 충족되지 않습니다.
3. 판정 불가 경고는 직원의 생년월일·입사일·주 소정근로시간을 보완하거나 수동 판단을 남길 수 있습니다. 해당 행 보기를 누르면 첫 대상 직원 행으로 이동해 강조합니다. 이대로 반영을 선택하면 경고 수락을 붙여 다시 요청합니다. Esc는 진행하지 않습니다.
4. 필수 계산 열이 빈 경우에는 “계산되지 않은 항목이 있어 반영할 수 없어요”와 열별 행 수가 표시됩니다. 소득세·지방소득세가 전부 비었으면 간이세액표 및 입력/계산 실행을 점검합니다. 계산 결과 0은 유효값이므로 누락과 다릅니다.
5. 검사를 통과하면 서버는 해당 원천 시트가 만든 기존 수당/공제 출력을 소프트 삭제하고 현재 결과를 새 레코드로 기록합니다. 응답에는 호환성을 위한 갱신 카운트가 있지만 현재 교체 방식의 갱신 값은 0이며 신규 삽입으로 집계합니다. 직원이 연결되지 않거나 비필수 금액이 비면 건너뛴 건수를 확인해야 합니다.
6. 결과 요약 뒤 급여대장을 다시 열어 공제 열과 합계를 확인합니다. 다음 번 반영은 당시 계산값으로 출력을 다시 만듭니다. 과거 확정 명세서 스냅샷까지 자동으로 재확정하는 절차는 아닙니다.

급여 담당자의 공제 반영 안내 화면입니다. 위 3번 절차의 「해당 행 보기」와 「이대로 반영」 버튼 위치를 보여 줍니다. 화면의 상태와 수치는 예시이며 공제 계산의 정확성을 검증한 결과는 아닙니다.

상수와 기준 자료 운영

1. 수식 편집기의 상수 영역에서 관리를 엽니다. 상수는 namespace+key로 찾습니다. 기존 값·단위·설명을 확인하고 변경 사유와 새 값을 입력한 뒤 해당 행 저장을 누릅니다.
2. 신규 상수는 namespace·key·이름·값을 입력하고 단위를 필요하면 지정합니다. 중복 식별자, 허용 문자/길이, 값 타입 불일치는 서버가 거부합니다. 예시 식별자 $급여.최저시급과 statutory.*는 실제 조직 카탈로그 존재 여부를 확인해야 합니다.
3. 저장은 OrganizationParameter의 현재값과 OrganizationParameterVersion을 남깁니다. 귀속월 계산은 해당 기간에 유효한 버전을 읽고 반영 레코드의 appliedParameters에도 사용값을 보존합니다. 현재 UI에는 과거 시행일을 따로 선택하는 입력이 없으므로 현시점 값 변경을 과거월 개정 작업과 혼동하지 않습니다.
4. 법정 상수 개정은 운영 스크립트 update-statutory-parameter.ts, 세액표 적재는 import-simplified-tax-table.ts가 담당합니다. 이 문서 작업에서는 실행하지 않았습니다. 조직·시행일·표 버전을 지정한 뒤 릴리스 대조 절차를 수행하고 결과를 남겨야 해당 개정의 검증 근거가 됩니다.

단일 계산 시트는 귀속월의 요율과 입력으로 만든 잠정액을 표시합니다. 실제 신고 고지액 대사·연말/퇴직 정산의 모든 항목이 자동 완료되는 것으로 해석하지 않습니다. 설계와 법률 검토 질문에 적힌 후속 단계/검토 사항도 구분합니다.

잠정액과 직원 명세서

공제 출력의 settlementState: provisional은 확정/지급 상태와 별도입니다. 급여를 확정해도 법정공제의 정산 필요성이 사라지지 않습니다. 직원 앱이 공제 레코드에서 잠정 상태를 받으면 “4대보험·소득세는 잠정액이에요. 연말정산·퇴직정산에서 다시 계산해 차액을 정산해요.” 안내를 표시합니다. 공개·본인 확인·인쇄는 급여 배포 절차를 사용합니다.

직원 명세서의 잠정 안내 위치입니다. 「작성중」 상태와 공제 항목·금액은 예시이며 공제 계산의 정확성이나 완료 상태를 설명하는 이미지는 아닙니다.

소스·변경 이력·검증 공백

확인한 소스	역할
시드 템플릿	법정공제 열, 자동/수동 판단, 반영 대상, 차단·경고·사유·잠정 설정
워크북 반영, SheetViewService	확인/행 이동/재요청과 typed API 연결
계산·반영 서버, 소득세 모듈	과세소득 합산·표 버전/구간 조회·계산·출력 교체
상수 API, 스키마	권한·키/값 검증·버전 기록
공제 엔티티, 법정공제 수식 golden 테스트	계보·판정·잠정 상태, 경계값 회귀 사례. 이번 실행 결과 아님

계산 엔진의 “기초가 없으면 계약 기본급”은 게이트에서 제거된 과거 동작입니다. 기존 한국 급여 안내의 고정 요율·누진세 설명을 이 시트의 현재 세액표·유효 버전과 동일하게 읽지 않습니다. 시드 설명의 PoC/미지원 문구도 실행 산식의 구현 시점과 다를 수 있으므로 이 문서는 열 정의와 실제 loader를 기준으로 작성했습니다.

검증 공백: 현재 조직의 상수/표 적재 여부, 시행일 전후/상하한/인원/비율/비과세 한도·고액구간, 단시간/60·65세/입퇴사 경계, 수동 판단 사유와 경고 취소 후 기존 장부 보존, 전 직원 빈 소득세 차단, 반영 재실행 후 중복 여부를 새로 실행하지 않았습니다. 공식 계산기 표본 대조·신고 고지액 대사·잠정액 정산 완료도 확인하지 않았습니다. 현재 화면에서 입력→경고→행 보완→반영→대장→직원 명세서로 이어지는 번호별 캡처와 실제 금액/API 재조회가 다음 증거입니다.