@primocaredentgroup/compensi-medici-core 0.1.0

package/convex/workflow/pendingCompletions.ts

@@ -0,0 +1,148 @@
+import { v } from "convex/values";
+import { mutation, query, internalMutation, internalQuery } from "../_generated/server";
+
+/**
+ * Gestione coda di eseguiti in attesa di elaborazione.
+ *
+ * Flusso:
+ *   1. PrimoUpCore chiama recordCompletion quando un CPR viene completato
+ *   2. Un cron orario chiama getPendingByPeriod per verificare se ci sono pending
+ *   3. Se ci sono, triggera il Python Worker per il calcolo batch
+ *   4. A calcolo completato, markAsProcessed segna le righe come elaborate
+ */
+
+export const recordCompletion = mutation({
+  args: {
+    carePlanRowId: v.string(),
+    carePlanId: v.string(),
+    userId: v.string(),
+    clinicId: v.string(),
+    companyId: v.optional(v.string()),
+    period: v.string(),
+    amount: v.number(),
+    serviceDescription: v.optional(v.string()),
+    completedAt: v.number(),
+    completedBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("pendingCompletions")
+      .withIndex("by_cpr_id", (q) => q.eq("carePlanRowId", args.carePlanRowId))
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        amount: args.amount,
+        completedAt: args.completedAt,
+        completedBy: args.completedBy,
+        isProcessed: false,
+        processedAt: undefined,
+        processedRunId: undefined,
+      });
+      return existing._id;
+    }
+
+    return await ctx.db.insert("pendingCompletions", {
+      ...args,
+      isProcessed: false,
+      createdAt: Date.now(),
+    });
+  },
+});
+
+export const getPendingSummary = query({
+  args: {},
+  handler: async (ctx) => {
+    const pending = await ctx.db
+      .query("pendingCompletions")
+      .withIndex("by_processed", (q) => q.eq("isProcessed", false))
+      .collect();
+
+    const byPeriod = new Map<string, number>();
+    for (const p of pending) {
+      byPeriod.set(p.period, (byPeriod.get(p.period) ?? 0) + 1);
+    }
+
+    return {
+      totalPending: pending.length,
+      byPeriod: Object.fromEntries(byPeriod),
+    };
+  },
+});
+
+export const listPendingByPeriod = query({
+  args: { period: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("pendingCompletions")
+      .withIndex("by_period_processed", (q) =>
+        q.eq("period", args.period).eq("isProcessed", false),
+      )
+      .collect();
+  },
+});
+
+export const markAsProcessed = mutation({
+  args: {
+    period: v.string(),
+    runId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const pending = await ctx.db
+      .query("pendingCompletions")
+      .withIndex("by_period_processed", (q) =>
+        q.eq("period", args.period).eq("isProcessed", false),
+      )
+      .collect();
+
+    const now = Date.now();
+    let count = 0;
+
+    for (const p of pending) {
+      await ctx.db.patch(p._id, {
+        isProcessed: true,
+        processedAt: now,
+        processedRunId: args.runId,
+      });
+      count++;
+    }
+
+    return { markedCount: count };
+  },
+});
+
+// ── Internal: usato dal cron per controllare se ci sono pending ──
+
+export const _hasPendingCompletions = internalQuery({
+  args: {},
+  handler: async (ctx) => {
+    const pending = await ctx.db
+      .query("pendingCompletions")
+      .withIndex("by_processed", (q) => q.eq("isProcessed", false))
+      .first();
+
+    if (!pending) return { hasPending: false, periods: [] };
+
+    const allPending = await ctx.db
+      .query("pendingCompletions")
+      .withIndex("by_processed", (q) => q.eq("isProcessed", false))
+      .collect();
+
+    const periods = [...new Set(allPending.map((p) => p.period))];
+
+    return { hasPending: true, periods };
+  },
+});
+
+export const _getPendingCountForPeriod = internalQuery({
+  args: { period: v.string() },
+  handler: async (ctx, args) => {
+    const pending = await ctx.db
+      .query("pendingCompletions")
+      .withIndex("by_period_processed", (q) =>
+        q.eq("period", args.period).eq("isProcessed", false),
+      )
+      .collect();
+    return pending.length;
+  },
+});

