HBHR283_월 마감 공제 요약 리포트

(Hereby) HR 급여 관리 > 시트 워크스페이스 > 법정공제 시트 > 월 마감 공제 요약 리포트

앱	HR 급여 관리 (hr-system, 포트 4000)
대상 사용자	공제 시트 조회·확정 capability 보유자 (실제 RBAC 토큰 TBU — 현행 DEDUCTION_READ/DEDUCTION_MANAGE 계열 추정)
프로토타입	mockup-tax-report-mode.html 장면 ① — HBHR283 월 마감 공제 요약 리포트
관련 정책	[[POL_공제_판정]] · [[POL_공제_계산·확정]] · [[POL_공제_잠정·정산]] · [[POL_공제_요율개정_운영]] · [[POL_공제_경계]] (참조만 — 정의 금지)
Status	draft (콸 리뷰 게이트 — 승격 전 PR 금지)
Owner	카나
부모	[[HBHR280_법정공제 시트 (4대보험·소득세 월별)]]
하위 또는 관련	[[HBHR281_판정 상세·수동 판정 모달]] · [[HBHR282_계산 진단 패널 드로어]] · [[HBAD272_공제 산정 모드]] · [[HBHR290_병행운영 대사 리포트]]

개요

• 📋 제안 — 미구현 기획 화면이다. develop 실측(2026-09-21) 결과 월 마감 공제 요약/리포트/export UI·라우터는 코드에 없다. 법정공제 계산·판정·6종 커밋 PoC(ded_statutory_*, commitToKind="deduction", slug statutory_insurance)만 구현돼 있고, 요약 리포트는 벤더 콘솔용 설계문서(docs/internal/design-system-admin-statutory-monitor.md)에 CSV export 구상으로만 존재한다. 아래 UI 문구·필드는 모두 목업 기준 기획 문구이며 라이브 확정 원문이 아니다.
• 월 마감 공제 요약 리포트는 한 귀속월의 확정(또는 확정 직전) 공제 6종을 한 장으로 집계·점검하고, 시스템 밖으로 내보내는 리포트 화면이다. [[HBHR280_법정공제 시트]]의 6종 커밋 결과(DeductionRecord)를 귀속월·조직 단위로 모아 인원수·항목별 합계·전월 대비 증감·판정 예외·요율 버전·미해소 잔량을 한 화면에 요약한다.
• 두 트랙 공통 부품이다 ([[HBAD272_공제 산정 모드]] 세무 운영 모드와 짝):
  • 트랙 Z (담당자 셀프 확정): 담당자가 셀프 확정 버튼을 누르기 전 최종 점검 리포트로 본다.
  • 트랙 T (세무사 검토 — C안): 세무사에게 넘길 검토 자료의 원본으로 동일 리포트를 재사용한다. CASE04 [C안 확정 (콸 2026-09-21)] — 세무사 검토는 초기엔 시스템 밖 export(PDF/엑셀) 리뷰 루프로 시작하고(계정 방식은 추후), 이 리포트가 그 export의 1급 산출물이다.
• C안(export 리뷰 루프)의 핵심: 리포트는 회신을 받기 위한 문서 양식을 갖춘다 — ①리포트 고유 번호(귀속월+버전, 회신 매칭용) ②항목별 확인 체크 여백·의견 기입란(문서 차원). 세무사 의견이 돌아오면 담당자가 시스템에 기록하고(검토 의견 기록), 수정 요청이면 시트 수정 후 리포트를 재발행(버전 증가)한다 — 발행→검토중→확인됨/수정요청→재발행 상태 흐름을 이 사양이 정의한다.
• 이 리포트가 보증하는 것/않는 것을 고지한다. 리포트는 판정·계산·요율 규칙을 재정의하지 않는다 — 규칙은 위 정책과 [[HBHR280]]을 따른다. 리포트는 커밋된 DeductionRecord와 판정 근거를 집계·표현할 뿐이며, 세무사 검토·전자신고·납부의 법적 책임을 대체하지 않는다(§7 결정 4 법률 검토 대기).

문서 히스토리

