GPS 출퇴근 스펙

GPS 출퇴근은 직원이 지정된 근무지 반경 내에 위치할 때만 출퇴근 체크를 허용하는 기능이다. 근태 관리 스펙의 하위 기능으로, GPS 위치 검증 로직과 실패 시 관리자 승인 워크플로를 포함한다.

GPS 정확도 및 타임아웃

• 정확도: ±35m 범위의 GPS 정확도를 기반으로 근무지 반경 설정
• 고정확도 모드 타임아웃: 기존 8초 → 15초로 확대 [fix-task-0622.md]
• 원인: 삼성 브라우저 등에서 GPS 칩 응답 전 타임아웃 발생
• 폴백: WiFi/IP 기반 저정확도 위치로 전환 시 "WiFi/네트워크 기반으로 위치 확인 중" 안내 메시지 추가 [fix-task-0622.md]
• 확인 필요: 삼성 브라우저에서 재확인 필요 [fix-task-0622.md]

체크인 반경 설정

• 필수 항목: 근무지 설정 후 체크인 반경(검증 거리)을 반드시 사전 설정해야 함
• 기본값: 체크 반경 기본 100m로 세팅 [fix-taskNew-0702 (26년 07월 02일 우선수정사항)]
• 초기 설정 시 허용 방법: 출퇴근 GPS만 사용, 나머지 방법은 막아두기 [fix-taskNew-0702 (26년 07월 02일 우선수정사항)]
• 근무지 안내 배너: 근무지 이름 및 좌표가 등록되지 않으면 안내 배너 유지 [fix-taskNew-0702 (26년 07월 02일 우선수정사항)]
• 미설정 시 동작: withinRadius 검사 결과가 null로 표시되며, 출퇴근이 정상 처리되지 않음

IP 폴백 및 정확도 기반 폴백 (0803 신규)

GPS 미확보 또는 저정밀 GPS인 경우 IP 인증으로 자동 전환하는 로직이 추가되었다. [fix-task 0803 — 수정완료 항목]

• 트리거 조건: GPS 미확보(!myGps) 또는 GPS 정확도가 임계값 초과
• 임계값 기준: 근무지의 gps_required_accuracy 설정값 우선, 없으면 기본 200m
• 데스크톱 WiFi 저정밀 좌표(±수백~수천m)도 IP 폴백 대상
• 동작: allowed_ips가 있는 근무지라면 auth_methods에 "IP"가 없어도 "IP로 출퇴근" 노출·기본 선택
• 안내 배너: "GPS 정확도가 낮아(±Xm) 사내망 IP로 …" 메시지 표시
• 백엔드 검증: 서버가 client_ip ∈ allowed_ips 검증 (백엔드 무변경, 기존 하드닝 그대로 커버)
• 하드닝: 명시 IP 경로인데 allowed_ips 없으면 ATT_IP_NO_ALLOWLIST 오류로 거절 [fix-task 0803 — 수정완료 항목]

외부 IP 캡처 및 IP 인증 보안 (0803)

[fix-task 0803 — 수정완료 항목]

• 외부 IP만 캡처: get_client_ip가 공인 IP만 잡히도록 구현 완료
• IP 인증 fail-closed (후속·미완료): allowed_ips 매칭에서 공인 IP를 못 잡으면(사설/내부홉이면) IP 인증 422 처리
• 위치: attendance_service check_in(3567)·check_out(3708)에 _is_private_ip(client_ip) 조건 추가 예정
• 전제: get_client_ip 공인 복구가 실제로 되는지 검증 완료 후 활성화(미검증 시 사무실 WiFi 모바일 IP 출근까지 차단될 수 있음)
• 관리자는 공인 IP만 등록 가능

[fix-task 0803 — 수정완료 항목] [fix-task-0622.md]

퇴근 플로우

• 반경 내: 직접 퇴근 처리
• 반경 외: 출근과 동일하게 관리자 승인 워크플로 진입 [fix-task-0622.md]
• 동작: CheckInLocationSheet 다이얼로그 표시, 내부 텍스트는 출근/퇴근 상황에 맞게 동적 표시 [fix-task-0622.md]
• IP 폴백 대칭: 출근과 동일하게 퇴근 시에도 GPS 저정밀 → IP 폴백 적용 [fix-task 0803 — 수정완료 항목]

