@primocaredentgroup/compensi-medici-core 0.1.0

package/convex/calculation/production.ts

@@ -0,0 +1,495 @@
+import { v } from "convex/values";
+import { mutation, query, internalMutation } from "../_generated/server";
+import {
+  productionSourceRecordValidator,
+  mapSourceToLedgerEntry,
+  type ProductionSourceRecord,
+} from "./productionData";
+
+/**
+ * Pipeline di produzione base — ingestione dati nel ledger.
+ *
+ * Da analisi.md:
+ * - "Produzione da care_plan_rows (prestazioni eseguite)"
+ * - "Storni (già forniti da Primoupcore)"
+ * - "Mese aperto: sempre ricalcolabile"
+ *
+ * Questo modulo gestisce il ciclo di vita delle righe di produzione:
+ *
+ * 1. clearProductionEntries — rimuove le righe automatiche production/storno
+ * 2. ingestProductionData — scrive nuove righe da dati sorgente
+ * 3. refreshProduction — clear + ingest (operazione idempotente)
+ *
+ * Strategia di idempotenza:
+ *   Al ricalcolo, si cancellano SOLO le righe con:
+ *   - type in ("production", "storno")
+ *   - isManual = false
+ *   Le righe manuali (rimborsi, rettifiche, bonus manuali) restano intatte.
+ *   Poi si riscrivono le righe di produzione dai dati sorgente aggiornati.
+ *
+ * Shadow mode:
+ *   La pipeline non distingue run ufficiali da shadow.
+ *   Le righe vengono scritte sul run passato come argomento.
+ *   L'isolamento avviene a livello di run (isShadowRun sul compensationRun).
+ */
+
+// ── Guard: verifica stato run ────────────────────────────
+
+/**
+ * Valida che il run esista e sia in uno stato che ammette
+ * modifiche alle righe di produzione.
+ */
+async function assertRunWritable(
+  ctx: { db: { get: (id: any) => Promise<any> } },
+  runId: any,
+): Promise<{ period: string }> {
+  const run = await ctx.db.get(runId);
+  if (!run) throw new Error("Run non trovato");
+  if (run.status === "closed") {
+    throw new Error(
+      "Impossibile modificare la produzione di un run chiuso. " +
+        "Riaprire il run per creare una nuova versione.",
+    );
+  }
+  if (run.status === "approved") {
+    throw new Error(
+      "Impossibile modificare la produzione di un run approvato. " +
+        "Riportarlo in reviewing o draft prima di rigenerare.",
+    );
+  }
+  return { period: run.period };
+}
+
+// ── Clear ────────────────────────────────────────────────
+
+/**
+ * Cancella le righe automatiche di produzione e storno per un run.
+ *
+ * Filtra per:
+ *   type in ("production", "storno") AND isManual = false
+ *
+ * NON tocca mai: reimbursement, adjustment, fixed, bonus,
+ * né qualunque riga con isManual = true.
+ */
+export const clearProductionEntries = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await assertRunWritable(ctx, args.runId);
+
+    const entries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    let productionDeleted = 0;
+    let stornoDeleted = 0;
+
+    for (const entry of entries) {
+      const isAutoProduction =
+        !entry.isManual &&
+        (entry.type === "production" || entry.type === "storno");
+
+      if (isAutoProduction) {
+        await ctx.db.delete(entry._id);
+        if (entry.type === "production") productionDeleted++;
+        else stornoDeleted++;
+      }
+    }
+
+    const totalDeleted = productionDeleted + stornoDeleted;
+
+    if (totalDeleted > 0) {
+      await ctx.db.insert("auditLogs", {
+        entityType: "compensationRuns",
+        entityId: args.runId,
+        action: "production_entries_cleared",
+        userId: args.userId,
+        payload: { productionDeleted, stornoDeleted },
+        createdAt: Date.now(),
+      });
+    }
+
+    return { productionDeleted, stornoDeleted, totalDeleted };
+  },
+});
+
+// ── Ingest ───────────────────────────────────────────────
+
+/**
+ * Scrive righe di produzione nel ledger a partire da dati sorgente.
+ *
+ * Riceve un array di ProductionSourceRecord e li mappa
+ * in ledger entries tramite mapSourceToLedgerEntry.
+ *
+ * NON cancella righe esistenti — va chiamato dopo clearProductionEntries
+ * oppure usare refreshProduction per l'operazione completa.
+ */
+export const ingestProductionData = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    sourceRecords: v.array(productionSourceRecordValidator),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const { period } = await assertRunWritable(ctx, args.runId);
+
+    const now = Date.now();
+    let productionCount = 0;
+    let stornoCount = 0;
+    let totalAmount = 0;
+
+    const insertedIds: string[] = [];
+
+    for (const source of args.sourceRecords) {
+      if (source.period !== period) {
+        throw new Error(
+          `Periodo del record sorgente (${source.period}) non corrisponde ` +
+            `al periodo del run (${period}). carePlanRowId: ${source.carePlanRowId}`,
+        );
+      }
+
+      const entry = mapSourceToLedgerEntry(
+        source as ProductionSourceRecord,
+        args.runId,
+        args.userId,
+      );
+
+      const id = await ctx.db.insert("ledgerEntries", {
+        ...entry,
+        createdAt: now,
+      });
+
+      insertedIds.push(id);
+      totalAmount += source.amount;
+
+      if (source.isStorno) stornoCount++;
+      else productionCount++;
+    }
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "production_ingested",
+      userId: args.userId,
+      payload: {
+        productionCount,
+        stornoCount,
+        totalRecords: args.sourceRecords.length,
+        totalAmount,
+      },
+      createdAt: now,
+    });
+
+    return {
+      insertedCount: insertedIds.length,
+      productionCount,
+      stornoCount,
+      totalAmount,
+    };
+  },
+});
+
+// ── Refresh (idempotente) ────────────────────────────────
+
+/**
+ * Rigenera la produzione per un run: clear + ingest.
+ *
+ * Operazione idempotente: può essere chiamata più volte
+ * per lo stesso run con lo stesso risultato.
+ *
+ * Flusso:
+ *   1. Cancella le righe automatiche production/storno
+ *   2. Inserisce le nuove righe dai dati sorgente
+ *   3. Logga l'operazione completa
+ *
+ * Le righe manuali (rimborsi, rettifiche) non vengono toccate.
+ */
+export const refreshProduction = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    sourceRecords: v.array(productionSourceRecordValidator),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const { period } = await assertRunWritable(ctx, args.runId);
+
+    // ── Step 1: Clear ──
+    const allEntries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    let clearedCount = 0;
+    for (const entry of allEntries) {
+      if (
+        !entry.isManual &&
+        (entry.type === "production" || entry.type === "storno")
+      ) {
+        await ctx.db.delete(entry._id);
+        clearedCount++;
+      }
+    }
+
+    // ── Step 2: Ingest ──
+    const now = Date.now();
+    let productionCount = 0;
+    let stornoCount = 0;
+    let totalAmount = 0;
+
+    for (const source of args.sourceRecords) {
+      if (source.period !== period) {
+        throw new Error(
+          `Periodo non corrispondente: record=${source.period}, run=${period}`,
+        );
+      }
+
+      const entry = mapSourceToLedgerEntry(
+        source as ProductionSourceRecord,
+        args.runId,
+        args.userId,
+      );
+
+      await ctx.db.insert("ledgerEntries", {
+        ...entry,
+        createdAt: now,
+      });
+
+      totalAmount += source.amount;
+      if (source.isStorno) stornoCount++;
+      else productionCount++;
+    }
+
+    // ── Step 3: Audit ──
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "production_refreshed",
+      userId: args.userId,
+      payload: {
+        clearedCount,
+        productionCount,
+        stornoCount,
+        totalRecords: args.sourceRecords.length,
+        totalAmount,
+      },
+      createdAt: now,
+    });
+
+    return {
+      clearedCount,
+      insertedCount: args.sourceRecords.length,
+      productionCount,
+      stornoCount,
+      totalAmount,
+    };
+  },
+});
+
+// ── Query: sommario produzione ───────────────────────────
+
+/**
+ * Riepilogo produzione per un run: totale produzione, totale storni,
+ * netto, conteggi. Solo righe automatiche di tipo production/storno.
+ */
+export const getProductionSummary = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    const allEntries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    let productionTotal = 0;
+    let productionCount = 0;
+    let stornoTotal = 0;
+    let stornoCount = 0;
+
+    for (const entry of allEntries) {
+      if (!entry.isManual) {
+        if (entry.type === "production") {
+          productionTotal += entry.amount;
+          productionCount++;
+        } else if (entry.type === "storno") {
+          stornoTotal += entry.amount;
+          stornoCount++;
+        }
+      }
+    }
+
+    return {
+      runId: args.runId,
+      productionTotal,
+      productionCount,
+      stornoTotal,
+      stornoCount,
+      netProduction: productionTotal + stornoTotal,
+      totalEntries: productionCount + stornoCount,
+    };
+  },
+});
+
+/**
+ * Riepilogo produzione per un run e un medico specifico.
+ */
+export const getProductionSummaryByUser = query({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const entries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run_user", (q) =>
+        q.eq("runId", args.runId).eq("userId", args.userId),
+      )
+      .collect();
+
+    let productionTotal = 0;
+    let productionCount = 0;
+    let stornoTotal = 0;
+    let stornoCount = 0;
+
+    const byClinic: Record<
+      string,
+      { production: number; storno: number; net: number }
+    > = {};
+
+    for (const entry of entries) {
+      if (!entry.isManual) {
+        if (entry.type === "production") {
+          productionTotal += entry.amount;
+          productionCount++;
+        } else if (entry.type === "storno") {
+          stornoTotal += entry.amount;
+          stornoCount++;
+        }
+
+        if (entry.type === "production" || entry.type === "storno") {
+          if (!byClinic[entry.clinicId]) {
+            byClinic[entry.clinicId] = { production: 0, storno: 0, net: 0 };
+          }
+          if (entry.type === "production") {
+            byClinic[entry.clinicId].production += entry.amount;
+          } else {
+            byClinic[entry.clinicId].storno += entry.amount;
+          }
+          byClinic[entry.clinicId].net += entry.amount;
+        }
+      }
+    }
+
+    return {
+      runId: args.runId,
+      userId: args.userId,
+      productionTotal,
+      productionCount,
+      stornoTotal,
+      stornoCount,
+      netProduction: productionTotal + stornoTotal,
+      byClinic,
+    };
+  },
+});
+
+/**
+ * Riepilogo produzione per run, raggruppato per medico.
+ * Utile per la vista riepilogativa del run.
+ */
+export const getProductionByUserSummary = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    const allEntries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const byUser: Record<
+      string,
+      {
+        productionTotal: number;
+        productionCount: number;
+        stornoTotal: number;
+        stornoCount: number;
+        netProduction: number;
+      }
+    > = {};
+
+    for (const entry of allEntries) {
+      if (
+        !entry.isManual &&
+        (entry.type === "production" || entry.type === "storno")
+      ) {
+        if (!byUser[entry.userId]) {
+          byUser[entry.userId] = {
+            productionTotal: 0,
+            productionCount: 0,
+            stornoTotal: 0,
+            stornoCount: 0,
+            netProduction: 0,
+          };
+        }
+        const u = byUser[entry.userId];
+        if (entry.type === "production") {
+          u.productionTotal += entry.amount;
+          u.productionCount++;
+        } else {
+          u.stornoTotal += entry.amount;
+          u.stornoCount++;
+        }
+        u.netProduction += entry.amount;
+      }
+    }
+
+    return {
+      runId: args.runId,
+      users: byUser,
+      totalUsers: Object.keys(byUser).length,
+    };
+  },
+});
+
+/**
+ * Elenca le righe di produzione di un run (production + storno, non manuali).
+ */
+export const listProductionEntries = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    const allEntries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    return allEntries.filter(
+      (e) =>
+        !e.isManual &&
+        (e.type === "production" || e.type === "storno"),
+    );
+  },
+});
+
+/**
+ * Elenca le righe di produzione di un run per un medico.
+ */
+export const listProductionEntriesByUser = query({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const entries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run_user", (q) =>
+        q.eq("runId", args.runId).eq("userId", args.userId),
+      )
+      .collect();
+
+    return entries.filter(
+      (e) =>
+        !e.isManual &&
+        (e.type === "production" || e.type === "storno"),
+    );
+  },
+});

