123 lines
7.8 KiB
Markdown
123 lines
7.8 KiB
Markdown
# Personal Leave Planning
|
|
|
|
VacOptimizer helps one person turn expiring leave balances into a leave plan across a planning horizon. It combines leave placements with weekends, French public holidays, and ordered planning rules, then reports the resulting time-off periods and any unplaced balances.
|
|
|
|
## Language
|
|
|
|
**Leave entitlement**:
|
|
A quantity of leave granted by a company or generated by an applicable planning rule, with an availability date and an expiry date.
|
|
|
|
**Leave balance**:
|
|
The unspent quantity of a leave entitlement, identified by leave type, availability date, and expiry date.
|
|
_Avoid_: vacation day, VacDay
|
|
|
|
**At-risk balance**:
|
|
A leave balance whose expiry date falls between the planning horizon's start and end, including both boundary dates. Its unplaced quantity is at risk of being lost.
|
|
|
|
**Unavoidable expiry**:
|
|
Leave whose expiry date precedes the planning horizon and therefore cannot be saved by that plan.
|
|
|
|
**Deferred balance**:
|
|
The unspent portion of a leave balance that expires after the planning horizon. It needs no ordinary placement in the current plan but remains available to explicit planning rules and supporting placements.
|
|
|
|
**Leave type**:
|
|
The category of leave in a balance: CP (paid leave), RTT (working-time reduction leave), or Other (a user-managed catch-all).
|
|
_Avoid_: ANY as a leave type; `ANY` is only a rule selector.
|
|
|
|
**Planning horizon**:
|
|
The user-selected half-open date interval of at most 12 months within which leave may be placed. It defaults to today's Europe/Paris calendar date through the same date 12 months later.
|
|
|
|
**Working day**:
|
|
A Monday-to-Friday calendar date that is not a French national public holiday. Only working days can receive leave placements.
|
|
|
|
**Public holiday**:
|
|
A French calendar date that cannot receive a leave placement and contributes to a time-off period.
|
|
|
|
**Public-holiday week**:
|
|
A Monday-to-Friday window containing a weekday French public holiday where every other working day is a leave placement.
|
|
|
|
**Public-holiday week value**:
|
|
The distance of every weekday holiday from the nearest weekend, summed within and across completed public-holiday weeks: Monday or Friday is 1, Tuesday or Thursday is 2, and Wednesday is 3.
|
|
|
|
**Leave placement**:
|
|
Using one or more working days from a leave balance on specific dates within the planning horizon.
|
|
|
|
**Supporting placement**:
|
|
A leave placement from a deferred balance that completes a public-holiday week, captures additional adjacent non-working dates, eliminates a short work sequence, or reduces the longest work sequence. Merely extending an existing period by the placed day itself is not sufficient.
|
|
|
|
**Time-off period**:
|
|
A contiguous period containing at least one leave placement together with any adjacent weekends and public holidays, including those immediately outside the planning horizon.
|
|
|
|
**Time-off duration**:
|
|
The number of distinct calendar dates covered by all planned time-off periods.
|
|
|
|
**Non-working-day gain**:
|
|
The distinct weekend and public-holiday dates contained in planned time-off periods. Leave placement dates themselves do not contribute to this gain.
|
|
|
|
**Work sequence**:
|
|
The working days in an interval delimited by planned time-off periods or by the planning horizon edges. Intervening weekends and public holidays neither count nor split the sequence.
|
|
|
|
**Short work sequence**:
|
|
A work sequence of fewer than five working days between two planned time-off periods.
|
|
|
|
**Planning rule**:
|
|
A user instruction that requests leave placements around a calendar opportunity or inside a date window. Its force is either an obligation or a preference.
|
|
|
|
**Obligation rule**:
|
|
A planning rule that every valid plan must satisfy. Obligation rules are resolved jointly; their order only breaks ties between valid plans.
|
|
|
|
**Preference rule**:
|
|
A planning rule that guides placement but may remain unsatisfied to preserve validity or prevent more at-risk leave from expiring.
|
|
|
|
**IF_THEN rule**:
|
|
A planning rule evaluated independently for every French public holiday on its configured weekday. A preference requests a complete pattern around each occurrence when possible; an obligation requires it for every occurrence.
|
|
|
|
**IF_THEN placement mode**:
|
|
`before` and `after` fix every requested day on one side; `around` considers every split with at least one day on each side; `auto` considers every split, including the all-before and all-after extremes.
|
|
|
|
**TIME_WINDOW rule**:
|
|
A planning rule targeting working days in an inclusive date window. A preference requests up to its configured quantity; an obligation requires exactly that quantity.
|
|
|
|
**Rule priority**:
|
|
The user-defined lexicographic order of preference rules. Each earlier preference is satisfied as far as possible before a later preference is considered.
|
|
|
|
**Rule satisfaction**:
|
|
The relationship in which a plan fulfils a planning rule. One compatible leave placement may contribute to the satisfaction of multiple rules.
|
|
|
|
**Placement provenance**:
|
|
The consumed leave entitlement and every planning rule satisfied by a leave placement.
|
|
|
|
**Planning conflict**:
|
|
A set of obligation rules that cannot all be satisfied by one plan within the planning horizon and available leave balances.
|
|
|
|
**Invalid planning input**:
|
|
A malformed request that cannot describe a plan, such as a reversed date window. A valid but unsatisfiable request is a planning conflict instead.
|
|
|
|
**Planning outcome**:
|
|
The result of a calculation: invalid input, a planning conflict, an optimization result, or an incomplete calculation.
|
|
|
|
**Stable plan explanation**:
|
|
A deterministic explanation derived from the final displayed plan. It identifies each placement's entitlement and rule provenance, contributions, full objective vector, and the first objective that distinguishes the plan with that placement restored from the same plan with only that placement removed.
|
|
|
|
**Original decision trace**:
|
|
The untruncated phase-by-phase record captured by the calculation that produced the displayed outcome, including atomic decisions, candidate statuses, and state deltas. It is historical evidence and is never recomputed from the final plan.
|
|
|
|
**Counterfactual date analysis**:
|
|
A hypothetical comparison that keeps the calculation snapshot and all unrelated placements fixed while testing one selected placement across every date in the half-open planning horizon. It neither mutates the plan nor rewrites the original trace.
|
|
|
|
**Incomplete calculation**:
|
|
A calculation stopped before it completed the planning objective order. It may expose its best valid plan but never implies that the obligations conflict.
|
|
|
|
**Planning objective order**:
|
|
The lexicographic quality order applied after joint obligation feasibility: minimize unplaced at-risk leave; satisfy each preference in user order; maximize public-holiday week value; maximize non-working-day gain; minimize the longest work sequence; minimize the total deficit of internal work sequences shorter than five days; minimize supporting placements; consume earlier-expiring balances; then prefer earlier placement dates. Complete holiday weeks therefore precede broader calendar-gain and work-sequence optimization. A lower criterion never degrades a higher one.
|
|
|
|
**Earned leave entitlement**:
|
|
A leave entitlement created for each completed occurrence of an applicable planning rule after its generating time-off period ends. It becomes available the following day, expires one year later, and may fund any later compatible placement.
|
|
_Avoid_: reward, bonus days
|
|
|
|
**Optimization result**:
|
|
A valid deterministic plan produced after completing the planning objective order, containing leave placements and their provenance, time-off periods, unsatisfied preference reasons, and remaining balances with reasons. It does not claim mathematical global optimality.
|
|
|
|
**Remaining balance**:
|
|
Any quantity left unspent by the optimization result, reported as unavoidable expiry, an unplaced at-risk balance, or a deferred balance.
|