TK-FB-Project/개발로그/2026-01-19_계정통합_연차출근관리.md

작업자-계정 통합 및 연차/출근 관리 시스템 구축

작업 일시

2026-01-19

작업 개요

작업자와 계정을 1:1로 통합하여 모든 작업자가 개인 계정으로 로그인해서 본인의 연차 정보, 출근 기록, 근무 시간 통계를 확인할 수 있는 시스템을 구축했습니다.

주요 변경사항

1. 데이터베이스 마이그레이션

1.1 Workers 테이블 확장 (20260119120000)

• salary DECIMAL(12,2) NULL - 급여 정보 (선택 사항)
• base_annual_leave INT DEFAULT 15 - 기본 연차 일수

1.2 출근/근태 관련 테이블 생성 (20260119120001)

• work_attendance_types: 출근 유형 (정상, 지각, 조퇴, 결근, 휴가)
• vacation_types: 휴가 유형 (연차, 반차, 병가, 경조사)
• daily_attendance_records: 일일 출근 기록
• worker_vacation_balance: 작업자 연차 잔액 (연도별)

1.3 기존 작업자 계정 자동 생성 (20260119120002)

• 계정이 없는 기존 작업자들에게 자동으로 users 테이블 계정 생성
• Username: 이름 기반 자동 생성 (예: 홍길동 → hong.gildong)
• 초기 비밀번호: "1234" (첫 로그인 시 변경 권장)
• 현재 연도 연차 잔액 자동 초기화

1.4 게스트 역할 추가 (20260119120003)

• Guest 역할 추가 (계정 없이 특정 기능 접근 가능)
• 게스트 전용 페이지 추가 (신고 채널)

2. 백엔드 API 구현

2.1 한글→영문 변환 유틸리티

• 파일: api.hyungi.net/utils/hangulToRoman.js
• 한글 이름을 로마자로 변환 (예: 홍길동 → hong.gildong)
• 중복 username 자동 처리 (hong.gildong2, hong.gildong3...)
• 국립국어원 표기법 기준 적용

2.2 UserRoutes API 확장

• 파일: api.hyungi.net/routes/userRoutes.js
• 개인 정보 조회 API 추가 (관리자 권한 불필요):
  • GET /api/users/me - 내 정보
  • GET /api/users/me/attendance-records - 내 출근 기록
  • GET /api/users/me/vacation-balance - 내 연차 잔액
  • GET /api/users/me/work-reports - 내 작업 보고서
  • GET /api/users/me/monthly-stats - 내 월별 통계

3. 프론트엔드 구현

3.1 나의 대시보드 페이지

• 파일: web-ui/pages/profile/my-dashboard.html
• JS: web-ui/js/my-dashboard.js
• CSS: web-ui/css/my-dashboard.css

구성 요소:

1. 사용자 정보 카드: 부서, 직책, 입사일
2. 연차 정보 위젯: 총 연차, 사용, 잔여 + 프로그레스 바
3. 월별 출근 캘린더: 날짜별 출근 상태 (정상/지각/휴가/결근)
4. 근무 시간 통계: 이번 달 총 근무 시간 및 근무 일수
5. 최근 작업 보고서: 최근 7일간의 작업 보고서 목록

3.2 네비게이션 바 메뉴 추가

• 파일: web-ui/components/navbar.html
• 드롭다운 메뉴에 "나의 대시보드" 링크 추가
• 위치: 프로필 메뉴 최상단

핵심 기능

1. 작업자-계정 1:1 통합

• 모든 작업자는 로그인 계정 필요
• 작업자 등록 시 자동으로 계정 생성
• Username은 이름 기반으로 자동 생성
• 기존 작업자들에게는 마이그레이션으로 일괄 계정 생성

2. 연차 관리

• 연도별 연차 잔액 관리
• 총 연차, 사용 연차, 잔여 연차 자동 계산
• 휴가 사용 시 자동 차감
• 휴가 유형별 차감 일수 설정 (연차: 1일, 반차: 0.5일)

3. 출근 기록

