TK-FB-Project/docs/vacation-data-flow-guide.md

휴가 데이터 흐름 가이드

작성일: 2026-02-05 목적: 휴가 관련 데이터 저장 구조 및 연동 방식 문서화

---

1. 테이블 구조

1.1 vacation_balance_details (연간 휴가 잔액)

목적: 작업자별 연간 휴가 발생/사용 일수 관리

컬럼	설명	예시
worker_id	작업자 ID	1
vacation_type_id	휴가 유형 ID (vacation_types 참조)	1 (이월), 2 (정기연차)
year	연도	2026
total_days	발생 일수	15
used_days	사용 일수 (자동 연동)	3
remaining_days	잔여 일수 (자동 계산 컬럼)	12

1.2 daily_attendance_records (일별 근태 기록)

목적: 일별 출근/휴가/근무시간 기록

컬럼	설명	예시
worker_id	작업자 ID	1
record_date	기록 날짜	2026-02-05
attendance_type_id	근태 유형 (1=정상, 2=지각, 3=조퇴, 4=결근, 5=휴가)	5
vacation_type_id	휴가 사용 유형 (1=연차, 2=반차, 3=반반차)	1
total_work_hours	총 근무시간	8.0

1.3 vacation_types (휴가 유형 마스터)

목적: 휴가 유형 정의 및 차감 우선순위

type_code	type_name	priority	용도
CARRYOVER	이월	1	작년 이월 연차
ANNUAL	정기연차	2	올해 발생 연차
LONG_SERVICE	장기근속	3	장기근속 보상
WEDDING	결혼	4	경조사
SPOUSE_BIRTH	배우자 출산	4	경조사
...	...	4	기타 경조사

---

2. 데이터 흐름

┌─────────────────────────────────────────────────────────────────┐
│                      휴가 데이터 흐름도                           │
└─────────────────────────────────────────────────────────────────┘

[annual-overview.html]                    [work-status.html]
연간 연차 현황 페이지                       근무 현황 페이지
       │                                        │
       │ 발생 일수 입력                          │ 휴가 사용 기록
       │ (이월, 정기연차, 장기근속, 경조사)        │ (연차/반차/반반차)
       ▼                                        ▼
┌──────────────────┐                    ┌──────────────────┐
│ vacation_balance │◀───── 연동 ───────│ daily_attendance │
│ _details         │                    │ _records         │
│                  │                    │                  │
│ total_days: 15   │    used_days      │ vacation_type_id │
│ used_days: 3  ◀──┼──── 자동 업데이트 ──┼── 1 (연차)       │
│ remaining: 12    │                    │                  │
└──────────────────┘                    └──────────────────┘

---

3. 연동 로직

3.1 휴가 사용 시 (work-status.html에서 저장)

파일: api.hyungi.net/services/attendanceService.js

// upsertAttendanceRecordService 함수 내부

// 1. 기존 기록 조회
const existingRecord = await AttendanceModel.getDailyAttendanceRecords(record_date, worker_id);

// 2. 휴가 사용 유형 → 차감 일수 변환
//    vacation_type_id: 1=연차(1일), 2=반차(0.5일), 3=반반차(0.25일)
const daysMap = { 1: 1, 2: 0.5, 3: 0.25 };
const newDays = daysMap[vacation_type_id] || 0;

// 3. 이전 휴가가 있었으면 복구 (변경된 경우)
if (previousDays > 0) {
  await vacationBalanceModel.restoreByPriority(worker_id, year, previousDays);
}

// 4. 새 휴가 차감 (우선순위: 이월 → 정기연차 → 장기근속 → 경조사)
if (newDays > 0) {
  await vacationBalanceModel.deductByPriority(worker_id, year, newDays);
}

3.2 차감 우선순위 로직

파일: api.hyungi.net/models/vacationBalanceModel.js

// deductByPriority 함수

// 1. 우선순위순으로 잔여 일수가 있는 잔액 조회
SELECT * FROM vacation_balance_details vbd
INNER JOIN vacation_types vt ON vbd.vacation_type_id = vt.id
WHERE vbd.worker_id = ? AND vbd.year = ?
  AND (vbd.total_days - vbd.used_days) > 0
ORDER BY vt.priority ASC  -- 이월(1) → 정기연차(2) → 장기근속(3) → 경조사(4)

// 2. 순서대로 차감
for (const balance of balances) {
  const available = balance.remaining_days;
  const toDeduct = Math.min(remaining, available);

  UPDATE vacation_balance_details
  SET used_days = used_days + ?
  WHERE id = ?
}

---

4. 주요 파일 위치

