@primocaredentgroup/compensi-medici-core 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,151 @@
+# @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:
+
+```http
+Authorization: Bearer <WORKER_SECRET>
+```
+
+Configura `WORKER_SECRET` nelle variabili d'ambiente del deployment Convex (PrimoUpCore).
+
+### Registrazione route (PrimoUpCore)
+
+In `PrimoUpCore/convex/http.ts`:
+
+```typescript
+import { registerWorkerRoutes } from "compensi-medici-core/convex/http";
+import { httpAction } from "./_generated/server";
+import { components } from "./_generated/api";
+
+registerWorkerRoutes(http, httpAction, components.compensiMedici);
+```
+
+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 `{}`
+
+```json
+{ "run": { "id": "...", "period": "2025-04", "status": "queued", "created_at": 1710000000 } }
+```
+
+oppure `{ "run": null }`.
+
+**claim-run**
+
+```json
+{ "runId": "jh7...", "workerId": "railway-worker-1" }
+```
+
+**update-progress**
+
+```json
+{ "runId": "jh7...", "progress": 45, "message": "Calcolo commissioni..." }
+```
+
+**save-results**
+
+```json
+{
+  "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**
+
+```json
+{ "runId": "jh7..." }
+```
+
+**mark-failed**
+
+```json
+{
+  "runId": "jh7...",
+  "errorMessage": "Timeout calcolo",
+  "errorStack": "..."
+}
+```
+
+### Accodare un run (mutation UI)
+
+```typescript
+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)
+
+```env
+CONVEX_HTTP_URL=https://<deployment>.convex.site
+WORKER_SECRET=<stesso valore di Convex>
+WORKER_ID=railway-worker-1
+USE_MOCK_API=false
+```

package/convex/http/INTEGRATION.md

@@ -0,0 +1,19 @@
+# Integrazione HTTP worker in PrimoUpCore
+
+Dopo il deploy del componente, verifica che `PrimoUpCore/convex/http.ts` contenga:
+
+```typescript
+import { registerWorkerRoutes } from "compensi-medici-core/convex/http";
+
+registerWorkerRoutes(http, httpAction, components.compensiMedici);
+```
+
+Imposta su Convex (dashboard → Environment Variables):
+
+- `WORKER_SECRET` — stesso valore configurato su Railway per il worker Python
+
+Per accodare un run dal frontend (mutation pubblica del componente, via wrapper PrimoUpCore se necessario):
+
+```typescript
+components.compensiMedici.workflow.workerApi.enqueueRun
+```

package/convex/http/auth.ts

@@ -0,0 +1,5 @@
+export {
+  assertWorkerAuthorization,
+  assertWorkerSecret,
+  WorkerUnauthorizedError,
+} from "../workflow/workerAuth";

package/convex/http/worker.ts

