Cron-motor és ütemezési módszertan – Rendszerleírás

Architektúra

A motor lánca: a tárhely-szolgáltató crontabja percenként meghívja az OpenCart cron-diszpécsert, az a regisztrált doliBIT_cronqueue cron-bejegyzésen át a catalog cron/cronqueue controllert, amely BELSŐ hívással indítja a worker-t (masterdata/cronqueue.run). A run() a cron-secretet (module_dolibit_cron_secret) a configból injektálja a belső híváshoz, így a külső HTTP-hívók secret nélkül 403-at kapnak, a belső lánc viszont nem zárja ki önmagát. A párhuzamos futást lock-fájl (logs/cronqueue.lock, max 10 perc) akadályozza meg; a worker minden futáskor heartbeat-fájlt ír, fatal hibánál a shutdown-handler szabadítja fel a lockot és nevesített FATAL-sort ír az error logba. Egy futás legfeljebb ~45 másodpercig dolgoz fel sorokat, a végén összefoglaló sort logol ("cronqueue FUTÁS KÉSZ | feldolgozott job-item=N").

Adatmodell

doliBIT_cron_queue: queue_id, job_type, company_id, job_id (Main Jobhoz), status (0=várakozik, 1=folyamatban, 2=kész, 3=hiba), attempts, scheduled, payload (JSON), is_template + frequency + run_hour/run_minute (ütemező template-sorok), priority. doliBIT_job: aggregált Main Job (total/completed_items, found_items, státusz) a nagy manuális futásokhoz. A feldolgozási sorrendet a JOB_ORDER konstans adja (taxaccount, missingtaxreturn, …, email_task, doc_text).

ÜTEMEZÉSI MÓDSZERTAN — forrás-vezérelt újragenerálás (kötelező minta)

Minden cron-érintett objektum EGYSÉGES szabályt követ: a queue-sort egy forrás-objektum hozza létre, és a sor csak akkor generálódik újra, ha a forrás még aktív — azokkal a paraméterekkel (gyakoriság, időpont), amelyeket a forrás megad. Job-típusonként:

• nav_invoice_sync (15 perces számla-szinkron): forrás = az ügyfélcég (doliBIT_nav: NAV-belépő + digest_status=1 + aktív cég). Az ELSŐ sort a bootstrap-seed hozza létre a következő negyedóra-határra (nav_sync_seeded flag cégenként egyszer); utána a sor önfenntartó: minden futás végén önmagát ütemezi a következő negyedóra-határra (cégenkénti digest_interval). Ha a lánc megszakad (fatal, 3x hiba), a bootstrap lánc-öngyógyítása helyreállítja, KIVÉVE ha a cégen digest_status=0 (szándékos kikapcsolás — azt nem éleszti újra).
• nav_invoice_data (számlánkénti teljes letöltés): EGYSZERI sor, a digest sorolja be új számlánként; sosem ütemeződik újra magától — a beragadt (orphan) pending_data számlákat külön öngyógyító lépés sorolja vissza.
• email_task: forrás = doliBIT_emailtask sor. Az ütemezést a CRON SCHEDULER template-sora tartja (is_template=1, frequency/run_hour/run_minute A TASK CONFIGJÁBÓL); az enqueueDueTemplates esedékességkor futtatható instance-t szúr be és a template-et a gyakoriság szerint előrelépteti. Inaktív task = nem készül instance (a template tovább ketyeg, aktiválás után magától folytatódik). A task szerkesztése a következő újragenerálástól érvényes.
• taxaccount / missingtaxreturn (adófolyószámla, hiányzó bevallás): forrás = a NAV-cégtörzs. Napi futás hajnali sávban (05:00 + job-típusonkénti perc-eltolás), futás után másnapra ütemeződik újra, amíg a cég szerepel az aktív NAV-cégek közt.
• doc_text (PDF szöveg-kinyerés, Smalot): EGYSZERI, dokumentumonkénti sor — a feltöltés (queueTextExtract, pending-dedup védelemmel) vagy a backfill-SQL sorolja be; sosem ütemeződik újra, és a lejárat-kezelő SEM törli (a régi scheduled-del is lefut).
• globális sorok: email/email_commands/email_ai (1-2 percenként, kapcsoló: module_dolibit_cron_email), contract_passthrough_scan (2 perc), otpkelfo_ingest (napi 05:40), taskdigest (heti, hétfő 05:30) — hiányukat a bootstrap-seed pótolja.

Lejárat-kezelés (handleExpired)

A mai nap ELŐTTRE ütemezett, feldolgozatlan sorok törlődnek (log: "lejárt sor törölve"), majd a fenti forrás-szabály szerint AZONNAL új sor készül (nav_invoice_sync → következő negyedóra-határ; napi jobok → holnap hajnal; taskdigest → következő hétfő). Kivételek: Main Jobhoz tartozó itemek és a doc_text sorok érintetlenek (lefutnak), az email_task/nav_invoice_data/contract_passthrough nem itt termelődik újra. Így a motor leállása után a láncok beavatkozás nélkül helyreállnak.

Számla-letöltés részletesen (digest → data)

1) A nav_invoice_sync futás cégenként lekéri a NAV invoiceDigest-et a 15 perces insDate-ablakra, MINDKÉT irányban (INBOUND+OUTBOUND). 2) A fejlécek upsertálódnak a doliBIT_invoice-ba (company_client_id = a cég), a MÁR meglévők kimaradnak. 3) Minden ÚJ számlához nav_invoice_data queue-sor készül, amelyet a worker az invoiceData hívással teljes adatra bővít: tételek, partneradatok, bankszámlaszám (a központi normalizálóval, 24 jegyű kanonikus formára), címke-kötések. 4) Manuális szinkronnál a rövid ablak azonnal fut; a hosszú ablak Main Jobot (doliBIT_job) készít, a cégek queue-itemként futnak, a befejezéskor aggregált értesítés megy. Futás-értesítés (2026-08-02-től): harang-notification CSAK eredménynél (új számla sorolva) vagy hibánál; a sikeres-üres futás néma.

Leállítás és diagnosztika

Teljes leállítás egy helyen: a core Cron Jobs listában a doliBIT_cronqueue bejegyzés kikapcsolása a TELJES feladatsor-feldolgozást megállítja (minden doliBIT háttérfolyamat egyszerre áll le). Szelektív kapcsolók: module_dolibit_nav_sync_enabled (NAV-szinkron), module_dolibit_cron_email (e-mail jobok), cégenkénti digest_status. Öndiagnózis: a cronqueue.status végpont egy lapon mutatja a worker utolsó futását (heartbeat), a kapcsolók állását, a NAV-cégek seed-állapotát, az utolsó queue-sorokat és a helyes crontab-parancsot; óránként NAV-SZINKRON DIAG sor kerül az error logba a lánc állapotáról.

Függőségek

• NAV-funkciókhoz cégenkénti NAV API belépő kell (Companies form, navapi funkciójoggal védett blokk).
• Az email_task forrásaihoz API-fiók kell (Gmail API / IMAP / MS365 — Master data → API accounts).
• Az értesítések címzettjei a cégre TARTALMI joggal rendelkező felhasználók (lásd: Jogosultsági rendszer – Rendszerleírás).