Confidential leave categories, HR tools, in-app handbooks, i18n and performance

[karlitschek]

One combined PR for the August round of work, developed and verified on the devel instance with demo data. Everything is enforced server-side and covered by tests (215 PHP / 43 frontend, psalm clean).

Confidential leave categories (new §5.7)

Leave types gain an hr_only flag. Maternity leave 🤱, parental leave 🍼, medical work prohibition ⚕️ and doctor's note 🩺 ship seeded — on existing installations too, idempotently per key. HR records them by picking Sick leave and a Category; only HR ever sees which. Everyone else — including the employee's own views, calendars, timelines, balance rows and even the type list in the browser — gets a neutral "Absent". The admin's "reveal types" calendar setting deliberately does not extend to these.

HR-only disability flag on annual leave (new §5.8)

For the additional statutory entitlement: a tick HR can set when recording/editing annual leave. Withheld from every non-HR viewer (the employee included), excluded from the request history, recorded in the always-on audit log. A crafted self-service payload cannot set it.

HR tooling

• Exports accept a group filter (endpoint + UI, backed by a new HR-only GET /api/groups)
• Statistics reworked: average sick days per employee over the calendar year, and a "most vacation still to take" ranking of unplanned available days (flagging >50% of entitlement unused)
• Managers get a team balances table under the team timeline (GET /api/team/balances, scoped strictly to the caller's own reports — the same canViewBalanceOf rule that already applied per person)

In-app handbooks

Illustrated handbook for employees & team leads plus an extended HR edition, linked in the sidebar. Element-level screenshots ship under img/handbook/ (REUSE-covered); all strings translatable.

Correctness & UX

• Escalation job can no longer clobber a concurrent decision (conditional UPDATE … WHERE status='PENDING')
• Working days validated against the calendar span (catches the 40-for-4 typo)
• HR corrections publish an honest request_updated activity subject
• ⚠️ estimate warning under the working-days field in both dialogs
• Optional employees group setting: only members count as employees — keeps service accounts out and bounds directory enumeration on large instances

i18n

Every server-side user-facing string (domain exceptions, calendar titles, settings) now goes through IL10N; personal calendar events use the employee's language.

Performance (large-instance work)

• Direct reports resolved from one indexed preference query instead of walking the user backend on nearly every request; isManagerOf() reads the employee's own manager property
• Batch balances aggregated in SQL — scales with headcount, not years of history; single-employee views load only the requested year
• Session badges via COUNT(*); leave types memoised per request; new indexes (status, created_at) and supersedes_id

Docs & assets

README + SPECIFICATION updated throughout (§3.2, §5.7, §5.8, §13.1, indexes, manager resolution); screenshots refreshed against the current UI with descriptive names; built js/ included per convention. Version bump intentionally left out.

🤖 Generated with Claude Code