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. 마이그레이션 실행
```bash
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. 기존 작업자 계정 생성 확인
```sql
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 허용 (선택 사항)
   - 급여 정보는 민감 정보이므로 접근 제어 필요

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