package/convex/workflow/pythonWorker.ts

@@ -0,0 +1,190 @@
+import { v } from "convex/values";
+import { action, internalMutation, internalQuery } from "../_generated/server";
+import { internal } from "../_generated/api";
+
+/**
+ * Action di collegamento con il Python Worker.
+ *
+ * Flusso:
+ *   1. Frontend chiama triggerCalculation
+ *   2. Action legge l'URL del worker da globalSettings (key: "python_worker_url")
+ *   3. Action fa POST al worker con runId + period
+ *   4. Il Python worker calcola tutto e scrive i risultati direttamente su Convex
+ *   5. Il Python worker aggiorna lo stato del run a "calculated"
+ *
+ * In locale: il worker gira su http://localhost:8000
+ * In produzione: il worker gira su Railway (URL configurato in globalSettings)
+ */
+
+export const triggerCalculation = action({
+  args: {
+    runId: v.id("compensationRuns"),
+    workerUrl: v.optional(v.string()),
+    userIds: v.optional(v.array(v.string())),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const run = await ctx.runQuery(internal.workflow.runs._getInternal, { runId: args.runId });
+    if (!run) throw new Error("Run non trovato");
+
+    if (run.status !== "draft") {
+      throw new Error(
+        `Il run è in stato "${run.status}". Solo i run in stato "draft" possono essere calcolati.`,
+      );
+    }
+
+    let workerUrl = args.workerUrl;
+    if (!workerUrl) {
+      workerUrl = await ctx.runQuery(internal.workflow.pythonWorker._getWorkerUrl, {});
+    }
+    if (!workerUrl) {
+      throw new Error(
+        "URL del Python Worker non configurato. " +
+        "Aggiungi una globalSetting con key='python_worker_url' o passa workerUrl come argomento.",
+      );
+    }
+
+    const endpoint = `${workerUrl.replace(/\/$/, "")}/calculate`;
+
+    await ctx.runMutation(internal.workflow.pythonWorker._logWorkerCall, {
+      runId: args.runId,
+      userId: args.userId,
+      endpoint,
+      status: "started",
+    });
+
+    try {
+      let response: Response;
+      try {
+        response = await fetch(endpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            run_id: args.runId,
+            period: run.period,
+            user_ids: args.userIds ?? null,
+          }),
+        });
+      } catch (fetchErr: any) {
+        const msg = fetchErr?.message ?? String(fetchErr);
+        if (msg.includes("forbidden") || msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+          throw new Error(
+            `Impossibile raggiungere il Python Worker su ${endpoint}. ` +
+            `Assicurati che il worker sia in esecuzione e che l'URL sia raggiungibile da Convex cloud ` +
+            `(localhost non funziona — usa un URL pubblico come Railway).`,
+          );
+        }
+        throw new Error(`Errore di connessione al Python Worker: ${msg}`);
+      }
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Python Worker ha risposto con ${response.status}: ${errorText}`);
+      }
+
+      const result = await response.json();
+
+      await ctx.runMutation(internal.workflow.pythonWorker._logWorkerCall, {
+        runId: args.runId,
+        userId: args.userId,
+        endpoint,
+        status: "completed",
+        summary: result.summary ?? result,
+      });
+
+      return {
+        status: "ok",
+        runId: args.runId,
+        period: run.period,
+        summary: result.summary ?? result,
+      };
+    } catch (error: any) {
+      await ctx.runMutation(internal.workflow.pythonWorker._logWorkerCall, {
+        runId: args.runId,
+        userId: args.userId,
+        endpoint,
+        status: "error",
+        summary: { error: error.message },
+      });
+      throw error;
+    }
+  },
+});
+
+export const testConnection = action({
+  args: {
+    runId: v.id("compensationRuns"),
+    workerUrl: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const run = await ctx.runQuery(internal.workflow.runs._getInternal, { runId: args.runId });
+    if (!run) throw new Error("Run non trovato");
+
+    let workerUrl = args.workerUrl;
+    if (!workerUrl) {
+      workerUrl = await ctx.runQuery(internal.workflow.pythonWorker._getWorkerUrl, {});
+    }
+    if (!workerUrl) {
+      throw new Error("URL del Python Worker non configurato.");
+    }
+
+    const healthUrl = `${workerUrl.replace(/\/$/, "")}/health`;
+    const healthResp = await fetch(healthUrl);
+    if (!healthResp.ok) {
+      throw new Error(`Health check fallito: ${healthResp.status}`);
+    }
+
+    const testUrl = `${workerUrl.replace(/\/$/, "")}/calculate/test`;
+    const testResp = await fetch(testUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        run_id: args.runId,
+        period: run.period,
+      }),
+    });
+
+    if (!testResp.ok) {
+      throw new Error(`Test calcolo fallito: ${testResp.status}`);
+    }
+
+    return await testResp.json();
+  },
+});
+
+// ── Internal queries/mutations ───────────────────────────
+
+export const _getWorkerUrl = internalQuery({
+  args: {},
+  handler: async (ctx) => {
+    const setting = await ctx.db
+      .query("globalSettings")
+      .withIndex("by_key", (q: any) => q.eq("key", "python_worker_url"))
+      .first();
+    return setting?.value ?? null;
+  },
+});
+
+export const _logWorkerCall = internalMutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+    endpoint: v.string(),
+    status: v.string(),
+    summary: v.optional(v.any()),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: `python_worker_${args.status}`,
+      userId: args.userId,
+      payload: {
+        endpoint: args.endpoint,
+        status: args.status,
+        summary: args.summary,
+      },
+      createdAt: Date.now(),
+    });
+  },
+});

package/convex/workflow/runIssues.ts

@@ -0,0 +1,364 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+import { issueSeverity, issueType } from "../schema";
+import {
+  resolveUserTaxProfile,
+  type ResolvedTaxProfile,
+  type ResolvedUserTaxAssignment,
+} from "../documents/invoiceEngine";
+
+/**
+ * Anomalie strutturate di un run — raccolta, persistenza e interrogazione.
+ *
+ * Da analisi.md:
+ * - "differenze spiegabili" (criterio di successo)
+ * - "audit completo disponibile"
+ *
+ * A differenza degli auditLogs, le runIssues:
+ * - Sono rigenerate ad ogni ciclo di verifica (idempotenti)
+ * - Rappresentano lo stato corrente, non lo storico
+ * - Sono interrogabili per tipo e severità
+ * - Servono per il readiness check prima della chiusura
+ *
+ * Severità:
+ * - error: blocca la chiusura del run
+ * - warning: segnalazione, non blocca
+ * - info: informativo
+ */
+
+// ── Raccolta anomalie ────────────────────────────────────
+
+/**
+ * Scansiona lo stato corrente del run e persiste tutte le anomalie
+ * trovate nella tabella runIssues.
+ *
+ * Idempotente: cancella le issue precedenti e le rigenera.
+ *
+ * Anomalie rilevate:
+ * 1. Righe production/storno senza regola matchata (no_active_plan / no_matching_rule)
+ * 2. Medici con commissioni ma senza profilo fiscale (no_tax_profile / multiple_tax_profiles)
+ * 3. Anomalie fiscali nelle bozze (fiscal_anomaly)
+ * 4. Medici con commissioni ma senza bozza fattura (missing_invoices)
+ */
+export const collectIssues = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const run = await ctx.db.get(args.runId);
+    if (!run) throw new Error("Run non trovato");
+
+    const now = Date.now();
+
+    // Clear issue precedenti
+    const existingIssues = await ctx.db
+      .query("runIssues")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+    for (const issue of existingIssues) {
+      await ctx.db.delete(issue._id);
+    }
+
+    const issues: Array<{
+      issueType: string;
+      severity: string;
+      userId?: string;
+      clinicId?: string;
+      message: string;
+      details?: Record<string, unknown>;
+    }> = [];
+
+    // ── 1. Carica tutte le entry del run ──
+    const allEntries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const productionEntries = allEntries.filter(
+      (e) =>
+        !e.isManual &&
+        (e.type === "production" || e.type === "storno"),
+    );
+
+    const commissionEntries = allEntries.filter(
+      (e) => !e.isManual && e.type === "commission",
+    );
+
+    // ── 2. Righe senza regola matchata ──
+    const ruleApps = await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const matchedSourceIds = new Set(
+      ruleApps.map((ra) => ra.sourceLedgerEntryId),
+    );
+
+    const unmatchedByUser = new Map<
+      string,
+      { count: number; totalAmount: number; hasActivePlan: boolean }
+    >();
+
+    for (const entry of productionEntries) {
+      if (!matchedSourceIds.has(entry._id)) {
+        const existing = unmatchedByUser.get(entry.userId) ?? {
+          count: 0,
+          totalAmount: 0,
+          hasActivePlan: false,
+        };
+        existing.count++;
+        existing.totalAmount += entry.amount;
+        unmatchedByUser.set(entry.userId, existing);
+      }
+    }
+
+    for (const [uid, data] of unmatchedByUser) {
+      const plans = await ctx.db
+        .query("commissionPlans")
+        .withIndex("by_user_status", (q) =>
+          q.eq("userId", uid).eq("status", "active"),
+        )
+        .collect();
+
+      const hasPlan = plans.length > 0;
+
+      issues.push({
+        issueType: hasPlan ? "no_matching_rule" : "no_active_plan",
+        severity: "error",
+        userId: uid,
+        message: hasPlan
+          ? `${data.count} righe produzione/storno senza regola matchata per userId=${uid}`
+          : `Nessun piano provvigionale attivo per userId=${uid}`,
+        details: {
+          unmatchedCount: data.count,
+          unmatchedAmount: data.totalAmount,
+          hasActivePlan: hasPlan,
+        },
+      });
+    }
+
+    // ── 3. Problemi profilo fiscale ──
+    const commissionUserIds = [
+      ...new Set(commissionEntries.map((e) => e.userId)),
+    ];
+
+    for (const uid of commissionUserIds) {
+      const assignments = await ctx.db
+        .query("userTaxProfiles")
+        .withIndex("by_user", (q) => q.eq("userId", uid))
+        .collect();
+
+      const resolvedAssignments: ResolvedUserTaxAssignment[] = assignments.map(
+        (a) => ({
+          _id: a._id,
+          userId: a.userId,
+          taxProfileId: a.taxProfileId,
+          effectiveFrom: a.effectiveFrom,
+          effectiveTo: a.effectiveTo,
+        }),
+      );
+
+      const profilesMap = new Map<string, ResolvedTaxProfile>();
+      for (const a of assignments) {
+        const profile = await ctx.db.get(a.taxProfileId);
+        if (profile) {
+          profilesMap.set(a.taxProfileId, {
+            _id: profile._id,
+            code: profile.code,
+            name: profile.name,
+            vatRatePercent: profile.vatRatePercent,
+            withholdingRatePercent: profile.withholdingRatePercent,
+            contributionRatePercent: profile.contributionRatePercent,
+            stampDutyAmount: profile.stampDutyAmount,
+          });
+        }
+      }
+
+      const resolution = resolveUserTaxProfile(
+        resolvedAssignments,
+        profilesMap,
+        uid,
+        run.period,
+      );
+
+      if (resolution.status !== "found") {
+        const typeMap: Record<string, string> = {
+          no_assignment: "no_tax_profile",
+          multiple_assignments: "multiple_tax_profiles",
+          profile_not_found: "no_tax_profile",
+          profile_inactive: "inactive_tax_profile",
+        };
+
+        issues.push({
+          issueType: typeMap[resolution.status] ?? "no_tax_profile",
+          severity: "error",
+          userId: uid,
+          message: resolutionToMessage(resolution),
+          details: { resolution },
+        });
+      }
+    }
+
+    // ── 4. Anomalie fiscali nelle bozze ──
+    const invoices = await ctx.db
+      .query("draftInvoices")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    for (const inv of invoices) {
+      if (inv.subtotal <= 0) {
+        issues.push({
+          issueType: "fiscal_anomaly",
+          severity: "warning",
+          userId: inv.userId,
+          clinicId: inv.clinicId,
+          message: `Subtotale non positivo (${inv.subtotal}) per userId=${inv.userId}, clinicId=${inv.clinicId}`,
+          details: { subtotal: inv.subtotal, invoiceId: inv._id },
+        });
+      }
+      if (inv.netToPay < 0) {
+        issues.push({
+          issueType: "fiscal_anomaly",
+          severity: "warning",
+          userId: inv.userId,
+          clinicId: inv.clinicId,
+          message: `Netto a pagare negativo (${inv.netToPay}) per userId=${inv.userId}, clinicId=${inv.clinicId}`,
+          details: {
+            netToPay: inv.netToPay,
+            total: inv.total,
+            invoiceId: inv._id,
+          },
+        });
+      }
+    }
+
+    // ── 5. Medici con commissioni ma senza bozza ──
+    const invoiceUserClinicKeys = new Set(
+      invoices.map((inv) => `${inv.userId}|${inv.clinicId}`),
+    );
+
+    const commissionKeys = new Set(
+      commissionEntries.map((e) => `${e.userId}|${e.clinicId}`),
+    );
+
+    for (const key of commissionKeys) {
+      if (!invoiceUserClinicKeys.has(key)) {
+        const [uid, cid] = key.split("|");
+        issues.push({
+          issueType: "missing_invoices",
+          severity: "error",
+          userId: uid,
+          clinicId: cid,
+          message: `Commissioni presenti ma nessuna bozza fattura per userId=${uid}, clinicId=${cid}`,
+        });
+      }
+    }
+
+    // ── Persist ──
+    for (const issue of issues) {
+      await ctx.db.insert("runIssues", {
+        runId: args.runId,
+        issueType: issue.issueType as any,
+        severity: issue.severity as any,
+        userId: issue.userId,
+        clinicId: issue.clinicId,
+        message: issue.message,
+        details: issue.details,
+        createdAt: now,
+      });
+    }
+
+    return {
+      totalIssues: issues.length,
+      errors: issues.filter((i) => i.severity === "error").length,
+      warnings: issues.filter((i) => i.severity === "warning").length,
+      infos: issues.filter((i) => i.severity === "info").length,
+    };
+  },
+});
+
+// ── Query ────────────────────────────────────────────────
+
+export const listByRun = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("runIssues")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+  },
+});
+
+export const listErrorsByRun = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("runIssues")
+      .withIndex("by_run_severity", (q) =>
+        q.eq("runId", args.runId).eq("severity", "error"),
+      )
+      .collect();
+  },
+});
+
+export const listByRunAndType = query({
+  args: {
+    runId: v.id("compensationRuns"),
+    issueType: issueType,
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("runIssues")
+      .withIndex("by_run_type", (q) =>
+        q.eq("runId", args.runId).eq("issueType", args.issueType),
+      )
+      .collect();
+  },
+});
+
+export const getSummary = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    const issues = await ctx.db
+      .query("runIssues")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const byType: Record<string, number> = {};
+    let errors = 0;
+    let warnings = 0;
+
+    for (const issue of issues) {
+      byType[issue.issueType] = (byType[issue.issueType] ?? 0) + 1;
+      if (issue.severity === "error") errors++;
+      else if (issue.severity === "warning") warnings++;
+    }
+
+    return {
+      runId: args.runId,
+      totalIssues: issues.length,
+      errors,
+      warnings,
+      byType,
+      hasBlockingIssues: errors > 0,
+    };
+  },
+});
+
+// ── Helpers ──────────────────────────────────────────────
+
+function resolutionToMessage(resolution: { status: string; userId?: string; count?: number; taxProfileId?: string; profileCode?: string }): string {
+  switch (resolution.status) {
+    case "no_assignment":
+      return `Nessun profilo fiscale assegnato per userId=${resolution.userId}`;
+    case "multiple_assignments":
+      return `Profili fiscali multipli (${resolution.count}) per userId=${resolution.userId}`;
+    case "profile_not_found":
+      return `Profilo fiscale ${resolution.taxProfileId} non trovato per userId=${resolution.userId}`;
+    case "profile_inactive":
+      return `Profilo fiscale "${resolution.profileCode}" non attivo per userId=${resolution.userId}`;
+    default:
+      return "Anomalia profilo fiscale";
+  }
+}