Alerty krytyczne (Monitoring systemu)

Wykaz sytuacji awaryjnych, które system AcePark wykrywa automatycznie i sygnalizuje pracownikowi czerwonym lub pomarańczowym paskiem na samej górze panelu (CriticalAlertBar).

W odróżnieniu od Powiadomień systemowych, które komunikują się z klientem (e-mail / SMS), alerty krytyczne są skierowane do pracownika i informują o problemach technicznych wymagających reakcji obsługi (odrzucona faktura KSeF, błąd fiskalizacji paragonu, drukarka offline itd.).

👤 Instrukcja dla pracownika (Recepcja / Administracja)

Gdy system wykryje problem techniczny, na górze panelu pojawia się pasek z opisem awarii:

• Czerwony pasek = błąd krytyczny (critical) – wymaga reakcji, część operacji może być wstrzymana (np. nie powstał paragon / faktura).
• Pomarańczowy pasek = ostrzeżenie (warning) – sytuacja niepokojąca, ale niepilna (np. faktura długo czeka na potwierdzenie z KSeF).

Co zrobić, gdy widzisz alert?

1. Przeczytaj treść – pasek wskazuje czego dotyczy problem (numer faktury, numer płatności, nazwę urządzenia).
2. Kliknij „Napraw teraz" – przenosi Cię bezpośrednio do sekcji, w której można rozwiązać problem (np. lista płatności, panel sprzętu, faktura w Fakturowni).
3. Po rozwiązaniu zamknij alert krzyżykiem (✕). Alert znika dopiero po ręcznym zamknięciu — system nie usuwa go sam, aby problem nie został przeoczony.

Brak zalewania alertami

System deduplikuje powiadomienia o tej samej treści. Jeśli ten sam błąd powtarza się wielokrotnie (np. drukarka cyklicznie traci połączenie), na pasku pojawi się tylko jeden alert, a nie dziesiątki identycznych.

Rodzaje wykrywanych awarii

Sytuacja	Poziom	Co oznacza dla pracownika
Faktura odrzucona przez KSeF	🔴 Krytyczny	Krajowy System e-Faktur odrzucił dokument. Faktura nie jest wprowadzona do obiegu prawnego — trzeba ją poprawić w Fakturowni.
Błąd komunikacji z KSeF	🔴 Krytyczny	Nie udało się przesłać faktury do KSeF (błąd techniczny). Należy ponowić wysyłkę.
Faktura czeka na potwierdzenie KSeF (> 4h)	🟠 Ostrzeżenie	Dokument wysłany, ale od ponad 4 godzin brak potwierdzenia. Zwykle ustępuje sam; jeśli trwa — sprawdź status w Fakturowni.
Błąd przetwarzania paragonu	🔴 Krytyczny	Online'owa fiskalizacja paragonu po płatności nie powiodła się. Paragon może wymagać ręcznego wystawienia.
Błąd wystawienia dokumentu w Fakturowni	🔴 Krytyczny	Nie udało się wygenerować faktury/paragonu dla płatności (np. API Fakturowni nie odpowiada).
Urządzenie offline (drukarka / sterownik)	🔴 Krytyczny	Drukarka fiskalna lub sterownik kortu przestał odpowiadać. Sprzedaż detaliczna na tym urządzeniu może być niemożliwa.
Alert testowy	🔴 Krytyczny	Wygenerowany ręcznie z zakładki Powiadomienia → testy w celu weryfikacji działania paska.

Powiązania

Kontekst faktur i paragonów: zob. Wystawianie Faktur i Paragony. Komunikacja z klientem (e-mail/SMS): zob. Powiadomienia systemowe.

---

🛠️ Dokumentacja techniczna

Przeznaczone dla QA / Devs.

Architektura

