Ammonly Docs

Motyw

Zadania CRON i Harmonogram Automatyzacji ​

Silnik Harmonogramu Zadań CRON w platformie Ammonly odpowiada za w pełni zautomatyzowane, cykliczne wykonywanie krytycznych procesów w tle, takich jak synchronizacja poczty i kalendarzy, nadzór nad statusem spraw biznesowych, kolejkowanie zadań asynchronicznych oraz automatyczne czyszczenie logów.

Architektura API-First i Multi-DB

Zadania CRON operują w architekturze Multi-Tenant/Multi-DB. Wszystkie zadania implementują standardowy interfejs CronTaskInterface i mogą być wykonywane zarówno w profilu zarządzania konsolą (app-admin), jak i w profilach biznesowych klientów SaaS (app-client).

Spis treści ​

1. Architektura silnika zadań CRON ​

Silnik harmonogramu opiera się na centralnym rejestrze zadań (a_mod_cron_records), rejestrze logów wykonania (a_logs_cron_records) oraz module wykonawczym CronRunner.

mermaid
flowchart TD
    SystemCron[Systemowy Demon Cron OS: * * * * *] --> CLIEntry[CLI Entrypoint: php bin/cron]
    CLIEntry --> CronRunner[CronRunner Engine]
    CronRunner --> ReadTasks[Odczyt aktywnych zadan z a_mod_cron_records]
    ReadTasks --> CheckSchedule{Czy nadszedl czas wg wyrazenia cron?}
    CheckSchedule -- Nie --> Skip[Pomin zadanie]
    CheckSchedule -- Tak --> CheckLock{Czy is_running = 1?}
    CheckLock -- Tak i nie wygasl timeout --> SkipRunning[Pomin: zadanie w toku]
    CheckLock -- Nie lub timeout wygasl --> Execute[Wywolaj command_class::run]
    Execute --> AuditLog[Zapisz czas, status i pamiec w a_logs_cron_records]
    AuditLog --> UpdateNextRun[Zaktualizuj next_run_at i is_running = 0]

Kluczowe właściwości architektury: ​

  1. Pojedynczy interfejs kontraktowy: Każda klasa zadania implementuje App\Core\Cron\CronTaskInterface z metodą public function run(): string.
  2. Zabezpieczenie przed zakleszczeniem (Concurrency Lock): Każde zadanie oznacza flagę is_running = 1 wraz ze znacznikiem czasu. W przypadku awarii serwera, po przekroczeniu timeout_seconds zadanie jest resetowane.
  3. Izolacja bazodanowa: Każde zadanie używa dynamicznego mechanizmu MultiDbRouter lub FallbackPdoResolver, dzięki czemu może operować na właściwym schemacie (ammonly_admin lub ammonly_client).

2. Atrybuty konfiguracyjne i metryki zadania ​

Tabela a_mod_cron_records definiuje zachowanie każdego zadania:

PoleTypOpis
nameVARCHAR(64)Unikalna nazwa identyfikacyjna zadania (np. calendar_status_supervisor).
labelVARCHAR(255)Czytelna nazwa wyświetlana w panelu administracyjnym.
command_classVARCHAR(255)W pełni kwalifikowana nazwa klasy PHP implementującej CronTaskInterface.
expressionVARCHAR(64)Standardowe 5-polowe wyrażenie cron (np. */15 * * * * lub 0 3 * * *).
timeout_secondsINTMaksymalny dozwolony czas trwania (domyślnie 300 sekund) przed zwolnieniem blokady.
is_activeTINYINT(1)Flaga włączenia zadania (1 = aktywne, 0 = wyłączone).
is_runningTINYINT(1)Flaga aktywnego wykonywania (1 = w trakcie biegu).
last_run_atDATETIMEZnacznik czasu ostatniego uruchomienia.
next_run_atDATETIMEWyliczony czas następnego planowanego wykonania.
last_statusVARCHAR(32)Status ostatniego wykonania: success, failed, running, idle.
last_duration_msINTCzas wykonania zadania w milisekundach.

3. Szczegółowy katalog akcji CRON ​

