MEGAINFRA-WEBAPP/docs/clock-daily-exceptions-rollout.md

MEGA Clock: new-day scans and missed scan-outs

Agreed operator behavior

The installed phone app keeps its existing SITE MANAGER ACCESS PIN page, Person scanner, confirmation screen, and API request shape. Workers do not sign in. A scan after midnight in Africa/Johannesburg starts a new IN for that local day, even if an earlier day's IN has no matching OUT. The older scan remains unresolved; the new day's later scan closes only the new day's attendance.

The on-site dashboard has a fourth Needs attention column. It shows unmatched earlier-day IN scans with no seven-day expiry. A worker can be both on site today and in Needs attention for an older day. Clicking a card asks for the actual leaving date, leaving time, and a reason. The original QR event is retained. A correction creates a separate audit row and updates or creates the direct time total for the original local day once.

There is no new login screen. The manual correction route checks the existing shared PIN against server APP_PIN and requires a same-origin request. The PIN is currently displayed on the app's login page and does not identify an individual operator; this is the current app's shared-PIN trust level. A future main-app login should replace this with a named user and site authorization before relying on individual accountability.

Implementation boundaries

• /api/clock/employee-lookup and /api/clock/scan keep the request and response fields used by installed phones. They compare the last scan's South African local date with today's local date. A prior-day IN yields nextDirection: "in" and creates a fresh raw IN event, with no hours for the old unresolved day.
• clock_events stays the QR audit log. No old event is edited or given a fabricated OUT.
• The dashboard derives unresolved scans from the full event history, independently of the seven-day Not arrived roster. Corrections are excluded by their unique clock_in_event link.
• The additive clock_missed_out_corrections collection stores the original IN event, worker, site, actual out instant, reason, recording instant, and direct timesheet entry. A unique index prevents two corrections for one IN. All direct browser rules are locked.
• The internal clock_correction_locks collection serializes corrections for one worker. A stale lock must be reviewed and removed by an administrator after verifying the correction and time entry; it is never silently stolen.
• A correction rejects a missing reason, leaving time before the original IN, a future time, a time overlapping the next IN, an already-resolved event, or duplicate direct time rows for the same employee/day. An imported sheet row is never updated. The direct time row and audit correction are written together in a PocketBase batch. The production batch setting was read-only checked as enabled (50 requests, 30-second timeout) on 2026-09-25.
• The exact PocketBase date filter uses a space (YYYY-MM-DD 00:00:00.000Z) even though app code writes ISO with T; this avoids missing an existing direct row. The timesheet's stored date remains midnight UTC for the local work date.
• The production service worker normally caches API GET responses using NetworkFirst. The new build gives employee lookup a NetworkOnly rule and a no-store response so yesterday's confirmation is not reused when the network is unavailable. Scan POST already requires a network connection.

Read-only evidence and local verification

At the last read-only check, production had 119 QR events: 63 IN and 56 OUT. The seven unresolved 23 September badges were MCW025, MCW034, MCW070, MCW127, MCW177, SUB00109, and SUB0098. The local dashboard preview showed seven Needs attention cards and zero on-site rows before any new-day scans. The local lookup endpoint returned in for all seven. Of the seven, only SUB00109 had an existing direct 23 September time row; it was unique. No live schema, event, time, or correction record was written during these checks.

The prior shift-backfill prototype found nine historical anomalies outside the immediate seven-case flow. This design avoids a historical backfill. Corrections for any employee/day with duplicate direct entries fail closed for manual review.

Tests cover the South African midnight boundary, old unmatched IN followed by today's IN, direct-row date matching, correction overlap, duplicate correction, imported-sheet preservation, and the worker appearing in today's state and Needs attention at once. On 2026-09-25 the complete Vitest suite passed (121 files, 1,372 tests), the production build passed, TypeScript passed, and the migration's two Python tests passed. The generated service worker contains the NetworkOnly employee-lookup rule before the default runtime routes. The migration's offline dry run reported the two locked collections and made no writes.

Production sequence (pending review)