api.hyungi.net/
├── models/
│   ├── vacationBalanceModel.js   # 휴가 잔액 DB 쿼리
│   │   ├── deductByPriority()    # 우선순위 차감 ★
│   │   └── restoreByPriority()   # 우선순위 복구 ★
│   └── attendanceModel.js        # 근태 기록 DB 쿼리
│
├── services/
│   └── attendanceService.js      # 근태 저장 비즈니스 로직
│       └── upsertAttendanceRecordService()  # 연동 로직 포함 ★
│
├── controllers/
│   ├── vacationBalanceController.js  # 휴가 잔액 API
│   └── attendanceController.js       # 근태 API
│
└── routes/
    ├── vacationBalanceRoutes.js
    └── attendanceRoutes.js

web-ui/pages/attendance/
├── annual-overview.html    # 연간 연차 현황 (발생 일수 입력) - 관리자 전용
├── my-vacation-info.html   # 내 연차 정보 (잔여 확인 + 연장근로) - 전체 사용자 ★
├── work-status.html        # 근무 현황 (휴가 사용 기록)
└── monthly.html            # 월별 출근부 (조회 전용)

---

5. API 엔드포인트

5.1 휴가 잔액 관련

Method	Endpoint	설명
GET	/vacation-balances/year/:year	연도별 전체 잔액 조회
GET	/vacation-balances/worker/:workerId/year/:year	작업자별 잔액 조회
POST	/vacation-balances/bulk-upsert	일괄 저장 (연간 연차 현황)

5.2 근태 기록 관련

Method	Endpoint	설명
POST	/attendance/records	근태 기록 저장 (휴가 연동 포함)
GET	/attendance/records?date=&worker_id=	근태 기록 조회

---

6. 차감 일수 매핑

6.1 휴가 사용 유형 (daily_attendance_records.vacation_type_id)

ID	유형	차감 일수
1	연차 (ANNUAL_FULL)	1일
2	반차 (ANNUAL_HALF)	0.5일
3	반반차 (ANNUAL_QUARTER)	0.25일

6.2 근태 유형 (daily_attendance_records.attendance_type_id)

ID	유형	설명
1	NORMAL	정상 출근
2	LATE	지각
3	EARLY_LEAVE	조퇴
4	ABSENT	결근
5	VACATION	휴가

---

7. 주의사항

7.1 휴가 잔액이 없는 경우

• 잔액이 없어도 근태 기록은 저장됨
• 콘솔에 경고 로그 출력
• 관리자가 연간 연차 현황에서 발생 일수를 먼저 입력해야 함

7.2 휴가 수정 시

• 기존 휴가 → 복구 (restoreByPriority)
• 새 휴가 → 차감 (deductByPriority)
• 연차 → 반차 변경 시: 1일 복구 → 0.5일 차감

7.3 복구 우선순위

• 차감 우선순위의 역순으로 복구
• 마지막에 차감된 유형부터 먼저 복구
• 예: 경조사(4) → 장기근속(3) → 정기연차(2) → 이월(1)

---

8. 테스트 시나리오

8.1 기본 플로우

1. [연간 연차 현황] 김철수에게 정기연차 15일 입력 → 저장
2. [근무 현황] 2026-02-05에 김철수 연차 선택 → 저장
3. [연간 연차 현황] 새로고침 → 총 사용: 1일, 잔여: 14일 확인

8.2 수정 플로우

1. [근무 현황] 기존 연차(1일) → 반차(0.5일)로 변경 → 저장
2. [연간 연차 현황] 새로고침 → 총 사용: 0.5일, 잔여: 14.5일 확인

8.3 우선순위 테스트

1. [연간 연차 현황] 이월 2일, 정기연차 15일 입력
2. [근무 현황] 연차 3회 사용 (3일)
3. [연간 연차 현황] 확인:
   • 이월: 2일 발생, 2일 사용, 0일 잔여
   • 정기연차: 15일 발생, 1일 사용, 14일 잔여

---

9. 내 연차 정보 페이지 (my-vacation-info.html)

9.1 기능

• 연차 잔여 현황: 유형별(이월, 정기연차, 장기근속, 경조사) 잔여 일수 표시
• 월간 연장근로: 선택한 월의 연장근로 시간 및 일별 상세

9.2 접근 권한

사용자 유형	기능
일반 사용자	본인 정보만 조회 (user.worker_id 기준)
관리자	작업자 선택하여 조회 가능

9.3 연장근로 계산 로직

// daily_attendance_records에서 8시간 초과분 합산
records.forEach(r => {
  const hours = parseFloat(r.total_work_hours) || 0;
  if (hours > 8) {
    totalOvertimeHours += (hours - 8);
  }
});

9.4 메뉴 위치

• 근태 관리 > 내 연차 정보 (최상단)

---

10. 향후 개선 사항

• 휴가 신청/승인 시스템 연동 (vacation_requests 테이블)
• 연차 촉진제 알림 기능
• 휴가 사용 내역 상세 조회 기능
• 부서별 휴가 현황 대시보드