Poniżej znajduje się kompletny opis wszystkich akcji automatyzacji zaimplementowanych w platformie Ammonly:

3.1. Nadzorca statusów zdarzeń kalendarza (calendar_status_supervisor) ​

  • Identyfikator techniczny: calendar_status_supervisor
  • Klasa wykonawcza: App\Modules\Calendar\Task\CalendarStatusSupervisorTask
  • Harmonogram domyślny: * * * * * (co minutę)
  • Dostępność w profilach: client, admin

Cel i zasada działania: ​

Automatycznie nadzoruje cykl życia wszystkich zdarzeń zarejestrowanych w module Kalendarza (a_mod_calendar_records). Zapewnia, że statusy spotkań, telefonów i zadań odzwierciedlają upływający czas rzeczywisty:

  1. Przejście planned ➔ in_progress: Gdy nadejdzie czas rozpoczęcia spotkania (start_date <= NOW() < end_date), zadanie automatycznie przestawia status na „W trakcie” (in_progress), co skutkuje żółtym wyróżnieniem w kalendarzu i na pulpicie.
  2. Przejście planned / in_progress ➔ overdue: Gdy minie planowany czas zakończenia (end_date <= NOW()), a zdarzenie nie zostało wcześniej zamknięte przez użytkownika, zadanie oznacza je jako „Zaległe” (overdue), generując czerwony alert w widgetach.
  3. Ochrona stanów końcowych: Statusy terminalne (completed, cancelled, postponed) są nienaruszalne i nigdy nie podlegają automatycznej modyfikacji.

Wpływ na działanie systemu

Bez tego zadania zdarzenia w kalendarzu pozostawałyby w stanie planowanym nawet po upływie terminu spotkania, co uniemożliwiłoby poprawne działanie widgetów zaległych spraw na pulpicie (Dashboard).

3.2. Synchronizacja poczty przychodzącej i Helpdesk (inbound_email_sync) ​

  • Identyfikator techniczny: inbound_email_sync
  • Klasa wykonawcza: App\Modules\Mail\Task\InboundEmailSyncTask
  • Harmonogram domyślny: * * * * * (co minutę)
  • Dostępność w profilach: client, admin

Cel i zasada działania: ​

Łączy się ze wszystkimi aktywnymi skrzynkami systemowymi oraz kontami użytkowników (protokoły IMAP / POP3 / SSL) w celu pobrania nowej korespondencji:

  1. Pobieranie i dekodowanie wiadomości: Pobiera nagłówki RFC 822, treść MIME (HTML i tekst zwykły) oraz załączniki, zapisując je w a_mod_emails_records.
  2. Kojarzenie z kartoteką CRM: Na podstawie adresu e-mail nadawcy automatycznie wiąże wiadomość z istniejącą firmą (companies) lub kontaktem (contacts).
  3. Automatyzacja Email-to-Ticket: Dla wiadomości trafiających na dedykowane skrzynki wsparcia (Helpdesk) uruchamia reguły automatycznego tworzenia nowych zgłoszeń serwisowych (tickets) lub dołączania odpowiedzi do istniejącego wątku zgłoszenia.

3.3. Dyspozytor wychodzącej kolejki e-mail (mail_queue_worker) ​

  • Identyfikator techniczny: mail_queue_worker
  • Klasa wykonawcza: App\Modules\Mail\Task\ProcessMailQueueTask
  • Harmonogram domyślny: * * * * * (co minutę)
  • Dostępność w profilach: client, admin

Cel i zasada działania: ​

Odpowiada za bezpieczną, asynchroniczną wysyłkę wiadomości zebranych w kolejce a_mod_mail_queue_records:

  1. Pobieranie oczekujących paczek: Wybiera wiadomości o statusie pending, posortowane wg priorytetu (high, normal, low) i daty zakolejkowania.
  2. Wysyłka przez właściwy serwer SMTP: Używa poświadczeń przypisanych do skrzynki nadawcy lub globalnego serwera SMTP systemu.
  3. Obsługa błędów i ponowień (Retry Loop): W przypadku przejściowych błędów sieciowych lub odmowy SMTP (Greylisting, błędy 4xx), zadanie zwiększa licznik prób (attempts_count) i planuje ponowienie z wykładniczym opóźnieniem (Exponential Backoff). Po przekroczeniu limitu prób wiadomość otrzymuje status failed.

