tasq/.github/prompts/plan-attendanceShiftReminders.prompt.md

Plan: Attendance Shift Reminders (pg_cron / Supabase-scheduled)

TL;DR — Use pg_cron in your Supabase Postgres to schedule a SQL job every minute that enqueues due notifications into a Postgres table (scheduled_notifications). A lightweight processor (preferred: Cloud Run worker) will pick up queued notifications, deduplicate via notification_pushes/try_mark_notification_pushed, and call the existing send_fcm function to deliver pushes. This makes scheduling fully server-side and reliable even when user devices are offline.

High-level approach

• Use Postgres-side scheduling (pg_cron) to run a stored procedure every minute. The stored procedure finds:
  • shifts starting in ~15 minutes (15-minute reminder), and
  • shifts ending now (exact end reminder).
• The procedure enqueues one row per user per reminder into scheduled_notifications (idempotent insert).
• A processor service (Cloud Run worker or Edge Function) polls or streams scheduled_notifications rows, marks them using try_mark_notification_pushed(notification_id) and calls send_fcm for delivery.

Why this design?

• pg_cron keeps scheduling close to data and avoids external cron reliance.
• Enqueue + processor splits concerns: SQL is simple and reliable; sending FCM is a network task better handled in application code.
• Deduplication and skip-if-checked logic are enforced before enqueue and again at send-time for safety.

Detailed Steps

1. Add DB schema and helper functions

• notification_pushes (dedupe table) — if not present, create: CREATE TABLE IF NOT EXISTS notification_pushes ( notification_id text PRIMARY KEY, created_at timestamptz DEFAULT now(), payload jsonb );

• scheduled_notifications (queue table): CREATE TABLE IF NOT EXISTS scheduled_notifications ( id bigserial PRIMARY KEY, schedule_id bigint NOT NULL, user_id uuid NOT NULL, notify_type text NOT NULL, -- 'start_15' | 'end' scheduled_for timestamptz NOT NULL, created_at timestamptz DEFAULT now(), processed boolean DEFAULT false, processed_at timestamptz, retry_count int DEFAULT 0, last_error text ); CREATE INDEX ON scheduled_notifications (processed, scheduled_for); ALTER TABLE scheduled_notifications ADD CONSTRAINT IF NOT EXISTS uniq_sched_user_type UNIQUE (schedule_id, user_id, notify_type);

• try_mark_notification_pushed SQL helper (if not present): CREATE OR REPLACE FUNCTION try_mark_notification_pushed(nid text, payload jsonb DEFAULT '{}'::jsonb) RETURNS boolean LANGUAGE plpgsql AS $$ BEGIN INSERT INTO notification_pushes(notification_id, payload) VALUES (nid, payload); RETURN TRUE; EXCEPTION WHEN unique_violation THEN RETURN FALSE; END;

  ;
  
  

2. Stored procedure to enqueue due reminders

• Function: enqueue_due_shift_notifications()

• Behavior:

  • Compute current UTC now().
  • For 15-minute reminders: find duty_schedules where start_at BETWEEN now() + interval '15 minutes' - interval '30 seconds' AND now() + interval '15 minutes' + interval '30 seconds' (1-minute window). Adjust tolerance as desired.
  • For end reminders: find duty_schedules where end_at BETWEEN now() - interval '30 seconds' AND now() + interval '30 seconds'.
  • For each schedule, resolve the assigned user_id (or multiple participants).
  • Skip enqueue if attendance_logs already shows a check-in for that schedule and remind type is start_15 (you selected this behavior).
  • Insert into scheduled_notifications with ON CONFLICT DO NOTHING to avoid duplicates.

• Example function outline (PL/pgSQL): CREATE OR REPLACE FUNCTION enqueue_due_shift_notifications() RETURNS void LANGUAGE plpgsql AS $$ DECLARE rec RECORD; BEGIN FOR rec IN SELECT id AS schedule_id, assigned_user_id AS user_id, start_at FROM duty_schedules WHERE start_at BETWEEN now() + interval '15 minutes' - interval '30 seconds' AND now() + interval '15 minutes' + interval '30 seconds' AND status = 'active' LOOP IF EXISTS (SELECT 1 FROM attendance_logs al WHERE al.schedule_id = rec.schedule_id AND al.type = 'check_in') THEN CONTINUE; END IF; INSERT INTO scheduled_notifications (schedule_id, user_id, notify_type, scheduled_for) VALUES (rec.schedule_id, rec.user_id, 'start_15', rec.start_at) ON CONFLICT (schedule_id, user_id, notify_type) DO NOTHING; END LOOP;

  FOR rec IN SELECT id AS schedule_id, assigned_user_id AS user_id, end_at FROM duty_schedules WHERE end_at BETWEEN now() - interval '30 seconds' AND now() + interval '30 seconds' AND status = 'active' LOOP INSERT INTO scheduled_notifications (schedule_id, user_id, notify_type, scheduled_for) VALUES (rec.schedule_id, rec.user_id, 'end', rec.end_at) ON CONFLICT (schedule_id, user_id, notify_type) DO NOTHING; END LOOP; END;

  ;
  
  

