Documentation Index
Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
Use this file to discover all available pages before exploring further.
Version: 1.0.0
Last Updated: 2026-03-09
Spec: specs/hr/specs/HR-05-ENHANCEMENTS.md
Overview
HR-05 Enhancements extend Time & Attendance with geofencing (EN-03), real-time exception alerts (EN-08), and planned integrations with PTO (EN-05), Payroll (EN-06), and Scheduling (EN-04).
Integration Points
EN-03: Advanced Geofencing (✅ Implemented)
| Aspect | Detail |
|---|
| Table | hr_site_geofence |
| Pattern | Intra-core (HR-05 ↔ HR punch validation) |
| Direction | HR Settings → Punch mutation reads geofence config |
| Cross-core? | No — uses PF pf_sites via FK only |
EN-08: Real-time Exception Alerts (✅ Implemented)
| Aspect | Detail |
|---|
| Pattern | Event (DB trigger → Edge Function → PF-10 notification) |
| Trigger | trg_hr_time_exceptions_notify on hr_time_exceptions INSERT |
| Edge Function | time-exception-notify |
| Channel | hr_events (via PF-10 notification system) |
| Notification Type | timesheet_exception |
| Recipient | Employee’s manager (resolved via hr_employees.manager_id) |
EN-05: PTO Integration (📝 Planned)
| Aspect | Detail |
|---|
| Pattern | Event-driven (HR-06 emits PTO-approved → HR-05 consumes) |
| Direction | HR-06 → HR-05 |
| Note | HR-06 does not currently emit this event; producer side must be coordinated |
EN-06: Automated Payroll Import (📝 Planned)
| Aspect | Detail |
|---|
| Pattern | API (HR-07 pulls approved timesheets from HR-05 endpoint) |
| Direction | HR-05 → HR-07 |
| Note | HR-07 consumer adoption is a separate coordination item |
Event Contracts
| Event | Publisher | Subscriber | Channel | Status |
|---|
hr_timesheet_exception_created | HR (DB trigger on hr_time_exceptions) | time-exception-notify edge function | hr_events | ✅ |
pto.approved | HR-06 | HR-05 (planned consumer) | domain_events | 📝 |
Payload Schema: hr_timesheet_exception_created
interface HrTimesheetExceptionCreatedPayload {
event_type: 'hr_timesheet_exception_created';
exception_id: string; // UUID
employee_id: string; // UUID
exception_type: string; // e.g. 'missed_punch', 'overtime', 'geofence_violation'
exception_date: string; // ISO date
organization_id: string; // UUID — required for tenant isolation
site_id?: string; // UUID — optional site context
timestamp: string; // ISO 8601 timestamptz
correlation_id?: string; // UUID — optional for distributed tracing
}
SQL Trigger Implementation
The trigger trg_hr_time_exceptions_notify fires on INSERT to hr_time_exceptions and calls the hr_notify_time_exception() SECURITY DEFINER function, which:
- Retrieves
supabase_functions_url and supabase_anon_key from the vault
- Skips notification if vault values are missing (fail-safe)
- POSTs to
time-exception-notify edge function with the payload above
Testing
- Unit: Verify
time-exception-notify edge function handles valid/invalid payloads
- Integration: Insert into
hr_time_exceptions and verify notification created in pf_notifications
- RLS: Confirm
hr_time_exceptions policies enforce org isolation
Backward Compatibility
This event was introduced in the same PR as the trigger — no prior consumers exist. The rename from timesheet_exception_created to hr_timesheet_exception_created follows the canonical {core}_{entity}_{action} naming convention.
Security
- All geofence operations scoped by
organization_id via RLS + application-level filter
- Exception notifications resolve recipients server-side (no client-side manager lookup)
- Geofence CRUD gated by
hr.geofence.view/create/update/delete permissions
- Edge function
time-exception-notify requires Authorization header