3.4. Robot kolejki zadań asynchronicznych (queue_worker) ​

  • Identyfikator techniczny: queue_worker
  • Klasa wykonawcza: App\Modules\Automation\Queue\Task\ProcessQueueTask
  • Harmonogram domyślny: * * * * * (co minutę)
  • Dostępność w profilach: client, admin

Cel i zasada działania: ​

Przetwarza ciężkie operacje w tle zarejestrowane w tabeli a_mod_queue_records:

  1. Zadania w tle: Masowe operacje na rekordach (edycja masowa, usuwanie kaskadowe), przebudowa struktur WBS, generowanie zestawień analitycznych, przeliczanie sum wartości kontraktów i budżetów projektów.
  2. Śledzenie postępu w czasie rzeczywistym: Aktualizuje wskaźnik procentowy progress_percent oraz liczniki processed_items / total_items, umożliwiając prezentację paska postępu w interfejsie użytkownika.
  3. Wykrywanie zawieszonych zadań (Heartbeat): Co kilka sekund odświeża znacznik heartbeat_at. Jeśli proces padnie, kolejny przebieg robota przejmie lub zrestartuje przerwane zadanie.

3.5. Synchronizacja wychodząca CalDAV/CardDAV (dav_queue_worker) ​

  • Identyfikator techniczny: dav_queue_worker
  • Klasa wykonawcza: App\Modules\Dav\Task\ProcessDavQueueTask
  • Harmonogram domyślny: * * * * * (co minutę)
  • Dostępność w profilach: client, admin

Cel i zasada działania: ​

Wysyła lokalne modyfikacje zdarzeń kalendarza oraz kontaktów do zewnętrznych serwerów CalDAV/CardDAV (np. Google Calendar, Apple iCloud, Nextcloud, Microsoft Exchange via DavGateway):

  1. Generuje obiekty iCalendar (RFC 5545) oraz vCard (RFC 6352).
  2. Wysyła zapytania PUT, DELETE lub PROPPATCH z zachowaniem wersji ETag i sekwencji rewizji (sequence).

3.6. Synchronizacja przychodząca CalDAV/CardDAV (dav_pull_sync) ​

  • Identyfikator techniczny: dav_pull_sync
  • Klasa wykonawcza: App\Modules\Dav\Task\PullDavSyncTask
  • Harmonogram domyślny: */2 * * * * (co 2 minuty)
  • Dostępność w profilach: client, admin

Cel i zasada działania: ​

Cyklicznie odpytuje zewnętrzne serwery CalDAV/CardDAV (metoda REPORT / sync-collection) o nowe zdarzenia i kontakty utworzone na urządzeniach mobilnych użytkowników:

  1. Pobiera zmienione zasoby i parsuje struktury .ics oraz .vcf.
  2. Zapisuje nowe rekordy w bazie Ammonly lub aktualizuje istniejące powiązania.

3.7. Czyszczenie wygasłych sesji użytkowników (session_cleanup) ​

  • Identyfikator techniczny: session_cleanup
  • Klasa wykonawcza: App\Core\Session\CleanupExpiredSessionsTask
  • Harmonogram domyślny: */15 * * * * (co 15 minut)
  • Dostępność w profilach: admin, client

Cel i zasada działania: ​

Usuwa przeterminowane sesje użytkowników z tabeli a_mod_user_sessions:

  1. Porównuje znacznik last_activity z globalnym czasem życia sesji (session.lifetime).
  2. Trwale usuwa rekordy wygasłych sesji, chroniąc bazę przed niekontrolowanym wzrostem wolumenu danych oraz realizując wytyczne bezpieczeństwa NIST AC-12 (Session Termination).

3.8. Retencja i czyszczenie logów CRON (cron_log_cleanup) ​

  • Identyfikator techniczny: cron_log_cleanup
  • Klasa wykonawcza: App\Core\Cron\CleanupCronLogsTask
  • Harmonogram domyślny: 0 3 * * * (codziennie o 03:00 w nocy)
  • Dostępność w profilach: admin, client

