HBAD250_근태 현황 (근무)
(Hereby) 관리자 패널 > 근태 관리 > 근태 현황 > 근무 탭
| 메타 | 앱: 관리자 패널 (HBAD)대상 사용자: 조건1 [근태 관리] / 조건2 [근태 조회] / 조건3 [근태 조회 (팀)]프로토타입: TBU관련 정책: [[POL_근태원천]] · [[POL_출퇴근]] · [[POL_근무설정]]Status: reviewOwner: 카나 |
개요
근태 현황은 상단 4탭(근무 / 연차 / 연장근무 / 외근) 으로 구성된 근태 조회·수정·결재 콘솔이며, 본 문서는 4탭 공통 구조와 근무 탭을 다룬다.근무 탭 본문은 Team Manager 앱 임베드(/team-manager/?att=1&embedded=1)로 로드되며, 원천은 Secom 지문 단말기 punch가 attendances로 정규화된 값이다 ([[POL_근태원천]]).각 탭 우상단 설정 버튼(근무 → "근무 설정" 등)은 "유형·기준 관리" 모달을 열어 유형·기준을 관리한다. [2026-09-15 표 가로 스크롤바 정리(4184fdb)] 가로로 넘치는 표에 위·아래 두 곳으로 붙던 가로 스크롤바를 아래쪽 한 줄로 통일했다. 근태 현황의 표처럼 스크롤 박스가 화면에 맞는 표에서 헤더 위에 겹쳐 보이던 두 번째 바가 사라지고, 화면보다 긴 표에서도 아래 바가 화면 하단에 붙어(sticky) 계속 보인다. 화면마다 개별로 위 바를 끄던 방식은 폐지되어 모든 관리자 표에 공통 적용된다.
문서 히스토리
- 2026-07-06 최초 작성 - 카나/콸
- 2026-07-10 라이브 기능 검토 반영 (근무 탭 TM 임베드 확인) - 카나/콸
- 2026-07-21 GC700 깊이 재작성 - 카나/콸
- 2026-07-21 셀 스타일 확정판 적용 (콸 승인) - 카나/PM
- 2026-07-23 코드 변경 반영(a5b0975) - 카나/콸
- 2026-07-29 코드 변경 반영(7c2eab6) - 카나/PM
- 2026-07-30 코드 변경 반영(8b3e0a0) - 카나/PM
- 2026-09-15 표 가로 스크롤바 아래쪽 단일 sticky 바로 통일(위 바 제거, 4184fdb) - 카나/콸
- 2026-09-17 근무 탭(TM 임베드) 출퇴근 그리드에 「다운로드」(기간 전체 엑셀) 버튼 반영(6397f95) — 9/18 라이브 실사 확인 - 카나/PM
- 2026-09-21 근무형태 판정 일원화(shift-resolution.service) — 출퇴근 기록에 판정 출처(metadata.shiftSource) 표시, 판정 순서 근무표→직원 배정→그룹→조직 기본 근무형태→조직 기본 기준시간 반영(c4eb0f9, #804) — 커밋 근거, 라이브 실사 이월(TBU) - 카나/PM
- 2026-09-25 낮 스윕 실사 — 근무 탭 목록에 판정 출처 컬럼 없음 확인(ㄴ33-1 표시 위치 미확인, TBU 유지). 근태 현황 = team-manager 임베드(
/team-manager/?att=1&embedded=1) 실측 - 카나/PM - 2026-09-26 주간 스윕 재실사 — 근태 현황 목록 행 클릭 시 상세/수정 모달 없음·DOM에 판정 출처 표기 없음 확인. ㄴ33-1은 화면 미노출(데이터만 기록) 가능성 → 표시 위치 개발 확인 질의로 전환(TBU 유지) - 카나/PM
- 2026-10-07 PR #1035(afd9bb68) 반영: 「정정 요청」 탭 신설 — 직원 앱 출퇴근 정정·기록 추가 요청 검토(대기 배지·필터·검토 팝업·반려 사유 모달, attendance_correction_requests 마이그 1948·attendanceCorrection 라우터). 탭 포인터만 채록, 상세 사양은 HBAD254(가칭) 신규 채번 제안 — 커밋 근거, 라이브 실사 이월(TBU) - 카나/PM
- 2026-10-09 (10/8 머지분) PR #1122(1dcffae9) 반영: 출퇴근 정정 요청이 결재선 종류(attendance_correction)로 편입 — 「결재선 사용」 초기값 꺼짐(현행대로 근태 승인 권한 관리자가 바로 처리, 10/2 「승인은 관리자만」 유지). 병원이 켜면 정정 목록에서 내 차례가 아니면 버튼 비활성 + 결재 칩 노출, 출퇴근 기록 수정은 최종 승인 때만. 직원 앱 정정 폼 결재자 고르기는 아직 없어 팀·병원 기본 → 자동 결재선 적용. 상세 탭 사양은 HBAD254 채번 제안 유지 - 카나/PM
Data I/O
Server → Client
변수
| 메타 | $ |
| 메타 | $ |
| 메타 | $ |
| 메타 | $ |
| 메타 | $ |
| 메타 | $ |
| 메타 | $ |
Client → Server
| 액션 | 전달 값 | tRPC procedure | 권한 토큰 |
|---|---|---|---|
| 소속·기간 필터 변경 | teamId, period | (TM 임베드 재조회) | 근태 조회 |
| 근태 수정 (추정) | attendanceId, actualCheckIn/Out, 수정 사유(필수) | sdk.attendance.update() (추정) | 근태 수정 / 근태 수정 (본인) |
외부 통합 (cross-app)
| 외부 시스템 | 데이터 | 동기/비동기 | 비고 |
|---|---|---|---|
| Secom 지문 단말기 | 출퇴근 punch → secom_events → attendances 정규화 | 비동기 (secom_sync_state) | 활성 근태 원천 |
| 급여 시트 (HBHR) | attendances 근무 시간 집계 → 급여 근태 source (추정) | 비동기 | [[HBHR201_급여 시트]] |
메인 화면 (근무 탭) 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 노출 조건 | - | • 조건1 [근태 조회/관리 권한] 인증 시 노출- CASE01 [미인증]: /admin/signin 리다이렉트- CASE02 [권한 없음]: 사이드바 "근태 현황" 메뉴 미노출(추정) | 인증 세션 · RBAC | TBU: 권한 없음 |
| 01 | 초기 상태 | - | • 4탭 중 "근무" 탭 기본 선택, TM 임베드 로드 | ||
| 10 | 탭 네비게이터 | Tab | • "근무" / "연차" / "연장근무" / "외근" / "근로시간 마감" 5탭 (원문 카피, "근로시간 마감" 코드 반영: 8b3e0a0) • 「정정 요청」 탭 신설(10/7, #1035, afd9bb68) — 직원 앱 출퇴근 정정·기록 추가 요청을 근태 승인 권한자가 승인·반려하는 탭: 대기 배지 · 상태/종류/이름 필터 · 표, 줄 클릭 → 검토 팝업(지금 ↔ 승인하면 출퇴근·근무시간 미리 계산), 반려 사유 모달. 알림 벨의 정정 요청 알림이 이 탭으로 염(공용 벨이 navigate-section에 알림 type 동봉). 승인 자격 = attendance:approve(팀 범위는 담당 팀만)·본인 요청 처리 불가, 급여 확정·지급 기간·근로시간 마감일은 요청·승인 모두 차단, 승인은 관리자 근태 수정과 같은 계산(services/attendance-time-edit)으로 반영 + 수정 이력. 상세 사양은 별도 문서 분리 제안(HBAD254 가칭) — 신규 채번 대기 • 선택 시: 해당 탭 뷰 전환 + 우상단 설정 버튼 라벨 전환 - CASE01 [재진입(4s 로드)]: 근무 탭 유지 (s4 프로브 확인) | [[HBAD251_연차 현황·결재]]~[[HBAD253_외근 현황]] · 근로시간 마감(신규 사양서) | 5탭 (마감 탭 신설: 8b3e0a0) |
| 15 | 탭 설정 버튼 | Button | • 현재 탭의 유형·기준 관리를 여는 버튼 (근무 탭 = "근무 설정" 원문) • 클릭 시: "유형·기준 관리" 모달 오픈 - CASE01 [근무 탭]: "근무 설정" - CASE02 [연차 탭]: "연차 부여 기준" / "휴가 유형" - CASE03 [연장근무 탭]: "연장 근무 유형" - CASE04 [외근 탭]: "외근 유형" | 유형·기준 관리 모달 | 4탭 공통 |
| ㄴ16 | 유형·기준 관리 모달 | Modal | • 좌측 네비 5종("근무 설정" / "연장근무 유형" / "외근 유형" / "연차 부여 기준" / "휴가 유형")으로 유형·기준을 관리하는 모달 • 클릭 시: 해당 섹션 전환 | [[HBAD260]]~[[HBAD262]] | TBU: 내부 미확인 (s3-attend TAB_NOT_FOUND) |
| 18 | 근무 탭 임베드 | Embed | • 근무 탭 본문 = TM 임베드 /team-manager/?att=1&embedded=1 (s6 프로브 src 확인)- CASE01 [로드 성공]: 출퇴근 기록 그리드 - CASE02 [로드 실패/미인증]: 임베드 영역 공백 또는 TM 자체 에러 | Team Manager | 타 앱 embed · TBU: 무반응 시 버그 후보 |
| 19 | 근로시간 마감 탭 | Tab | • 근태 관리에 신설된 "근로시간 마감" 탭 — 마감 기록 조회/추가/수정/삭제 및 직원별 확정/확정 해제를 다루는 근로시간 마감 콘솔로 진입 • 선택 시: switchAttendanceTab('closing') → 마감 내역 로드 (worktime-closing.html 임베드)• 하위 서브탭 "마감 내역" / "개인별 마감 상태" 보유(원문). 상세 사양은 신규 사양서 대상 | worktime_closings · [[HBAD251_연차 현황·결재]] 계열 · 근로시간 마감(신규 사양서) | 신설 · 탭 존재+진입만 (코드 반영: 8b3e0a0) |
| 20 | 소속 필터 | Dropdown | • "소속" 드롭다운으로 팀 필터. 옵션(라이브): "전체 / 간호부 / 원무팀 / 진료부 / 총무팀 / 치료팀 / 스포츠재활 / 팀1 / 병동1 / 1팀" 등 • 선택 시: teamId 기준 목록 재조회 - CASE01 [값 없음]: "전체" 기본 | 목록 재조회 | s6 원문 |
| 25 | 기간 필터 | Segmented | • "이번 주 / 지난 1주 / 이번 달 / 지난 1개월 / 지난 3개월 / 전체" 6종 (s6 원문) • 선택 시: workDate 기준 재조회 | 목록 재조회 (date 기준) | 6종 |
| 30 | 출퇴근 기록 그리드 | Grid | • 직원별 출퇴근 기록 그리드. 컬럼(s6 원문): 사번 / 이름 / 소속 / 근무일 / 출근 시간 / 퇴근 시간 - CASE01 [기록 0건]: Empty state | attendances | 6컬럼 · TBU: Empty 원문 |
| ㄴ31 | 사번 | Cell | • 직원 사번 (read-only). 예: "bestrhrn267" | employees.employeeNumber | |
| ㄴ32 | 이름 | Cell | • 직원 성명. 예: "유채현" | employees.name | |
| ㄴ33 | 소속 | Cell | • 소속 팀. 미배정 시 "-" (라이브 관찰) | team_members / teams | 미배정 "-" |
| ㄴ33-1 | 근무형태 판정 출처 | Cell | • 그 기록의 근무형태가 어디서 정해졌는지를 표시(metadata.shiftSource)- 판정 순서: 근무표 → 직원 배정 → 그룹 → 조직 기본 근무형태 → 조직 기본 기준시간 - 값 없음: 출처 미기록(서비스 도입 이전 기록) 표기 = TBU • 근거: 근무형태를 읽는 경로가 넷(앱 출근·지문·연차·소정시간)으로 갈라져 있던 것을 판정 서비스 한 곳(shift-resolution.service)으로 모음 | attendances.metadata.shiftSource · [[HBAD200_직원 관리]] · [[HBEA200_근무 탭 (홈)]] | 신설 (코드 반영: c4eb0f9, #804) · 2026-09-25 실사: 근태 현황 근무 탭 목록 7컬럼(사번/이름/소속/근무일/출근 시간/퇴근 시간/휴가)에는 출처 컬럼 없음 실측 — 표시 위치(기록 상세/수정 모달 추정) 미확인, TBU 유지. 참고: 직원 관리 목록에서는 근무형태 셀 툴팁 둘째 줄 "배정 출처: {값}" 실측 · 2026-09-26 재실사: 행 클릭 상세 모달 없음·페이지 DOM에 출처 표기 없음 → 화면 미노출 가능성, 개발 확인 질의 대상 |
| ㄴ34 | 근무일 | Cell | • 근무일 (YYYY-MM-DD). 예: "2026-07-10" | attendances.date | |
| ㄴ35 | 출근 시간 | Cell | • 실제 출근 시각 (HH:MM). Secom punch 정규화. 예: "06:25" | attendances.actualCheckIn | Secom 원천 · 미기록 TBU |
| ㄴ36 | 퇴근 시간 | Cell | • 실제 퇴근 시각 (HH:MM). 미기록 시 "-" (라이브 관찰: "06:25 -") | attendances.actualCheckOut | 미기록 "-" |
| 37 | 다운로드 (기간 전체) | Button | • 현재 필터(소속·기간·검색) 조건의 전 직원 출퇴근 기록을 엑셀(.xlsx)로 내려받는 버튼. 라벨 "다운로드"(다운로드 중 "받는 중"). 「근로시간 마감」 탭과 동일 자리·스타일 • 클릭 시: 서버 목록을 1000건씩 이어받아 전체 저장. 파일명 "출퇴근기록_{from}_{to}.xlsx" - CASE01 [50,000건 초과]: 다운로드 전 차단 "기록이 {N}건이라 한 번에 받을 수 없어요. 기간을 나눠서 받아 주세요. (한 번에 50,000건까지)" - 엑셀 헤더(고정): 사번 / 이름 / 소속 / 근무일 / 요일 / 근무형태 / 출근 시간 / 퇴근 시간 / 휴게(시간) / 총 근무시간 / 휴가. 야간 퇴근 시각 뒤 " (익일)" | attendances (Secom 원천) · [[HBTM200_대시보드]] | 신설 (코드 반영: 6397f95) · 라이브 실사 확인(9/18: TM 임베드 근무 현황에 "다운로드" 노출) |
| 40 | 근태 수정 | Modal | • 출퇴근 시각을 수정하는 모달 (추정, 실화면 미오픈) • 저장 시: 정규화 레코드(attendances) 갱신, 원천 punch 불변(추정) - CASE01 ["수정 사유 *" 미입력]: 저장 불가(필수, 추정) • 모달 바디는 스크롤하지 않고 표 래퍼(.ds-table-scroll)가 세로 스크롤 컨테이너 — 컬럼 헤더(날짜·근무·출근 등) 고정 | attendances.actualCheckIn/Out · notes | 근태 수정 · 코드 반영(7c2eab6) · TBU: 실화면·실패 처리 |
| ㄴ41 | 수정 사유 | Input | • "수정 사유 *" 입력 (필수, 추정) • 입력 시: 값 반영 - CASE01 [미입력]: 저장 불가 | 감사 이력 부착 | 필수 · TBU |
| ㄴ42 | 수정 내역 | Output | • "수정 내역" — 수정 이력(누가·언제·무엇을·사유) 누적 표시 | 업무별 이력 | 이력 · TBU: 저장 위치(notes vs audit) |
| ㄴ43 | 익일 퇴근 체크박스 | Checkbox | • "퇴근 시간" 라벨 우측 "익일 퇴근" 체크박스. 기본 비활성(disabled), 출근보다 이른 퇴근 시각 입력 시 활성+자동 체크되어 익일 퇴근으로 계산됨을 표시 • 툴팁 "출근보다 이른 퇴근 시각을 입력하면 자동으로 익일 퇴근으로 처리돼요." • 기존 안내문 "출근보다 이른 시각 입력 시 익일(+1) 퇴근으로 처리됩니다." 제거 | attnEditIsNextDay() | 신설 (코드 반영: 7c2eab6) |
| ㄴ44 | 근무 시간 h:mm 입력·표기 | Input/Output | • 근무 시간 8개 구분 셀·합계를 소수("8.5") 대신 h:mm("8:30")으로 표기·입력. 소수 입력도 허용 — 저장 시 h:mm로 정규화. 합계 문구 "합계 8:30" (기존 "합계 8.5 시간" 제거) | fmtHM · attendanceEditForm.hours | h:mm 표기 (코드 반영: 7c2eab6) |
| 45 | 마감 확정 기간 근태 수정 차단 | Guard | • 근로시간 마감이 확정(마감)된 기간의 근태 기록은 생성·수정·근로시간 수정 불가(조회만 가능) - CASE01 [마감 확정 기간 근태 수정 시도]: 서버( assertWorkTimeNotClosed)가 FORBIDDEN 반환 — 메시지 "마감된 기간의 근태는 수정할 수 없습니다."• 판정 기준: 해당 직원의 확정 대상 중 마감 건 closingDate가 편집 대상 날짜 이상(>=)이면 잠금 | attendances(create/update) · worktime_closings · 근로시간 마감(신규 사양서) | 신설 · 마감 연동 (코드 반영: 8b3e0a0) · 클라이언트 피드백 표기 TBU |
| 50 | 3교대 휴일 시간 컬럼 조건 표시 | Cell | • 직원 근태 모달에서 휴일 시간 컬럼을 duty 여부에 따라 조건 표시 - CASE01 [일반 직원]: 휴일 시간 컬럼 노출 - CASE02 [3교대(duty) 직원]: 휴일 개념 미적용 — 휴일 시간을 일반/연장 계산으로 병합, 휴일 컬럼 조건 처리 | attendanceDutyMode (computed) · holidayHours | 신설 (코드 반영: a5b0975) · 세부 UI TBU |
| ㄴ51 | 직원 근태 모달 — 익일 퇴근 표기 | Cell | • 일별 표 퇴근 시각 뒤 익일 퇴근 시 표기를 기존 "(+1)" → "익일 퇴근" 문자 라벨로 변경 (checkOutDayOffset > 0 시) | checkOutDayOffset(r) | 표기 변경 (코드 반영: 7c2eab6) |
| ㄴ52 | 직원 근태 모달 — h:mm 표기 | Cell | • 일별 표 근무 시간 컬럼(휴일 일반/연장/야간/야간연장·합계·휴게)·외근 배지를 소수(8.5) 대신 h:mm(8:30)으로 표기. 외근 배지 "외근 8:30" | fmtHM(r.*) | h:mm 표기 (코드 반영: 7c2eab6) |
근태 상태·유형 (ERD 근거)
| 항목 | ERD 근거 | 값 | 비고 |
|---|---|---|---|
| status | attendances.status (attendances_status_enum, default scheduled) | TBU | enum 전체 값 미확인 |
| type | attendances.type (attendances_type_enum, default regular) | TBU | enum 전체 값 미확인 |
| 근무 시간 집계 | regularHours / overtimeHours / nightHours / weekendHours / holidayHours (numeric(5,2)) | - | 급여 근태 source |
| 3교대(duty) 처리 | attendanceDutyMode 등 computed 신설 — duty 직원은 휴일 개념 미적용, 휴일 시간을 일반/연장 계산으로 병합 | - | 코드 반영: a5b0975 (7/21 베스트 실무진 3교대 휴일 오적용 요구 반영) |
권한 · 상태 분기 요약
| 시나리오 | 트리거 | 결과 화면 | 비고 |
|---|---|---|---|
CASE01 [조회] | 조건2 [근태 조회] 진입 | 4탭 열람, 수정 버튼 노출 여부 TBU | |
CASE02 [팀 한정] | 조건3 [근태 조회 (팀)] | 본인 팀 기록만 노출 (추정) | scope 제한 |
CASE03 [수정] | 조건1 [근태 수정] | 근태 수정 모달 활성 (추정) | |
CASE04 [미인증] | 세션 없음 | /admin/signin |
Open Question
- 유형·기준 관리 모달 내부 구성 (라이브 프로브 미오픈, s3-attend
TAB_NOT_FOUND). TBU. - attendances_status_enum / type_enum 전체 값. TBU.
- 근태 수정 모달 실화면 (필드·"수정 사유 *" 필수 여부·저장 동작). TBU.
- 근무 탭 Empty state 원문 문구. TBU.
- Secom 원천 punch 대조 UI 노출 방식. TBU.