jacobh2/F-r-ldraledigplannerare
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4e4766d54ebda62b88479ffd76aee74faa6456b4
F-r-ldraledigplannerare/backend/app/models/plan.py
T
jacobh2 782415122d Separate user intent from planner output via day assertions 
The calendar mixed two kinds of truth in one table. `planned_leave_day` was
simultaneously the allocator's output cache, the user's override store
(`is_pinned`, plus ad-hoc rows with no `wish_id`), and the resource ledger that
analytics and the age-4 maths read. The planner therefore had to ask "am I
allowed to touch this row?" on every sync, and got it wrong at the edges.

Every user assertion is now one `day_assertion` row — a concrete `day_type`
replaces a pinned day, a row with no `wish_id` replaces an ad-hoc day, and
`day_type='none'` replaces `planned_day_exclusion`. `planned_leave_day` becomes
purely derived with a single writer, and `PlanningService.pinned_keys()` is the
single answer to "is this day pinned", used by the allocator's loader, by
`sync_plan` and by the read router alike.

On top of that, every calendar band is now a real event: an ad-hoc band opens
the same full editor as a wish-backed one and saving it promotes it to a
`LeaveWish`, so it can be named, repeated yearly, assigned to either or both
parents, and handed to the planner. "Planering" is a `moveable` toggle plus a
from/to month bound plus a separate lock/unlock action on the days themselves,
replacing a three-rung ladder whose "planner decides" rung set a search window
equal to the drawn dates and so could never move anything.

Bugs found and fixed along the way:

- The plan erased its own history. Fixed windows clip to today, so an elapsed
  auto-placed day fell into `stale_keys` and was deleted on the next sync —
  and a background sync runs on every workspace load. Past rows are now frozen
  and counted as spent.
- Migration 010's downgrade silently destroyed every pinned day and exclusion
  (`is_pinned` returned as DEFAULT 0, the exclusion table came back empty,
  exit 0, no warning). It now reconstructs both from `day_assertion`, and 009
  itemises what it cannot recover before dropping the table.
- Deleting a period left its assertions behind, locking those dates forever
  with no UI path to clear them. Wish deletion now clears them by `wish_id`.
- `DayAssertionService` and `LeaveWishService` committed multi-statement writes
  without a transaction; a crash mid-write diverged the tables or half-deleted
  a series. Both now run in a unit of work.
- A sibling year's shortfall was never surfaced: the toast only inspected the
  edited occurrence's outcome, so a fully unfunded later year rendered as an
  empty band with no warning.
- A flexible window whose bound had entirely elapsed was dropped from the
  proposal with no outcome at all. It now reports as `unplaced`.
- Unlocking a period deleted its days instead of returning them to the planner.
- The e2e global setup posted to a route deleted in this change, which would
  have failed the whole suite before its first test.

Gates: backend 938 tests / 91% coverage, frontend 1351 / 97.4 | 92.2 | 94.37 |
97.4. Migrations 009 and 010 audited against a hand-built realistic database:
the upgrade reconciles exactly and a constraint violation fails safe, leaving
the schema at 008.

Not complete. Step 4's toggle, month picker and lock/unlock action are verified
by browser walk and unit tests, but the partial-lock readout was not exercised.
`ideas.md` §7 adds a full plan for the vacation-forfeiture defect (the planner
detects expiring days and then does nothing about them) — not implemented here.
Remaining smaller items are listed in the session's restructure notes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4wjgbVL4HAC5Rdaw75VbV
2026-09-21 07:20:14 +02:00

579 lines
20 KiB
Python
Raw Blame History

