HBHR210_계약급여내역 시트
(Hereby) HR 급여 관리 > 시트 워크스페이스 > 계약급여내역 시트
| 앱 | HR 급여 관리 (hr-system, 포트 4000) |
| 대상 사용자 | 조건1 [HR_ADMIN] / 조건2 [SUPER_ADMIN] |
| 프로토타입 | TBU |
| 관련 정책 | [[POL_급여정본경계]] · [[POL_호봉승급규칙]] |
| Status | review |
| Owner | 카나 |
| 부모 | [[HBHR100_시트 워크스페이스 (공통 Shell)]] |
개요
- 계약급여내역 시트는 직원별 근로계약 조건(임금유형·기본급·호봉·시급·계약기간·주표준시간)을 한 행으로 표현하는 **급여 입력 원천 시트(작업공간)**다.
- 좌→우 17컬럼 구조이며, employment_contracts / salary_grades를 근거로 한다.
- 이 시트 값은 근로계약 calculator(11 output keys)의 입력 원천으로 소비되어 급여대장([[HBHR200_급여대장 시트]])의 기본급·제수당 산출로 연결된다.
- 좌측 시스템 컬럼(#/사번/성명/팀/재직상태)은 read-only로 employee에 바인딩되고, 우측 급여 항목 컬럼은 ƒ(수식)로 calculator output key에 바인딩된다.
- 시트=작업공간, 정본=commit 경계다. 시트 값은 확정 전까지 정본이 아니며 확정(commit) 시 allowance_records / payroll_records로 정본화된다 ([[POL_급여정본경계]] 참조).
문서 히스토리
| 날짜 | 작성자 | 팀 | 변경 내용 |
|---|---|---|---|
| 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-10-02 | 카나 | PM | 계약 시행일 변경(예약) 행 메뉴·모달·예약 목록 신설(a0298fde, #962)·백엔드 예약 액션/호봉 승급 시행일 예약 전환(c7ccf7fa, #960)·예약 목록 「검사」(dry-run)(fca2c067, #976)·목록 계약 종류만 필터(0f3a2fe3, #985) 반영 — 커밋 근거, 라이브 실사 이월(TBU) |
| 2026-10-08 | 카나 | PM | (10/7 머지분) 예약 가드·권한 정비(#1084, bee96793·3d441c2e, MED-827): ㄴ12 CASE06 같은 시행일 중복 예약 차단(화면·서버 문구) / ㄴ13 실행 버튼 라벨 4분기(지금 적용·다시 실행·다시 예약·시행일 전 비노출)·컨펌 문구 교체·「모든 예약 보기」(이 직원으로 좁혀 관리자 화면)·시행일 전 실행 거절·처리 중 잠금 문구 / Client→Server 목록 조회 권한 payroll:read.all(조직 전체) 전환 / 상태표 CASE04 잠금·시행일 전 실행 불가·소유자 알림 — 커밋·코드 근거, 라이브 실사 이월(TBU) |
Data I/O
Server → Client
| 변수 | DB 엔티티.컬럼 | 값 없을 때 | 비고 |
|---|---|---|---|
${sheet.rows} | employment_contracts[] (직원별 현행 계약 행) | 0건 시 빈 그리드 | "293/293건" 형태 카운트 |
${row.baseSalary} | salary_grades.baseSalary / 계약 기본급 | 미산정 시 빈 텍스트 | 임금유형=월급 기준 |
${row.hobong} | salary_grades.grade | 공란 | 호봉가산·장기근속 산출 입력 |
${column.fieldKey} | sheet_views.columnLayout (컬럼 바인딩 키) | 미바인딩 시 커스텀 열 | 시스템 컬럼 read-only |
Client → Server
| 액션 | 전달 값 | tRPC procedure | 권한 토큰 |
|---|---|---|---|
| 셀 편집 | rowId, columnKey, value | sdk.payrollSheet.updateCell() (추정) | payroll:write (추정) |
| 컬럼 수식/바인딩 변경 | columnKey, formula/calculatorKey | sdk.payrollSheet.updateColumn() ([[HBHR107_컬럼 헤더 컨트롤]]) | payroll:write (추정) |
| 재계산 preview | sheetId | compute preview (읽기 전용, [[HBHR203_재계산 diff 뷰]]) | — |
| 계약 시행일 변경 예약 | employeeId, effectiveDate, note, 바꿀 값 patch | sdk.employee.upsertContract({ mode: "effective", effectiveDate, note, ... }) — 시행일 ≤ 조직 오늘이면 커밋 뒤 즉시 실행, 결과 status 반환 (#960·#962) | employee:update |
| 예약 목록·취소·지금 적용·검사 | employeeId, kind=contract_change / action id | sdk.scheduledAction.list / cancel / run / dryRun (#960·#976·#985·#1084) | 취소·실행·검사: 대상 직원 기준 employee:update · 실행 판정은 예약 소유자의 현재 권한 / 목록 조회(10/8, #1084): 금액이 담겨 급여 조회 조직 전체(payroll:read.all) 필요 — 없으면 "권한이 없습니다: 예약된 변경에는 급여 금액이 들어 있어 급여 조회(조직 전체, payroll:read.all) 권한이 필요합니다." · 생성 시 같은 직원·같은 시행일 중복 거절 · 시행일 전 계약 변경 run 거절 |
Calculator 연동
컬럼(ƒ) ↔ 근로계약 calculator(11 output keys): 기본급·호봉가산·장기근속·통상시급 환산 산출 (11키 세부 = TBU). 산출 결과는 전체 확정([[HBHR201_전체 확정 (commit)]]) 시 allowance_records / payroll_records로 반영.
화면 플로우 (Mermaid)
이 시트는 INPUT 원천 시트다. ƒ 컬럼의 compute는 preview일 뿐이며 정본 record 생성은 급여대장 전체 확정([[HBHR201_전체 확정 (commit)]])에서만 발생한다.
컬럼 사양표 (17컬럼, 좌→우 — 기본 템플릿 기준)
컬럼 순서·명칭은 기본 템플릿 기준이며, 시트별 실데이터는 사용자 컬럼 편집으로 변형될 수 있다. 내부 fieldKey 16종: employeeNumber / employeeName / team / employeeStatus / contractNumber / contractType / wageType / baseSalary / hobongAmount / longevityAmount / hourlyRate / salaryGrade / startDate / endDate / standardWeeklyHours / jobDuty.
| # | 컬럼 | 타입 | 설명 (용도·형식) | 연관 (ERD/calculator/타 앱) | 비고 |
|---|---|---|---|---|---|
| 1 | # | Index | • 행 순번을 표시하는 시스템 컬럼 (read-only) | sheet_rows.sortOrder | read-only |
| 2 | 사번 | Text (system) | • 직원을 식별하는 사번 컬럼. employee 마스터에 read-only 바인딩 | employees.employeeNumber / fieldKey=employeeNumber | 시스템 컬럼 |
| 3 | 성명 | Text (system) | • 직원 성명을 표시하는 시스템 컬럼 (read-only) | employees.name / fieldKey=employeeName | 시스템 컬럼 |
| 4 | 팀 | Text (system) | • 소속 팀/부서를 표시하는 시스템 컬럼 (read-only) | teams / fieldKey=team | 시스템 컬럼 |
| 5 | 재직상태 | Badge | • 재직/휴직/퇴사 등 재직 상태를 표시하는 Badge 컬럼 | employees.status / fieldKey=employeeStatus · 휴직=leave_of_absence_records([[HBHR260_휴직·퇴사 내역 시트 (2섹션)]]) · 퇴사=resignation_records | 휴직/퇴사 행 회색 처리(추정) · TBU: enum 값 |
| 6 | 계약번호 | Text | • 근로계약을 식별하는 계약 번호 컬럼 | employment_contracts.contractNumber(추정) / fieldKey=contractNumber | 엔티티명 TBU |
| 7 | 계약유형 | Badge/Text | • 정규직/계약직/시간제 등 계약 유형을 표시하는 컬럼 | employment_contracts.contractType(추정) / fieldKey=contractType | TBU: enum 값 |
| 8 | 임금유형 | Badge/Text | • 월급/시급/연봉 등 산정 방식을 표시하며 calculator 분기 입력이 되는 컬럼 | employment_contracts.wageType(추정) / fieldKey=wageType → calculator 분기 입력 | TBU: enum 값 |
| 9 | 기본급 | Output/Number | • 월 기본급(원)을 표시하는 Output 컬럼. 임금유형=월급 기준 | salary_grades.baseSalary / fieldKey=baseSalary · 근로계약 calculator | 통화 포맷 |
| 10 | 호봉가산 | Output/Number | • 호봉 기반 가산액을 표시하는 Output 컬럼 | salary_grades.hobongAmount / fieldKey=hobongAmount · 근로계약 calculator | 호봉 종속 |
| 11 | 장기근속 | Output/Number | • 근속연수 기반 장기근속 가산액을 표시하는 Output 컬럼 | 근로계약 calculator (yearsOfService 입력) / fieldKey=longevityAmount | 산출식 TBU |
| 12 | 시급 | Output/Number | • 통상임금 환산 시간당 임금(원/h)을 표시하는 Output 컬럼 | 근로계약 calculator (통상시급 key) / fieldKey=hourlyRate | 연장/야간 배수 기준([[HBHR220_연장근무 내역 시트]]) |
| 13 | 호봉 | Number | • 호봉 단계(정수)를 표시하는 컬럼. 호봉가산 산정 입력 | salary_grades.grade / fieldKey=salaryGrade | 호봉가산 산정 입력 |
| 14 | 계약시작 | DatePicker | • 근로계약 시작일(YYYY-MM-DD)을 표시하는 DatePicker 컬럼 | employment_contracts.startDate(추정) / fieldKey=startDate | — |
| 15 | 계약종료 | DatePicker | • 근로계약 종료일을 표시하는 DatePicker 컬럼. 무기계약 시 공란 | employment_contracts.endDate(추정) / fieldKey=endDate | 계약직만 유효 |
| 16 | 주표준시간 | Number | • 주 소정근로시간(h)을 표시하는 컬럼. 통상임금·연장 판정 기준 | employment_contracts.weeklyStandardHours(추정) / fieldKey=standardWeeklyHours · 52시간 판정([[HBHR220_연장근무 내역 시트]]) 입력 | — |
| 17 | 직무 | Text | • 직무/직종 구분을 표시하는 컬럼 | employees.jobTitle(추정) / fieldKey=jobDuty | 인센티브 taxonomy 참고([[HBHR250_인센티브 세션 시트]]) |
공통 우측 컬럼군(재계산 diff + eCount)은 [[HBHR203_재계산 diff 뷰]] 참조.
연동·플로우
- 입력 원천 역할: 계약급여내역 → 근로계약 calculator(11키) → 급여대장([[HBHR200_급여대장 시트]]) 기본급/제수당 산출.
- 호봉 승급: grade_promotion_requests(currentGrade/nextGrade·currentBaseSalary/newBaseSalary·currentHobongAmount/newHobongAmount) 승인 결과가 호봉·기본급·호봉가산에 반영. 승인 = 승급일(promotionDate) 시행 예약(요청 상태
SCHEDULED신설, 승급일이 오늘 이하면 즉시 APPLIED) — 종전 「승인 즉시 소급(옛 계약 startDate 유지)」 결함 수정 (c7ccf7fa, #960). - 정정 vs 시행일 변경: 시트 칸 편집 = 정정(같은 계약 v+1, 계약이 걸친 모든 미확정 달 변경) / 「계약 시행일 변경…」 = 시행일 전날 옛 계약 종료(endDate=시행일−1) + 시행일부터 새 계약 → 시행 전 달은 옛 값·후 달은 새 값·걸친 달은 일할 (#960).
- 확정 경계: 값 확정은 급여대장 전체 확정([[HBHR201_전체 확정 (commit)]], commit)에서 allowance_records/payroll_records로 정본화. AI는 preview/preflight까지만 관여.
행 메뉴 — 계약 시행일 변경 (예약) 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 10 | 계약 시행일 변경… | MenuItem | • 행 우클릭 메뉴 항목(직원이 매핑된 행). 툴팁(원문): "정해진 날부터 기본급·계약 조건이 바뀌도록 예약해요. 그 전달 시트 값은 그대로예요." • 클릭 → "계약 시행일 변경" 모달(580px) - CASE01 [노출 시트]: 자동 채움 원천 employment_contract/employee 또는 직원 기준 시트(계약급여내역·직원 마스터·급여대장)만 — 날짜 기준 시트 미노출- CASE02 [여러 행 선택]: 비활성, 툴팁 "여러 행을 선택한 상태에서는 쓸 수 없어요" | 행 우클릭 메뉴(공통 Shell) · [[HBHR200_급여대장 시트]] | 신설 (코드 반영: a0298fde, #962, MED-821) · 항목명은 admin 「예약된 변경」 안내문("…계약급여내역 행 우클릭 「계약 시행일 변경…」…")으로 라이브 교차 확인(10/2) · TBU: hr-system 메뉴·모달 직접 실사 이월 |
| ㄴ11 | 모달 입력 | Form | • 설명(원문): "— 고른 날부터 새 근로계약이 시작돼요. 그 전날까지는 지금 계약이 그대로라 지난달 시트 값은 바뀌지 않아요." • "시행일"(아래 "현재 계약 시작일 {date} · 기본급 {n}") / "바꿀 값 — 비운 칸은 그대로 두어요": "계약 기본급"·"호봉인상분 (월)"·"장기근속 단가 (월)"·"통상시급"(placeholder "변경 없음")·"계약유형"·"임금유형"(기본 "변경 없음") / "메모 (선택)"(placeholder "예: 수습 종료 후 100%") • 안내(원문): "시행일이 오늘 이전이면 바로 적용돼요. 호봉을 배정한 계약이면 기본급·호봉인상분은 시행일의 호봉표 값이 우선해요. 예약은 만든 사람의 권한으로 실행되니, 권한이 바뀌면 실패로 남고 아래 목록에 사유가 보여요." | sdk.employee.upsertContract(mode=effective) | 호봉 배정은 이 모달에서 다루지 않음(승급 승인 경로) · 입력 있으면 닫기 시 저장확인 |
| ㄴ12 | 예약 | Button | • 클릭 → 즉시 실행(예약 생성), 저장 중 "저장 중…" - CASE01 [적용됨(시행일 ≤ 오늘)]: "{date} 부터의 새 계약을 적용했어요." + 시트 재로드 - CASE02 [예약됨]: "{date} 에 적용되도록 예약했어요." - CASE03 [적용 실패]: "예약은 만들어졌지만 적용에 실패했어요: {사유}" - CASE04 [시행일 ≤ 현재 계약 시작일]: "시행일은 현재 계약 시작일({date}) 뒤여야 해요. 같은 날부터 바꾸려면 시트 칸에서 직접 고쳐 주세요(정정)." - CASE05 [바꿀 값 없음]: "바꿀 값을 하나 이상 입력해 주세요." - CASE06 [같은 시행일의 진행 중 예약(예약됨·확인 대기·실패)이 이미 있음 — 10/8, #1084]: 만들지 않고 알림 "{date} 에 시행되는 예약이 이미 있어요({변경 요약}). 바꾸려면 아래 목록에서 기존 예약을 취소한 뒤 다시 만들어 주세요." · 서버도 같은 직원·같은 시행일 계약 변경을 만들 때 막음(동시 생성도 하나만): "같은 시행일({date})의 계약 변경 예약이 이미 있어요. 「예약된 변경」에서 기존 예약을 확인하고, 바꾸려면 기존 예약을 취소한 뒤 다시 만들어 주세요." | ㄴ13 | 시행일 미입력 시 버튼 비활성 · 실패: "예약 실패: {오류}" · CASE06 신설(bee96793·3d441c2e, #1084) — 종전엔 시행일에 먼저 만든 것만 적용되고 나머지는 실패 |
| ㄴ13 | 예약된 변경 (이 직원 목록) | List | • 행 = 상태 배지("예약됨" 파랑/"확인 대기"/"적용됨" 초록/"실패" 빨강/"건너뜀"/"취소됨") · "{date} 시행" · 출처("승급 승인"/"AI 제안") · 변경 요약 · 메모 · "소유자 {이름}" · 실패 시 사유(danger notice) • 목록 머리 "예약된 변경" 옆 "모든 예약 보기"(밑줄 글자 버튼) → 관리자 「예약된 변경」 화면을 이 직원으로 좁혀 엶(지난 이력·다른 종류 예약까지) — 시트를 단독으로 연 경우(관리자 임베드 아님) 비노출 (10/8, #1084) • 예약됨·실패 행 버튼: "검사"(툴팁 "지금 실행하면 어떻게 되는지 쓰지 않고 봐요") / 실행 버튼 / "취소" - 실행 버튼 라벨(10/8, #1084): CASE01 [예약됨 · 시행일 ≤ 오늘] "지금 적용" · CASE02 [예약됨 · 시행일 전] 비노출(시행일 전 계약 변경은 미리 실행하지 않음) · CASE03 [실패 · 시행일 ≤ 오늘] "다시 실행" · CASE04 [실패 · 시행일 전] "다시 예약" - 지금 적용 → 컨펌 "지금 적용할까요? {date} 시행으로 새 계약이 적용되고, 적용되면 되돌릴 수 없어요." / 다시 실행 → "다시 실행할까요? {date} 시행으로 새 계약이 적용되고, 적용되면 되돌릴 수 없어요." / 다시 예약 → "지금 적용하지 않고, 시행일({date})에 자동으로 적용되도록 다시 예약할까요?" → 성공 "시행일({date})에 자동으로 적용되도록 다시 예약했어요."(상태 예약됨으로만 복귀) - 서버 가드: 시행일 전 계약 변경 실행 요청은 거절 "계약 변경은 시행일({date}) 전에 실행할 수 없어요. 시행일에 자동으로 적용돼요. 지금부터 바꿔야 하면 이 예약을 취소하고 시행일을 오늘로 다시 예약해 주세요." · 같은 예약을 시행일 잡과 동시에 처리하면 "다른 곳에서 이 예약을 처리하고 있어요. 잠시 뒤 새로고침해 주세요." - 취소 → 컨펌 "이 예약을 취소할까요? 시행일에 계약이 바뀌지 않아요." → 실행 - 검사 → 알림 한 문단(실패 예상 "지금 실행하면 실패해요: {사유}" / "바뀌는 곳 {N}개: · {대상}: {전} → {후}") | sdk.scheduledAction.list(kind=contract_change)/run/cancel/dryRun | 목록 kind 필터(#985) · 검사(fca2c067, #976) · 실패: "적용 실패:"/"취소 실패:"/"검사 실패: {오류}" |
| ㄴ13-E | Empty | Text | • "예약된 변경이 없어요." |
권한·상태 분기 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
CASE01 [시스템 컬럼 편집 시도] | 사번/성명/팀/재직상태 셀 편집 | 차단 (read-only 바인딩, 입력 무시) | employee 마스터가 SoT |
CASE02 [ƒ 컬럼/원천 셀 편집] | 기본급/호봉 등 셀·수식 변경 | 작업공간 업데이트 (payroll:write 추정) | commit 무관 |
CASE03 [휴직·퇴사 행] | 재직상태 = 휴직/퇴사 | 행 회색 처리(추정) | 정산 계산 대상 |
CASE04 [계약 시행일 변경 예약] | 행 메뉴 「계약 시행일 변경…」 → 예약 | 시행일 매시 잡이 소유자 현재 권한으로 계약 기간 분할 · 권한 상실/퇴직 시 FAILED(자동 재시도·승계 없음) · (10/8) 예약 1건은 한 번에 한 곳만 처리(잠금 — 동시 처리 시 "다른 곳에서 이 예약을 처리하고 있어요…") · 시행일 전 실행 불가(실패 건은 "다시 예약"으로 예약됨 복귀) · 같은 직원·같은 시행일 중복 생성 차단 · 실행/실패 알림이 예약 소유자에게도 감 | #960·#962·#1084 |
Open Question
- employment_contracts 엔티티/컬럼명 확정 (03 ERD 미노출, salary_grades/grade_promotion_requests만 확인). TBU.
- 근로계약 calculator 11 output key 세부 및 컬럼별 매핑. TBU.
- 재직상태·계약유형·임금유형 enum 값 목록. TBU.
- 장기근속/통상시급 산출식 및 주표준시간과의 관계. TBU.
- 시스템 컬럼 외 셀 편집 가능 여부(기본급/호봉 수기 vs calculator read-only). TBU.
- 「계약 시행일 변경」 모달 = 사양서 없는 신규 모달 → 전용 문서 신규 화면 채번 대기(현재 이 문서 행 10~ㄴ13에 요약). 조직 전체 예약 관리는 admin 「급여 관리 › 예약된 변경」(#980, 신규 화면 채번 대기).