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-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

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) • 선택 시: 해당 탭 뷰 전환 + 우상단 설정 버튼 라벨 전환 　- 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)
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	미배정 "-"
ㄴ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	미기록 "-"
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
ㄴ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.