Files
dbx-main/app/modules/vacation/store.py
T
king 4b2defac3a feat(vacation): 연차 12/31 소멸 삭제 — 입사일 기준, 연차마다 쓸 수 있는 기한
- store.leave_grants/leave_period/leave_status: 1년 미만 월 1일 = 입사일부터 1년까지, 근속 n년 연차 = 생긴 날부터 1년까지(근로기준법 제60조)
- 승인된 연차·반차를 날짜별(usage_units = compute_days 규칙)로 나눠 그날 쓸 수 있는 연차 중 먼저 소멸하는 것부터 차감, 생기기 전이면 당겨 씀
- 화면: 지금 연차 기간 · 생기는 연차(오늘까지 +앞으로) · 사용 · 오늘 쓸 수 있는 잔여 · 먼저 소멸(날짜·일수), 해 이동 없음, 달력 위 내 연차도 같은 값
- 직접 입력 = 지금 연차 기간이 시작한 해 줄(override_year), 시스템 전 사용 = 2026 줄(도입일에 쓴 것으로)
- 테스트: 규칙(10/12 입사 사례·먼저 소멸·당겨 씀·시스템 전·입사일 없음), 실제 PG, 실제 앱, 브라우저

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 16:27:50 +09:00

239 lines
11 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""휴가 관리 모듈 상수 및 순수 계산 헬퍼.
- 데이터 저장은 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, ...] = (
"연차",
"오전반차",
"오후반차",
"병가",
"경조",
"대체휴무",
"기타",
)
# 신청 상태 워크플로
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"