Cel i zasada działania: ​

Czyści wpisy w dzienniku a_logs_cron_records starsze niż zdefiniowany w parametrach systemu okres retencji (domyślnie 30 dni), zapobiegając degradacji wydajności zapytań indeksowych bazy.

3.9. Retencja i czyszczenie logów żądań API (api_log_cleanup) ​

  • Identyfikator techniczny: api_log_cleanup
  • Klasa wykonawcza: App\Core\Cron\CleanupApiLogsTask
  • Harmonogram domyślny: 0 3 * * * (codziennie o 03:00 w nocy)
  • Dostępność w profilach: admin, client

Cel i zasada działania: ​

Przegląda tabelę rejestru wywołań interfejsu REST/HTMX a_logs_api_requests_records i usuwa wpisy przekraczające dopuszczalny okres przechowywania (zgodnie ze standardami NIST AU-9 oraz AU-11).

3.10. Retencja dziennika audytowego (audit_log_cleanup) ​

  • Identyfikator techniczny: audit_log_cleanup
  • Klasa wykonawcza: App\Core\Audit\Infrastructure\Cron\AuditRetentionCronJob
  • Harmonogram domyślny: 0 4 * * * (codziennie o 04:00 w nocy)
  • Dostępność w profilach: admin, client

Cel i zasada działania: ​

Nadzoruje tabele dziennika audytu zmian (a_logs_audit_create_records, a_logs_audit_read_records, a_logs_audit_update_records, a_logs_audit_delete_records). Archiwizuje lub usuwa wpisy starsze niż ustalony okres zgodności prawnej i bezpieczeństwa (np. 90 lub 365 dni).

3.11. Asynchroniczne generowanie dokumentów PDF (pdf_queue_worker) ​

  • Identyfikator techniczny: pdf_queue_worker
  • Klasa wykonawcza: App\Modules\Pdf\Task\ProcessPdfQueueTask
  • Dostępność w profilach: admin, client

Cel i zasada działania: ​

Pobiera zadania masowego generowania plików PDF (faktury, oferty handlowe, raporty kart pracy, umowy SLA) i kompiluje szablony HTML/Twig do plików PDF w tle, zapobiegając blokowaniu żądań HTTP użytkowników.

4. Cykl życia i diagram wykonania zadania ​

mermaid
stateDiagram-v2
    [*] --> Idle: Inicjalizacja zadania
    Idle --> Scheduled: Nadszedł czas (Cron Expression)
    Scheduled --> Running: Przejęcie blokady (is_running = 1)
    Running --> Success: Wykonanie poprawne (run() -> string)
    Running --> Failed: Błąd / Wyjątek Throwable
    Running --> Timeout: Przekroczenie timeout_seconds
    Timeout --> Idle: Zwolnienie blokady przez Supervisor
    Success --> Idle: Zapis logu, is_running = 0, wyliczenie next_run_at
    Failed --> Idle: Zapis błędu w logu, is_running = 0

5. Zarządzanie zadaniami z poziomu CLI i API ​

Uruchamianie przez konsolę CLI: ​

bash
# Uruchomienie pełnego przebiegu wszystkich oczekujących zadań
php bin/cron

# Wymuszenie natychmiastowego wykonania konkretnego zadania
php bin/cron --task=calendar_status_supervisor

# Uruchomienie harmonogramu dla konkretnego profilu
php bin/cron --profile=client

Zarządzanie przez panel WWW i REST API: ​

  • Panel Administratora: Moduł dostępny pod ścieżką /automation/cron.
  • REST API Endpoint:
    • GET /api/v1/engine/automation_cron/records – pobranie listy zadań i ich statusów.
    • POST /api/v1/engine/automation_cron/{id}/run – natychmiastowe wyzwolenie zadania.
    • PATCH /api/v1/engine/automation_cron/{id} – zmiana harmonogramu lub aktywacja/deaktywacja zadania.

Ammonly Documentation System

Copyright © 2026 Ammonly. Wszelkie prawa zastrzeżone.