@primocaredentgroup/compensi-medici-core 0.1.0

package/convex/workflow/runs.ts

@@ -0,0 +1,718 @@
+import { v } from "convex/values";
+import { mutation, query, internalQuery } from "../_generated/server";
+import { runStatus, scopeType, calculationMode } from "../schema";
+import { VALID_TRANSITIONS, type RunStatus } from "../lib/types";
+
+/**
+ * Gestione run mensili e workflow del mese.
+ *
+ * Da analisi.md:
+ * - Mese aperto: sempre ricalcolabile, preview aggiornata, modificabile
+ * - Mese chiuso: snapshot immutabile, riapertura solo loggata
+ * - Ricalcolo crea nuova versione
+ *
+ * Invarianti di immutabilità:
+ * - Un run "closed" non può essere modificato in nessun modo
+ * - La riapertura crea una nuova versione (basedOnRunId)
+ * - Il closureSummary è lo snapshot ufficiale dei totali
+ */
+
+// ── Helpers ──────────────────────────────────────────────
+
+function assertNotClosed(run: { status: string }): void {
+  if (run.status === "closed") {
+    throw new Error(
+      "Impossibile modificare un run chiuso. " +
+        "Riaprire il run per creare una nuova versione.",
+    );
+  }
+}
+
+// ── Create ───────────────────────────────────────────────
+
+export const createRun = mutation({
+  args: {
+    period: v.string(),
+    isShadowRun: v.optional(v.boolean()),
+    scopeType: v.optional(scopeType),
+    scopePayload: v.optional(v.any()),
+    calculationMode: v.optional(calculationMode),
+    notes: v.optional(v.string()),
+    triggeredBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    const existing = await ctx.db
+      .query("compensationRuns")
+      .withIndex("by_period", (q) => q.eq("period", args.period))
+      .collect();
+
+    const maxVersion = existing.reduce(
+      (max, r) => Math.max(max, r.version),
+      0,
+    );
+
+    const runId = await ctx.db.insert("compensationRuns", {
+      period: args.period,
+      status: "draft",
+      version: maxVersion + 1,
+      isShadowRun: args.isShadowRun ?? false,
+      scopeType: args.scopeType ?? "global",
+      scopePayload: args.scopePayload,
+      calculationMode: args.calculationMode ?? "manual",
+      triggeredBy: args.triggeredBy,
+      notes: args.notes,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: runId,
+      action: "created",
+      userId: args.triggeredBy,
+      payload: {
+        period: args.period,
+        version: maxVersion + 1,
+        isShadowRun: args.isShadowRun ?? false,
+        scopeType: args.scopeType ?? "global",
+        calculationMode: args.calculationMode ?? "manual",
+      },
+      createdAt: now,
+    });
+
+    return runId;
+  },
+});
+
+// ── Status transitions ───────────────────────────────────
+
+export const updateStatus = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    newStatus: runStatus,
+    notes: v.optional(v.string()),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const run = await ctx.db.get(args.runId);
+    if (!run) throw new Error("Run non trovato");
+
+    assertNotClosed(run);
+
+    if (args.newStatus === "closed") {
+      throw new Error(
+        "Per chiudere un run usare la funzione closeRun dedicata, " +
+          "che include la generazione dello snapshot.",
+      );
+    }
+
+    const currentStatus = run.status as RunStatus;
+    const allowed = VALID_TRANSITIONS[currentStatus];
+
+    if (!allowed.includes(args.newStatus as RunStatus)) {
+      throw new Error(
+        `Transizione non valida: ${currentStatus} → ${args.newStatus}. ` +
+          `Transizioni permesse: ${allowed.join(", ")}`,
+      );
+    }
+
+    const now = Date.now();
+    const patch: Record<string, unknown> = {
+      status: args.newStatus,
+      updatedAt: now,
+    };
+    if (args.notes !== undefined) {
+      patch.notes = args.notes;
+    }
+
+    await ctx.db.patch(args.runId, patch);
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "status_changed",
+      userId: args.userId,
+      payload: { from: currentStatus, to: args.newStatus },
+      createdAt: now,
+    });
+  },
+});
+
+// ── Close ────────────────────────────────────────────────
+
+/**
+ * Chiude un run con generazione dello snapshot ufficiale.
+ *
+ * Da analisi.md:
+ * - "Snapshot mese chiuso (immutabile)"
+ * - "Salvataggio completo del ledger"
+ * - "Salvataggio delle regole applicate"
+ * - "Salvataggio profilo fiscale"
+ * - "Salvataggio documento generato"
+ *
+ * Strategia snapshot: IMPLICITA.
+ * I dati del run (ledgerEntries, ruleApplications, draftInvoices)
+ * sono già persistiti e immutabili dopo la chiusura.
+ * Il closureSummary contiene i totali aggregati per accesso rapido.
+ * Il taxProfileSnapshot è già salvato dentro ogni draftInvoice.
+ *
+ * Pre-condizioni:
+ * - Il run deve essere in stato "approved"
+ * - Non devono esserci anomalie bloccanti (severity = "error")
+ */
+export const closeRun = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+    force: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const run = await ctx.db.get(args.runId);
+    if (!run) throw new Error("Run non trovato");
+
+    assertNotClosed(run);
+
+    if (run.status !== "approved") {
+      throw new Error(
+        `Solo run in stato "approved" possono essere chiusi. Stato attuale: ${run.status}`,
+      );
+    }
+
+    // ── Readiness check inline ──
+    const blockingIssues = await ctx.db
+      .query("runIssues")
+      .withIndex("by_run_severity", (q) =>
+        q.eq("runId", args.runId).eq("severity", "error"),
+      )
+      .collect();
+
+    if (blockingIssues.length > 0 && !args.force) {
+      throw new Error(
+        `Impossibile chiudere il run: ${blockingIssues.length} anomalie bloccanti. ` +
+          `Risolvere le anomalie o usare force=true per forzare la chiusura.`,
+      );
+    }
+
+    // ── Build closure summary ──
+    const allEntries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    let totalProductionAmount = 0;
+    let totalStornoAmount = 0;
+    let totalCommissionAmount = 0;
+    let totalManualAmount = 0;
+    let productionCount = 0;
+    let stornoCount = 0;
+    let commissionCount = 0;
+    let manualCount = 0;
+    const userIds = new Set<string>();
+
+    for (const entry of allEntries) {
+      userIds.add(entry.userId);
+      if (entry.isManual) {
+        totalManualAmount += entry.amount;
+        manualCount++;
+      } else if (entry.type === "production") {
+        totalProductionAmount += entry.amount;
+        productionCount++;
+      } else if (entry.type === "storno") {
+        totalStornoAmount += entry.amount;
+        stornoCount++;
+      } else if (entry.type === "commission") {
+        totalCommissionAmount += entry.amount;
+        commissionCount++;
+      }
+    }
+
+    const ruleApps = await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const invoices = await ctx.db
+      .query("draftInvoices")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    let totalNetToPay = 0;
+    let totalInvoiceSubtotal = 0;
+    for (const inv of invoices) {
+      totalNetToPay += inv.netToPay;
+      totalInvoiceSubtotal += inv.subtotal;
+    }
+
+    const allIssues = await ctx.db
+      .query("runIssues")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const closureSummary = {
+      totalUsers: userIds.size,
+      totalLedgerEntries: allEntries.length,
+      productionCount,
+      stornoCount,
+      commissionCount,
+      manualCount,
+      totalProductionAmount: Math.round(totalProductionAmount * 100) / 100,
+      totalStornoAmount: Math.round(totalStornoAmount * 100) / 100,
+      netProduction:
+        Math.round((totalProductionAmount + totalStornoAmount) * 100) / 100,
+      totalCommissionAmount:
+        Math.round(totalCommissionAmount * 100) / 100,
+      totalManualAmount: Math.round(totalManualAmount * 100) / 100,
+      totalRuleApplications: ruleApps.length,
+      totalInvoices: invoices.length,
+      totalInvoiceSubtotal:
+        Math.round(totalInvoiceSubtotal * 100) / 100,
+      totalNetToPay: Math.round(totalNetToPay * 100) / 100,
+      issuesSummary: {
+        total: allIssues.length,
+        errors: allIssues.filter((i) => i.severity === "error").length,
+        warnings: allIssues.filter((i) => i.severity === "warning").length,
+      },
+      closedAt: Date.now(),
+      closedBy: args.userId,
+    };
+
+    const now = Date.now();
+    await ctx.db.patch(args.runId, {
+      status: "closed",
+      closedAt: now,
+      closedBy: args.userId,
+      closureSummary,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "closed",
+      userId: args.userId,
+      payload: {
+        closureSummary,
+        forceClosed: args.force ?? false,
+        blockingIssuesAtClose: blockingIssues.length,
+      },
+      createdAt: now,
+    });
+
+    return { runId: args.runId, closureSummary };
+  },
+});
+
+// ── Reopen ───────────────────────────────────────────────
+
+/**
+ * Riapre un run chiuso creando una NUOVA versione.
+ * Da analisi.md: "riapertura solo loggata, ricalcolo crea nuova versione"
+ *
+ * Il run chiuso resta intatto e leggibile.
+ * Il nuovo run parte in stato "draft" con basedOnRunId che punta all'originale.
+ */
+export const reopenRun = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    notes: v.optional(v.string()),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const run = await ctx.db.get(args.runId);
+    if (!run) throw new Error("Run non trovato");
+    if (run.status !== "closed") {
+      throw new Error(
+        `Solo run in stato "closed" possono essere riaperti. Stato attuale: ${run.status}`,
+      );
+    }
+
+    const existing = await ctx.db
+      .query("compensationRuns")
+      .withIndex("by_period", (q) => q.eq("period", run.period))
+      .collect();
+
+    const maxVersion = existing.reduce(
+      (max, r) => Math.max(max, r.version),
+      0,
+    );
+
+    const now = Date.now();
+    const newRunId = await ctx.db.insert("compensationRuns", {
+      period: run.period,
+      status: "draft",
+      version: maxVersion + 1,
+      isShadowRun: run.isShadowRun,
+      basedOnRunId: args.runId,
+      scopeType: run.scopeType,
+      scopePayload: run.scopePayload,
+      calculationMode: "reopen",
+      triggeredBy: args.userId,
+      notes: args.notes,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: newRunId,
+      action: "reopened_from",
+      userId: args.userId,
+      payload: {
+        originalRunId: args.runId,
+        originalVersion: run.version,
+        newVersion: maxVersion + 1,
+        originalClosureSummary: run.closureSummary,
+      },
+      createdAt: now,
+    });
+
+    return newRunId;
+  },
+});
+
+// ── Readiness check ──────────────────────────────────────
+
+/**
+ * Verifica se un run è pronto per la chiusura.
+ *
+ * Controlla:
+ * 1. Stato coerente (deve essere "approved")
+ * 2. Presenza di ledger entries calcolate
+ * 3. Presenza di draft invoices generate
+ * 4. Assenza di anomalie bloccanti (severity = "error")
+ *
+ * Restituisce un oggetto con dettaglio dei check e un flag `isReady`.
+ */
+export const checkReadiness = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    const run = await ctx.db.get(args.runId);
+    if (!run) throw new Error("Run non trovato");
+
+    const checks: Array<{
+      check: string;
+      passed: boolean;
+      details: string;
+    }> = [];
+
+    // Check 1: Stato
+    const statusOk = run.status === "approved";
+    checks.push({
+      check: "status_approved",
+      passed: statusOk,
+      details: statusOk
+        ? "Run in stato approved"
+        : `Run in stato "${run.status}", deve essere "approved"`,
+    });
+
+    // Check 2: Ledger entries presenti
+    const entries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const commissions = entries.filter(
+      (e) => !e.isManual && e.type === "commission",
+    );
+    const hasCommissions = commissions.length > 0;
+    checks.push({
+      check: "has_commissions",
+      passed: hasCommissions,
+      details: hasCommissions
+        ? `${commissions.length} righe commission presenti`
+        : "Nessuna riga commission trovata",
+    });
+
+    // Check 3: Draft invoices presenti
+    const invoices = await ctx.db
+      .query("draftInvoices")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const hasInvoices = invoices.length > 0;
+    checks.push({
+      check: "has_invoices",
+      passed: hasInvoices,
+      details: hasInvoices
+        ? `${invoices.length} bozze fattura presenti`
+        : "Nessuna bozza fattura trovata",
+    });
+
+    // Check 4: Anomalie bloccanti
+    const blockingIssues = await ctx.db
+      .query("runIssues")
+      .withIndex("by_run_severity", (q) =>
+        q.eq("runId", args.runId).eq("severity", "error"),
+      )
+      .collect();
+
+    const noBlockingIssues = blockingIssues.length === 0;
+    checks.push({
+      check: "no_blocking_issues",
+      passed: noBlockingIssues,
+      details: noBlockingIssues
+        ? "Nessuna anomalia bloccante"
+        : `${blockingIssues.length} anomalie bloccanti da risolvere`,
+    });
+
+    const isReady = checks.every((c) => c.passed);
+
+    return {
+      runId: args.runId,
+      period: run.period,
+      version: run.version,
+      currentStatus: run.status,
+      isReady,
+      checks,
+      blockingIssues: noBlockingIssues ? [] : blockingIssues,
+    };
+  },
+});
+
+// ── Snapshot / detail ────────────────────────────────────
+
+/**
+ * Dettaglio completo di un run chiuso: closure summary + conteggi attuali.
+ * Utile per verificare la coerenza dello snapshot.
+ */
+export const getRunSnapshot = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    const run = await ctx.db.get(args.runId);
+    if (!run) throw new Error("Run non trovato");
+
+    const entries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const ruleApps = await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const invoices = await ctx.db
+      .query("draftInvoices")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const issues = await ctx.db
+      .query("runIssues")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    return {
+      run,
+      closureSummary: run.closureSummary ?? null,
+      currentCounts: {
+        ledgerEntries: entries.length,
+        ruleApplications: ruleApps.length,
+        draftInvoices: invoices.length,
+        issues: issues.length,
+      },
+      isClosed: run.status === "closed",
+    };
+  },
+});
+
+// ── Version comparison ───────────────────────────────────
+
+/**
+ * Confronta due run dello stesso periodo (es. versione N vs N+1).
+ * Mostra le differenze nei totali tra i due snapshot.
+ */
+export const compareRuns = query({
+  args: {
+    runIdA: v.id("compensationRuns"),
+    runIdB: v.id("compensationRuns"),
+  },
+  handler: async (ctx, args) => {
+    const runA = await ctx.db.get(args.runIdA);
+    const runB = await ctx.db.get(args.runIdB);
+    if (!runA) throw new Error("Run A non trovato");
+    if (!runB) throw new Error("Run B non trovato");
+
+    if (runA.period !== runB.period) {
+      throw new Error(
+        `I run devono essere dello stesso periodo. A: ${runA.period}, B: ${runB.period}`,
+      );
+    }
+
+    const buildSummary = async (runId: typeof args.runIdA) => {
+      const entries = await ctx.db
+        .query("ledgerEntries")
+        .withIndex("by_run", (q) => q.eq("runId", runId))
+        .collect();
+
+      let production = 0;
+      let storno = 0;
+      let commission = 0;
+      let manual = 0;
+      let productionCount = 0;
+      let commissionCount = 0;
+      const users = new Set<string>();
+
+      for (const e of entries) {
+        users.add(e.userId);
+        if (e.isManual) {
+          manual += e.amount;
+        } else if (e.type === "production") {
+          production += e.amount;
+          productionCount++;
+        } else if (e.type === "storno") {
+          storno += e.amount;
+        } else if (e.type === "commission") {
+          commission += e.amount;
+          commissionCount++;
+        }
+      }
+
+      const invoices = await ctx.db
+        .query("draftInvoices")
+        .withIndex("by_run", (q) => q.eq("runId", runId))
+        .collect();
+
+      let netToPay = 0;
+      for (const inv of invoices) {
+        netToPay += inv.netToPay;
+      }
+
+      return {
+        totalUsers: users.size,
+        totalEntries: entries.length,
+        productionCount,
+        commissionCount,
+        production: Math.round(production * 100) / 100,
+        storno: Math.round(storno * 100) / 100,
+        netProduction: Math.round((production + storno) * 100) / 100,
+        commission: Math.round(commission * 100) / 100,
+        manual: Math.round(manual * 100) / 100,
+        totalInvoices: invoices.length,
+        netToPay: Math.round(netToPay * 100) / 100,
+      };
+    };
+
+    const summaryA = await buildSummary(args.runIdA);
+    const summaryB = await buildSummary(args.runIdB);
+
+    const diff = (a: number, b: number) =>
+      Math.round((b - a) * 100) / 100;
+
+    return {
+      period: runA.period,
+      runA: {
+        runId: args.runIdA,
+        version: runA.version,
+        status: runA.status,
+        summary: summaryA,
+      },
+      runB: {
+        runId: args.runIdB,
+        version: runB.version,
+        status: runB.status,
+        summary: summaryB,
+      },
+      differences: {
+        production: diff(summaryA.production, summaryB.production),
+        storno: diff(summaryA.storno, summaryB.storno),
+        netProduction: diff(
+          summaryA.netProduction,
+          summaryB.netProduction,
+        ),
+        commission: diff(summaryA.commission, summaryB.commission),
+        manual: diff(summaryA.manual, summaryB.manual),
+        netToPay: diff(summaryA.netToPay, summaryB.netToPay),
+        entries: summaryB.totalEntries - summaryA.totalEntries,
+        invoices: summaryB.totalInvoices - summaryA.totalInvoices,
+      },
+    };
+  },
+});
+
+// ── Query base ───────────────────────────────────────────
+
+export const get = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.runId);
+  },
+});
+
+export const _getInternal = internalQuery({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.runId);
+  },
+});
+
+export const listByPeriod = query({
+  args: { period: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("compensationRuns")
+      .withIndex("by_period", (q) => q.eq("period", args.period))
+      .collect();
+  },
+});
+
+export const listByStatus = query({
+  args: { status: runStatus },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("compensationRuns")
+      .withIndex("by_status", (q) => q.eq("status", args.status))
+      .collect();
+  },
+});
+
+export const listClosed = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("compensationRuns")
+      .withIndex("by_status", (q) => q.eq("status", "closed"))
+      .collect();
+  },
+});
+
+export const listShadowByPeriod = query({
+  args: { period: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("compensationRuns")
+      .withIndex("by_shadow", (q) =>
+        q.eq("isShadowRun", true).eq("period", args.period),
+      )
+      .collect();
+  },
+});
+
+/**
+ * Storico versioni di un periodo: tutti i run ordinati per versione.
+ */
+export const getVersionHistory = query({
+  args: { period: v.string() },
+  handler: async (ctx, args) => {
+    const runs = await ctx.db
+      .query("compensationRuns")
+      .withIndex("by_period", (q) => q.eq("period", args.period))
+      .collect();
+
+    const sorted = runs.sort((a, b) => a.version - b.version);
+
+    return sorted.map((r) => ({
+      runId: r._id,
+      version: r.version,
+      status: r.status,
+      basedOnRunId: r.basedOnRunId,
+      calculationMode: r.calculationMode,
+      isShadowRun: r.isShadowRun,
+      createdAt: r.createdAt,
+      closedAt: r.closedAt,
+      closedBy: r.closedBy,
+      closureSummary: r.closureSummary,
+    }));
+  },
+});