Complete NextSteps roadmap: planning engine UI, calendar cluster, flexible wishes

Works through every numbered item in NextSteps260913.md section 3, plus the three known verification issues in section 4.1. Surface what the backend already computed: - 3.1 render surplus_advice in PlanResults, mirroring the shortfall remedies - 3.2 surface VacationBalance.is_assumed so assumed statutory years are visible - 3.3 age-4 expiry given the proposed plan, via a new Age4Projection reusing the existing _age4_projections arithmetic (Dashboard stat verified, not rebuilt) Calendar cluster (one pass over the holiday data): - new GET /api/calendar/days exposing roda dagar, klamdagar and day overrides, paginated four years at a time - 3.4 shade roda dagar/klamdagar, with R/K badges so colour is not the only signal - 3.6 click-to-override behind an explicit mode toggle, leaving drag multi-select intact - 3.7 click month/year to advance - 3.8 per-year red-days list in Settings, statutory days plus overrides i18n: - 3.5 five backend-generated Swedish surfaces converted to message_key + data, following the tips_service pattern; old string fields replaced, not kept Flexible wishes (3.9): - PLANNING_ENGINE_SPEC section 10: window_mode, candidate search, cost function, deterministic tie-break, two-pass ordering, test matrix rows 15-24 - backend: entity, migration 006, _FULL_SCHEMA sync, repository, allocator - frontend: season-preset toggle in WishEditor, unplaced outcome rendering Fixes (4.1): - pin typecheck to the local tsc rather than npx resolving a newer TypeScript - ignore generated coverage/ and dist/ in the ESLint flat config - fix the flaky usePlanApply test properly, with waitFor rather than a retry Tests: backend 361 -> 404, frontend 540 -> 704. Coverage 89.47% -> 96.52% lines. Not yet verified in a browser. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RXMhc9nT6sNz1SL4j8dznL
2026-09-14 02:33:03 +02:00
parent 3ca1418d94
commit 76b1e712b9
218 changed files with 29867 additions and 6085 deletions
@@ -46,6 +46,7 @@ export interface WorkspaceCreateRequest {
 export interface WorkspaceUpdateRequest {
  name?: string
  planningGoal?: 'max_time' | 'max_money' | 'balanced'
+  planningMode?: 'solo' | 'couple'
 }

 // Parental leave manual entry
@@ -65,6 +66,31 @@ export interface ManualFetchRequest {
  lagstaNivaUsed: number
 }

+// Leave wishes (recurring "N weeks off inside this yearly window" intents)
+export interface LeaveWishCreateRequest {
+  workspaceId: string
+  childId?: string | null
+  name: string
+  windowStartMonth: number
+  windowStartDay: number
+  windowEndMonth: number
+  windowEndDay: number
+  targetWeeks: number
+  recurrence: 'yearly' | 'once'
+  firstYear: number
+  lastYear?: number | null
+  priority?: number
+  parentMode?: 'either' | 'both' | 'specific'
+  parentPersonalDataUuid?: string | null
+  goalOverride?: 'max_time' | 'max_money' | 'balanced' | null
+
+  // PLANNING_ENGINE_SPEC.md §10.1 — defaults to 'fixed' server-side when omitted.
+  windowMode?: 'fixed' | 'flexible'
+}
+
+/** Partial update — only supplied fields are changed. */
+export type LeaveWishUpdateRequest = Partial<Omit<LeaveWishCreateRequest, 'workspaceId'>>
+
 // Planned days
 export interface AddPlannedDayRequest {
  workspaceId: string
@@ -79,3 +105,55 @@ export interface UpdatePlannedDayRequest {
  dayType?: 'sjukpenning' | 'lagsta' | 'vacation'
  isDubbeldag?: boolean
 }
+
+// Plan apply endpoint (POST /api/plan/apply)
+export interface ProposedDayApplyItem {
+  date: string // ISO-8601 date
+  parentPersonalDataUuid: string
+  childId: string
+  dayType: 'sjukpenning' | 'lagsta' | 'vacation' | 'free'
+  isDubbeldag?: boolean
+}
+
+export interface PlanApplyRequest {
+  workspaceId: string
+  days: ProposedDayApplyItem[]
+  replace: boolean
+}
+
+export interface DayCollision {
+  date: string
+  parentPersonalDataUuid: string
+  childId: string
+  existingDayType: string
+  proposedDayType: string
+}
+
+/** §3.5 — a single reason a batch (or part of it) was refused, i18n-ready:
+ * `messageKey` + `data` (the same shape as a `Tip`) rather than a
+ * pre-rendered string, so `PlanResults.tsx` can render it in the caller's
+ * active locale.
+ */
+export interface Rejection {
+  messageKey: string
+  data: Record<string, unknown>
+}
+
+export interface PlanApplyResponse {
+  accepted: boolean
+  createdCount: number
+  skippedIdenticalCount: number
+  skippedFreeCount: number
+  replacedCount: number
+  collisions: DayCollision[]
+  rejections: Rejection[]
+  createdDays: object[]
+}
+
+// Day overrides (calendar exceptions)
+export interface DayOverrideCreateRequest {
+  workspaceId: string
+  date: string // ISO-8601 date
+  isWorkingDay: boolean
+  note: string | null
+}
@@ -5,6 +5,7 @@ export interface Workspace {
  id: string
  name: string
  planningGoal: 'max_time' | 'max_money' | 'balanced'
+  planningMode: 'solo' | 'couple'
  createdAt: string // ISO-8601
 }

@@ -23,18 +24,33 @@ export interface Child {
  name: string
  birthDate: string // ISO-8601 date
  preschoolStartDate: string | null
+  preschoolPlanningDaysPerYear: number
  createdAt: string
 }

-export interface BreakPeriod {
+export interface LeaveWish {
  id: string
  workspaceId: string
+  childId: string | null
  name: string
-  startDate: string
-  endDate: string
+  windowStartMonth: number
+  windowStartDay: number
+  windowEndMonth: number
+  windowEndDay: number
  targetWeeks: number
-  createdAt: string
-  updatedAt: string
+  recurrence: 'yearly' | 'once'
+  firstYear: number
+  lastYear: number | null
+  priority: number
+  parentMode: 'either' | 'both' | 'specific'
+  parentPersonalDataUuid: string | null
+  goalOverride: 'max_time' | 'max_money' | 'balanced' | null
+  // PLANNING_ENGINE_SPEC.md §10.1 — 'fixed': window_start_*/window_end_* are the
+  // exact placement. 'flexible': the same fields describe the bounding range the
+  // allocator searches within for the best-costing placement.
+  windowMode: 'fixed' | 'flexible'
+  createdAt: string | null
+  updatedAt: string | null
 }

 export interface TierData {
@@ -88,6 +104,41 @@ export interface PlannedLeaveDay {
  updatedAt: string
 }

+export interface DayOverride {
+  id: string
+  workspaceId: string
+  date: string // ISO-8601 date
+  isWorkingDay: boolean
+  note: string | null
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+// Calendar metadata (röda dagar / klämdagar) — GET /api/calendar/days,
+// backing §3.4 (Kalender shading), §3.6 (click-to-override) and §3.8
+// (Settings red-days list). Named `CalendarDayEntry` (not `CalendarDay`) to
+// avoid colliding with the `CalendarDay` component.
+export type CalendarDayType = 'red_day' | 'klamdag' | 'weekend' | 'working_day'
+
+export interface CalendarDayEntry {
+  date: string // ISO-8601 date
+  /** Exact holiday name (may be the combined "X; Söndag" form); null unless dayType === 'red_day'. */
+  name: string | null
+  dayType: CalendarDayType
+  isOverride: boolean
+  overrideIsWorkingDay: boolean | null
+  /** Effective free-day status after workspace overrides are applied. */
+  isFree: boolean
+}
+
+export interface CalendarWindow {
+  startYear: number
+  endYear: number
+  minYear: number | null
+  maxYear: number | null
+  days: CalendarDayEntry[]
+}
+
 export interface Age4Projection {
  personalDataUuid: string
  childId: string
@@ -116,3 +167,106 @@ export interface Tip {
  messageKey: string
  data: Record<string, unknown>
 }
+
+// Planning engine — POST /api/plan/propose (read-only preview, nothing is saved)
+
+export interface ProposedDay {
+  date: string // ISO-8601 date
+  parentPersonalDataUuid: string
+  childId: string | null
+  dayType: 'free' | 'vacation' | 'sjukpenning' | 'lagsta'
+  isDubbeldag: boolean
+  wishId: string
+  reason: string
+}
+
+export interface ShortfallRemedy {
+  kind: string
+  messageKey: string
+  data: Record<string, unknown>
+  daysFreed: number
+}
+
+/** Always carries all four keys; each defaults to 0 when the wire payload omits it. */
+export interface CostBreakdown {
+  free: number
+  vacation: number
+  sjukpenning: number
+  lagsta: number
+}
+
+export interface WindowOutcome {
+  wishId: string
+  wishName: string
+  year: number
+  startDate: string // ISO-8601 date
+  endDate: string // ISO-8601 date
+  weeksWished: number
+  weeksFunded: number
+  shortfallDays: number
+  strategy: string // 'dubbeldag' | 'parent_swap' | 'solo' — kept open-ended, see allocation_service.py
+  messageKey: string
+  data: Record<string, unknown>
+  costBreakdown: CostBreakdown
+  remedies: ShortfallRemedy[]
+}
+
+export interface PlanWarning {
+  kind: string // 'sgi_risk' | 'days_lost_at_age_4' | 'vacation_expiring'
+  messageKey: string
+  data: Record<string, unknown>
+}
+
+export interface PoolBalance {
+  parentPersonalDataUuid: string
+  childId: string
+  sjukpenningLeft: number
+  lagstaLeft: number
+  dubbeldagarLeft: number
+}
+
+export interface VacationBalance {
+  parentPersonalDataUuid: string
+  year: number
+  totalDays: number
+  savedDaysIn: number
+  alreadyUsed: number
+  // True when no `vacation_days` row existed for this (parent, year) and the
+  // backend defaulted `totalDays` to the statutory entitlement (25) rather
+  // than an entered value — §3.2. The UI should prompt the user to confirm.
+  isAssumed: boolean
+}
+
+/** §9.2 — the mirror of `ShortfallRemedy`: a suggestion for a parent forecast
+ * to *forfeit* FP days at the age-4 boundary rather than run short.
+ */
+export interface SurplusAdvice {
+  kind: string // 'wish_more_leave' | 'shift_mix_to_fp' | 'front_load_early_years' | 'use_less_vacation'
+  messageKey: string
+  daysInvolved: number
+  data: Record<string, unknown>
+}
+
+/** §3.3 part 2 — plan-aware age-4 projection: what the *proposed* (not yet
+ * applied) plan implies at the child's 4th birthday, per (parent, child).
+ * Distinct from the Dashboard's `Age4Projection` (which reflects the
+ * currently committed plan).
+ */
+export interface PlanAge4Projection {
+  parentPersonalDataUuid: string
+  childId: string
+  fourthBirthday: string // ISO-8601 date
+  projectedLeftAtB4: number
+  savableAfterB4: number
+  expiringAtB4: number
+}
+
+export interface PlanProposal {
+  days: ProposedDay[]
+  outcomes: WindowOutcome[]
+  warnings: PlanWarning[]
+  poolBalances: PoolBalance[]
+  vacationBalances: VacationBalance[]
+  surplusAdvice: SurplusAdvice[]
+  age4Projections: PlanAge4Projection[]
+}