F-r-ldraledigplannerare/backend/app/entities/leave_wish.py

"""Domain entity: LeaveWish.

A family's recurring intent to be home for N weeks inside a yearly window
(e.g. "6 weeks every summer until the child turns 4"). Renamed and extended
from `BreakPeriod` (see PLANNING_ENGINE_SPEC.md §2.1): the old entity was
single-year with no notion of recurrence, priority, or which parent. This is
the input side of the planning engine's allocator (§3); the allocator itself
is Phase B.

The recurring window is stored as month/day integers (not dates) so it can
repeat yearly without a custom SQLite type. If the window's end sorts before
its start, it wraps into the next year — e.g. Jullov 12-20 -> 01-07.
"""

from dataclasses import dataclass
from datetime import date, datetime
from uuid import UUID


@dataclass
class LeaveWish:
    """A family's recurring intent to be home for N weeks inside a yearly window."""

    id: UUID
    workspace_id: UUID
    child_id: UUID | None  # None = family-wide; set = tied to that child's pools
    name: str  # "Sommar", "Jullov" — persisted, possibly-translated display text

    # Recurring anchor stored as month/day ints (SQLite-friendly, no custom type).
    window_start_month: int  # 1-12
    window_start_day: int  # 1-31
    window_end_month: int
    window_end_day: int

    target_weeks: int  # 6
    recurrence: str  # 'yearly' | 'once'
    first_year: int  # 2027
    last_year: int | None  # None = until the child's 4th birthday

    priority: int  # 1 = highest; drives best-effort fill order
    parent_mode: str  # 'either' | 'both' | 'specific'
    parent_personal_data_uuid: UUID | None  # required when parent_mode == 'specific'

    # PLANNING_ENGINE_SPEC.md §10.1 — 'fixed' (default): window_start_*/window_end_*
    # are the exact placement, as above. 'flexible': the SAME four fields instead
    # describe the BOUNDING RANGE the allocator searches inside for the
    # best-costing placement (e.g. "vår" = 03-01..05-31) — target_weeks is still
    # the wanted duration inside that range. recurrence/first_year/last_year are
    # unchanged, so a 'yearly' flexible wish still re-resolves its bounding range
    # every anchor year through window_for_year()/applies_to_year() below,
    # completely unmodified.
    window_mode: str = "fixed"  # 'fixed' | 'flexible'

    # §Decision A (co-leave, 2026-09-18 correction) — dubbeldagar are OPT-IN,
    # never automatic, even when `parent_mode == 'both'` and the child is
    # still inside the 15-month dubbeldagar window with quota left. Only set
    # when the user has explicitly requested them for this wish. NOTE: no
    # frontend exposes this yet -- the period editor's dubbeldag checkbox is
    # not built, and there is no `wantsDubbeldag` in the TS types, so today
    # the flag is only reachable through the API. When that UI lands it must
    # show the checkbox only where `WindowOutcome.dubbeldagar_legally_available`
    # says they legally could apply -- see allocation_service.py. Defaults to False so every
    # existing wish (and every wish that never opts in) gets the new
    # PL+vacation co-leave behaviour instead of dubbeldagar. Meaningless
    # outside `parent_mode == 'both'` -- `LeaveWishService._validate` rejects
    # setting it otherwise.
    wants_dubbeldag: bool = False

    # Provenance of `name`: when a wish is created from a preset (Sommar,
    # Jullov, Höstlov, ...) this holds the i18n message key that produced the
    # translated string stored in `name` (e.g. "wishEditor.presetSommar").
    # Nullable — free-typed names, and every row created before this field
    # existed, have no key and just show `name` verbatim. Cleared by
    # `LeaveWishService.update` the moment the user edits `name`, since a
    # user-typed name is no longer a preset label and must never silently
    # revert to one.
    name_message_key: str | None = None

    # A calendar-drawn period (e.g. dragging a band on the calendar UI) is not
    # a whole number of weeks. NULL (every row created before this field
    # existed, and any wish still specified in weeks) falls back to
    # `target_weeks * 7` — see `target_span_days()`.
    target_days: int | None = None

    created_at: datetime | None = None
    updated_at: datetime | None = None

    def target_span_days(self) -> int:
        """Wanted duration in days. `target_days` wins when set; otherwise weeks * 7."""
        return self.target_days if self.target_days is not None else self.target_weeks * 7

    def window_wraps(self) -> bool:
        """Whether (end_month, end_day) sorts before (start_month, start_day).

        A wrapping window (e.g. Jullov 12-20 -> 01-07) ends in the year *after*
        the anchor year passed to `window_for_year`.
        """
        return (self.window_end_month, self.window_end_day) < (
            self.window_start_month,
            self.window_start_day,
        )

    def window_for_year(self, year: int) -> tuple[date, date]:
        """Concrete (start_date, end_date) for this wish's window anchored at `year`.

        `year` is the year the window *starts* in. If the window wraps, the
        end date lands in `year + 1` — this also means a wrapping window spans
        two different vacation-year budgets (see PLANNING_ENGINE_SPEC.md §3.2);
        callers that debit vacation must account for both years separately.
        """
        start = date(year, self.window_start_month, self.window_start_day)
        end_year = year + 1 if self.window_wraps() else year
        end = date(end_year, self.window_end_month, self.window_end_day)
        return start, end

    def applies_to_year(self, year: int) -> bool:
        """Whether this wish recurs (or occurs once) with an anchor of `year`.

        `year` is compared against `first_year`/`last_year` as an *anchor*
        year (the year the window starts in), not a calendar year the window
        merely overlaps.
        """
        if year < self.first_year:
            return False
        if self.recurrence == "once":
            return year == self.first_year
        # recurrence == 'yearly'
        return self.last_year is None or year <= self.last_year