@primocaredentgroup/compensi-medici-core

Componente Convex per il motore compensi medici (PrimoUpCore).

Worker Integration API

API HTTP worker-only per il Python worker su Railway. Il componente Convex resta source of truth; il worker è solo esecutore esterno.

Autenticazione

Tutte le richieste richiedono:

Authorization: Bearer <WORKER_SECRET>

Configura WORKER_SECRET nelle variabili d'ambiente del deployment Convex (PrimoUpCore).

Registrazione route (PrimoUpCore)

Non importare il package dentro convex/http.ts dell'host (vedi convex/http/INTEGRATION.md). Usa convex/compensiWorkerRoutes.ts e:

import { registerCompensiWorkerRoutes } from "./compensiWorkerRoutes";

registerCompensiWorkerRoutes(http);

Base URL: https://<deployment>.convex.site

Endpoint

| Metodo | Path | Descrizione | |--------|------|-------------| | POST | /worker/get-next-run | Primo run con workerStatus=queued (FIFO) | | POST | /worker/claim-run | Claim atomico → processing | | POST | /worker/update-progress | Aggiorna progress / progressMessage | | POST | /worker/save-results | Salva ledger, fatture, issues, summary | | POST | /worker/mark-completed | workerStatus=completed, business status=calculated | | POST | /worker/mark-failed | workerStatus=failed + errore |

Flow esecuzione

enqueue (UI) → queued
     ↓
get-next-run → claim-run → processing
     ↓
update-progress (opzionale, ripetibile)
     ↓
save-results (solo in processing)
     ↓
mark-completed → completed + status business "calculated"

In caso di errore: mark-failed → failed.

Esempi payload

get-next-run — body vuoto {}

{ "run": { "id": "...", "period": "2025-04", "status": "queued", "created_at": 1710000000 } }

oppure { "run": null }.

claim-run

{ "runId": "jh7...", "workerId": "railway-worker-1" }

update-progress

{ "runId": "jh7...", "progress": 45, "message": "Calcolo commissioni..." }

save-results

{
  "runId": "jh7...",
  "result": {
    "summary": { "totale_medici": 2, "totale_lordo": 7300, "totale_netto": 5840 },
    "ledger_entries": [
      { "medico_id": "u1", "clinic_id": "c1", "importo_netto": 3360, "descrizione": "..." }
    ],
    "draft_invoices": [
      { "medico_id": "u1", "clinic_id": "c1", "importo": 3360 }
    ],
    "issues": [
      { "code": "MISSING_TIMESHEET", "severity": "warning", "message": "..." }
    ]
  }
}

mark-completed

{ "runId": "jh7..." }

mark-failed

{
  "runId": "jh7...",
  "errorMessage": "Timeout calcolo",
  "errorStack": "..."
}

Accodare un run (mutation UI)

await ctx.runMutation(components.compensiMedici.workflow.workerApi.enqueueRun, {
  runId,
  userId: "...",
});

Il run deve essere in stato business draft (o non closed). Imposta workerStatus: "queued".

Modello dati worker vs business

| Campo | Significato | |-------|-------------| | workerStatus | Coda worker: queued → processing → completed / failed | | status | Workflow business: draft → calculated → reviewing → approved → closed |

Il worker vede status nel JSON HTTP = workerStatus. Al completamento, Convex imposta anche status: "calculated".

Idempotenza

• claim: stesso workerId su run già processing → OK (ritorna il run).
• mark-completed / mark-failed: se già nello stato finale → OK.
• save-results: solo con workerStatus=processing; sostituisce dati auto-generati precedenti.

Variabili Railway (worker Python)

CONVEX_HTTP_URL=https://<deployment>.convex.site
WORKER_SECRET=<stesso valore di Convex>
WORKER_ID=railway-worker-1
USE_MOCK_API=false

Worker Monitor (DEV example)

UI tecnica per debugging runtime del worker — non produzione.

Vedi example/README.md per setup Vite + mini-host Convex.

API nel componente (convex/workflow/workerMonitor.ts):

• Query: listWorkerRuns, getWorkerMetrics, getWorkerRunDetails
• Dev mutations: enqueueRunDev, retryRunDev, resetWorkerStatusDev, createFakeFailedRunDev, createFakeProcessingStuckRunDev

Helper: convex/lib/workerMonitorHelpers.ts (duration, stuck detection, metrics).