1. Confirm a restorable PocketBase backup and save its local path. Do not remove or rewrite historical QR events.
2. Run scripts/migrations/2026-09-25-add-missed-clock-outs.py without flags using PB_URL, PB_ADMIN_EMAIL, and PB_ADMIN_PASSWORD; it prints a read-only schema diff. Review the two locked collections and unique indexes.
3. After the deployment decision, run the migration with --apply --backup-confirmed /absolute/path/to/backup. Read back the collection rules and indexes.
4. Deploy the app build as one server release. No phone app reinstall or new login is required. Open the installed PWA online so the updated service worker activates; verify the lookup reaches the network.
5. Before any test write, read back all seven lookups: each must say in. The dashboard must show seven Needs attention cards, with none falsely shown as On site now. Observe a real worker's new-day IN and later OUT; verify the older card remains until corrected. Do not use a live worker badge for a synthetic test.
6. For each correction, obtain the real leaving date/time and reason from the supervisor. After saving, read back the correction row, unchanged original IN event, and direct time entry for the original local date. Never guess a leaving time.

If the app release must be rolled back, pause worker scans first. Keep new correction rows and original QR events. Reconcile any new-day IN scans written after cutover before running the old scan server again, because the old server would treat an unmatched earlier-day IN as the next OUT.

Final gate

Do not apply the schema or deploy until this local diff, test/build results, backup, and the existing shared-PIN limitation have been reviewed. Production data remains untouched at this stage.

Paid hours rule

QR sessions store PAID hours, not the raw elapsed span, because the company pays and bills a fixed work schedule. The rule lives in one pure module, src/lib/clock-paid-hours.ts, and both the scan route and the missed-out correction call it, so a corrected arrival lands on the same day a QR scan would have recorded. All comparisons are in Africa/Johannesburg, and the schedule is chosen from the work date of the IN scan.

The schedule is:

Day	Paid shift	Expected hours
Monday–Thursday	07:00–16:30	9.00
Friday	07:00–15:00	7.50
Last Friday of the month	07:00–12:00	5.00
Saturday / Sunday	07:00–16:30	none (all work is extra)

• Paid start: an IN at or before 10 minutes past the shift start (any earlier too) pays from the shift start; anything later pays from the actual scan instant (short day).
• Paid end: an OUT within 10 minutes either side of the shift end (16:20–16:40, 14:50–15:10, 11:50–12:10) pays to the shift end; an earlier exit is a short day, a later one is overtime.
• Lunch is smooth rather than a cliff: one minute of lunch per minute of span past 5 hours, capped at 30 minutes. So 9.5h span pays 9.00, 8h pays 7.50, 5h and 5h11 both pay 5.00, 5h45 pays 5.25, and anything under 5h is unpaid in full (a rain-shortened 2h50 pays 2.83). Paid hours are rounded to 2 decimals.

Examples: 06:52 to 16:34 is 9.00, 07:10 to 16:40 is 9.00, 07:15 to 16:30 is 8.75, 07:00 to 17:30 is 10.00. On a Friday 06:55 to 15:08 is 7.50, 07:00 to 15:11 is 7.68 and 07:00 to 14:49 is 7.32. On the last Friday of the month 06:58 to 12:06 is 5.00, 07:00 to 12:11 is 5.00 (the smooth lunch absorbs the extra minute) and 07:00 to 11:49 is 4.82; working on to 15:00 that day is 7.50.

Because the timesheet matrix reads the stored hours, it needs no change and renders the same paid figures with worked status. The worker calendar does change: it used to compare every day against the employee's single stored hours_per_day_standard. It now compares each day against expectedPaidHours(date), so a 9-hour Friday correctly shows as extra rather than normal, and a 5-hour last Friday is a full day. The calendar day details label the figure "Paid hours" with the day's expected hours and its kind (Mon–Thu / Friday / Last Friday / Weekend), and the worker detail cards show the schedule (9h Mon–Thu, 43.5h standard week) instead of the stored standard hours.

scripts/migrations/2026-10-09-recalc-clock-paid-hours.py replays the rule over existing scans so rows written before the change agree with new ones. It is dry-run by default and only writes with --apply and --backup-confirmed pointing at an existing directory, where it writes 2026-10-09-recalc-clock-paid-hours-v2.json. An entry is rewritten when its stored hours still match the recomputed raw total or the superseded v1 paid total, so hand-edited rows are skipped and reported rather than overwritten; entries already on the current rule are reported as unchanged, which makes a re-run a no-op. The earlier rule is kept in the script as paid_session_hours_v1 purely to recognise what the first run wrote. Its read-only dry run on 2026-10-09 (before the schedule change) reported 467 rows to change, 29 unchanged and 0 skipped.