"""API schemas (Pydantic) for the planning-engine endpoints.
See PLANNING_ENGINE_SPEC.md §4. `POST /api/plan/propose` is read-only and
persists nothing — it just runs `PlanningEngineService.propose()` and shapes
the resulting (pure) `PlanProposal` for the wire.
`POST /api/plan/apply` is the other half: it takes a (possibly user-edited)
subset of a proposal's `days` and turns it into real `planned_leave_day`
rows via `PlanningService.apply_proposed_days`. See that method's docstring
for the idempotency/collision/`replace` semantics.
"""
from datetime import date
from typing import Literal
from uuid import UUID
from pydantic import BaseModel, Field, model_validator
from app.models.leave_wish import LeaveWishResponse, LeaveWishUpdate
from app.models.planned_leave import PlannedLeaveDayResponse
from app.services.allocation_service import PlanProposal
from app.services.planning_service import (
DayCollision,
DayLockAction,
PlanApplyResult,
PlanChange,
PlanSyncResult,
ProposedDayInput,
Rejection,
WishCreateInput,
WishSyncResult,
WishUpdateInput,
)
class PlanProposeRequest(BaseModel):
workspace_id: UUID
class ProposedDayResponse(BaseModel):
date: date
parent_personal_data_uuid: UUID
child_id: UUID | None
day_type: str
is_dubbeldag: bool
wish_id: UUID
reason: str
class ShortfallRemedyResponse(BaseModel):
kind: str
message_key: str
data: dict[str, object]
days_freed: int
class SurplusAdviceResponse(BaseModel):
"""§9.2 — the mirror of `ShortfallRemedyResponse`: a concrete suggestion
for a parent forecast to *forfeit* FP days at the age-4 boundary, rather
than run short. Same (kind, message_key/data, day-count) shape as the
remedy; `data` mirrors `PlanWarningResponse.data` for the (parent, child)
scope.
"""
kind: str
message_key: str
days_involved: int
data: dict[str, object]
class WindowOutcomeResponse(BaseModel):
wish_id: UUID
wish_name: str
# i18n provenance of `wish_name` — see `WindowOutcome.wish_name_message_key`
# (app/services/allocation_service.py). `None` for a free-typed/user-renamed
# wish, or any row predating this field.
wish_name_message_key: str | None
year: int
start_date: date
end_date: date
weeks_wished: int
weeks_funded: float
shortfall_days: int
strategy: str
requested_strategy: str
strategy_degraded: bool
dubbeldagar_legally_available: bool
message_key: str
data: dict[str, object]
cost_breakdown: dict[str, int]
remedies: list[ShortfallRemedyResponse]
# Mirrors `WindowOutcome.shift_gain_days` (app/services/allocation_service.py)
# — spendable days the flexible placement search saved versus the naive
# bound-start placement. 0 for a fixed window or a reused flexible one.
shift_gain_days: int = 0
# Mirrors `WindowOutcome.series_id` — see its docstring. Lets a caller
# that only knows ONE occurrence's wish id (e.g. `sync_with_wish`'s
# returned `wish.id`) find every OTHER outcome in this same batch that
# belongs to the same repeating wish.
series_id: UUID | None = None
class PlanWarningResponse(BaseModel):
kind: str
message_key: str
data: dict[str, object]
class PoolBalanceResponse(BaseModel):
parent_personal_data_uuid: UUID
child_id: UUID
sjukpenning_left: int
lagsta_left: int
dubbeldagar_left: int
class VacationBalanceResponse(BaseModel):
parent_personal_data_uuid: UUID
year: int
total_days: int
saved_days_in: int
already_used: int
# True when no `vacation_days` row existed for this (parent, year) and the
# loader defaulted `total_days` to the statutory entitlement rather than
# an entered value — see `VacationBudget.is_assumed`. The UI should use
# this to prompt the user to confirm/override the assumed year instead of
# silently treating it as a real entry.
is_assumed: bool
class Age4ProjectionResponse(BaseModel):
"""§3.3 part 2 — plan-aware age-4 projection: what this *proposed* plan
(not yet applied) implies at the child's 4th birthday, per (parent,
child). Always present, unlike `surplus_advice` which is only emitted
when there's a surplus to advise on.
"""
parent_personal_data_uuid: UUID
child_id: UUID
fourth_birthday: date
projected_left_at_b4: int
savable_after_b4: int
expiring_at_b4: int
savable_cap_at_b4: int
class PlanProposalResponse(BaseModel):
days: list[ProposedDayResponse]
outcomes: list[WindowOutcomeResponse]
warnings: list[PlanWarningResponse]
pool_balances: list[PoolBalanceResponse]
vacation_balances: list[VacationBalanceResponse]
surplus_advice: list[SurplusAdviceResponse]
age4_projections: list[Age4ProjectionResponse]
@classmethod
def from_domain(cls, proposal: PlanProposal) -> "PlanProposalResponse":
return cls(
days=[
ProposedDayResponse(
date=d.date,
parent_personal_data_uuid=d.parent_personal_data_uuid,
child_id=d.child_id,
day_type=d.day_type,
is_dubbeldag=d.is_dubbeldag,
wish_id=d.wish_id,
reason=d.reason,
)
for d in proposal.days
],
outcomes=[
WindowOutcomeResponse(
wish_id=o.wish_id,
wish_name=o.wish_name,
wish_name_message_key=o.wish_name_message_key,
year=o.year,
start_date=o.start_date,
end_date=o.end_date,
weeks_wished=o.weeks_wished,
weeks_funded=o.weeks_funded,
shortfall_days=o.shortfall_days,
strategy=o.strategy,
requested_strategy=o.requested_strategy,
strategy_degraded=o.strategy_degraded,
dubbeldagar_legally_available=o.dubbeldagar_legally_available,
message_key=o.message_key,
data=o.data,
cost_breakdown=o.cost_breakdown,
remedies=[
ShortfallRemedyResponse(
kind=r.kind,
message_key=r.message_key,
data=r.data,
days_freed=r.days_freed,
)
for r in o.remedies
],
shift_gain_days=o.shift_gain_days,
series_id=o.series_id,
)
for o in proposal.outcomes
],
warnings=[
PlanWarningResponse(kind=w.kind, message_key=w.message_key, data=w.data)
for w in proposal.warnings
],
pool_balances=[
PoolBalanceResponse(
parent_personal_data_uuid=parent_id,
child_id=child_id,
sjukpenning_left=pool.sjukpenning_left,
lagsta_left=pool.lagsta_left,
dubbeldagar_left=pool.dubbeldagar_left,
)
for (parent_id, child_id), pool in proposal.balances_after.pools_after.items()
],
vacation_balances=[
VacationBalanceResponse(
parent_personal_data_uuid=parent_id,
year=year,
total_days=budget.total_days,
saved_days_in=budget.saved_days_in,
already_used=budget.already_used,
is_assumed=budget.is_assumed,
)
for (parent_id, year), budget in proposal.balances_after.vacation_after.items()
],
surplus_advice=[
SurplusAdviceResponse(
kind=a.kind,
message_key=a.message_key,
days_involved=a.days_involved,
data=a.data,
)
for a in proposal.surplus_advice
],
age4_projections=[
Age4ProjectionResponse(
parent_personal_data_uuid=p.parent_personal_data_uuid,
child_id=p.child_id,
fourth_birthday=p.fourth_birthday,
projected_left_at_b4=p.projected_left_at_b4,
savable_after_b4=p.savable_after_b4,
expiring_at_b4=p.expiring_at_b4,
savable_cap_at_b4=p.savable_cap_at_b4,
)
for p in proposal.age4_projections
],
)
# ---------------------------------------------------------------------------
# POST /api/plan/apply
# ---------------------------------------------------------------------------
class ProposedDayApplyItem(BaseModel):
"""One day to persist. Same shape as `ProposedDayResponse` minus the
explain-only `reason` (harmless if a caller sends it anyway — a frontend
can hand back `ProposedDayResponse` entries from `/propose` verbatim;
extra fields are ignored). `wish_id` DOES carry persistence meaning here
(unlike `reason`): it links the persisted row back to the wish that
produced it, so a client handing back a `/propose` day verbatim gets that
attribution persisted for free.
`day_type` additionally accepts 'free' (an automatic weekend/red-day
entry from a proposal) purely so a client doesn't have to filter those
out itself — they are always skipped, never persisted, see
`PlanApplyResponse.skipped_free_count`.
"""
date: date
parent_personal_data_uuid: UUID
child_id: UUID
day_type: str = Field(pattern="^(sjukpenning|lagsta|vacation|free)$")
is_dubbeldag: bool = False
wish_id: UUID | None = None
def to_domain(self) -> ProposedDayInput:
return ProposedDayInput(
date=self.date,
parent_personal_data_uuid=self.parent_personal_data_uuid,
child_id=self.child_id,
day_type=self.day_type,
is_dubbeldag=self.is_dubbeldag,
wish_id=self.wish_id,
)
class PlanApplyRequest(BaseModel):
workspace_id: UUID
days: list[ProposedDayApplyItem]
replace: bool = False
class DayCollisionResponse(BaseModel):
date: date
parent_personal_data_uuid: UUID
child_id: UUID
existing_day_type: str
proposed_day_type: str
@classmethod
def from_domain(cls, collision: DayCollision) -> "DayCollisionResponse":
return cls(
date=collision.date,
parent_personal_data_uuid=collision.parent_personal_data_uuid,
child_id=collision.child_id,
existing_day_type=collision.existing_day_type,
proposed_day_type=collision.proposed_day_type,
)
class RejectionResponse(BaseModel):
"""§3.5 — a single reason a batch (or part of it) was refused, i18n-ready:
`message_key` + `data` (the `tips_service.Tip` shape) instead of a
pre-rendered string, so `PlanResults.tsx` can render it in the caller's
active locale.
"""
message_key: str
data: dict[str, object]
@classmethod
def from_domain(cls, rejection: Rejection) -> "RejectionResponse":
return cls(message_key=rejection.message_key, data=rejection.data)
class PlanApplyResponse(BaseModel):
accepted: bool
created_count: int
skipped_identical_count: int
skipped_free_count: int
replaced_count: int
deleted_count: int
collisions: list[DayCollisionResponse]
rejections: list[RejectionResponse]
created_days: list[PlannedLeaveDayResponse]
@classmethod
def from_domain(cls, result: PlanApplyResult) -> "PlanApplyResponse":
return cls(
accepted=result.accepted,
created_count=result.created_count,
skipped_identical_count=result.skipped_identical_count,
skipped_free_count=result.skipped_free_count,
replaced_count=result.replaced_count,
deleted_count=result.deleted_count,
collisions=[DayCollisionResponse.from_domain(c) for c in result.collisions],
rejections=[RejectionResponse.from_domain(r) for r in result.rejections],
created_days=[PlannedLeaveDayResponse.from_entity(d) for d in result.created],
)
# ---------------------------------------------------------------------------
# POST /api/plan/sync
# ---------------------------------------------------------------------------
class PlanSyncRequest(BaseModel):
workspace_id: UUID
class PlanChangeResponse(BaseModel):
"""One (child, parent, date) slot's delta from a `sync` call — see
`PlanChange`'s docstring for the `kind` vocabulary. Structured data only;
the frontend composes the toast copy ("Sommar 2028 flyttades 2 dagar —
Ångra") itself.
"""
kind: str
date: date
parent_personal_data_uuid: UUID
child_id: UUID
old_day_type: str | None
new_day_type: str | None
old_is_dubbeldag: bool | None
new_is_dubbeldag: bool | None
old_wish_id: UUID | None
new_wish_id: UUID | None
# Only ever `True` on a `kind == 'removed'` change — see `PlanChange.
# evicted`'s docstring: distinguishes "this wish's own edit shed the
# row" (evicted=False, the ordinary case) from "a different wish's edit
# won a shared pool ahead of it" (evicted=True) so the UI can call out
# displacement distinctly instead of folding it into a silent count.
evicted: bool
@classmethod
def from_domain(cls, change: PlanChange) -> "PlanChangeResponse":
return cls(
kind=change.kind,
date=change.date,
parent_personal_data_uuid=change.parent_personal_data_uuid,
child_id=change.child_id,
old_day_type=change.old_day_type,
new_day_type=change.new_day_type,
old_is_dubbeldag=change.old_is_dubbeldag,
new_is_dubbeldag=change.new_is_dubbeldag,
old_wish_id=change.old_wish_id,
new_wish_id=change.new_wish_id,
evicted=change.evicted,
)
class PlanSyncResponse(BaseModel):
proposal: PlanProposalResponse
apply_result: PlanApplyResponse
changes: list[PlanChangeResponse]
@classmethod
def from_domain(cls, result: PlanSyncResult) -> "PlanSyncResponse":
return cls(
proposal=PlanProposalResponse.from_domain(result.proposal),
apply_result=PlanApplyResponse.from_domain(result.apply_result),
changes=[PlanChangeResponse.from_domain(c) for c in result.changes],
)
# ---------------------------------------------------------------------------
# POST /api/plan/sync-with-wish — the calendar's four create/edit-then-sync
# paths, collapsed into one atomic backend call. See
# `PlanningService.sync_with_wish`'s docstring for the atomicity guarantee.
# ---------------------------------------------------------------------------
class WishCreatePayload(BaseModel):
"""Fields for the wish behind a drawn/promoted/preset period.
Field-for-field identical to `LeaveWishCreate` minus `workspace_id`
(carried once, on `PlanSyncWithWishRequest` itself).
"""
child_id: UUID | None = None
name: str = Field(min_length=1, max_length=255)
name_message_key: str | None = Field(default=None, max_length=255)
window_start_month: int = Field(ge=1, le=12)
window_start_day: int = Field(ge=1, le=31)
window_end_month: int = Field(ge=1, le=12)
window_end_day: int = Field(ge=1, le=31)
target_weeks: int = Field(ge=1, le=52)
target_days: int | None = Field(default=None, ge=1)
recurrence: str = "once"
first_year: int = Field(ge=2000, le=2200)
last_year: int | None = Field(default=None, ge=2000, le=2200)
priority: int = Field(default=1, ge=1)
parent_mode: str = "either"
parent_personal_data_uuid: UUID | None = None
window_mode: str = "fixed"
series_id: UUID | None = None
wants_dubbeldag: bool = False
def to_domain(self) -> WishCreateInput:
return WishCreateInput(
child_id=self.child_id,
name=self.name,
name_message_key=self.name_message_key,
window_start_month=self.window_start_month,
window_start_day=self.window_start_day,
window_end_month=self.window_end_month,
window_end_day=self.window_end_day,
target_weeks=self.target_weeks,
target_days=self.target_days,
recurrence=self.recurrence,
first_year=self.first_year,
last_year=self.last_year,
priority=self.priority,
parent_mode=self.parent_mode,
parent_personal_data_uuid=self.parent_personal_data_uuid,
window_mode=self.window_mode,
series_id=self.series_id,
wants_dubbeldag=self.wants_dubbeldag,
)
class WishUpdatePayload(BaseModel):
"""One wish's occurrence/series edit, addressed by id — reuses
`LeaveWishUpdate` verbatim for `patch` (it already has no `workspace_id`
field, so it needs no stripped-down mirror the way `WishCreatePayload`
does).
"""
leave_wish_id: UUID
scope: Literal["occurrence", "series"] = "occurrence"
patch: LeaveWishUpdate
def to_domain(self) -> WishUpdateInput:
fields_set = self.patch.model_fields_set
p = self.patch
return WishUpdateInput(
leave_wish_id=self.leave_wish_id,
scope=self.scope,
child_id=p.child_id,
name=p.name,
name_message_key=p.name_message_key,
window_start_month=p.window_start_month,
window_start_day=p.window_start_day,
window_end_month=p.window_end_month,
window_end_day=p.window_end_day,
target_weeks=p.target_weeks,
target_days=p.target_days,
recurrence=p.recurrence,
first_year=p.first_year,
last_year=p.last_year,
priority=p.priority,
parent_mode=p.parent_mode,
parent_personal_data_uuid=p.parent_personal_data_uuid,
window_mode=p.window_mode,
wants_dubbeldag=p.wants_dubbeldag,
clear_child_id="child_id" in fields_set and p.child_id is None,
clear_last_year="last_year" in fields_set and p.last_year is None,
clear_parent_personal_data_uuid=(
"parent_personal_data_uuid" in fields_set and p.parent_personal_data_uuid is None
),
clear_name_message_key=(
"name_message_key" in fields_set and p.name_message_key is None
),
clear_target_days="target_days" in fields_set and p.target_days is None,
)
DayLockActionKind = Literal["attach", "pin", "unpin", "detach"]
class DayLockActionRequest(BaseModel):
"""One already-persisted `planned_leave_day` row to re-point/pin/delete
as part of the same atomic call — see `DayLockAction`'s docstring
(app/services/planning_service.py) for what each `action` does.
"""
planned_day_id: UUID
action: DayLockActionKind
def to_domain(self) -> DayLockAction:
return DayLockAction(planned_day_id=self.planned_day_id, action=self.action)
class PlanSyncWithWishRequest(BaseModel):
workspace_id: UUID
# Exactly one of these two — this call always touches exactly one wish.
wish_create: WishCreatePayload | None = None
wish_update: WishUpdatePayload | None = None
day_actions: list[DayLockActionRequest] = Field(default_factory=list)
@model_validator(mode="after")
def _exactly_one_wish_op(self) -> "PlanSyncWithWishRequest":
if (self.wish_create is None) == (self.wish_update is None):
raise ValueError("exactly one of wish_create/wish_update must be provided")
return self
class PlanSyncWithWishResponse(BaseModel):
"""`wish` reflects the fields the caller asked for even when
`sync.apply_result.accepted` is `False` — see `WishSyncResult`'s
docstring: in that case nothing was actually persisted (the whole point
of the atomic call), but the frontend still needs the would-be id/fields
to render the outcome (e.g. matching `sync.proposal.outcomes` by
`wish_id`).
"""
wish: LeaveWishResponse
sync: PlanSyncResponse
@classmethod
def from_domain(cls, result: WishSyncResult) -> "PlanSyncWithWishResponse":
return cls(
wish=LeaveWishResponse.from_entity(result.wish),
sync=PlanSyncResponse.from_domain(result.sync),
)
Reference in New Issue View Git Blame Copy Permalink