날짜	작성자	팀	변경 내용
2026-09-21	카나	PM	최초 작성 (📋 제안 미구현 · develop 실측 기준 · 세무 트랙 Z/T 공통 부품 · C안 확정 반영)

정책 → 로직 → UI 경계

층위	이 문서에서 따르는 내용
정책	전 직원 × 6종 판정·제외 사유 기록, 유효 요율/표 없는 확정 금지, 확정 시 근거 동결, 세무사 검사는 판정표에서 시작 ([[POL_공제_판정]])
비즈니스 로직	귀속월·조직 단위 DeductionRecord 집계, 전월 대비 산출, 판정 예외 추출, 요율 버전 조회, 미해소 잔량 판정, 리포트 버전 채번
UI 로직	집계 카드·항목별 표·예외 목록·요율 버전·경고를 표시하고, export·검토 의견 기록·재발행으로 연결
사양	아래 필드·상태·분기. procedure명·RBAC 토큰·문구 원문은 확인 전 TBU

실제 Hereby 화면 구조 재사용

• [[HBHR280_법정공제 시트]]와 동일하게 시트 워크스페이스 셸([[HBHR100_시트 워크스페이스 (공통 Shell)]])을 재사용한다: 상단 월 선택 툴바 → 좌측 시트 사이드바 → 가운데 콘텐츠 → 우측 레일. 공제 전용 "가공 전용 셸"을 새로 만들지 않는다(실존 화면 재사용 원칙).
• 리포트 본문은 기존 리포트 패턴([[HBHR290_병행운영 대사 리포트]]의 gate-summary 카드 + 집계 표 레이아웃)을 재사용한다 — 상단 요약 카드 밴드 + 항목별 표 + 예외 목록.
• 상태 배지는 기존 .ds-label, 버튼은 기존 ds-btn, 경고 박스는 기존 .ds-notice(--warning/--danger), 툴팁은 기존 DS tooltip을 재사용한다. 새 배지·버튼·테이블 계열을 정의하지 않는다.
• export·재발행 확인은 DS 3종 모달(.ds-dialog 컨펌 / .ds-modal 일반) 중 하나를 쓰고 새 모달 종류를 만들지 않는다.

Data I/O

미구현 기획이라 procedure·파라미터 키는 (추정)/TBU이며 지어내지 않는다. 집계 원천은 [[HBHR280]]이 커밋한 DeductionRecord다.

Server → Client

변수	DB 엔티티.컬럼 / 근거	값 없을 때	비고
${report.month}	귀속월 (year·month)	미선택 시 현재 월 기본	조직·귀속월 단위
${report.no}	리포트 고유 번호 = 귀속월-버전 (예: 2026-08-v2)	최초 발행 전 미부여	회신 매칭용 · 재발행 시 버전 증가
${report.status}	리포트 상태 (발행 전/발행됨/검토중/확인됨/수정요청/재발행)	미발행	저장 원천 키 TBU
${summary.headcount}	대상 재직자 수 (DeductionRecord distinct employeeId)	0	예: 17명
${summary.byItem}	6종 항목별 합계·건수 (amount SUM, COUNT)	항목별 0	6종 = 국민연금·건강보험·장기요양·고용보험·소득세·지방소득세
${summary.prevMonth}	전월 동일 집계 (증감 산출용)	전월 데이터 부재 시 "전월 없음"	증감 = 당월−전월
${exceptions.list}	판정 예외 목록 (제외·수동 판정 + 사유)	Empty	DeductionExclusionReason enum 근거
${rate.versions}	항목별 적용 요율 버전·시행일	부재 시 N/A + 경고	statutory.* 파라미터 스토어 (추정)
${warnings.unresolved}	미해소 잔량 (판정불가·요율 부재·stale·lock 건수)	0이면 "미해소 없음"	커밋 게이트 경고(commitWarnings) 집계
${review.record}	검토 의견 기록 (확인됨/수정요청 + 내용 + 기록자·시각)	미기록 시 hide	C안 회신 수렴 원천 · 키 TBU

Client → Server

