HBHR230_출퇴근 내역 시트
(Hereby) HR 급여 관리 > 시트 워크스페이스 > 출퇴근 내역 시트
| 앱 | HR 급여 관리 (hr-system, 포트 4000) |
| 대상 사용자 | 조건1 [HR_ADMIN] / 조건2 [SUPER_ADMIN] |
| 프로토타입 | TBU |
| 관련 정책 | [[POL_급여정본경계]] · [[POL_근태원천]] |
| Status | review |
| Owner | 카나 |
| 부모 | [[HBHR100_시트 워크스페이스 (공통 Shell)]] |
개요
- 출퇴근 내역 시트는 직원별 일자별 실제 출퇴근 및 근무시간 분해(정규/연장/야간/주말/총시간)를 한 행으로 표현하는 **근태 원천 시트(작업공간)**다.
- 좌→우 13컬럼 구조이며, Secom punch 원천(secom_events → attendances)을 근거로 한다.
- Secom 게이트웨이가 수집한 punch 이벤트(secom_events)가 attendances로 정규화되어 근무시간이 정규/연장/야간/주말으로 분해된다.
- 근무시간 분해값(attendances 저장값)은 급여용 근무시간의 1차 원천(SoT)으로, 근태 내역([[HBHR231_근태 내역 시트 (근무시간 유형 집계)]]) 및 급여 산출로 연결된다.
- 시트=작업공간, 정본=commit 경계다. 근태 원천값은 급여대장 전체 확정(commit) 전까지 급여 정본이 아니다 ([[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 | 셀 스타일 확정판 적용 (콸 승인) |
Data I/O
Server → Client
| 변수 | DB 엔티티.컬럼 | 값 없을 때 | 비고 |
|---|---|---|---|
${sheet.rows} | attendances[] (employeeId·date별) | 0건 시 빈 그리드 | 일자별 근태 행 |
${row.actualCheckIn/Out} | attendances.actualCheckIn / actualCheckOut | 미출근 시 공란 | 실제 출근/퇴근 시각 |
${row.hours} | attendances.regular/overtime/night/weekendHours (numeric(5,2)) | 0 | 근무시간 분해 |
${row.status} | attendances.status (attendances_status_enum, default scheduled) | default scheduled | 근태 상태 |
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 뷰]]) | — |
원천 흐름 (Secom → attendances)
secom_sync_state(게이트웨이 폴링) → secom_events(raw punch: eventDatetime·terminalId·cardNumber·employeeNumber·eventType) → 매칭 → attendances(employeeId·date·shiftId·scheduledCheckIn/Out·actualCheckIn/Out). secom_events.attendanceId FK로 punch가 attendance에 연결. 미매칭 이벤트는 status=pending/error(secom_events_status_enum). 근무시간 분해(정규/연장/야간/주말/휴일)는 attendances 저장값 = 근태 원천 SoT.
화면 플로우 (Mermaid)
이 시트는 INPUT 근태 원천 시트다. Secom 자동 산출값이 근무시간의 SoT이며, 정본 급여 record 생성은 급여대장 전체 확정([[HBHR201_전체 확정 (commit)]])에서만 발생한다.
컬럼 사양표 (13컬럼, 좌→우 — 기본 템플릿 기준)
컬럼 순서·명칭은 기본 템플릿 기준이며, 시트별 실데이터는 사용자 컬럼 편집으로 변형될 수 있다. 내부 fieldKey: employeeNumber / employeeName / team / date / actualCheckIn / actualCheckOut / regularHours / overtimeHours / nightHours / weekendHours / totalHours / status.
| # | 컬럼 | 타입 | 설명 (용도·형식) | 연관 (ERD/calculator/타 앱) | 비고 |
|---|---|---|---|---|---|
| 1 | # | Index | • 행 순번을 표시하는 시스템 컬럼 (read-only) | sheet_rows.sortOrder | read-only |
| 2 | 사번 | Text (system) | • 직원 사번을 표시하는 시스템 컬럼 (read-only) | employees.employeeNumber / secom_events.employeeNumber / fieldKey=employeeNumber | 시스템 컬럼 |
| 3 | 성명 | Text (system) | • 직원 성명을 표시하는 시스템 컬럼 (read-only) | employees.name / fieldKey=employeeName | 시스템 컬럼 |
| 4 | 팀 | Text (system) | • 소속 팀을 표시하는 시스템 컬럼 (read-only) | teams / fieldKey=team | 시스템 컬럼 |
| 5 | 일자 | DatePicker | • 근무 일자(YYYY-MM-DD)를 지정하는 DatePicker 컬럼 • 입력 시: attendances.date 갱신 (작업공간) | attendances.date / fieldKey=date | — |
| 6 | 출근 | Time/Output | • 실제 출근 시각을 표시하는 컬럼. Secom punch 원천 | attendances.actualCheckIn / fieldKey=actualCheckIn ← secom_events | 미출근 시 공란 |
| 7 | 퇴근 | Time/Output | • 실제 퇴근 시각을 표시하는 컬럼. Secom punch 원천 | attendances.actualCheckOut / fieldKey=actualCheckOut ← secom_events | — |
| 8 | 정규 | Output/Number | • 정규 근무시간(h)을 표시하는 Output 컬럼. numeric(5,2), 휴게 차감 후 | attendances.regularHours / fieldKey=regularHours | 휴게 차감 후 |
| 9 | 연장 | Output/Number | • 연장 근무시간(h)을 표시하는 Output 컬럼 | attendances.overtimeHours / fieldKey=overtimeHours · [[HBHR220_연장근무 내역 시트]] 연장근무와 정합 | — |
| 10 | 야간 | Output/Number | • 야간(22-06시) 근무시간(h)을 표시하는 Output 컬럼 | attendances.nightHours / fieldKey=nightHours | 야간가산 입력 |
| 11 | 주말 | Output/Number | • 주말 근무시간(h)을 표시하는 Output 컬럼 | attendances.weekendHours / fieldKey=weekendHours | 휴일=holidayHours 별도([[HBHR231_근태 내역 시트 (근무시간 유형 집계)]]) |
| 12 | 총시간 | Output/Number | • 총 근무시간(h)을 표시하는 Output 컬럼. 분해값 합산 | attendances.totalHours / fieldKey=totalHours | 합계행 ∑ |
| 13 | 상태 | Badge | • 근태 상태(정상/지각/결근/스케줄 등)를 표시하는 Badge 컬럼 | attendances.status (attendances_status_enum) / fieldKey=status | TBU: status enum 전체값 |
공통 우측 컬럼군(재계산 diff + eCount)은 [[HBHR203_재계산 diff 뷰]] 참조.
연동·플로우
- 근태 원천 SoT: Secom punch(secom_events) → attendances 정규화 → 이 시트가 급여용 근무시간의 1차 원천.
- 근태 집계 연결: 일자별 분해값(정규/연장/야간/주말/휴일)이 근태 내역([[HBHR231_근태 내역 시트 (근무시간 유형 집계)]])에서 직원별 유형 집계로 롤업.
- 연장 정합: attendances.overtimeHours(자동)와 HBTM 승인 overtime_records([[HBHR220_연장근무 내역 시트]])의 정합/우선순위 = [[POL_근태원천]](배정근무 vs 실제 출퇴근 비교).
- attendances의 holidayHours·holidayRegularHours·holidayNightHours는 13컬럼 미노출 — 휴일 세부는 [[HBHR231_근태 내역 시트 (근무시간 유형 집계)]]에서 표현.
권한·상태 분기 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
CASE01 [시스템 컬럼 편집 시도] | 사번/성명/팀 셀 편집 | 차단 (read-only 바인딩, 입력 무시) | employee 마스터가 SoT |
CASE02 [ƒ 컬럼/원천 셀 편집] | 출퇴근·근무시간 셀 변경 | 작업공간 업데이트 (payroll:write 추정) · 수기 보정 허용 정책 = TBU | Secom 산출값 SoT |
CASE03 [미매칭 punch] | secom_events.status = pending/error | 시트 노출 여부 = TBU | 처리 동선 미확인 |
Open Question
- attendances_status_enum 전체 값(정상/지각/조퇴/결근/scheduled 등). TBU.
- attendances.overtimeHours(자동)와 overtime_records(승인, [[HBHR220_연장근무 내역 시트]])의 급여 우선순위/정합 규칙. TBU.
- 야간(nightHours) 시간대 정의 및 야간가산 배수(organization_parameters 추정). TBU.
- Secom 미매칭 punch(status=error) 처리 동선 및 시트 노출 여부. TBU.
- Secom 자동 산출값 수기 보정 허용 정책. TBU.