"""휴가 관리 모듈 상수 및 순수 계산 헬퍼. - 데이터 저장은 vacation_db(PostgreSQL) 전용이다(`db.py`). 운영 데이터가 JSON 과 DB 로 갈라지는 것을 막기 위해 JSON 폴백을 두지 않는다. VACATION_DB_URL 미설정 시 라우터가 "설정 필요" 안내 페이지를 보여준다. - 이 모듈에는 상수와 순수 계산 헬퍼(휴가일수 계산)만 둔다. 공휴일 집합은 db.py 가 vacation_holidays 에서 읽어 넘겨준다(holiday provider 분리). """ from __future__ import annotations from datetime import date, timedelta from typing import Iterable # 휴가 종류 (한글 라벨 그대로 저장) VACATION_TYPES: tuple[str, ...] = ( "연차", "오전반차", "오후반차", "병가", "경조", "대체휴무", "기타", ) # 신청 상태 워크플로 # 협의중 = 협의자 승인 대기(2026-11-02, 마이그레이션 003) — 협의자가 모두 승인하면 제출(결재자 승인 대기) STATUSES: tuple[str, ...] = ("작성중", "협의중", "제출", "승인", "반려", "취소") # 시작/종료일 구분 HALVES: tuple[str, ...] = ("full", "am", "pm") HALF_LABELS: dict[str, str] = {"full": "종일", "am": "오전", "pm": "오후"} # 수정/삭제(취소) 가능한 상태 — 본인 편집 허용 EDITABLE_STATUSES: tuple[str, ...] = ("작성중", "반려") # 연차에서 차감하는 휴가 종류(2026-10-27) — 승인되면 연차에서 빠진다. 병가·경조·대체휴무·기타는 차감하지 않는다. # 연차는 입사일 기준(leave_grants·leave_status) — 연차마다 쓸 수 있는 기한이 따로(12/31 소멸 규칙은 2026-10-27 없앰). DEDUCT_TYPES: tuple[str, ...] = ("연차", "오전반차", "오후반차") # 이 시스템을 쓰기 시작한 해 — 그해만 잔여 연차 표에 "시스템 전 사용"(도입 전에 이미 쓴 연차) 칸(2026-10-27) SYSTEM_START_YEAR = 2026 def add_months(d: date, n: int) -> date: """d 에서 n 달 뒤 같은 날(없는 날이면 그 달 말일 — 1/31 + 1달 = 2/28).""" m = d.month - 1 + n y, m = d.year + m // 12, m % 12 + 1 last = (date(y + (m == 12), m % 12 + 1, 1) - timedelta(days=1)).day return date(y, m, min(d.day, last)) # 시스템 전 사용(prior_used)을 쓴 것으로 치는 날 — 이 시스템을 쓰기 시작한 날(그때까지 쓴 연차) SYSTEM_START_DATE = date(2026, 10, 27) def leave_grants(hire: date, until: date) -> list[dict]: """입사일부터 until 까지 생기는 연차(근로기준법 제60조) — 생긴 날마다 한 줄, 쓸 수 있는 마지막 날(expires) 포함. · 입사 1년 미만: 입사일 + m개월(m = 1~11)마다 1일 — 입사일부터 1년(첫 입사 기념일 전날)까지 사용(제60조 ②·⑦ 단서) · 근속 n년이 되는 날: min(25, 15 + (n−1)//2)일 — 그날부터 1년(다음 입사 기념일 전날)까지 사용(제60조 ①④⑦) 출근율(1개월 개근·1년 80%)은 따지지 않는다(모두 채운 것으로 본다). """ out: list[dict] = [] first_end = add_months(hire, 12) - timedelta(days=1) for m in range(1, 12): g = add_months(hire, m) if g > until: break out.append({"date": g, "expires": first_end, "days": 1.0, "label": f"입사 {m}개월(월 1일)", "period": 0}) n = 1 while True: g = add_months(hire, 12 * n) if g > until: break out.append({"date": g, "expires": add_months(hire, 12 * (n + 1)) - timedelta(days=1), "days": float(min(25, 15 + (n - 1) // 2)), "label": f"근속 {n}년", "period": n}) n += 1 return out def leave_period(hire: date, as_of: date) -> tuple[int, date, date]: """as_of 가 든 연차 기간 = (만 근속 n, 시작, 끝) — 입사일(또는 입사 기념일)부터 다음 기념일 전날까지.""" n = 0 while add_months(hire, 12 * (n + 1)) <= as_of: n += 1 start = hire if n == 0 else add_months(hire, 12 * n) return n, start, add_months(hire, 12 * (n + 1)) - timedelta(days=1) def usage_units(*, start_date: date, end_date: date, start_half: str = "full", end_half: str = "full", vacation_type: str = "연차", holidays: set[str] | None = None) -> list[tuple[date, float]]: """휴가 하나를 날짜별 사용량 [(날짜, 1 또는 0.5)]으로 — compute_days 와 같은 규칙(합계가 같다).""" holidays = holidays or set() if end_date < start_date: return [] if vacation_type in _HALF_DAY_TYPES: return [(start_date, 0.5)] if is_working_day(start_date, holidays) else [] days = [d for d in _daterange(start_date, end_date) if is_working_day(d, holidays)] if start_date == end_date: return [(start_date, 0.5 if start_half in ("am", "pm") else 1.0)] if days else [] out = [] for d in days: amt = 1.0 if (d == start_date and start_half in ("am", "pm")) or (d == end_date and end_half in ("am", "pm")): amt = 0.5 out.append((d, amt)) return out def leave_status(*, hire: date | None, as_of: date, usages: list[tuple[date, float]], prior: float = 0.0, override: float | None = None) -> dict: """입사일 기준 연차 현황(2026-10-27 — 12/31 소멸 없음). 연차마다 생긴 날·쓸 수 있는 마지막 날을 따로 두고, 쓴 날(usages, 승인된 연차·반차)마다 그날 쓸 수 있는 연차 중 **먼저 소멸하는 것부터** 뺀다(없으면 다음에 생길 연차를 당겨 씀). prior = 시스템 전 사용(SYSTEM_START_DATE 에 쓴 것으로 침). override = 이번 연차 기간 연차를 직접 입력(그 기간 법정 연차 대신). 반환: period(n, start, end) · granted(이번 기간 생기는 연차 합) · granted_so_far(오늘까지 생긴 것) · upcoming(앞으로 생길 것) · used(이번 기간에 쓴 날 합) · available(지금 쓸 수 있는 잔여) · expiring({date, days} 가장 먼저 소멸할 잔여) · grants(이번 기간 줄). """ out = {"has_hire": hire is not None, "service_years": 0, "period_start": "", "period_end": "", "granted": 0.0, "granted_so_far": 0.0, "upcoming": 0.0, "used": 0.0, "available": 0.0, "expiring": None, "grants": []} if hire is None or as_of < hire: if override is not None: # 입사일 없음 — 직접 입력 연차만(기간 = 그해), 사용 = 그해 쓴 날 y0, y1 = date(as_of.year, 1, 1), date(as_of.year, 12, 31) used = sum(a for d, a in usages if y0 <= d <= y1) + (prior if y0 <= SYSTEM_START_DATE <= y1 else 0.0) out.update(period_start=y0.isoformat(), period_end=y1.isoformat(), granted=float(override), granted_so_far=float(override), used=round(float(used), 2), available=round(float(override) - used, 2)) return out n, p0, p1 = leave_period(hire, as_of) grants = leave_grants(hire, p1) if override is not None: grants = [g for g in grants if not p0 <= g["date"] <= p1] grants.append({"date": p0, "expires": p1, "days": float(override), "label": "직접 입력", "period": n}) grants.sort(key=lambda g: g["date"]) for g in grants: g["left"] = g["days"] events = sorted(usages) if prior and hire <= SYSTEM_START_DATE: events = sorted(events + [(SYSTEM_START_DATE, float(prior))]) short = 0.0 # 어느 연차로도 못 채운 날 advance = 0.0 # 오늘까지 쓴 날 중 아직 안 생긴(오늘 뒤에 생기는) 연차를 당겨 쓴 만큼 — 지금 잔여에서 뺀다 for d, amt in events: rem = amt now = sorted((g for g in grants if g["date"] <= d <= g["expires"] and g["left"] > 0), key=lambda g: (g["expires"], g["date"])) later = sorted((g for g in grants if g["date"] > d and g["left"] > 0), key=lambda g: g["date"]) for g in now + later: take = min(g["left"], rem) g["left"] -= take rem -= take if d <= as_of < g["date"]: advance += take if rem <= 0: break short += rem active = [g for g in grants if g["date"] <= as_of <= g["expires"]] in_period = [g for g in grants if p0 <= g["date"] <= p1] left = [g for g in active if g["left"] > 0] expiring = None if left: first = min(g["expires"] for g in left) expiring = {"date": first.isoformat(), "days": round(sum(g["left"] for g in left if g["expires"] == first), 2)} out.update( service_years=n, period_start=p0.isoformat(), period_end=p1.isoformat(), granted=round(float(sum(g["days"] for g in in_period)), 2), granted_so_far=round(float(sum(g["days"] for g in in_period if g["date"] <= as_of)), 2), upcoming=round(float(sum(g["days"] for g in in_period if g["date"] > as_of)), 2), used=round(float(sum(a for d, a in events if p0 <= d <= p1)), 2), available=round(float(sum(g["left"] for g in active)) - advance - short, 2), expiring=expiring, grants=[{"date": g["date"].isoformat(), "expires": g["expires"].isoformat(), "days": g["days"], "label": g["label"], "left": round(g["left"], 2)} for g in grants if p0 <= g["date"] <= p1 or (g["date"] <= as_of <= g["expires"])], ) return out # 반차 성격의 휴가 종류 (단일 일자 0.5일 강제) _HALF_DAY_TYPES: dict[str, str] = {"오전반차": "am", "오후반차": "pm"} def _daterange(start: date, end: date) -> Iterable[date]: cur = start while cur <= end: yield cur cur += timedelta(days=1) def is_working_day(d: date, holidays: set[str]) -> bool: """주말(토/일)과 공휴일(holidays: ISO 날짜 집합)을 제외하면 근무일.""" if d.weekday() >= 5: # 5=토, 6=일 return False return d.isoformat() not in holidays def compute_days( *, start_date: date, end_date: date, start_half: str = "full", end_half: str = "full", vacation_type: str = "연차", holidays: set[str] | None = None, ) -> float: """휴가 일수 계산. 서버에서 항상 이 함수로 재계산한다(클라이언트 신뢰 금지). - 주말 + 공휴일(is_red) 제외. - 오전/오후 반차는 0.5일. - 같은 날 + 반차면 0.5일. - 여러 날에서 시작/종료가 반차면 시작일/종료일 각각 0.5 차감. - 휴가 종류가 오전반차/오후반차면 단일 일자 0.5일로 강제. """ holidays = holidays or set() if end_date < start_date: return 0.0 # 반차 종류는 단일 일자 0.5 if vacation_type in _HALF_DAY_TYPES: if is_working_day(start_date, holidays): return 0.5 return 0.0 working = [d for d in _daterange(start_date, end_date) if is_working_day(d, holidays)] n = len(working) if n == 0: return 0.0 if start_date == end_date: return 0.5 if start_half in ("am", "pm") else 1.0 total = float(n) if start_half in ("am", "pm") and is_working_day(start_date, holidays): total -= 0.5 if end_half in ("am", "pm") and is_working_day(end_date, holidays): total -= 0.5 return max(0.0, total) def normalize_half(value: str | None) -> str: v = (value or "full").strip().lower() return v if v in HALVES else "full"