sam-react-prod/claudedocs/hr/[IMPL-2025-12-16] mobile-attendance.md

모바일 출퇴근 시스템 구현 체크리스트

Last Updated: 2025-12-18

개요

• 목적: 모바일 기기에서 GPS 기반 출퇴근 기록
• 대상: 특정 사용자 (하드코딩)
• 조건: 지정된 현장 좌표 100m 반경 내에서만 출퇴근 가능

기술 스택

• 지도 API: Google Maps JavaScript API (카카오맵에서 변경)
• API 키: .env.local에 NEXT_PUBLIC_GOOGLE_MAPS_API_KEY 저장
• 현장 좌표: 37.557358, 126.864414 (본사)
• 반경: 100m

---

Phase 1: 환경 설정 ✅

• Google Maps API 키 .env.local에 추가
• @types/google.maps 패키지 설치

Phase 2: 페이지 구조 ✅

• /hr/attendance 라우트 생성 (기존 protected 레이아웃 활용)
• 모바일 전용 레이아웃 (AuthenticatedLayout 모바일 모드 활용)
• 페이지 컴포넌트 기본 구조

Phase 3: 지도 컴포넌트 ✅

• GoogleMap 컴포넌트 생성 (src/components/attendance/GoogleMap.tsx)
• 현장 좌표에 100m 파란 원(Circle) 표시
• 현재 위치 마커 표시 (빨간색)
• GPS watchPosition으로 실시간 위치 추적
• 개발 환경 GPS 시뮬레이션 (localhost에서 본사 근처 50m로 자동 설정)

Phase 4: 출퇴근 로직 ✅

• GPS 거리 계산 함수 (Haversine formula)
• 100m 반경 체크 → 버튼 활성화/비활성화
• 출근 상태 관리 (출근전/출근중/퇴근완료)
• 현재 시간 실시간 표시

Phase 5: 완료 화면 ✅

• 출근 완료 화면 구현 (src/components/attendance/AttendanceComplete.tsx)
  • ✓ 체크 아이콘
  • "출근 완료" 텍스트 (빨간색)
  • 시간 표시 (HH:MM:SS)
  • 날짜 표시 (YYYY년 MM월 DD일 요일)
  • 위치 표시 (본사)
  • 확인 버튼
• 퇴근 완료 화면 구현 (동일 컴포넌트 재사용)

Phase 6: 모바일 감지 & 리다이렉트 ⏳

• User-Agent 기반 모바일 감지
• 특정 사용자 하드코딩 체크
• 로그인 후 자동 리다이렉트 로직
• 별도 모바일 레이아웃 (헤더/사이드바 제거)
• 웹에서 접근 차단 (모바일 전용)

Phase 7: API 연동 ⏳

• 출퇴근 기록 API 설계
• 출근 API (POST /api/attendance/check-in)
• 퇴근 API (POST /api/attendance/check-out)
• 오늘 출퇴근 상태 조회 API (GET /api/attendance/today)
• 현장 좌표 API에서 가져오기 (하드코딩 제거)

Phase 8: 사용자 정보 연동 ⏳

• 로그인 사용자 정보 연동 (TEST_USER 제거)
• 출퇴근 가능 사용자 권한 체크
• 현장별 사용자 배정 로직

---

생성된 파일

파일	설명
src/components/attendance/GoogleMap.tsx	Google Maps 컴포넌트 (원, 마커, GPS 추적)
src/components/attendance/AttendanceComplete.tsx	출퇴근 완료 화면
src/app/[locale]/(protected)/hr/attendance/page.tsx	출퇴근 메인 페이지

---

테스트 URL

http://localhost:3000/ko/hr/attendance

모바일 테스트: Chrome DevTools → Toggle Device Toolbar (Ctrl+Shift+M)

---

하드코딩 설정값 (추후 API로 대체 필요)

// 현장 좌표 (본사) - page.tsx:12-17
const SITE_LOCATION = {
  name: '본사',
  lat: 37.557358,
  lng: 126.864414,
  radius: 100, // meters
};

// 테스트용 사용자 정보 - page.tsx:19-23
const TEST_USER = {
  name: '홍길동',
  department: '부서명',
  position: '직급명',
};

---

개발 중 해결한 이슈

1. Hydration 에러

• 원인: 서버/클라이언트 HTML 불일치 (Date, localStorage 등)
• 해결: mounted 상태 체크 + suppressHydrationWarning 속성

2. Google Maps API 중복 로드

• 원인: React 컴포넌트 리렌더링 시 스크립트 중복 추가
• 해결: window.googleMapsLoading 플래그 + 기존 스크립트 체크

3. GPS 권한 거부 (localhost)

• 원인: HTTPS가 아닌 환경에서 GPS 권한 제한
• 해결: 개발 환경 감지 후 테스트 좌표로 시뮬레이션

const isDevelopment =
  hostname === 'localhost' ||
  hostname === '127.0.0.1' ||
  hostname.startsWith('192.168.') ||
  process.env.NODE_ENV === 'development';

---

UI 스펙 (스크린샷 기반)

출퇴근 메인 화면

┌─────────────────────────────┐
│  <  🏠  ⚙️⚙️⚙️  ☰          │  ← 헤더 (AuthenticatedLayout)
├─────────────────────────────┤
│        출퇴근하기            │  ← 타이틀
├─────────────────────────────┤
│                             │
│    ┌───────────────────┐    │
│    │                   │    │
│    │   🔵 (100m 원)    │    │  ← Google Maps
│    │      📍          │    │
│    │                   │    │
│    └───────────────────┘    │
│                             │
├─────────────────────────────┤
│  👤 홍길동                   │
│     부서명 직급명            │
│                             │
│     08:43:15 (빨간색)       │  ← 실시간 시간
├─────────────────────────────┤
│  [  출근하기  ] [  퇴근하기  ]│  ← 버튼
└─────────────────────────────┘

완료 화면

┌─────────────────────────────┐
│  <  🏠  ⚙️⚙️⚙️  ☰          │
├─────────────────────────────┤
│        출근하기              │
├─────────────────────────────┤
│                             │
│           ✓                 │  ← 체크 아이콘 (원형)
│                             │
│       출근 완료              │  ← 빨간색
│       08:43:15              │
│                             │
│    2025년 12월 15일 (월)    │
│                             │
│    📍 본사                   │
│                             │
├─────────────────────────────┤
│        [  확인  ]            │
└─────────────────────────────┘

---

다음 작업 TODO

1. Phase 6 진행: 모바일 전용 레이아웃 + User-Agent 감지
2. API 설계: 백엔드 팀과 출퇴근 API 협의
3. 테스트: 실제 모바일 기기에서 GPS 테스트 (HTTPS 환경)

---

참고 사항

• MVP 버전: API 연동 없이 하드코딩으로 동작 확인 (현재 상태)
• 추후 개선: 출퇴근 기록 API, 현장 좌표 DB 저장, 사용자 권한 체크
• Phase 6 (모바일 감지 & 리다이렉트)는 MVP 테스트 후 진행