package/convex/calculation/productionData.ts

@@ -0,0 +1,155 @@
+import { v } from "convex/values";
+import type { Id } from "../_generated/dataModel";
+
+/**
+ * Source model per i dati di produzione da Primoupcore.
+ *
+ * Da analisi.md:
+ * - Fonte dati: "Primoupcore → eseguiti + storni"
+ * - "Produzione: somma delle prestazioni eseguite nel mese per medico"
+ * - "Storni: già forniti da Primoupcore"
+ *
+ * Questo modulo definisce:
+ * 1. Il tipo TypeScript per il dato sorgente
+ * 2. Il validator Convex corrispondente (per args delle mutations)
+ * 3. La funzione pura di mapping sorgente → ledger entry
+ * 4. Il placeholder per il fetch da Primoupcore
+ */
+
+// ── Source model ─────────────────────────────────────────
+
+/**
+ * Record sorgente di produzione da Primoupcore.
+ * Rappresenta una singola riga di prestazione eseguita o storno.
+ *
+ * Il campo isStorno distingue produzione da storni:
+ * - false → prestazione eseguita (riga produzione)
+ * - true  → storno già identificato da Primoupcore
+ *
+ * category, subcategory, conventionId sono opzionali
+ * ma saranno fondamentali per il futuro matching dei piani.
+ */
+export interface ProductionSourceRecord {
+  carePlanRowId: string;
+  userId: string;
+  clinicId: string;
+  amount: number;
+  performedAt: number;
+  period: string;
+  isStorno: boolean;
+  category?: string;
+  subcategory?: string;
+  conventionId?: string;
+  /** Per storni: riferimento alla riga originale stornata */
+  originalCarePlanRowId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Validator Convex per ProductionSourceRecord.
+ * Usato come arg nelle mutations che ricevono dati sorgente.
+ */
+export const productionSourceRecordValidator = v.object({
+  carePlanRowId: v.string(),
+  userId: v.string(),
+  clinicId: v.string(),
+  amount: v.number(),
+  performedAt: v.number(),
+  period: v.string(),
+  isStorno: v.boolean(),
+  category: v.optional(v.string()),
+  subcategory: v.optional(v.string()),
+  conventionId: v.optional(v.string()),
+  originalCarePlanRowId: v.optional(v.string()),
+  metadata: v.optional(v.any()),
+});
+
+// ── Mapping ──────────────────────────────────────────────
+
+/**
+ * Shape di una ledger entry pronta per l'inserimento.
+ * Corrisponde ai campi della tabella ledgerEntries meno _id e _creationTime.
+ */
+export interface LedgerEntryInsert {
+  runId: Id<"compensationRuns">;
+  userId: string;
+  clinicId: string;
+  type: "production" | "storno";
+  sourceType: "care_plan_row" | "storno";
+  sourceId: string;
+  description: string;
+  amount: number;
+  quantity: number;
+  unitAmount: number;
+  isManual: false;
+  effectiveDate: number;
+  period: string;
+  metadata: Record<string, unknown>;
+  createdBy: string;
+}
+
+/**
+ * Trasforma un record sorgente di produzione nella shape
+ * di una ledger entry pronta per l'inserimento.
+ *
+ * Funzione pura, testabile, senza side-effect.
+ * Non accede al DB — solo trasformazione dati.
+ */
+export function mapSourceToLedgerEntry(
+  source: ProductionSourceRecord,
+  runId: Id<"compensationRuns">,
+  createdBy: string,
+): LedgerEntryInsert {
+  const isStorno = source.isStorno;
+
+  const meta: Record<string, unknown> = {};
+  if (source.category) meta.category = source.category;
+  if (source.subcategory) meta.subcategory = source.subcategory;
+  if (source.conventionId) meta.conventionId = source.conventionId;
+  if (source.originalCarePlanRowId) {
+    meta.originalCarePlanRowId = source.originalCarePlanRowId;
+  }
+  if (source.metadata) {
+    Object.assign(meta, source.metadata);
+  }
+
+  return {
+    runId,
+    userId: source.userId,
+    clinicId: source.clinicId,
+    type: isStorno ? "storno" : "production",
+    sourceType: isStorno ? "storno" : "care_plan_row",
+    sourceId: source.carePlanRowId,
+    description: isStorno
+      ? `Storno: ${source.carePlanRowId}`
+      : `Produzione: ${source.carePlanRowId}`,
+    amount: source.amount,
+    quantity: 1,
+    unitAmount: source.amount,
+    isManual: false as const,
+    effectiveDate: source.performedAt,
+    period: source.period,
+    metadata: meta,
+    createdBy,
+  };
+}
+
+// ── Fetch placeholder ────────────────────────────────────
+
+/**
+ * PLACEHOLDER: recupera i dati di produzione da Primoupcore per un periodo.
+ *
+ * Verrà sostituito con l'integrazione reale (query Convex verso
+ * le tabelle di Primoupcore oppure chiamata API).
+ *
+ * Restituisce un array di ProductionSourceRecord già normalizzati.
+ * Il campo isStorno sarà true per gli storni.
+ */
+export async function fetchProductionForPeriod(
+  _period: string,
+  _scopeUserIds?: string[],
+  _scopeClinicIds?: string[],
+): Promise<ProductionSourceRecord[]> {
+  // TODO: integrare con Primoupcore
+  return [];
+}