Akira background jobs registry

Questo runbook registra i pattern background job canonical dopo ADR-0001 e ADR-0015. I tre pattern coesistono e non si sostituiscono a vicenda.

Worker	Pattern	ADR	Location
kam-cdr-bridge	NATS / JetStream stream consumer	ADR-0015	packages/akira_kam_cdr_bridge/
fs-esl-gateway	NATS event publisher/consumer side	ADR-0015	apps/fs-esl-gateway/
notification-dispatcher	NATS subscriber	ADR-0015	apps/backend/src/akira_backend/services/notifications/
akira-auto-upload	systemd timer	cron	apps/workers/auto_upload/
audit-retention	systemd timer	cron	infra/roles/audit_retention/
kamailio-htable-sync	systemd timer	cron	infra/roles/kamailio/
recordings-upload-sftp	systemd timer	cron	infra/roles/rtpengine/
(future) export-pdf-report	arq + Redis	ADR-0001	apps/backend/jobs/ (TBD)
(future) tariff-applier	arq + Redis	ADR-0001	apps/backend/jobs/ (TBD)
(future) agent-fee-recompute	arq + Redis	ADR-0001	apps/backend/jobs/ (TBD)

Note audit 2026-05-20: non risultano job arq runtime sotto apps/backend/src/. I job arq sono quindi documentati come pattern canonical per use case futuri submit-from-API + poll-result. I job pg_dump/WAL presenti nel repository usano script, archive_command o cron Ansible, non template *.timer.j2; non sono classificati come systemd timer in questo registry.

Auto-upload SFTP inbox

Pilot TASK-219 usa un inbox filesystem montato o gestito dal nodo Akira. Il path canonico per file caricati dal customer e':

/sftp/akira/inbox/<company_id>/<upload_type>/

Esempio rates customer:

/sftp/akira/inbox/42/rates/customer-rates.csv

Il worker akira-auto-upload.timer scansiona ogni 15 minuti le subdirectory <company_id>/<upload_type>/ e archivia i file processati in:

/sftp/akira/archived/<company_id>/<upload_type>/<YYYY-MM>/

In produzione impostare AUTO_UPLOAD_INBOX_DIR=/sftp/akira/inbox e AUTO_UPLOAD_ARCHIVE_DIR=/sftp/akira/archived nel file environment del backend. La sorgente email usa le mailbox ADR-0009 con ruolo rates_inbound: il mailbox poller scarica i messaggi in sola lettura e registra gli UID in tickets_email_ingestion_events, mentre akira-auto-upload.timer consuma gli eventi pending, applica il primo allegato tabellare e rispetta schedule_cron dei job email.

Decision tree

Quando aggiungi nuovo worker:

1. E' subscriber stream NATS? Usa NATSWorker, NATSJetStreamPushWorker o NATSJetStreamPullWorker (vedi packages/akira_workers/ e ADR-0015).
2. E' submit-from-API + poll-result UI/admin? Usa arq + Redis (ADR-0001).
3. E' cron schedule fisso? Usa systemd timer.

Esempio worker NATSWorker

from akira_workers import NATSJetStreamPushWorker


class MyWorker(NATSJetStreamPushWorker):
    name = "my-worker"
    subject = "akira.events.foo"
    durable_name = "my-worker-durable"

    async def process_message(self, data: dict) -> None:
        ...