Leave setup and usage

Leave is the module where the academic calendar stops being background configuration and starts changing numbers. Every day count in staff leave comes from the calendar: the range is walked one day at a time, Sundays and any date flagged as an individual, seasonal or weekend holiday are dropped, and only the remainder becomes workingDaysCount and the entitlement deduction. Set entitlement defaults once per academic year, then leave the counting alone.

Set this up before the first teaching week, because approval has side effects that are hard to unpick later. Approving staff leave writes an on-leave projection for each working day, deducts the balance, and — when a substitute is named — creates confirmed cover rows against every published timetable slot the absent teacher holds on those weekdays. All of that happens inside one transaction, so a failure rolls the whole approval back rather than leaving cover that does not match the leave record.

Prerequisites

• An active academic year whose dates cover the leave period; without one the application still saves but returns a warning that working days may be inaccurate.
• Holidays generated and synced at /academic-calendar, otherwise every calendar day except Sunday is counted as working.
• Entitlement defaults per academic year and leave type, so a balance exists to check against.
• A published timetable, if you want substitute cover rows to be created on approval.

Staff leave workflow

1. Configure entitlement defaults for the academic year and leave type (CL, EL, SL, ML and the rest) from the /leave admin tools; per-teacher entitlements override the default.
2. A teacher applies at /leave with dates, leave type and reason, optionally a half day and an attachment such as a medical certificate.
3. The application is rejected if it overlaps another pending or approved leave for the same teacher, and warns when the range includes non-working days.
4. Principal, Vice Principal, Platform Admin or Admin approves or rejects; a teacher may edit or withdraw only their own pending request.
5. Approval is blocked when the remaining balance is short, with the shortfall in the error - an explicit override flag is required to approve anyway.
6. On approve, optionally name a substitute; they must be an active staff account and cannot be the teacher themselves.
7. Cover appears on /timetable under substitute tools, and the substitute sees the duty under My substitutes.

Student leave workflow

1. A parent opens /student-leave?childId= (notification deep links carry childId and studentId) or the student opens the same page for themselves.
2. Dates must fall inside the active academic year; the request is refused with a clear message if no active year exists or the range falls outside it.
3. An overlapping pending or approved request for the same student is rejected and names the conflicting record.
4. The class or co-class teacher approves or rejects; school leadership may decide without homeroom scope.
5. Only a pending request can be decided - once approved, rejected or cancelled it is final. Students and parents may cancel their own pending request.

Who decides what

What breaks if you skip a step

• Holidays not synced: a week-long leave over a festival break deducts days the teacher never owed, and the deduction sticks until the leave is rejected or deleted.
• No entitlement configured: the balance check has nothing to compare against and simply passes, so overdrawn leave is approved silently.
• Timetable not published: approving with a substitute creates no cover rows, because cover is built only from published slots.
• Rejecting a previously approved leave reverses the balance and cancels its cover rows; deleting an approved leave does the same, but only Principal or Admin may delete one.

Handoff and limits

Staff leave hands off to the timetable, which owns the cover rows and reports coverage gaps in its analytics, and to notifications, which tell the applicant and the substitute. It does not hand off to payroll: loss-of-pay leave types are recorded but no deduction is calculated. Student leave hands off only to notifications; attendance, fees and report cards read nothing from it.

• There is no multi-step approval chain - one approver decides.
• Cover is created per published timetable slot on the matching weekday, so an ad-hoc or unpublished class is never covered automatically.
• Half-day leave must start and end on the same date, and always counts as a single half unit against the balance.