Warstwa	Plik	Rola
Baza danych	migrations/0139_create_critical_notifications_table.sql	Tabela critical_notifications (typ, severity, message, action_url, metadata, is_resolved, email_sent).
Akcje serwerowe	lib/actions/critical-notifications.ts	createCriticalNotification (z deduplikacją aktywnych), getActiveCriticalNotifications, resolveCriticalNotification, createTestCriticalNotification.
Monitoring KSeF	lib/actions/ksef-monitoring.ts	syncKSeFStatuses – odpytuje API Fakturowni o gov_status faktur z ostatnich 2 dni.
Hook paragonów	lib/actions/receipt-management.ts	Generuje alert e-receipt po nieudanej fiskalizacji w processReceiptAfterPayment.
Hook faktur	lib/actions/invoice-generation.ts	Generuje alert sync w bloku catch generateInvoiceFromPayment.
Hook sprzętu	lib/hardware-alerts.ts	checkAndSendHardwareAlerts – przy zdarzeniu offline_alert tworzy alert printer.
UI – pasek	components/notifications/CriticalAlertBar.tsx	Czerwony/pomarańczowy pasek; odświeża się co 2 minuty.
UI – layout	components/layout/dashboard-layout-wrapper.tsx	Przesuwa Header/Sidebar w dół, gdy pasek jest aktywny.
Stan globalny	lib/store/critical-notifications-store.ts	Zustand – globalna flaga hasActiveNotifications.
Tłumaczenia	messages/pl.json, messages/en.json	Klucz criticalNotifications.

Typy i wyzwalacze

type	severity	Źródło	Wyzwalacz
ksef	critical	syncKSeFStatuses (cron)	gov_status = rejected lub error
ksef	warning	syncKSeFStatuses (cron)	gov_status = pending/sent oraz gov_send_date starsze niż 4h
e-receipt	critical	processReceiptAfterPayment (hook)	Wyjątek przy fiskalizacji online paragonu
sync	critical	generateInvoiceFromPayment (hook)	Wyjątek przy generowaniu dokumentu w Fakturowni
printer	critical	checkAndSendHardwareAlerts (cron)	hardware_event_log.event_type = offline_alert
system	critical	createTestCriticalNotification	Ręczne wywołanie testowe

Wielodostępność (multi-tenant)

Alerty printer zapisywane są z tenant_id pochodzącym z rekordu hardware_event_log, dzięki czemu są poprawne także w środowisku wielu najemców. Pozostałe alerty używają getTenant() (domyślnie ace-park).

Zaplanowane zadania (Crons)

Cron	Częstotliwość	Zadanie	Powiązane alerty
*/30 * * * *	co 30 min	syncKSeFStatuses (bramkowany przez runGatedCron('ksef_status_sync'))	ksef
0 * * * *	co godzinę	checkAndSendHardwareAlerts	printer

Pozostałe alerty (e-receipt, sync) powstają synchronicznie w trakcie rozliczania płatności, nie w cronie.

Test lokalny crona KSeF (wymaga yarn dev:worker):

curl "http://localhost:3000/__scheduled?cron=*/30%20*%20*%20*%20*"

Test crona sprzętowego (godzinowego):

curl "http://localhost:3000/__scheduled?cron=0%20*%20*%20*%20*"

Test ręczny z panelu

W zakładce Dashboard → Powiadomienia (testy) (notification-tests) dostępne są przyciski:

• Utwórz testowy alert – wywołuje createTestCriticalNotification i przeładowuje stronę (pasek powinien się pojawić).
• Synchronizuj KSeF – ręcznie uruchamia syncKSeFStatuses i pokazuje liczbę wykrytych problemów (issuesFound).

Lista kontrolna QA

• Po utworzeniu testowego alertu pasek pojawia się na górze i przesuwa Header/Sidebar w dół.
• Kliknięcie „Napraw teraz" przekierowuje pod action_url.
• Zamknięcie (✕) ustawia is_resolved = 1 i pasek znika.
• Powtórne wywołanie tego samego błędu nie tworzy duplikatu (dedup po type + message + is_resolved = 0).
• Alert printer zapisywany jest z tenant_id urządzenia.
• Alert warning KSeF powstaje dopiero po przekroczeniu 4h od gov_send_date.