Red Flags
Red flags are policy violations attached to an attendance record. Each flag has a code, a severity, and the unit's configured action.
Codes
| Code | Trigger |
|---|---|
LATE_CHECK_IN | First punch after start. |
EARLY_CHECK_OUT | Last punch before end. |
GEO_VIOLATION | Distance > geo_radius_m while geo is enabled. |
MULTIPLE_PUNCHES | More than one in or out inside a shift. |
MISSING_CHECK_OUT | first_in_at present but no last_out_at within window. |
MISSING_CHECK_IN | last_out_at present but no first_in_at. |
DEVICE_MISMATCH | Punch from a fingerprint not in devices(approved). |
SHIFT_WINDOW_VIOLATION | Punch outside [earliest_in, latest_out] after manual insertion. |
MANUAL_PUNCH | A manager recorded the punch on behalf of an employee. |
Actions
Per-unit policy in red_flag_policies:
| Action | Behavior |
|---|---|
allow_flag | Accept the punch, attach the flag, continue. |
block | Reject the punch with 400. |
require_approval | Accept the punch but hold the attendance row in pending_approval until HR decides. |
Severity
info— advisory, no side effects (MANUAL_PUNCH).warn— visible in reports (LATE_CHECK_IN,EARLY_CHECK_OUT).critical— gates payroll export (GEO_VIOLATION,DEVICE_MISMATCH,SHIFT_WINDOW_VIOLATION).
Report Filters
GET /api/v1/attendance?flag=LATE_CHECK_IN&since=2026-04-01 — every flag is a first-class filter for HR dashboards.
Testing Strategy
The RedFlagEngine has a deterministic test matrix. Every pair of (code × action) × (permutation of punches) is asserted in Pest.