@@ -0,0 +1,181 @@
+import { HttpRouter } from "convex/server";
+import { assertWorkerAuthorization, WorkerUnauthorizedError } from "./auth";
+
+type HttpAction = (handler: (ctx: WorkerHttpCtx, request: Request) => Promise<Response>) => unknown;
+
+type WorkerHttpCtx = {
+  runMutation: (reference: unknown, args: Record<string, unknown>) => Promise<unknown>;
+};
+
+type CompensiWorkerApi = {
+  workflow: {
+    workerApi: {
+      getNextRun: unknown;
+      claimRun: unknown;
+      updateProgress: unknown;
+      saveResults: unknown;
+      markCompleted: unknown;
+      markFailed: unknown;
+    };
+  };
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function httpStatusForError(message: string): number {
+  const lower = message.toLowerCase();
+  if (lower.includes("non trovato")) return 404;
+  if (
+    lower.includes("già in processing") ||
+    lower.includes("già terminato") ||
+    lower.includes("non è in coda") ||
+    lower.includes("non consentito")
+  ) {
+    return 409;
+  }
+  if (lower.includes("richiede workerstatus") || lower.includes("impossibile")) {
+    return 409;
+  }
+  if (lower.includes("invalid json")) return 400;
+  return 400;
+}
+
+function errorResponse(error: unknown): Response {
+  if (error instanceof WorkerUnauthorizedError) {
+    return jsonResponse({ ok: false, error: error.message }, 401);
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const status = httpStatusForError(message);
+  console.error("[worker-http]", status, message);
+  return jsonResponse({ ok: false, error: message }, status);
+}
+
+async function parseJsonBody(request: Request): Promise<Record<string, unknown>> {
+  try {
+    const body = (await request.json()) as Record<string, unknown>;
+    return body ?? {};
+  } catch {
+    throw new Error("Invalid JSON body");
+  }
+}
+
+/**
+ * Registra le route HTTP worker-only sull'app host (PrimoUpCore).
+ *
+ * Esempio in PrimoUpCore/convex/http.ts:
+ *   import { registerWorkerRoutes } from "compensi-medici-core/convex/http";
+ *   registerWorkerRoutes(http, httpAction, components.compensiMedici);
+ */
+export function registerWorkerRoutes(
+  http: HttpRouter,
+  httpAction: HttpAction,
+  compensiMedici: CompensiWorkerApi,
+): void {
+  const api = compensiMedici.workflow.workerApi;
+
+  const route = (
+    path: string,
+    handler: (ctx: WorkerHttpCtx, request: Request, secret: string) => Promise<Response>,
+  ) => {
+    http.route({
+      path,
+      method: "POST",
+      handler: httpAction(async (ctx, request) => {
+        try {
+          const secret = assertWorkerAuthorization(request);
+          return await handler(ctx as WorkerHttpCtx, request, secret);
+        } catch (error) {
+          return errorResponse(error);
+        }
+      }),
+    });
+  };
+
+  route("/worker/get-next-run", async (ctx, _request, secret) => {
+    const result = await ctx.runMutation(api.getNextRun, { workerSecret: secret });
+    return jsonResponse(result);
+  });
+
+  route("/worker/claim-run", async (ctx, request, secret) => {
+    const body = await parseJsonBody(request);
+    const runId = body.runId;
+    const workerId = body.workerId;
+    if (typeof runId !== "string" || typeof workerId !== "string") {
+      return jsonResponse({ ok: false, error: "runId and workerId required" }, 400);
+    }
+    const result = await ctx.runMutation(api.claimRun, {
+      workerSecret: secret,
+      runId,
+      workerId,
+    });
+    return jsonResponse(result);
+  });
+
+  route("/worker/update-progress", async (ctx, request, secret) => {
+    const body = await parseJsonBody(request);
+    const runId = body.runId;
+    const progress = body.progress;
+    if (typeof runId !== "string" || typeof progress !== "number") {
+      return jsonResponse({ ok: false, error: "runId and progress required" }, 400);
+    }
+    const result = await ctx.runMutation(api.updateProgress, {
+      workerSecret: secret,
+      runId,
+      progress,
+      message: typeof body.message === "string" ? body.message : undefined,
+    });
+    return jsonResponse(result);
+  });
+
+  route("/worker/save-results", async (ctx, request, secret) => {
+    const body = await parseJsonBody(request);
+    const runId = body.runId;
+    const result = body.result;
+    if (typeof runId !== "string" || !result || typeof result !== "object") {
+      return jsonResponse({ ok: false, error: "runId and result required" }, 400);
+    }
+    const saved = await ctx.runMutation(api.saveResults, {
+      workerSecret: secret,
+      runId,
+      result,
+    });
+    return jsonResponse(saved);
+  });
+
+  route("/worker/mark-completed", async (ctx, request, secret) => {
+    const body = await parseJsonBody(request);
+    const runId = body.runId;
+    if (typeof runId !== "string") {
+      return jsonResponse({ ok: false, error: "runId required" }, 400);
+    }
+    const result = await ctx.runMutation(api.markCompleted, {
+      workerSecret: secret,
+      runId,
+    });
+    return jsonResponse(result);
+  });
+
+  route("/worker/mark-failed", async (ctx, request, secret) => {
+    const body = await parseJsonBody(request);
+    const runId = body.runId;
+    const errorMessage = body.errorMessage;
+    if (typeof runId !== "string" || typeof errorMessage !== "string") {
+      return jsonResponse(
+        { ok: false, error: "runId and errorMessage required" },
+        400,
+      );
+    }
+    const result = await ctx.runMutation(api.markFailed, {
+      workerSecret: secret,
+      runId,
+      errorMessage,
+      errorStack: typeof body.errorStack === "string" ? body.errorStack : undefined,
+    });
+    return jsonResponse(result);
+  });
+}

package/convex/http.ts

@@ -0,0 +1,6 @@
+export { registerWorkerRoutes } from "./http/worker";
+export {
+  assertWorkerAuthorization,
+  assertWorkerSecret,
+  WorkerUnauthorizedError,
+} from "./http/auth";

package/convex/lib/types.ts

@@ -20,6 +20,9 @@ export type RunStatus =
   | "approved"
   | "closed";
 
+/** Stato esecuzione worker Python (non confondere con RunStatus business). */
+export type WorkerStatus = "queued" | "processing" | "completed" | "failed";
+
 export const VALID_TRANSITIONS: Record<RunStatus, RunStatus[]> = {
   draft: ["calculated"],
   calculated: ["reviewing", "draft"],

package/convex/schema.ts

@@ -32,6 +32,14 @@ export const runStatus = v.union(
   v.literal("closed"),
 );
 
+/** Stato esecuzione del worker Python (coda / processing / esito). */
+export const workerStatus = v.union(
+  v.literal("queued"),
+  v.literal("processing"),
+  v.literal("completed"),
+  v.literal("failed"),
+);
+
 export const scopeType = v.union(
   v.literal("global"),
   v.literal("users"),
@@ -379,11 +387,24 @@ export default defineSchema({
      * Garantisce accesso rapido ai dati ufficiali senza ricalcolo.
      */
     closureSummary: v.optional(v.any()),
+    /** Coda worker Python — separato dal workflow business (draft → calculated → …). */
+    workerStatus: v.optional(workerStatus),
+    workerId: v.optional(v.string()),
+    startedAt: v.optional(v.number()),
+    workerCompletedAt: v.optional(v.number()),
+    workerFailedAt: v.optional(v.number()),
+    progress: v.optional(v.number()),
+    progressMessage: v.optional(v.string()),
+    errorMessage: v.optional(v.string()),
+    errorStack: v.optional(v.string()),
+    /** Snapshot summary restituito dal worker in save-results. */
+    resultSummary: v.optional(v.any()),
   })
     .index("by_period", ["period"])
     .index("by_period_version", ["period", "version"])
     .index("by_status", ["status"])
-    .index("by_shadow", ["isShadowRun", "period"]),
+    .index("by_shadow", ["isShadowRun", "period"])
+    .index("by_worker_status", ["workerStatus", "createdAt"]),
 
   // ── LEDGER ─────────────────────────────────────────────
 

package/convex/workflow/workerApi.ts

@@ -0,0 +1,578 @@
+import { v } from "convex/values";
+import { mutation, type MutationCtx } from "../_generated/server";
+import type { Doc, Id } from "../_generated/dataModel";
+import type { IssueType } from "../lib/types";
+import { assertWorkerSecret } from "./workerAuth";
+
+/**
+ * API worker-only — esecutore esterno (Python su Railway).
+ * La business logic e le regole di dominio restano qui in Convex.
+ *
+ * `status` nel JSON verso il worker = `workerStatus` (coda esecuzione).
+ * `status` business del run (draft/calculated/…) non viene esposto al worker.
+ */
+
+const workerSecretArg = { workerSecret: v.string() };
+
+const workerResultValidator = v.object({
+  summary: v.object({
+    totale_medici: v.optional(v.number()),
+    totaleMedici: v.optional(v.number()),
+    totale_lordo: v.optional(v.number()),
+    totaleLordo: v.optional(v.number()),
+    totale_netto: v.optional(v.number()),
+    totaleNetto: v.optional(v.number()),
+    valuta: v.optional(v.string()),
+  }),
+  ledger_entries: v.optional(v.array(v.any())),
+  ledgerEntries: v.optional(v.array(v.any())),
+  draft_invoices: v.optional(v.array(v.any())),
+  draftInvoices: v.optional(v.array(v.any())),
+  issues: v.optional(v.array(v.any())),
+});
+
+function pickStr(obj: Record<string, unknown>, ...keys: string[]): string | undefined {
+  for (const k of keys) {
+    const val = obj[k];
+    if (typeof val === "string" && val.length > 0) return val;
+  }
+  return undefined;
+}
+
+function pickNum(obj: Record<string, unknown>, ...keys: string[]): number | undefined {
+  for (const k of keys) {
+    const val = obj[k];
+    if (typeof val === "number" && !Number.isNaN(val)) return val;
+  }
+  return undefined;
+}
+
+/** Serializza un run per il worker Python (snake_case). */
+export function serializeRunForWorker(run: Doc<"compensationRuns">) {
+  const clinicIds = extractClinicIds(run);
+  return {
+    id: run._id,
+    period: run.period,
+    company_id: extractCompanyId(run),
+    clinic_ids: clinicIds,
+    status: run.workerStatus ?? null,
+    created_at: run.createdAt,
+    progress: run.progress ?? 0,
+    progress_message: run.progressMessage ?? null,
+    worker_id: run.workerId ?? null,
+  };
+}
+
+function extractClinicIds(run: Doc<"compensationRuns">): string[] {
+  if (run.scopeType === "clinics" && Array.isArray(run.scopePayload)) {
+    return run.scopePayload.filter((x): x is string => typeof x === "string");
+  }
+  if (run.scopeType === "user_clinic_pairs" && Array.isArray(run.scopePayload)) {
+    return run.scopePayload
+      .map((p) => (typeof p === "object" && p && "clinicId" in p ? String((p as { clinicId: string }).clinicId) : null))
+      .filter((x): x is string => !!x);
+  }
+  return [];
+}
+
+function extractCompanyId(run: Doc<"compensationRuns">): string {
+  if (run.scopePayload && typeof run.scopePayload === "object" && !Array.isArray(run.scopePayload)) {
+    const cid = (run.scopePayload as Record<string, unknown>).companyId;
+    if (typeof cid === "string") return cid;
+  }
+  return "";
+}
+
+function assertRunNotClosed(run: Doc<"compensationRuns">, action: string): void {
+  if (run.status === "closed") {
+    throw new Error(
+      `Impossibile ${action}: run ${run._id} è chiuso (status=closed)`,
+    );
+  }
+}
+
+async function getRunOrThrow(
+  ctx: { db: { get: (id: Id<"compensationRuns">) => Promise<Doc<"compensationRuns"> | null> } },
+  runId: Id<"compensationRuns">,
+): Promise<Doc<"compensationRuns">> {
+  const run = await ctx.db.get(runId);
+  if (!run) throw new Error(`Run non trovato: ${runId}`);
+  return run;
+}
+
+async function clearWorkerGeneratedData(
+  ctx: MutationCtx,
+  runId: Id<"compensationRuns">,
+): Promise<void> {
+  const entries = await ctx.db
+    .query("ledgerEntries")
+    .withIndex("by_run", (q) => q.eq("runId", runId))
+    .collect();
+  for (const entry of entries) {
+    if (!entry.isManual) await ctx.db.delete(entry._id);
+  }
+
+  const invoices = await ctx.db
+    .query("draftInvoices")
+    .withIndex("by_run", (q) => q.eq("runId", runId))
+    .collect();
+  for (const inv of invoices) {
+    if (inv.isAutoGenerated) await ctx.db.delete(inv._id);
+  }
+
+  const issues = await ctx.db
+    .query("runIssues")
+    .withIndex("by_run", (q) => q.eq("runId", runId))
+    .collect();
+  for (const issue of issues) {
+    await ctx.db.delete(issue._id);
+  }
+}
+
+// ── get-next-run ─────────────────────────────────────────
+
+export const getNextRun = mutation({
+  args: workerSecretArg,
+  handler: async (ctx, args) => {
+    assertWorkerSecret(args.workerSecret);
+    console.log("[worker] get-next-run");
+
+    const queued = await ctx.db
+      .query("compensationRuns")
+      .withIndex("by_worker_status", (q) => q.eq("workerStatus", "queued"))
+      .collect();
+
+    queued.sort((a, b) => a.createdAt - b.createdAt);
+    const run = queued[0] ?? null;
+
+    if (!run) {
+      console.log("[worker] get-next-run: nessun run in coda");
+      return { run: null };
+    }
+
+    console.log(`[worker] get-next-run: trovato ${run._id}`);
+    return { run: serializeRunForWorker(run) };
+  },
+});
+
+// ── claim-run ────────────────────────────────────────────
+
+export const claimRun = mutation({
+  args: {
+    ...workerSecretArg,
+    runId: v.id("compensationRuns"),
+    workerId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    assertWorkerSecret(args.workerSecret);
+    console.log(`[worker] claim-run: ${args.runId} by ${args.workerId}`);
+
+    const run = await getRunOrThrow(ctx, args.runId);
+    assertRunNotClosed(run, "claim-run");
+
+    if (run.workerStatus === "processing" && run.workerId === args.workerId) {
+      console.log(`[worker] claim-run: idempotente, già processing per ${args.workerId}`);
+      return { run: serializeRunForWorker(run) };
+    }
+
+    if (run.workerStatus === "completed" || run.workerStatus === "failed") {
+      throw new Error(`Run ${args.runId} già terminato (workerStatus=${run.workerStatus})`);
+    }
+
+    if (run.workerStatus === "processing" && run.workerId !== args.workerId) {
+      throw new Error(
+        `Run ${args.runId} già in processing da worker ${run.workerId}`,
+      );
+    }
+
+    if (run.workerStatus !== "queued") {
+      throw new Error(
+        `Run ${args.runId} non è in coda (workerStatus=${run.workerStatus ?? "null"})`,
+      );
+    }
+
+    const now = Date.now();
+    await ctx.db.patch(args.runId, {
+      workerStatus: "processing",
+      workerId: args.workerId,
+      startedAt: now,
+      progress: 0,
+      progressMessage: "Claimed by worker",
+      updatedAt: now,
+    });
+
+    const updated = await getRunOrThrow(ctx, args.runId);
+    console.log(`[worker] claim-run: ok ${args.runId}`);
+    return { run: serializeRunForWorker(updated) };
+  },
+});
+
+// ── update-progress ──────────────────────────────────────
+
+export const updateProgress = mutation({
+  args: {
+    ...workerSecretArg,
+    runId: v.id("compensationRuns"),
+    progress: v.number(),
+    message: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    assertWorkerSecret(args.workerSecret);
+    const run = await getRunOrThrow(ctx, args.runId);
+
+    if (run.workerStatus !== "processing") {
+      throw new Error(
+        `Impossibile aggiornare progress: workerStatus=${run.workerStatus ?? "null"}`,
+      );
+    }
+
+    const progress = Math.max(0, Math.min(100, args.progress));
+    const now = Date.now();
+    await ctx.db.patch(args.runId, {
+      progress,
+      progressMessage: args.message,
+      updatedAt: now,
+    });
+
+    console.log(`[worker] update-progress: ${args.runId} → ${progress}%`);
+    return { ok: true, progress };
+  },
+});
+
+// ── save-results ─────────────────────────────────────────
+
+export const saveResults = mutation({
+  args: {
+    ...workerSecretArg,
+    runId: v.id("compensationRuns"),
+    result: workerResultValidator,
+  },
+  handler: async (ctx, args) => {
+    assertWorkerSecret(args.workerSecret);
+    console.log(`[worker] save-results: ${args.runId}`);
+
+    const run = await getRunOrThrow(ctx, args.runId);
+    assertRunNotClosed(run, "save-results");
+
+    if (run.workerStatus !== "processing") {
+      throw new Error(
+        `save-results richiede workerStatus=processing, attuale=${run.workerStatus ?? "null"}`,
+      );
+    }
+    if (run.status === "approved") {
+      throw new Error(
+        "save-results non consentito: run in stato approved",
+      );
+    }
+
+    const { result } = args;
+    const ledgerRaw = result.ledger_entries ?? result.ledgerEntries ?? [];
+    const invoicesRaw = result.draft_invoices ?? result.draftInvoices ?? [];
+    const issuesRaw = result.issues ?? [];
+
+    await clearWorkerGeneratedData(ctx, args.runId);
+
+    const now = Date.now();
+    const createdBy = run.workerId ?? "python-worker";
+
+    for (const raw of ledgerRaw) {
+      const row = raw as Record<string, unknown>;
+      const userId = pickStr(row, "userId", "medico_id", "medicoId") ?? "unknown";
+      const clinicId = pickStr(row, "clinicId", "clinic_id") ?? "unknown";
+      const amount =
+        pickNum(row, "amount", "importo_netto", "importoNetto", "importo") ?? 0;
+      const description = pickStr(row, "descrizione", "description") ?? "Worker entry";
+      const typeRaw = pickStr(row, "type");
+      const entryType =
+        typeRaw === "commission" ||
+        typeRaw === "fixed" ||
+        typeRaw === "bonus" ||
+        typeRaw === "production" ||
+        typeRaw === "storno" ||
+        typeRaw === "reimbursement" ||
+        typeRaw === "adjustment"
+          ? typeRaw
+          : "commission";
+
+      await ctx.db.insert("ledgerEntries", {
+        runId: args.runId,
+        userId,
+        clinicId,
+        type: entryType,
+        sourceType: "system",
+        sourceId: pickStr(row, "id", "sourceId"),
+        description,
+        amount,
+        quantity: pickNum(row, "quantity") ?? 1,
+        unitAmount: pickNum(row, "unitAmount", "unit_amount") ?? amount,
+        isManual: false,
+        effectiveDate: now,
+        period: run.period,
+        metadata: row,
+        createdBy,
+        createdAt: now,
+      });
+    }
+
+    for (const raw of invoicesRaw) {
+      const row = raw as Record<string, unknown>;
+      const userId = pickStr(row, "userId", "medico_id", "medicoId") ?? "unknown";
+      const clinicId = pickStr(row, "clinicId", "clinic_id") ?? "unknown";
+      const netToPay = pickNum(row, "importo", "netToPay", "net_to_pay") ?? 0;
+
+      await ctx.db.insert("draftInvoices", {
+        runId: args.runId,
+        userId,
+        clinicId,
+        period: run.period,
+        status: "draft",
+        isAutoGenerated: true,
+        isCompanyGrouped: false,
+        lineItemCount: pickNum(row, "lineItemCount") ?? 1,
+        netPrice: netToPay,
+        subtotal: netToPay,
+        vatRate: 0,
+        vatAmount: 0,
+        withholdingRate: 0,
+        withholdingOnRate: 100,
+        withholdingAmount: 0,
+        contributionRate: 0,
+        contributionAmount: 0,
+        stampDutyAmount: 0,
+        total: netToPay,
+        netToPay,
+        notes: pickStr(row, "notes"),
+        createdBy,
+        createdAt: now,
+        updatedAt: now,
+      });
+    }
+
+    for (const raw of issuesRaw) {
+      const row = raw as Record<string, unknown>;
+      const code = pickStr(row, "code") ?? "worker_issue";
+      const severityRaw = pickStr(row, "severity") ?? "warning";
+      const severity =
+        severityRaw === "error" || severityRaw === "info" || severityRaw === "warning"
+          ? severityRaw
+          : "warning";
+      const message = pickStr(row, "message") ?? code;
+
+      const knownTypes: IssueType[] = [
+        "no_active_plan",
+        "no_matching_rule",
+        "no_tax_profile",
+        "multiple_tax_profiles",
+        "inactive_tax_profile",
+        "fiscal_anomaly",
+        "missing_invoices",
+      ];
+      const mappedType: IssueType = knownTypes.includes(code as IssueType)
+        ? (code as IssueType)
+        : "fiscal_anomaly";
+
+      await ctx.db.insert("runIssues", {
+        runId: args.runId,
+        issueType: mappedType,
+        severity,
+        userId: pickStr(row, "userId", "medico_id"),
+        clinicId: pickStr(row, "clinicId", "clinic_id"),
+        message,
+        details: { workerCode: code, ...row },
+        createdAt: now,
+      });
+    }
+
+    const summary = {
+      totale_medici:
+        result.summary.totale_medici ?? result.summary.totaleMedici ?? 0,
+      totale_lordo:
+        result.summary.totale_lordo ?? result.summary.totaleLordo ?? 0,
+      totale_netto:
+        result.summary.totale_netto ?? result.summary.totaleNetto ?? 0,
+      valuta: result.summary.valuta ?? "EUR",
+    };
+
+    await ctx.db.patch(args.runId, {
+      resultSummary: summary,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "worker_results_saved",
+      userId: createdBy,
+      payload: {
+        ledgerCount: ledgerRaw.length,
+        invoiceCount: invoicesRaw.length,
+        issueCount: issuesRaw.length,
+        summary,
+      },
+      createdAt: now,
+    });
+
+    console.log(
+      `[worker] save-results: ok ${args.runId} (${ledgerRaw.length} ledger, ${invoicesRaw.length} invoices)`,
+    );
+    return { ok: true, summary };
+  },
+});
+
+// ── mark-completed ───────────────────────────────────────
+
+export const markCompleted = mutation({
+  args: {
+    ...workerSecretArg,
+    runId: v.id("compensationRuns"),
+  },
+  handler: async (ctx, args) => {
+    assertWorkerSecret(args.workerSecret);
+    console.log(`[worker] mark-completed: ${args.runId}`);
+
+    const run = await getRunOrThrow(ctx, args.runId);
+
+    if (run.workerStatus === "completed") {
+      console.log(`[worker] mark-completed: idempotente ${args.runId}`);
+      return { run: serializeRunForWorker(run) };
+    }
+
+    if (run.workerStatus !== "processing") {
+      throw new Error(
+        `mark-completed richiede workerStatus=processing, attuale=${run.workerStatus ?? "null"}`,
+      );
+    }
+
+    const now = Date.now();
+    await ctx.db.patch(args.runId, {
+      workerStatus: "completed",
+      workerCompletedAt: now,
+      progress: 100,
+      progressMessage: "Completed",
+      status: "calculated",
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "worker_completed",
+      userId: run.workerId ?? "python-worker",
+      payload: { resultSummary: run.resultSummary },
+      createdAt: now,
+    });
+
+    const updated = await getRunOrThrow(ctx, args.runId);
+    console.log(`[worker] mark-completed: ok ${args.runId}`);
+    return { run: serializeRunForWorker(updated) };
+  },
+});
+
+// ── mark-failed ──────────────────────────────────────────
+
+export const markFailed = mutation({
+  args: {
+    ...workerSecretArg,
+    runId: v.id("compensationRuns"),
+    errorMessage: v.string(),
+    errorStack: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    assertWorkerSecret(args.workerSecret);
+    console.log(`[worker] mark-failed: ${args.runId}`);
+
+    const run = await getRunOrThrow(ctx, args.runId);
+
+    if (run.workerStatus === "failed") {
+      console.log(`[worker] mark-failed: idempotente ${args.runId}`);
+      return { run: serializeRunForWorker(run) };
+    }
+
+    if (run.workerStatus !== "processing" && run.workerStatus !== "queued") {
+      throw new Error(
+        `mark-failed non consentito da workerStatus=${run.workerStatus ?? "null"}`,
+      );
+    }
+
+    const now = Date.now();
+    await ctx.db.patch(args.runId, {
+      workerStatus: "failed",
+      workerFailedAt: now,
+      errorMessage: args.errorMessage,
+      errorStack: args.errorStack,
+      progressMessage: args.errorMessage.slice(0, 500),
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "worker_failed",
+      userId: run.workerId ?? "python-worker",
+      payload: {
+        errorMessage: args.errorMessage,
+        errorStack: args.errorStack,
+      },
+      createdAt: now,
+    });
+
+    const updated = await getRunOrThrow(ctx, args.runId);
+    console.log(`[worker] mark-failed: ok ${args.runId}`);
+    return { run: serializeRunForWorker(updated) };
+  },
+});
+
+// ── enqueue (per UI / cron — mette in coda il worker) ───
+
+export const enqueueRun = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const run = await getRunOrThrow(ctx, args.runId);
+
+    if (run.status === "closed") {
+      throw new Error("Impossibile accodare un run chiuso");
+    }
+    if (run.status === "approved") {
+      throw new Error("Impossibile accodare un run approvato");
+    }
+
+    if (run.workerStatus === "queued" || run.workerStatus === "processing") {
+      return { runId: args.runId, workerStatus: run.workerStatus };
+    }
+
+    if (run.workerStatus === "completed") {
+      throw new Error(
+        "Impossibile riaccodare un run già completato dal worker",
+      );
+    }
+
+    const now = Date.now();
+    await ctx.db.patch(args.runId, {
+      workerStatus: "queued",
+      workerId: undefined,
+      startedAt: undefined,
+      workerCompletedAt: undefined,
+      workerFailedAt: undefined,
+      progress: 0,
+      progressMessage: "Queued for worker",
+      errorMessage: undefined,
+      errorStack: undefined,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "worker_enqueued",
+      userId: args.userId,
+      payload: { period: run.period },
+      createdAt: now,
+    });
+
+    console.log(`[worker] enqueue-run: ${args.runId}`);
+    return { runId: args.runId, workerStatus: "queued" as const };
+  },
+});

package/convex/workflow/workerAuth.ts

@@ -0,0 +1,32 @@
+/**
+ * Autenticazione worker-only (Bearer WORKER_SECRET).
+ * Usata da mutation workerApi e da HTTP routes nell'app host.
+ */
+
+export class WorkerUnauthorizedError extends Error {
+  constructor(message = "Unauthorized") {
+    super(message);
+    this.name = "WorkerUnauthorizedError";
+  }
+}
+
+export function assertWorkerSecret(workerSecret: string): void {
+  const expected = process.env.WORKER_SECRET;
+  if (!expected) {
+    console.error("[worker] WORKER_SECRET non configurato nel deployment Convex");
+    throw new WorkerUnauthorizedError("Worker secret not configured");
+  }
+  if (workerSecret !== expected) {
+    throw new WorkerUnauthorizedError("Invalid worker secret");
+  }
+}
+
+export function assertWorkerAuthorization(request: Request): string {
+  const header = request.headers.get("Authorization");
+  if (!header?.startsWith("Bearer ")) {
+    throw new WorkerUnauthorizedError("Missing Bearer token");
+  }
+  const token = header.slice("Bearer ".length).trim();
+  assertWorkerSecret(token);
+  return token;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primocaredentgroup/compensi-medici-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "description": "Componente Convex Compensi Medici — motore compensi strutturato, configurabile e integrato per PrimoUpCore",
@@ -18,6 +18,10 @@
       "@convex-dev/component-source": "./convex/convex.config.ts",
       "types": "./convex/convex.config.ts",
       "default": "./convex/convex.config.ts"
+    },
+    "./convex/http": {
+      "types": "./convex/http.ts",
+      "default": "./convex/http.ts"
     }
   },
   "publishConfig": {