액션	전달 값	tRPC procedure	권한 토큰
리포트 조회	year, month	sdk.deduction.summaryReport() (추정 · 미존재) TBU	deduction:read (추정)
PDF export	year, month, reportNo, 검토 여백 포함 여부	sdk.deduction.exportReport() (추정 · 미존재) TBU	deduction:read (추정)
엑셀 export	year, month, reportNo	상동 (format=xlsx) TBU	deduction:read (추정)
리포트 발행 (번호 채번)	year, month	신규 procedure TBU (버전 증가 규칙 포함)	deduction:manage (추정)
검토 의견 기록	reportNo, 결과(확인됨/수정요청), 의견 내용	신규 procedure TBU	deduction:manage (추정)
재발행 (수정 요청 후)	year, month (버전+1)	발행 procedure 재호출 TBU	deduction:manage (추정)

⚠ develop 실측: 현행 코드에는 deduction.review(year, month, employeeId?)(직원 단위 나열)·deduction.list summary({total, pending, approved, applied} 상태 카운트)만 있고, 항목별 집계·전월대비·요율버전·export·리포트 번호·검토 의견 기록 procedure는 전무하다. PDF/xlsx 생성 코드 없음(eCount import 파서는 스텁). 위 procedure명은 전부 신규 제안·추정이다.

외부 통합

외부 시스템	데이터	동기/비동기	비고
세무사 (사람)	export한 PDF/엑셀 리포트 → 검토 회신 (확인/수정 요청)	비동기 (오프라인 루프)	C안 초기 = 시스템 밖 리뷰 루프 (콸 2026-09-21) · 계정 방식(A)은 추후
이카운트	(트랙 T·B안 export 원본이 이카운트 인계 자료와 정합)	비동기	왕복=외부 import 모드 · 파서 완성 전제

---

화면 플로우 (Mermaid)

리포트는 트랙 Z·T 공통. 트랙 T(C안)에선 발행→검토중→확인됨/수정요청→재발행 루프가 상태 흐름으로 돈다. 수정 요청이면 [[HBHR280]] 시트를 고치고 버전을 올려 재발행한다.

---

리포트 상태 흐름 (C안 · 콸 2026-09-21)

상태	진입 조건	표시	다음
STEP1 [발행 전]	조회만, 아직 export/채번 안 함	리포트 미리보기 · "발행" 버튼	발행 → 발행됨
STEP2 [발행됨]	리포트 번호(귀속월-v버전) 채번 + export	번호·발행 시각 표기	트랙 T: 검토중 / 트랙 Z: 확정 진행
STEP3 [검토중]	세무사에게 export 전달 (트랙 T)	"세무사 검토중" 배지	회신 기록 → 확인됨/수정요청
STEP4a [확인됨]	검토 의견 = 확인됨 기록	"확인됨" 배지 + 기록자·시각	셀프/최종 확정 가능
STEP4b [수정요청]	검토 의견 = 수정 요청 + 내용 기록	"수정 요청" 배지 + 의견	시트 수정 → 재발행
STEP5 [재발행]	수정 후 버전+1 발행	새 번호(v+1) · 이전 버전 이력 보존	다시 검토중

상태 전이 시점의 확정 트리거·잠금·감사 계약은 [[HBAD272_공제 산정 모드]] 세무 운영 모드와 정합해야 한다. 상태 저장 원천·전이 procedure는 미구현 TBU.

---

월 마감 공제 요약 리포트 사양표

