Table of Contents
1) Goal & Preconditions
Goal: Provide a unified Alerts page to view, filter, and act on tenant-relevant alerts: billing/payment, device, certification, operational tickets. Consolidates Alerts store, Devices (lastReading), MonthlyRollup, and Subscriptions.
Preconditions:
- Authenticated tenant user with facility access.
- Tenant has at least one facility with subscription and certification metadata.
- Alerts store retains at least last 90 days of alerts.
2) Page Layout & Components
Header
- Title: “Alerts” / «التنبيهات» (EN/AR)
- Global filter bar: Facility (multi), Date range (7/30/90/custom), Severity, Parameter, Alert type
- Quick KPIs: Total alerts (selected range), Critical, Payment issues
Tabs
- Billing & Payments: renewal failures, grace countdowns, payment method failures, reactivation pending, invoice failures. Direct CTA to facility/subscription billing/checkout.
- Device & Certification: offline, missing readings, threshold breaches (CO₂, Temp, Humidity, Cold/Water), certification expiry (90/30/7d), provisional warnings. View‑only.
Alerts Table (shared)
- Columns: Time (facility local), Severity, Type, Affected Entity (breadcrumb), Parameter, Value/Context, Actions.
- Actions: Pay (billing only) or View Facility (others).
Detail Drawer
- Full alert payload + related event timeline (read-only).
- Quick links: Go‑to‑Facility, Open Device Drawer.
- Billing alerts: prominent “Pay Now” button to billing/checkout page.
Modals
- Only Pay Now flow navigates to billing/checkout. No other modals; no acknowledge/snooze.
3) Functional Requirements (compact)
- Read from
GET /v1/alerts?tenantId=&facilityId=&from=&to=&type=&severity=&limit=&offset=(paginated). Default 90 days. - Optional WS/SSE for new-alert toasts; page remains read-only (no state changes).
- Server-side filters for performance; search by facility, device id, parameter, free-text.
- Billing: Pay Now CTA links to billing/checkout (no in-app retry here).
- Device/Certification: view-only; link to device/facility details.
- Visibility: Billing Hold still shows alerts; Pay CTA navigates to billing page.
4) Data mapping & storage
- Alerts — id, tenant_id, facility_id, device_id, param, value, severity, message, created_at, metadata.
- Devices — lastReading, status, lastSeen.
- Subscriptions — facility subscription status, graceEndsAt.
- MonthlyRollup — certification alerts input (expiry, within_pct thresholds).
Canonical shapes align with Dashboard & Assets docs.
5) API Stubs (suggested)
GET /v1/alerts?tenantId=&facilityId=&from=&to=&type=&severity=&limit=&offset=
200 { items: [ { alertId, tenantId, facilityId, deviceId, type, severity, param, value, message, createdAt, metadata } ], meta: { total, limit, offset } }
GET /v1/billing/checkout-link?facilityId=&subscriptionId=
200 { checkoutUrl }
WS/SSE /v1/alerts/stream?tenantId=
// UI shows visual notification only; read-only page
6) UX Copy (EN / AR) — examples
Payment Due banner
EN: “Payment issue detected. Renewal failed — X days left in grace. Resolve payment to avoid suspension.”
AR: «مشكلة في الدفع. فشل تجديد الاشتراك — تبقّى X يوم في فترة السماح. الرجاء تسوية الفاتورة لتجنب الإيقاف.»
Device offline alert (row)
EN: “CO2 Sensor — Offline (last seen 3h ago).”
AR: «جهاز CO2 — غير متصل (آخر ظهور منذ 3 ساعات).»
Certification warning
EN: “Certification expiring in 7 days — schedule renewal or contact support.”
AR: «ستنتهي الشهادة خلال 7 أيام — قم بتجديدها أو تواصل مع الدعم.»
7) Edge Cases & Rules
- Deduplicate by alert fingerprint (entity+param+value window) for display; provide optional “raw” toggle to show all events.
- Billing Hold: reports & cert downloads disabled at facility; alerts remain visible; Pay CTA still navigates to billing.
- Certification breaches: prefer MonthlyRollup; for intra‑month realtime breaches, use device×bucket with fallback to lastReading.
- No acknowledge/snooze/status changes on this page.
8) Acceptance Criteria
- Given facility payment failure, When Alerts → Billing, Then Payment alert shows Pay Now that opens checkout URL.
- Given device missed readings > threshold, When Alerts → Devices, Then offline alert includes lastSeen and link to device view.
- Given cert expiry ≤ 7 days, When Alerts page loads, Then certification‑expiry alert with CTA to facility certification page.
9) Analytics (events)
alert_page_viewed{ tenantId, userId, filters }alert_opened{ alertId, userId }alert_pay_clicked{ alertId, facilityId, userId }alert_stream_connected{ tenantId, userId }
10) Implementation notes & performance
- Cache KPIs for 30s; paginate alerts; index by (tenant_id, facility_id, created_at, severity).
- Rate‑limit payment retry endpoints and require idempotency keys (outside Alerts page scope).