HBHR000_HR 급여 관리 (앱 개요)

(Hereby) HR 급여 관리 > 앱 개요

프로토타입	TBU
Status	review
Owner	카나 (PM)

개요

HR 급여 관리는 월 단위 스프레드시트 워크스페이스다. 모든 HR 데이터가 "시트(Sheet) 오브젝트" 단위로 폴더 분류·관리되며, 컬럼이 엔티티 필드/계산기(Calculator)에 바인딩되고 전체 확정(commit) 시점에 급여 정본 레코드/원장으로 변환된다. 핵심 경계: Sheet(작업공간) → Commit → Ledger(정본) — AI는 Sheet/preview/preflight까지만 관여하고, commit·Ledger 변경은 항상 사람이 실행한다 ([[POL_급여정본경계]]).

문서 히스토리

날짜	작성자	팀	변경 내용
2026-07-06	카나	PM	최초 작성
2026-07-10	카나	PM	라이브 기능 검토 반영
2026-07-21	카나	PM	GC700 깊이 재작성
2026-07-21	카나	PM	가독성 패스 + 액션 표기 (GUIDE §7·§8)
2026-07-21	카나	PM	셀 스타일 확정판 적용 (콸 승인)
2026-07-21	카나	PM	TC 크로스체크 확정분 반영 (🟡)
2026-10-01	카나	PM	메뉴바 「정산 진행」 드로어(정산 7단계·다음 할 일·이상치, AI 없이 — payrollCycle.status/anomalies)(a8ff8fa1, #884)·이카운트 내보내기 스탬프로 ⑦ 단계 판정(ee1d73d4, #885) 개요 반영 — 드로어 전용 사양서 미작성(신규 화면 후보), 커밋 근거 + 단계 탭 라이브 실측(dev 9월: 1/7 완료·남은 5·다음 할 일 카드 원문, 스샷 live-1001-hbhr100-payroll-cycle.png / 이상치 탭 실사 이월 TBU)
2026-10-02	카나	PM	정산 진행 ① 원천 입력 판정 변경 — 행 없는 자동 채움 시트를 막힘으로 보지 않음(ㄴ56, 74e6735e, #986, MED-849) — 커밋 근거, 라이브 실사 이월(TBU)

Data I/O

Server → Client

변수	DB 엔티티.컬럼	값 없을 때	비고
$	인증 세션 (HR_ADMIN / SUPER_ADMIN)	없으면 /hr-system/signin 리다이렉트	진입 게이트
$	조회 월 (YYYY-MM)	기본 당월	상단 Month/Year 스피너
$	PayrollSheet.folder (추정)	"(미분류)" fallback	폴더별 시트 그룹
$	PayrollSheet[] (추정)	"이 기간에 시트가 없습니다"	해당 월 시트 목록 (sheet_views[])
$	PayrollRecord[] (추정)	빈 그리드	"293/293건" 형태 카운트

Client → Server

액션	전달 값	tRPC / SDK	권한 토큰
시트 생성	name, folder, isPublic, template	sdk.payrollSheet.create() (추정)	payroll:write (추정)
셀 편집	rowId, columnId, value	sdk.payrollSheet.updateCell() (추정)	payroll:write (추정)
직원(행) 추가	employeeId[]	sdk.payrollSheet.addRows() (추정)	payroll:write (추정)
전체 확정(commit)	sheetId	sdk.payroll.commit() (추정)	payroll:confirm (추정)
정산 진행 판정	year, month (+ratio, absolute)	sdk.trpc.payrollCycle.status() / .anomalies() — 시트 AI 정산 도구(getPayrollCycleStatus)와 같은 판정 함수	payroll:read
이카운트 export	year, month	payroll.exportEcount() → 대상 기록 exportedAt·exportedBy 스탬프 ([[HBHR270_전자서명 발송·eCount 연동 시트 (2섹션)]])	payroll:confirm (추정)

외부 통합 (cross-app)

외부 시스템	데이터	동기/비동기	비고
Module Manager (HBMM)	컬럼 ƒ수식 ↔ calculator output key 참조	동기	9 calculator
Time Management (HBTM)	연장/야간/휴일 근무 → overtime_record source (추정)	TBU	근태 source
알림/발송 (HBNS)	임금명세서 전자서명 발송 연계	비동기	동선 TBU
Medical (HBMD)	치료일 인센티브 · fixed_incentive taxonomy source	TBU
이카운트(eCount)	코드/부서코드/사원명/금액 export	비동기

앱 전체 플로우 (Sheet → Commit → Ledger)

확정(commit)은 정본 생성 경계 — destructive. AI/검증은 모달 직전까지만, 실행은 사람.

앱 개요 사양표

번호	항목/기능명	타입	사양 및 기능 설명	연관/영향 범위	비고
00	화면 진입 조건	-	• 조건1 [HR_ADMIN] / 조건2 [SUPER_ADMIN] 인증 시에만 화면을 노출하는 진입 게이트 • 진입 시: 인증 세션 확인 후 워크스페이스 진입 　- CASE01 [미인증]: /hr-system/signin 리다이렉트	인증 세션	진입 게이트
01	초기 상태	-	• 진입 직후 최근 작업 시트로 자동 이동시키는 기능 • 진입 시: /sheets/{id}로 자동 리다이렉트 　- CASE01 [최근 시트 없음]: 동선 미확정	[[HBHR100_시트 워크스페이스 (공통 Shell)]]	TBU: 최근 시트 없을 때 진입 동선
10	글로벌 헤더	-	• 좌측 "hereby HR 급여 관리" 로고, 우측 계정·알림·로그아웃을 담는 전 화면 고정 헤더	—	전 화면 고정
ㄴ11	계정	Button	• 로그인 계정 ID를 표시하는 헤더 버튼 • 클릭 → TBU	—	TBU: 표시 값·클릭 동작
ㄴ12	알림	Button	• "알림"을 표시하는 헤더 버튼 • 클릭 → TBU	HBNS 연계 (추정)	TBU: 상세 동작
ㄴ13	로그아웃	Button	• 현재 세션을 종료하는 헤더 버튼 • 클릭 시: 세션 종료 후 /hr-system/signin (추정)	00 진입 조건
20	기간 네비게이터	-	• "이전 달" / Month·Year 스피너 / "다음 달" / "이번 달" 빠른 이동으로 조회 월을 바꾸는 기능 • 이동 시: period 변경 → 시트 리스트 재로드 　- CASE01 [period 값 없음]: 당월 기본	period 변경 시 시트 리스트 재로드	월 단위
30	좌측 사이드바	-	• "폴더" / "휴지통(🗑)" 탭, "▸▾" 접기, 시트 항목 "{이름} '26.7" + 건수를 담는 사이드바. 폴더 상단에 "폴더 관리" 액션 노출(7/21 신규)	[[HBHR108_폴더·휴지통 사이드바]]	상세 위임
ㄴ31	폴더 트리	List	• 폴더 10종((미분류) / eCount 연동 / 급여대장 / 문서·서명 / 병동 / 시트 에러 발생 케이스 / 연장근무 / 인센티브 / 출퇴근 / 치료실 인센티브 / 휴직·퇴사)을 나열하는 트리 • 클릭 시: 해당 시트 로드 　- CASE01 [폴더 없음]: "(미분류)" fallback 　- Empty: [[HBHR100_시트 워크스페이스 (공통 Shell)]] 참조	해당 시트 로드	"그룹"→"폴더" 용어 확정
40	스프레드시트 워크스페이스	-	• 파일/편집/보기/삽입/데이터 툴바 + 데이터 그리드로 구성된 Excel-like 워크스페이스. Shell 골격은 [[HBHR100_시트 워크스페이스 (공통 Shell)]], 시트 유형별 사양은 개별 화면 참조	[[HBHR100_시트 워크스페이스 (공통 Shell)]] / HBHR200~270	Excel-like
50	화면 목록 (I.A.)	-	• HBHR100 시트 워크스페이스(공통 Shell) 하위에 HBHR101~109 및 HBHR200~270 시트 유형 화면을 배치하는 정보구조	앱 하위 화면	트리 [[HBHR100_시트 워크스페이스 (공통 Shell)]]
55	정산 진행 드로어	Drawer	• 시트 메뉴바 "정산 진행"(히스토리 옆, 시트 열림 시 노출) 클릭 → 오른쪽 레일 드로어(다른 레일 드로어와 상호 배제). 사이드바 연·월 기준으로 급여 정산 7단계(원천 입력 → 시트 설정 → 계산 실행 → 급여 반영 → 급여대장 집계 → 급여 확정 → 명세서 발송·이카운트 내보내기) 진행을 AI 없이 표시 　- 탭 "단계": 요약 · "남은 단계 {n}개"(0이면 "이 기간의 정산 단계가 모두 끝났어요.") · "다음 할 일" 최대 3개 · "7단계" 전체(상태 "완료"/"일부"/"할 일"/"해당 없음"/"확인 불가") 　- 실측 원문(2026-10-01 dev, 9월): 드로어 헤더 "정산 진행 / 2026년 9월" + 새로고침·닫기. 요약 "2026년 9월 정산: 7단계 중 1단계 완료. 다음은 2. 시트 설정." · "남은 단계 5개". 다음 할 일 카드 — "2. 시트 설정" "설정 중인 시트: 「[QA] 권한참조 원본」·「[QA] 권한참조 수식」." + "설정 중인 시트는 툴바 「설정 완료」를 눌러야 실무자가 값을 넣을 수 있습니다." / "4. 급여 반영(커밋)" "아직 반영하지 않은 시트: 「법정공제 — 4대보험 (월별)」" + "소스 시트 툴바 「급여대장에 반영」, 또는 급여대장 툴바 「소스 전체 반영」으로 수당·공제 레코드를 만듭니다." / "5. 급여대장 집계" "이 기간에 급여대장(집계 열이 있는 시트)이 없습니다." + "급여대장의 집계 열은 반영된 레코드를 자동 합산합니다. 급여대장이 없으면 「새 시트 만들기 › 추천 템플릿」에서 급여대장을 적용합니다." — 각 카드에 걸린 시트 chip 버튼. 7단계 목록 "1 원천 입력 [확인 불가]"부터 수직 나열. 메뉴바 "정산 진행" 옆 배지 "5" 　- 탭 "이상치": "전월 대비 급변" / "퇴직자 금액" / "반영 열 공란" / "반영 뒤 변경" 건수·목록(0건 "확인할 이상치가 없어요.") 　- 걸린 시트 버튼 클릭 → 그 시트 열기(실행은 시트 툴바 기존 버튼). 드로어를 한 번 연 뒤 메뉴바 버튼에 남은 단계 수 배지	payrollCycle.status/anomalies (payroll:read) · [[HBHR100_시트 워크스페이스 (공통 Shell)]]	신설 (코드 반영: a8ff8fa1, #884, MED-179) · ⑦ 판정 이카운트 스탬프(ee1d73d4, #885) · 전용 사양서 미작성(신규 화면 후보) · 라이브 실사 2026-10-01 확인(단계 탭·스샷 live-1001-hbhr100-payroll-cycle.png) · TBU: 이상치 탭 실사 이월
ㄴ56	① 원천 입력 판정	Rule	• 자동 채움 시트가 1장 이상이면 ① = "완료" — 행 0건 시트(예: 연장근무 없는 달의 「연장근무 내역 전체」)도 막지 않음(종전 "할 일"/"일부"로 남아 「다음 할 일」 맨 위 고정되던 결함) 　- CASE01 [빈 자동 채움 시트 있음]: 상세(원문) "자동 채움 시트 {N}장 중 원천 기록이 없는 시트: {시트명}. 그달에 기록이 없으면 그대로 진행해도 됩니다. 뒤늦게 입력했다면 「데이터 ▾ › 새로고침 (자동 채움)」 으로 가져옵니다." + 시트 chip 사유 "원천 기록 없음 — 비어 있어도 진행 가능" 　- CASE02 [자동 채움 시트 없음]: "확인 불가"(종전 동일)	payrollCycle.status · 시트 AI 정산 도구(같은 규칙 안내)	판정 변경 (코드 반영: 74e6735e, #986, MED-849) · 드로어 UI 자체는 변경 없음(서버 판정·문구만) · TBU: 라이브 실사 이월
60	cross-app 연결	-	• HBMM(calculator) · HBTM(근태 source) · HBNS(명세서 발송) · HBMD(치료 인센티브) · eCount(export) 연동 지점	Data I/O 외부 통합 참조

AI 접점 요약

앱 전반의 AI 진입 표면은 시트 컬럼 수식(ƒ) = 자연어 진입점이며, backbone은 Module Manager Calculator Registry의 outputKeys + parameterSchema + sourceTables + targetTables다. 핵심 룰: AI는 Sheet / preview / preflight까지만 관여, commit·PayrollLedger 변경은 항상 사람이 실행.

AI Skill	트리거 위치	동작	안전 경계	우선도
formulaFromNL	컬럼 ƒ 수식 (HBHR200)	자연어 → 컬럼 수식/계산기 바인딩 제안 (자동 삽입 X)	Sheet 단계, commit 무관	★★★★★
recalcExplain	재계산 diff 뷰 (HBHR203)	변경 전/후 차액에 "왜 변동됐는지" 자연어 설명 부착	읽기 전용	★★★★★
commit preflight	전체 확정 직전 (HBHR201)	음수/±3σ 이상치/4대보험 config "미사용" 검증 후 경고	확정 차단·경고만, 실행은 사람	★★★★☆

권한 / 상태 요약

시나리오	트리거	결과	비고
CASE01 [미인증 진입]	/hr-system 직접	/hr-system/signin 리다이렉트
CASE02 [HR_ADMIN 진입]	인증 세션	최근 시트 /sheets/
CASE03 [전체 확정]	"전체 확정" 클릭 → 확인	정본 레코드/원장 생성	payroll:confirm (추정)

알려진 버그 후보 (노션 등록)

ID	위치	증상	상태
BL-001	[[HBHR106_데이터 메뉴]]	"승인 행 모두 지급 처리" 클릭 시 카운트·상태 불변, 에러 피드백 부재 — 무음 실패	노션 등록됨
BL-002	[[HBHR109_행 정보 패널·검색]]	급여명세서 실수령액 0원 행에서 "직원에게 발송" 클릭 시 무반응(성공/실패 피드백 부재)	노션 등록됨

Open Question

• 직원 마스터 시트 전용 사양서 미작성 — 「마스터에 적용」 개선(서식만 입힌 셀을 값으로 오인해 입사일을 지우던 결함 수정 + 반영 못 한 셀 있으면 결과 창 「리포트 보내기」 버튼 — 8ced12cd, #880, CS-OKBEST-260923-0008) 반영 대기 · 시스템 기록 픽커 개편(10/15 머지, 85e65fe #1249): 소스 테이블 첫 항목 「직원 마스터 — 근로자 정보」 명명 + 참조할 필드를 카탈로그 그룹(기본·근무·개인정보…)별 optgroup으로 묶음 — 반영 대기 누적 · 신규 화면 후보
• 급여 항목 컬럼 전체 목록 (기본급/수당/공제/실수령) = TBU
• 임금명세서 발급 동선 (HBNS 연계) = TBU
• 권한 토큰 실제 키 (payroll:* 추정) = TBU
• PayrollRecord status enum = draft→approved→confirmed→paid 확정 (published 미사용; 생성 직후 기본 draft, 최종 paid) — (TC 확정: payroll.test.ts: filter by status)
• BL-001 / BL-002 무음 실패 근본 원인 (owning docs 106/109) = TBU
• 최근 작업 시트가 없을 때의 진입 동선 (01) = TBU
• 계정 버튼(11) 표시 값 = TBU
• 알림 버튼(12) 상세 동작 = TBU