버그 및 개선 완료

확인 필요 항목

• 삼성 브라우저에서 GPS 고정확도 타임아웃 15초 재확인 [fix-task-0622.md]
• 삼성 브라우저 다크 테마 이슈 [fix-task-0622.md]
• 출퇴근 GPS 사용을 위한 브라우저 위치 허용 팝업 띄우기 (중요) [fix-taskNew-0702 (26년 07월 02일 우선수정사항)]

• 현상: PC 환경에서 "출근하기" 버튼이 비활성화되어 출근 등록 불가 [fix-task-0701 (26년 07월 01일 수정사항)]
• 원인 분석: 백엔드는 GPS 없이 출근을 허용하지만, 프론트엔드에서 GPS 좌표를 필수 조건으로 처리하여 CTA 버튼 비활성화 [fix-task-0701 (26년 07월 01일 수정사항)]
• PC GPS 한계: PC는 WiFi/IP 기반 위치 측정으로 정확도가 낮음 [fix-task-0701 (26년 07월 01일 수정사항)]
• 현재 폴백: GPS 실패 시 "출퇴근 요청하기" fallback 존재 [fix-task-0701 (26년 07월 01일 수정사항)]
• 개선 방향: checkin_radius 확대 또는 PC 전용 위치 우회 방식 도입 고려 필요 [fix-task-0701 (26년 07월 01일 수정사항)]

• 브라우저 위치 권한 미부여 여부 포함 재확인 필요 [fix-task-0701 (26년 07월 01일 수정사항)]

PC 출퇴근 위치 권한 안내 개선 (07.20)

• 수정 완료: 위치 권한이 허용되지 않았을 때, 안내 문구와 [위치 권한 요청]·[허용 방법 보기] 버튼을 항상 표시하도록 개선 [fix0720.md]
• 권한이 차단된 경우, 허용하는 방법을 단계별로 알려주는 안내창 추가 [fix0720.md]
• 참고: 브라우저 특성상 한 번 차단한 위치 권한은 자동으로 되돌릴 수 없으므로, 사용자가 직접 허용하도록 안내하는 방식으로 처리 [fix0720.md]

• 요구사항: 출장이 잦은 직원도 GPS로 출근 가능하되, 출근하기 누르면 현재 위치가 저장되도록 처리 [fix-taskNew-0702 (26년 07월 02일 우선수정사항)]
• 관련 스펙: 출장 관리 스펙 (신청·승인·근태 자동생성)

• 구현 완료: 출근하기 누르면 현재 위치가 저장되도록 구현 [fix-task-0703 (26년 07월 03일 수정사항)] [fix-taskNew-0706 (26년 07월 06일 우선수정사항)]

배경 및 수정 내용

관리자 근태 화면 표기 기준

• 당일 근로 정책: 정책에 설정된 시간
• 인정근로시간: 실제 근로 시간 (연장근무·관리자 수정 등 반영) [fix0720.md]

진행 중 항목

• 수정 중: 출퇴근관리 > 직원 상세에서 연장시간이 당일 근로정책에 맞춰 계산되어 올바르지 않게 보이는 현상 [fix0720.md]
• 구현 중: 근로정책 변경 시 사용자/모바일 모드에서도 관리자 모드처럼 기존 정책 유지 + 변경일 기준 수정 적용 (현재는 사용자·모바일에서 모든 정책이 새 정책으로 일괄 변경됨) [fix0720.md]

기본 출퇴근 결재선 자동 생성 및 보호

• 자동 생성: 서버 시작 시 checkin_approval_line_id가 NULL인 테넌트에 기본 결재선 자동 생성 [fix-task-0622.md]
• 삭제 차단: 기본 결재선 삭제 불가 — 삭제 시 "기본 출퇴근 결재선은 삭제할 수 없습니다" toast-notification-spec 표시 [fix-task-0622.md]

2026-07-29 기준 RN 앱과 웹모바일뷰의 출퇴근 인증방식에 실사용 차단 수준의 격차가 확인되었다. 상세 내용은 RN 앱 vs 웹모바일뷰 기능 격차 비교 참조. [RN 앱 ↔ 웹모바일뷰 기능 격차 감사 (0729)]