• 일일 출근 상태 기록 (정상/지각/조퇴/결근/휴가)
• 출근/퇴근 시간 기록
• 총 근무 시간 자동 계산
• 초과근무 승인 기능

4. 개인 대시보드

• 본인의 연차, 출근, 근무 시간만 조회 가능
• 월별 캘린더 형태로 출근 현황 시각화
• 실시간 통계 제공

배포 절차

1. 마이그레이션 실행

cd api.hyungi.net
npm run migrate:latest

실행 순서:

1. 20260119120000_add_worker_fields.js
2. 20260119120001_create_attendance_tables.js
3. 20260119120002_create_accounts_for_existing_workers.js
4. 20260119120003_add_guest_role.js

2. 초기 비밀번호 안내

• 자동 생성된 계정의 초기 비밀번호: 1234
• 모든 작업자에게 첫 로그인 후 비밀번호 변경 안내 필요

3. 프론트엔드 배포

• 브라우저 캐시 클리어 필요 (Ctrl+F5)
• 새로운 CSS 파일 배포 확인

테스트 시나리오

1. 기존 작업자 계정 생성 확인

SELECT u.username, u.name, w.worker_name
FROM users u
JOIN workers w ON u.worker_id = w.worker_id;

2. 작업자 로그인 테스트

1. 자동 생성된 username으로 로그인
2. 초기 비밀번호 "1234" 입력
3. 비밀번호 변경

3. 나의 대시보드 접근

1. 로그인 후 프로필 드롭다운 클릭
2. "나의 대시보드" 메뉴 클릭
3. 연차 정보, 출근 캘린더, 통계 확인

보안 및 권한

1. 본인 데이터만 조회 가능

• JWT에서 req.user.worker_id 추출
• API에서 본인 데이터만 필터링
• 다른 작업자 데이터 조회 시도 시 403 에러

2. 관리자 권한

• 관리자는 모든 작업자의 정보 조회 가능
• 기존 /api/users/* 엔드포인트는 관리자 전용 유지

향후 개선 계획

1. WorkerController 수정

   • 작업자 등록 시 자동 계정 생성 기능 추가
   • 작업자 관리 페이지에서 계정 정보 함께 관리

2. 연차 초기화 스케줄러

   • 매년 1월 1일 자동 연차 리셋
   • 전년도 잔여 연차 이월 로직

3. 출근 기록 자동 동기화

   • daily_work_reports와 daily_attendance_records 자동 동기화
   • 작업 보고서 입력 시 자동으로 출근 기록 생성

4. 대시보드 차트 추가

   • Chart.js를 활용한 근무 시간 그래프
   • 월별/주별 근무 시간 추이
   • 프로젝트별 작업 시간 분포

파일 목록

백엔드

• api.hyungi.net/db/migrations/20260119120000_add_worker_fields.js
• api.hyungi.net/db/migrations/20260119120001_create_attendance_tables.js
• api.hyungi.net/db/migrations/20260119120002_create_accounts_for_existing_workers.js
• api.hyungi.net/db/migrations/20260119120003_add_guest_role.js
• api.hyungi.net/utils/hangulToRoman.js
• api.hyungi.net/routes/userRoutes.js (수정)

프론트엔드

• web-ui/pages/profile/my-dashboard.html
• web-ui/js/my-dashboard.js
• web-ui/css/my-dashboard.css
• web-ui/components/navbar.html (수정)

문서

• 개발로그/2026-01-19_계정통합_연차출근관리.md

주의사항

1. 마이그레이션 rollback 주의

   • 계정 자동 생성 마이그레이션은 rollback 권장하지 않음
   • 필요시 수동으로 users 테이블 관리

2. 초기 비밀번호 보안

   • 모든 작업자가 동일한 초기 비밀번호 사용
   • 반드시 첫 로그인 후 변경하도록 안내

3. 급여 정보

   • salary 컬럼은 NULL 허용 (선택 사항)
   • 급여 정보는 민감 정보이므로 접근 제어 필요

관련 이슈

• 작업자-계정 분리로 인한 불편함 해소
• 작업자들의 개인 정보 조회 요구사항
• 연차 관리 시스템 필요성
• 출근 기록 추적 필요성