번호	항목/기능명	타입	사양 및 기능 설명	연관/영향 범위	비고
00	진입 조건	-	• 공제 시트 조회 capability + organization scope 확인 시 진입 　- CASE01 [미보유]: forbidden, 데이터 미노출	RBAC · [[POL_공제_경계]]	📋 제안 미구현
01	초기 상태	Output	• 진입 시 현재(또는 선택) 귀속월의 요약 리포트 로드 　- CASE01 [미선택]: 현재 월 기본 · CASE02 [Empty]: 20-E • 상단에 리포트 번호(발행 시)·상태 배지 표기	${report.month} · ${report.status}	조직·귀속월 단위
10	리포트 헤더	-	• 제목 "월 마감 공제 요약 리포트" (기획 문구) • ㄴ 리포트 번호·귀속월·상태·발행 시각	${report.no}
ㄴ11	리포트 번호	Text	• "리포트 번호: 2026-08-v2" 형식 (귀속월+버전, 기획 문구) • 발행 전엔 "미발행" · 재발행 시 버전 증가	${report.no}	C안 회신 매칭 키
ㄴ12	상태 배지	Badge	• 발행 전/발행됨/검토중/확인됨/수정요청 (리포트 상태 흐름 표) • .ds-label 재사용, 상태별 톤	${report.status}	트랙 T 흐름
20	집계 요약 카드	Grid	• 상단 카드 밴드 — gate-summary 패턴 재사용 　- 대상 직원 수 / 총 공제액 / 판정 예외 건수 / 미해소 잔량 • 예: 직원 17명 · 6종 = 102건 (17×6)	${summary.headcount} · ${summary.byItem}	[[HBHR290]] 카드 패턴
ㄴ20-E	ㄴ Empty	Text	• "이 달에 확정된 공제가 없어요" (기획 문구) • export·발행 버튼 비활성	${summary.byItem} 0건	공제 전용 빈 화면 아님 — 요약만 빈 상태
30	항목별 집계 표	List	• 6종 각 행: 항목명 · 대상 인원 · 합계 금액 · 전월 대비 증감 　- 증감: 당월−전월, +는 증가·−는 감소 (예: 국민연금 +₩85,000) 　- CASE01 [전월 없음]: 증감 "전월 없음" 표기 • tabular-nums 정렬 (금액 열)	${summary.byItem} · ${summary.prevMonth}	6종 앵커 = ded_statutory_*
ㄴ31	ㄴ 항목 행	Cell	• "국민연금 · 17명 · ₩1,530,000 · 전월 대비 +₩85,000" (기획 예시) • 6종: 국민연금·건강보험·장기요양보험·고용보험·소득세·지방소득세	6종 커밋 앵커
40	판정 예외 목록	List	• 제외·수동 판정된 직원·항목을 사유와 함께 나열 　- 제외 사유 = age_60(만 60세)·short_time(초단시간)·new_hire_65(65세 이상 신규)·dual_employment(이중고용)·manual(수동)·other 　- 수동 판정은 사유 필수 표기 → 클릭 시 [[HBHR281_판정 상세·수동 판정 모달]]	${exceptions.list} · DeductionExclusionReason enum ✅	세무사 검사 시작점 (POL_공제_판정 §1)
ㄴ40-E	ㄴ Empty	Text	• "판정 예외가 없어요 (전원 6종 적용)" (기획 문구)	${exceptions.list} 0건
50	요율 버전 표	List	• 항목별 적용 요율·시행일 표기 (예: 국민연금 4.5% / 시행 2026-01-01) 　- CASE01 [요율 부재]: N/A + 경고 (조용한 0 금지)	${rate.versions} · statutory.* 파라미터 (추정)	[[POL_공제_요율개정_운영]] · [[HBAD271_법정 요율 안내]]
60	경고·미해소 잔량	Info	• 판정불가·요율 부재·stale·lock 건수를 .ds-notice --warning/--danger로 요약 　- CASE01 [잔량 0]: "미해소 없음" success 톤 　- CASE02 [잔량 있음]: 건수 + [[HBHR282_계산 진단 패널 드로어]] 진입 링크	${warnings.unresolved} · commitWarnings	미해소 시 확정·발행 제약(TBU)
70	보증 고지	Info	• "이 리포트가 보증하는 것 / 않는 것" 고지 박스 (.ds-notice --info, 기획 문구) 　- 보증: 커밋된 공제 6종 집계·판정 근거 표현 　- 미보증: 세무사 검토·전자신고·납부의 법적 책임 대체 아님, 요율·판정 규칙 재정의 아님	[[POL_공제_경계]] · §7 결정 4	🔴 법적 책임 경계 = 법률 검토 대기
80	export (PDF/엑셀)	Button	• "PDF로 내보내기" / "엑셀로 내보내기" (기획 문구) • 클릭 → export 확인 모달(.ds-dialog) → 파일 생성·다운로드 　- C안: PDF에 항목별 확인 체크 여백·의견 기입란 포함 옵션 (문서 양식 차원) 　- CASE01 [Empty]: 비활성 · CASE02 [실패]: 에러 토스트·재시도 (동선 TBU)	sdk.deduction.exportReport() (추정)	🔴 PDF/xlsx 생성 코드 미존재
90	발행	Button	• "리포트 발행" (기획 문구) — 리포트 번호 채번(귀속월-v버전) • 클릭 → 상태 발행됨 전이 · export 동반 　- CASE01 [재발행]: 수정 요청 후 클릭 시 버전+1, 이전 버전 이력 보존	${report.no} · 발행 procedure (추정)	C안 상태 흐름 STEP2/STEP5
A0	검토 의견 기록	Button	• "검토 의견 기록" (기획 문구) — 세무사 회신을 시스템에 기록 • 클릭 → 기록 모달(.ds-modal): 결과 라디오(확인됨 / 수정 요청) + 의견 내용 입력 　- CASE01 [확인됨]: 상태 확인됨 전이 → 확정 가능 　- CASE02 [수정 요청]: 의견 필수 입력 → 상태 수정요청 → 시트 수정 유도	${review.record} · 기록 procedure (추정)	C안 회신 수렴 동선 (신설)
B0	확정 연계	-	• 상태=확인됨(트랙 T) 또는 최종 점검 완료(트랙 Z) 시 확정 플로우로 연계 • 확정 버튼·검토 태그 규칙은 [[HBAD272_공제 산정 모드]] 세무 운영 모드에 정의	[[HBAD272]] · [[HBHR280]] 커밋	모드별 확정 차이
C0	에러·실패	-	• 집계 조회 실패 시 원인코드·재시도 (조용한 0 금지) • export·발행·기록 실패 = 에러 피드백 (동선 TBU)	-	미구현 TBU
D0	권한별 차이	-	• 조회 capability 없거나 다른 조직: forbidden • 발행·검토 의견 기록·재발행은 deduction:manage(추정) 필요 　- 세무사 역할 노출 여부 = TBU (C안 초기엔 시스템 밖)	RBAC · [[POL_공제_경계]]	권한 분기 TBU