3. Schedule pg_cron job

• Enable pg_cron (Supabase project admin). Schedule: SELECT cron.schedule('shift_reminders_every_min', '*/1 * * * *', $$SELECT enqueue_due_shift_notifications();$$);
• Monitor cron.job and cron.job_run_details tables for health.

4. Processor options (choose one)

• Option A — Cloud Run / long-running worker (recommended):

  • Worker responsibilities:
    • Poll scheduled_notifications WHERE processed = false AND scheduled_for <= now() in batches, or LISTEN for notifications.
    • For each row: build notification_id = 'shift-' || schedule_id || '-' || user_id || '-' || notify_type.
    • Call SELECT try_mark_notification_pushed(notification_id, to_jsonb(row)); if it returns false, skip (already sent).
    • Otherwise, fetch FCM tokens for user_id from fcm_tokens table, and call existing send_fcm edge function (HTTP) with payload {user_id, title, body, data, notification_id} batching tokens if needed.
    • Mark scheduled row processed (processed = true, processed_at = now()). On transient failure increment retry_count and update last_error.
  • Deploy worker to Cloud Run with SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, SEND_FCM_URL as secrets.

• Option B — Supabase Edge Function polling (if you prefer serverless):

  • Deploy an Edge Function process_scheduled_notifications that runs quickly and processes a batch then exits. Use pg_cron to call it via HTTP if pg_http is enabled, or use GitHub Actions scheduled trigger to call it frequently. Less real-time but serverless-friendly.

• Option C — Postgres direct HTTP (only if pg_http / pg_net available):

  • Extend enqueue function to directly POST to send_fcm endpoint. Not recommended unless your Supabase instance supports and you accept putting external calls in DB.

5. Security & roles

• pg_cron runs as the role that created the cron job; ensure it has SELECT on duty_schedules and INSERT on scheduled_notifications.
• Processor uses SUPABASE_SERVICE_ROLE_KEY for API calls and to read fcm_tokens.

6. Observability, retries, and failure handling

• Add a retry_count and last_error to scheduled_notifications (already included) for DB-visible retries.
• Structured logs in the processor: notification_id, schedule_id, user_id, token_count, status.
• Monitor scheduled_notifications rows with retry_count > threshold.

7. Tests & verification

• Unit tests for enqueue_due_shift_notifications().
• Manual test: insert a test duty_schedules record 15 minutes ahead; run the function manually; assert a row in scheduled_notifications.
• Run processor in staging and confirm notification_pushes has the notification_id and device receives the push.

Files / artifacts to add

• supabase/migrations/xxxx_add_scheduled_notifications.sql — create tables and helper functions above.
• supabase/migrations/xxxx_add_notification_pushes.sql — if missing (or reuse existing migration).
• tools/notification_processor/ — worker service (Node or Dart) with Dockerfile for Cloud Run.
• DEPLOYMENT.md — enable pg_cron, run migrations, deploy processor, and set secrets.

Operational notes

• Ensure start_at / end_at columns are timestamptz and queries are UTC-aware.
• Skip-if-checked enforced at enqueue; processor double-checks dedupe before sending.
• Tune time window and polling batch sizes for expected scale.

Verification checklist

1. Enable pg_cron and run migrations to create scheduled_notifications and notification_pushes.
2. Manually call enqueue_due_shift_notifications() and confirm expected rows are created.
3. Start processor locally against staging DB; verify processing updates notification_pushes and calls send_fcm (mock/staging endpoint).
4. Validate on-device push delivery and skip-if-checked behavior.

Decision / assumptions

• Preferred flow: pg_cron enqueue + Cloud Run processor.
• If DB http extensions are available and approved, a simpler single-step approach is possible but less portable.
• You asked to skip reminders if user already checked in — implemented at enqueue time.