HBHR200_급여대장 시트
(Hereby) HR 급여 관리 > 시트 워크스페이스 > 급여대장 시트
| 앱 | HR 급여 관리 (hr-system, 포트 4000) |
| 대상 사용자 | 조건1 [HR_ADMIN] / 조건2 [SUPER_ADMIN] |
| 프로토타입 | TBU |
| 관련 정책 | [[POL_급여정본경계]] |
| Status | review |
| Owner | 카나 |
| 부모 | [[HBHR100_시트 워크스페이스 (공통 Shell)]] |
| 하위 | [[HBHR201_전체 확정 (commit)]] · [[HBHR202_직원 추가]] · [[HBHR203_재계산 diff 뷰]] |
개요
- 급여대장 시트는 전 직원의 급여를 한 시트에서 편집·검토하는 **급여 작업 시트(작업공간)**다. 확정(commit =
sheetView.commitToRecords)은allowance_records/deduction_records정본 record만 생성한다. 급여대장 정본(payroll_records)은 커밋이 만들지 않는다 — 별도 절차payroll.generateForPeriod(year, month)가 AR/DR을 집계해 PayrollRecord를 생성한다(중복 시 skip) — (TC 확정: 03:3.3 / payroll.test.ts). ([[POL_급여정본경계]] 참조 — 이중 경로: ①시트 커밋→AR/DR ②generateForPeriod→PayrollRecord) - 좌측 시스템 컬럼(#/사번/성명/팀/직급)은 read-only로 employee에 바인딩되고, 우측 급여 항목 컬럼은 각각 ƒ(수식)로 Module Manager calculator의 output key에 바인딩된다.
- 가상 스크롤 그리드이며, 상단 헤더에 건수 카운트("293/293건" 형태), 하단에 컬럼별 ∑ 합계행("n명")을 표시한다. 휴직·퇴사 행은 회색 처리된다.
- 본 화면의 컬럼 정의(시스템 컬럼 + 급여 항목 컬럼)는 기본 템플릿 기준이다. 라이브 시트는 사용자 편집으로 컬럼 구성이 변형될 수 있다 — 예: 사번 / 성명 / 팀 / 연장근무수당 + 커스텀 열 구성.
문서 히스토리
| 날짜 | 작성자 | 팀 | 변경 내용 |
|---|---|---|---|
| 2026-07-06 | 카나 | PM | 최초 작성 |
| 2026-07-10 | 카나 | PM | 라이브 기능 검토 반영 |
| 2026-07-13 | 카나 | PM | 버튼 행동 명세 보강 |
| 2026-07-21 | 카나 | PM | GC700 깊이 재작성 |
| 2026-07-21 | 카나 | PM | 가독성 패스 + 액션 표기 (GUIDE §7·§8) |
| 2026-07-21 | 카나 | PM | 셀 스타일 확정판 적용 (콸 승인) |
| 2026-07-21 | 카나 | PM | TC 크로스체크 확정분 반영 (🟡) |
| 2026-07-21 | 카나 | PM | 🔴 정정: 급여 생성 경계(커밋=AR/DR만·PayrollRecord=generateForPeriod)·record 타깃 페어 모델 (TC 정본, 콸 승인) |
| 2026-07-25 | 카나 | PM | 코드 변경 반영(17f8589·b83a51b) — 행 우클릭 메뉴 「직원 정보 수정」·「근태 기록 확인하기」 추가, 우클릭 행 추가 배치 버그 수정 |
Data I/O
Server → Client
| 변수 | DB 엔티티.컬럼 | 값 없을 때 | 비고 |
|---|---|---|---|
${sheet} | sheet_views (viewKind, year, month) | 시트 미선택 시 빈 그리드 | 급여대장 뷰 |
${rows} | sheet_rows[] (sheetViewId FK, sortOrder 순) | 0건 시 Empty (-E) | "293/293건" 카운트 |
${row.employee} | sheet_rows.employeeId FK → employees | employee 부재 시 시스템 컬럼 공란 | 시스템 컬럼 바인딩 |
${cell} | sheet_cells (sheetRowId, columnKey, kind) | 셀 없음 시 빈 셀 | literal/formula/ref 분기 |
${cell.computedValue} | sheet_cells.computedValue jsonb (+computedAt) | 미계산 시 빈 텍스트(미계산 표시) | ƒ 산출값 |
${column.fieldKey} | 컬럼 바인딩 키 | 미바인딩 시 커스텀 열 | (employeeNumber)/(employeeName)/(team)/(position) 등 |
${column.warning} | 컬럼 설정 검증 상태 | 정상이면 hide | 미검증 시 "⚠ 설정 확인 필요" 배지 |
${payslip.allowanceRecords} | payslip 응답의 allowanceRecords[] (수당 원천 링크) | 없으면 빈 배열 | grossPay 구성 = 월급여+연장+수당 합산 · (TC 확정: 07:7.10 payroll includes overtime from ALL categories) |
Client → Server
| 액션 | 전달 값 | tRPC procedure | 권한 토큰 |
|---|---|---|---|
| 셀 편집 | rowId, columnKey, value | sdk.payrollSheet.updateCell() (추정) | payroll:write (추정) |
| 컬럼 수식/설정 변경 | columnKey, formula, fieldKey, aggregate | sdk.payrollSheet.updateColumn() (추정) | payroll:write (추정) |
| 시트 내 검색 | query (사번/성명/사유/항목) | 클라이언트 필터 | — |
| 직원(행) 추가 진입 | — | [[HBHR202_직원 추가]] | payroll:write (추정) |
| 전체 확정 진입 | — | [[HBHR201_전체 확정 (commit)]] | payroll:confirm (추정) |
ƒ컬럼 ↔ Calculator output key 바인딩 (Module Manager)
| 급여 항목군 | 바인딩 |
|---|---|
| 기본급/호봉/장기근속/계약수당 | 근로계약 calculator ([[HBHR210_계약급여내역 시트]]) |
| 연장/야간/휴일/주말 | 초과근무·근태 calculator ([[HBHR220_연장근무 내역 시트]] / [[HBHR231_근태 내역 시트 (근무시간 유형 집계)]]) |
| 고정 인센티브 | 고정인센티브 calculator ([[HBHR250_인센티브 세션 시트]]) |
| 4대보험 공제 | InsuranceCalculator |
| 소득세 공제 | 소득세 calculator |
ƒ수식 저장 단위(formula string vs calculator key binding) = TBU. sheet_cells.formulaExpression(text)와 record ref가 병존.
시트 ↔ record 참조 모델 (2026-06-19 타깃 페어 모델)
시트 구조는 sheet_views(시트) → sheet_rows(행) → sheet_cells(셀).
커밋 산출 record(AR/DR)는 item-code FK를 갖지 않는다(migration 1816으로 제거). 대신 두 방향의 참조를 보유한다 — (TC 확정: 10:10.1~10.3 / sheet-fixtures):
| 방향 | 필드 | 의미 |
|---|---|---|
| record → 원천 시트 (lineage) | sourceSheetId / sourceSheetRowId / sourceSheetColumnKey + isAutoGenerated=true | 어느 시트·행·컬럼 커밋에서 생성됐는지 스탬프. 재커밋 시 sourceSheetId 단위 soft-delete 후 재삽입(멱등) |
| record → 급여대장 앵커 (target) | targetSheetSlug + targetColumnKey | 급여대장의 어느 집계 컬럼으로 흘러갈지 지정하는 페어. 실 급여대장 슬러그에 앵커되지 않으면 eCount export에서 excludedRecords로 제외 (TC 확정: 10:10.6) |
구(舊) 서술이던 sheet_rows.sourceAllowanceRecordId 등 행 단위 ref 4종·sheet_cells.refAllowanceRecordId 등 셀 단위 ref 4종(item-code 바인딩 모델)은 폐기된 모델이다.
화면 플로우 (Mermaid)
ƒ 컬럼의 compute는 preview일 뿐 정본이 아니다. AR/DR 정본 record 생성은 확정([[HBHR201_전체 확정 (commit)]])에서만. PayrollRecord 생성은 커밋이 아니라 payroll.generateForPeriod(별도 절차) — 이후 validate(year,month) → approvePayroll(id)/bulkApprove(ids[]) → confirm(year,month) → processPayment(id) → exportEcount(year,month) 순의 절차형 급여 사이클이 이어진다 (TC 확정: 03:3.3~3.5 / 07:7.11 / 08:8.9). 이 사이클의 UI 진입점 = TBU.
시트 lifecycle
급여대장 시트 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 노출 조건 | - | 조건1 [HR_ADMIN]/조건2 [SUPER_ADMIN] 인증 후 급여대장 폴더의 급여대장 시트 클릭 시 그리드 렌더. 미인증 시 [[HBHR100_시트 워크스페이스 (공통 Shell)]] 게이트에서 차단 | sheet_views | 인증 게이트 |
| 01 | 초기 상태 | Output | 전 행 로드, 상단 "293/293건" 형태 카운트. 검색 placeholder "사번 / 성명 / 사유 / 항목 검색 ( / )" | 가상스크롤 | |
| 10 | 시트 헤더 | - | "{이름} '26.7 · {수정 경과} · n/n건" + 검색창 + 💬. 시트명/기간 더블클릭 인라인 편집은 [[HBHR100_시트 워크스페이스 (공통 Shell)]] 위임 | [[HBHR100_시트 워크스페이스 (공통 Shell)]] | |
| 20 | 컬럼 헤더 | Cell | • 라벨 + ƒ(수식) + ⚙(설정) + ∑(집계) + (fieldKey) + ⇅ + ⌄ + "⚠ 설정 확인 필요" 배지로 구성된 프로그래머블 헤더. 헤더 버튼 "정렬 추가"/"필터 추가" • 클릭 시: 컬럼 헤더 컨트롤 노출 → 정렬/필터/수식·설정 진입 - CASE01 [정상]: ⚠ 배지 hide - CASE02 [미검증]: ⚠ 배지 노출 | [[HBHR107_컬럼 헤더 컨트롤]] | 프로그래머블 |
| 30 | 시스템 컬럼 | Column | • #/사번/성명/팀/직급. fieldKey employeeNumber/employeeName/team/position 바인딩, read-only • 편집 시: 차단(입력 무시). employee 마스터가 SoT | sheet_rows.employeeId → employees | 편집 불가 |
| ㄴ31 | # | Cell | • 행 순번 (sortOrder). read-only | ||
| ㄴ32 | 사번 | Cell | • employeeNumber 바인딩. read-only | ||
| ㄴ33 | 성명 | Cell | • employeeName 바인딩. read-only | ||
| ㄴ34 | 팀 | Cell | • team 바인딩. read-only | ||
| ㄴ35 | 직급 | Cell | • position 바인딩. read-only | ||
| 40 | 급여 항목 컬럼 (ƒ컬럼) | Column | • 기본급/수당/공제/실수령 등. 각 컬럼 ƒ로 calculator output key에 바인딩. 값은 sheet_cells.computedValue. 본 컬럼 구성은 기본 템플릿 기준이며 라이브 시트는 커스텀 열로 변형될 수 있음 - 값 없음: 미계산 시 빈 텍스트 | Calculator output key | 기본 템플릿 · TBU: 전체 목록 |
| ㄴ41 | 수식(ƒ) | Fill Handle | • 컬럼 값을 calculator output key / formula로 산출하는 채우기 핸들 • 조작 시: 셀 선택 후 Ctrl+D(아래 채우기)/Ctrl+R(오른쪽 채우기) → 수식 전파 | Calculator Registry | AI 진입 표면 · 저장 단위 TBU |
| ㄴ42 | 집계(∑) | - | • 컬럼 하단 합계/통계 | 합계행(60) | |
| ㄴ43 | 설정 검증 | Badge | • "⚠ 설정 확인 필요" — 컬럼 바인딩/수식 미검증 경고 | ||
| 50 | 데이터 행 | Row | • 시스템 컬럼 + 급여 항목 컬럼으로 구성된 직원 행 - CASE01 [재직]: 정상 표시 - CASE02 [휴직·퇴사]: 행 회색 처리 - CASE03 [확정됨]: 확정 후 회색(lockedAt) | 휴직·퇴사([[HBHR260_휴직·퇴사 내역 시트 (2섹션)]]) | 회색 = 정산/확정 대상 |
| 60 | 합계 행 | Cell | • 하단 컬럼별 ∑ 합계 + "{n}명" 카운트 | 전 시트 공통 | |
| 70 | 셀 메모 | Button | • 셀에 메모(💬)를 부착하는 기능. 미부착 시 아이콘 hover 노출 • 클릭 시: 셀에 메모 부착 (open/resolved 상태 관리) | payroll_cell_memos (columnKey, sheetRowId) | open/resolved 상태 |
| 80 | 직원 추가 진입 | Button | • 시트에 직원(행)을 추가하는 진입점. "➕ 직원 추가" • 클릭 시: [[HBHR202_직원 추가]] 모달 오픈 - 버그 수정: 우클릭 행 추가 시 새 행이 최하단에 붙거나 안 보이던 문제 해소 — 500행+ 시트에서도 새 행이 슬롯 위치에 정상 배치·리페인트(sheetRow.create 반환 id를 정렬 키로 직접 사용) | [[HBHR202_직원 추가]] | 코드 반영: b83a51b |
| 90 | 전체 확정 진입 | Button | • 시트를 정본으로 확정하는 진입점 — ★destructive. "💰 전체 확정" • 클릭 시: [[HBHR201_전체 확정 (commit)]] 진입 | [[HBHR201_전체 확정 (commit)]] | |
| A0 | 행 우클릭 메뉴 | Context Menu | • 직원 행 우클릭 시 나오는 컨텍스트 메뉴. 기존 항목(정보/추가/취소/삭제)에 「직원 정보 수정」·「근태 기록 확인하기」 2항목 추가 — 7/21 베스트 요구(시트에서 근태 바로 확인, 메뉴 왕복 제거) 반영 • 클릭 시: 해당 항목 실행 | sheet_rows.employeeId → employees | 코드 반영: 17f8589 |
| ㄴA1 | 직원 정보 수정 | Menu Item | • 우클릭 메뉴에서 직원 정보 편집 위저드를 여는 항목. 공용 editEmployeeWizard 재사용• 클릭 시: editEmployeeWizard 오픈 → 저장 시 employee-saved 이벤트로 해당 행만 갱신(전체 reload 없음) | 공용 editEmployeeWizard · employees | 코드 반영: 17f8589 · 행 단위 갱신 |
| ㄴA2 | 근태 기록 확인하기 | Menu Item | • 우클릭 메뉴에서 해당 직원 근태 팝업을 여는 항목. admin의 근태 팝업을 hr-system에 이식 • 클릭 시: 근태 팝업 오픈(시트에서 근태 바로 확인) | admin 근태 팝업 (hr-system 이식) | 코드 반영: 17f8589 · 메뉴 왕복 제거 |
| 20-E | Empty (0건) | Text | 시트 행 0건 시 빈 그리드. | 원문 미확인 · TBU: Empty 문구 원문 |
그리드 단축키 (HBHR-modals 카탈로그 반영)
| 카테고리 | 키 | 동작 |
|---|---|---|
| 탐색 | ↑ ↓ ← → | 셀 이동 |
| 탐색 | j / k | 사이드바 시트 전환 (다음 / 이전) |
| 탐색 | / | 검색창 포커스 |
| 탐색 | i | 선택 행 정보 패널 열기 ([[HBHR109_행 정보 패널·검색]]) |
| 선택 | Shift + 클릭 | 셀 범위 선택 |
| 선택 | 우클릭 (# 열) | 행 메뉴 (정보 / 추가 / 취소 / 삭제 / 직원 정보 수정 / 근태 기록 확인하기) — 코드 반영: 17f8589 |
| 편집 | Enter | 선택 셀 편집 / 편집 후 아래 셀로 이동 |
| 편집 | Tab / Shift+Tab | 편집 후 오른쪽 / 왼쪽 셀로 이동 |
| 편집 | Esc | 편집 취소 / 모달 닫기 |
| 편집 | Ctrl+C / Ctrl+V | 선택 셀 TSV 복사 / 붙여넣기 |
| 편집 | Ctrl+D / Ctrl+R | 아래로 / 오른쪽으로 채우기 (Excel 스타일) |
| 편집 | Ctrl+Z / Ctrl+Shift+Z | 되돌리기 / 다시 실행 |
단축키 도움말 모달 전체는 [[HBHR103_편집 메뉴·단축키]] 참조.
권한·상태 분기 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
CASE01 [시스템 컬럼 편집 시도] | 사번/성명/팀/직급 셀 편집 | 차단 (read-only 바인딩, 입력 무시) | employee 마스터가 SoT |
CASE02 [ƒ 컬럼 편집] | 급여 항목 셀/수식 변경 | 셀 업데이트 (작업공간) | payroll:write (추정) |
CASE03 [휴직·퇴사 행] | 재직상태 = 휴직/퇴사 | 행 회색 처리 | 정산 계산 대상 |
CASE04 [확정된 행] | 전체 확정 후 | 행 회색 처리(lockedAt) | 재편집 방지 |
Open Question
- 급여 항목 컬럼 전체 목록 (기본급/수당/공제/실수령 세부) = TBU
- ƒ수식 저장 단위: formulaExpression(string) vs calculator key binding = TBU
- 휴직·퇴사 행 회색 ↔ 확정 스킵(합계 0)의 연동 여부 = TBU
- 4대보험 config "미사용"(요율 코드 내장)의 ƒ 컬럼 반영 방식 = TBU
- Empty(20-E) 상태 노출 문구 원문 = TBU