export 문서 양식 표 — C안 회신용 (기획 문구·목업 기준)

구성	PDF	엑셀	근거
리포트 번호 (귀속월-v버전)	표지·머리말	첫 시트 상단	회신 매칭 키
집계 요약 (인원·항목별·증감)	요약 표	집계 시트	30·20 재현
판정 예외 목록 (사유)	예외 표	예외 시트	40 재현
요율 버전	각주·표	메타 시트	50 재현
항목별 확인 체크 여백	각 항목 우측 체크 칸	확인 열(빈칸)	C안 회신용 (문서 차원)
의견 기입란	하단 자유 기입 영역	의견 열·시트	C안 회신용 (문서 차원)
보증 고지	하단 고지문	안내 시트	70 재현

C안 확정 (콸 2026-09-21): 세무사 검토는 초기엔 시스템 밖 export 리뷰 루프로 시작한다. export 형식에 확인 체크·의견 기입란을 두어 회신을 받고, 회신은 「검토 의견 기록」(A0)으로 시스템에 수렴한다. 계정 방식(A)은 추후 전환.

---

검토 의견 기록 모달 사양표 (C안 · 신설)

번호	항목/기능명	타입	사양 및 기능 설명	연관/영향 범위	비고
00	노출 조건	-	• 리포트 A0 "검토 의견 기록" 클릭 시 노출 (상태=검토중일 때 주로) • .ds-modal 일반 모달 재사용	[[HBHR283]] A0	새 모달 종류 금지
10	제목	Text	• "검토 의견 기록" + 대상 리포트 번호 표기 (기획 문구)	${report.no}
20	결과 선택	Radio	• "확인됨" / "수정 요청" 2지 라디오 (기획 문구) 　- CASE01 [확인됨]: 의견 선택 입력 　- CASE02 [수정 요청]: 의견 필수 입력 (미입력 시 저장 차단)	${review.record} 결과
30	의견 내용	Input Box	• 자유 입력 텍스트영역, 라벨 "세무사 의견" (기획 문구) • 수정 요청 시 필수 · 확인됨 시 선택	${review.record} 내용
40	저장	Button	• "기록" 클릭 → 상태 전이(확인됨/수정요청) + 기록자·시각 저장 　- CASE01 [수정요청]: 저장 후 [[HBHR280]] 시트 수정 유도 안내 　- CASE02 [실패]: 에러 피드백 (동선 TBU)	기록 procedure (추정)	감사 로그 대상(TBU)
50	취소	Button	• "취소"·X·백드롭 클릭으로 닫기 (DS 모달 공통)	-