현황

• 웹모바일: CheckInLocationSheet.tsx에서 GPS / QR / IP(사내망) 3가지 방식 선택 지원
• RN 앱: CheckInSheet.tsx:161에서 check_in_method:'GPS' 하드코딩 — QR·IP 경로 전무

누락 항목 상세

[RN 앱 ↔ 웹모바일뷰 기능 격차 감사 (0729)]

착수 권장 (최우선)

RN CheckInSheet에 인증방식 선택 UI + QR 스캔(카메라) + IP 경로 추가. 근무지 auth_methods 및 allowed_ips 소비. 웹모바일 CheckInLocationSheet 로직 이식 기준. [RN 앱 ↔ 웹모바일뷰 기능 격차 감사 (0729)]

플랜별 메뉴 접근 제한 설계 및 요금제 시스템 구현 설계와 연관된 보안 수정이 0803에 함께 적용되었다. [fix-task 0803 — 수정완료 항목]

• 백엔드 메뉴 게이팅 전역 버그 수정: /admin 단독 키가 모든 /admin/* 상위경로로 처리되던 문제 → 정확일치만(k != "/admin" 가드)으로 수정. 대시보드-only 관리자가 API 직접 호출로 전 admin API에 접근 가능하던 보안 취약점 차단.
• 정산 API 게이팅: _MENU_PREFIXES에 /admin/billing 추가(menu_enforcement.py). 최고관리자 기본 노출, 타 관리자는 역할관리에서 부여/회수.
• 대시보드 역할별 렌더: 권한 없는 도메인 위젯이 403 오류로 표시되던 문제 → 전 위젯 + HERO 근태 viz를 menu_keys로 게이팅(없으면 fetch·렌더 안 함).

• 근태 관리 스펙 — 기본 출퇴근 관리 프레임
• 교대(변형)근로 관리 스펙 — 변형근무 설정 시 근무지 및 시간 연동
• 결재 관리 스펙 — GPS 실패 시 관리자 승인 요청 워크플로
• 근무 정책 스펙 — 근무지별 GPS 반경 기준 설정
• 모바일 UI/UX 개선 작업 — 모바일 환경 실제 출퇴근 시간 표시
• 모바일 앱 스펙 — GPS 출퇴근의 핵심 사용자 인터페이스
• RN 앱 vs 웹모바일뷰 기능 격차 비교 — QR·IP 인증방식 미구현 등 GPS 출퇴근 격차 전수 감사
• 토스트 알림 공통 컴포넌트 스펙 — 결재선 삭제 실패 등 사용자 피드백
• 플랜별 메뉴 접근 제한 설계 — 메뉴 게이팅 보안 관련
• 요금제 시스템 구현 설계 — 정산 메뉴 접근 제어 연계
• 초기 설정 가이드 구조 개편 스펙 — 초기 설정 완료 후 바로가기 연계
• fix-task-0701 — PC 출근 버튼 비활성화 이슈 및 개선 방향
• fix-taskNew-0702 — 체크 반경 기본값 100m, 브라우저 위치 허용 팝업, 출장자 GPS 위치 저장
• fix-task-0703 — 출장자 GPS 위치 저장 구현 완료
• fix-taskNew-0706 — 출장 잦은 직원 GPS 출근 현재 위치 저장 미완료 항목
• fix0720.md — PC 출퇴근 위치 권한 안내 개선, 근로정책 변경 시 인정시간 소급 적용 수정
• fix-task 0803 — IP 폴백·정확도 폴백·외부 IP 캡처·메뉴 게이팅 수정

GPS 출퇴근 기능은 모바일 앱 스펙의 핵심 입력 기능이며, 정확도 기반 근무지 반경 설정과 타임아웃 최적화가 데이터 신뢰성을 좌우한다. 0803 업데이트로 GPS 저정밀 환경(데스크톱 WiFi 등)에서도 IP 폴백이 자동 적용되어 출퇴근 실패율이 크게 낮아졌다. IP 인증 fail-closed(사설 IP 차단) 기능은 공인 IP 복구 검증 완료 후 별도 활성화 예정이다.