---

공통 상태

상태	표시·행동
loading	리포트 집계 중 로딩 표시; export/발행/기록 비활성
empty	대상 6종 커밋 0건 안내(20-E); export·발행 비활성
success	발행/재발행/기록 성공 피드백 (번호·버전·시각)
error	원인코드·재시도 경로; 조용한 0 금지
forbidden	capability/organization scope 불충족, 데이터 미노출
stale	상류 판정·요율·수당 변경 시 "재집계 필요" 표시, 재발행 유도
locked	급여 마감·외부 잠금 시 발행/재발행 차단, 잠금 주체·시각 표시

권한 요청 / 분기 요약

시나리오	트리거	결과 화면	비고
CASE01 [조회 진입]	조회 capability + org scope	요약 리포트 표시	기본
CASE02 [Empty]	대상 6종 커밋 0건	20-E 빈 상태	export/발행 비활성
CASE03 [트랙 Z]	셀프 확정 모드 조직	최종 점검 → 담당자 확정	[[HBAD272]] Z
CASE04 [트랙 T · C안 확정 (콸 2026-09-21)]	세무사 검토 모드 조직	export → 검토중 → 확인됨/수정요청 → 재발행	시스템 밖 리뷰 루프 · 계정 방식(A) 추후
CASE05 [미해소 잔량]	판정불가·요율 부재·stale·lock	경고 배너 + HBHR282 진단	확정·발행 제약(TBU)

미결 제안 — 현재 구현 아님

• 요약 리포트 집계 procedure 신설: 항목별 SUM·COUNT·전월 대비·요율 버전·미해소 잔량을 한 응답으로 주는 procedure(현행 deduction.review는 직원 단위 나열, deduction.list summary는 상태 카운트만). TBU.
• PDF/엑셀 export 엔진: 현재 코드에 생성기 없음. 문서 양식(확인 체크·의견 기입란)·리포트 번호 표기·다운로드 동선 TBU.
• 리포트 번호 채번·버전 관리: 귀속월+버전 스킴, 재발행 시 버전 증가·이전 버전 이력 보존 저장 계약 TBU.
• 검토 의견 기록·상태 저장: 발행→검토중→확인됨/수정요청→재발행 상태 원천·전이 procedure·감사 계약 TBU.
• 미해소 잔량이 발행·확정을 막는 수준: 경고인지 차단인지, 예외 권한 TBU ([[POL_공제_계산·확정]] 미결).

Open Question

• 리포트 상태와 [[HBAD272]] 세무 운영 모드(Z/T)·[[HBHR280]] 커밋 확정 상태의 정합 — 확정 전/후 리포트 재발행 허용 범위.
• 트랙 T에서 세무사 회신 전 담당자가 확정할 수 있는지, "확인됨" 태그가 확정의 게이트인지.
• export 문서 양식의 확인 체크·의견 기입란이 회신 후 시스템 기록(A0)과 어떻게 매칭되는지(수기 대조 vs 번호 기반).
• 0원 제외 항목의 리포트 표기(집계 0으로 표시 vs 예외 목록으로만) — [[HBHR280]] Open Question과 연동.
• 실제 RBAC 토큰(deduction:read/manage 추정)·procedure 공개 API 명칭·UI 원문.