@primocaredentgroup/compensi-medici-core 0.1.0

package/convex/documents/statements.ts

@@ -0,0 +1,185 @@
+import { v } from "convex/values";
+import { query } from "../_generated/server";
+
+/**
+ * Prospetto compensi — vista aggregata del ledger per un medico.
+ *
+ * Da analisi.md il ledger è "la fonte di verità per: prospetto, fattura, audit, storico".
+ * Il prospetto NON è un'entità salvata: è una vista calcolata al volo.
+ *
+ * Breakdown:
+ * - produzione base (production, storno) con netto
+ * - compensi calcolati (commission) con dettaglio regole applicate
+ * - righe manuali (rimborsi, rettifiche)
+ * - righe calcolate future (fixed, bonus)
+ */
+
+export const getByRunAndUser = 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();
+
+    const byType: Record<
+      string,
+      { count: number; total: number; manualCount: number }
+    > = {};
+    let grandTotal = 0;
+    let manualTotal = 0;
+    let calculatedTotal = 0;
+
+    let productionTotal = 0;
+    let productionCount = 0;
+    let stornoTotal = 0;
+    let stornoCount = 0;
+    let commissionTotal = 0;
+    let commissionCount = 0;
+
+    for (const entry of entries) {
+      if (!byType[entry.type]) {
+        byType[entry.type] = { count: 0, total: 0, manualCount: 0 };
+      }
+      byType[entry.type].count += 1;
+      byType[entry.type].total += entry.amount;
+
+      if (entry.isManual) {
+        byType[entry.type].manualCount += 1;
+        manualTotal += entry.amount;
+      } else {
+        calculatedTotal += entry.amount;
+
+        if (entry.type === "production") {
+          productionTotal += entry.amount;
+          productionCount++;
+        } else if (entry.type === "storno") {
+          stornoTotal += entry.amount;
+          stornoCount++;
+        } else if (entry.type === "commission") {
+          commissionTotal += entry.amount;
+          commissionCount++;
+        }
+      }
+
+      grandTotal += entry.amount;
+    }
+
+    const ruleApplications = await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const entryIds = new Set(entries.map((e) => e._id));
+    const userRuleApplications = ruleApplications.filter(
+      (ra) =>
+        entryIds.has(ra.sourceLedgerEntryId) ||
+        entryIds.has(ra.generatedLedgerEntryId),
+    );
+
+    return {
+      runId: args.runId,
+      userId: args.userId,
+      breakdown: byType,
+      production: {
+        total: productionTotal,
+        count: productionCount,
+        stornoTotal,
+        stornoCount,
+        netProduction: productionTotal + stornoTotal,
+      },
+      commissions: {
+        total: commissionTotal,
+        count: commissionCount,
+      },
+      grandTotal,
+      manualTotal,
+      calculatedTotal,
+      entryCount: entries.length,
+      rulesApplied: userRuleApplications.length,
+      entries,
+      ruleApplications: userRuleApplications,
+    };
+  },
+});
+
+export const getSummaryByRun = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    const entries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    const byUser: Record<
+      string,
+      {
+        total: number;
+        entryCount: number;
+        productionTotal: number;
+        stornoTotal: number;
+        netProduction: number;
+        commissionTotal: number;
+        commissionCount: number;
+        manualTotal: number;
+        calculatedTotal: number;
+      }
+    > = {};
+
+    for (const entry of entries) {
+      if (!byUser[entry.userId]) {
+        byUser[entry.userId] = {
+          total: 0,
+          entryCount: 0,
+          productionTotal: 0,
+          stornoTotal: 0,
+          netProduction: 0,
+          commissionTotal: 0,
+          commissionCount: 0,
+          manualTotal: 0,
+          calculatedTotal: 0,
+        };
+      }
+
+      const u = byUser[entry.userId];
+      u.total += entry.amount;
+      u.entryCount += 1;
+
+      if (entry.isManual) {
+        u.manualTotal += entry.amount;
+      } else {
+        u.calculatedTotal += entry.amount;
+        if (entry.type === "production") {
+          u.productionTotal += entry.amount;
+        } else if (entry.type === "storno") {
+          u.stornoTotal += entry.amount;
+        } else if (entry.type === "commission") {
+          u.commissionTotal += entry.amount;
+          u.commissionCount++;
+        }
+      }
+      u.netProduction = u.productionTotal + u.stornoTotal;
+    }
+
+    let grandTotal = 0;
+    let totalCommissions = 0;
+    for (const u of Object.values(byUser)) {
+      grandTotal += u.total;
+      totalCommissions += u.commissionTotal;
+    }
+
+    return {
+      runId: args.runId,
+      users: byUser,
+      totalUsers: Object.keys(byUser).length,
+      totalEntries: entries.length,
+      grandTotal,
+      totalCommissions,
+    };
+  },
+});

package/convex/ledger/entries.ts

@@ -0,0 +1,314 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+import { ledgerEntryType, sourceType } from "../schema";
+
+/**
+ * CRUD per le righe del ledger compensi — entità CORE del sistema.
+ *
+ * Da analisi.md:
+ * "Il sistema NON salva solo totali.
+ *  Ogni mese per medico viene costruito un ledger di righe."
+ *
+ * "Questo ledger è la fonte di verità per: prospetto, fattura, audit, storico"
+ *
+ * Rimborsi e rettifiche sono normali righe del ledger con isManual=true,
+ * categoria e motivazione nel metadata.
+ *
+ * Le righe calcolate hanno isManual=false e referenziano planId/ruleId.
+ */
+
+/**
+ * Verifica che il run esista e sia in uno stato che ammette scritture.
+ * Blocca: closed (immutabile) e approved (pre-chiusura, no modifiche).
+ */
+async function assertRunWritableForLedger(
+  ctx: { db: { get: (id: any) => Promise<any> } },
+  runId: any,
+): Promise<void> {
+  const run = await ctx.db.get(runId);
+  if (!run) throw new Error("Run non trovato");
+  if (run.status === "closed") {
+    throw new Error(
+      "Impossibile modificare righe di un run chiuso. " +
+        "I dati di un run chiuso sono congelati.",
+    );
+  }
+  if (run.status === "approved") {
+    throw new Error(
+      "Impossibile modificare righe di un run approvato. " +
+        "Riportare il run in stato precedente prima di modificare.",
+    );
+  }
+}
+
+export const create = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+    clinicId: v.string(),
+    type: ledgerEntryType,
+    sourceType: sourceType,
+    sourceId: v.optional(v.string()),
+    planId: v.optional(v.id("commissionPlans")),
+    ruleId: v.optional(v.id("commissionRules")),
+    description: v.string(),
+    amount: v.number(),
+    quantity: v.optional(v.number()),
+    unitAmount: v.optional(v.number()),
+    isManual: v.boolean(),
+    effectiveDate: v.number(),
+    period: v.string(),
+    metadata: v.optional(v.any()),
+    createdBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await assertRunWritableForLedger(ctx, args.runId);
+
+    const { createdBy, ...entryData } = args;
+
+    const entryId = await ctx.db.insert("ledgerEntries", {
+      ...entryData,
+      createdBy,
+      createdAt: Date.now(),
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "ledgerEntries",
+      entityId: entryId,
+      action: "created",
+      userId: createdBy,
+      payload: {
+        type: args.type,
+        amount: args.amount,
+        isManual: args.isManual,
+      },
+      createdAt: Date.now(),
+    });
+
+    return entryId;
+  },
+});
+
+/**
+ * Inserimento batch — usato dall'orchestratore per scrivere
+ * molte righe calcolate in un'unica mutation.
+ */
+export const createBatch = mutation({
+  args: {
+    entries: v.array(
+      v.object({
+        runId: v.id("compensationRuns"),
+        userId: v.string(),
+        clinicId: v.string(),
+        type: ledgerEntryType,
+        sourceType: sourceType,
+        sourceId: v.optional(v.string()),
+        planId: v.optional(v.id("commissionPlans")),
+        ruleId: v.optional(v.id("commissionRules")),
+        description: v.string(),
+        amount: v.number(),
+        quantity: v.optional(v.number()),
+        unitAmount: v.optional(v.number()),
+        isManual: v.boolean(),
+        effectiveDate: v.number(),
+        period: v.string(),
+        metadata: v.optional(v.any()),
+        createdBy: v.string(),
+      }),
+    ),
+  },
+  handler: async (ctx, args) => {
+    if (args.entries.length > 0) {
+      await assertRunWritableForLedger(ctx, args.entries[0].runId);
+    }
+
+    const now = Date.now();
+    const ids: string[] = [];
+
+    for (const entry of args.entries) {
+      const { createdBy, ...entryData } = entry;
+      const id = await ctx.db.insert("ledgerEntries", {
+        ...entryData,
+        createdBy,
+        createdAt: now,
+      });
+      ids.push(id);
+    }
+
+    return ids;
+  },
+});
+
+/**
+ * Cancella tutte le righe NON manuali di un run.
+ * Usato prima del ricalcolo per rigenerare le righe calcolate
+ * senza perdere rimborsi/rettifiche inseriti manualmente.
+ */
+export const deleteCalculatedByRun = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await assertRunWritableForLedger(ctx, args.runId);
+
+    const entries = await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    let count = 0;
+    for (const entry of entries) {
+      if (!entry.isManual) {
+        await ctx.db.delete(entry._id);
+        count++;
+      }
+    }
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "compensationRuns",
+      entityId: args.runId,
+      action: "calculated_entries_cleared",
+      userId: args.userId,
+      payload: { deletedCount: count },
+      createdAt: Date.now(),
+    });
+
+    return { deletedCount: count };
+  },
+});
+
+export const listByRun = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+  },
+});
+
+export const listByRunAndUser = query({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run_user", (q) =>
+        q.eq("runId", args.runId).eq("userId", args.userId),
+      )
+      .collect();
+  },
+});
+
+export const listByRunUserClinic = query({
+  args: {
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+    clinicId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run_user_clinic", (q) =>
+        q
+          .eq("runId", args.runId)
+          .eq("userId", args.userId)
+          .eq("clinicId", args.clinicId),
+      )
+      .collect();
+  },
+});
+
+export const listByRunAndType = query({
+  args: {
+    runId: v.id("compensationRuns"),
+    type: ledgerEntryType,
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_run_type", (q) =>
+        q.eq("runId", args.runId).eq("type", args.type),
+      )
+      .collect();
+  },
+});
+
+export const listByPeriodAndUser = query({
+  args: {
+    period: v.string(),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ledgerEntries")
+      .withIndex("by_period_user", (q) =>
+        q.eq("period", args.period).eq("userId", args.userId),
+      )
+      .collect();
+  },
+});
+
+export const update = mutation({
+  args: {
+    entryId: v.id("ledgerEntries"),
+    description: v.optional(v.string()),
+    amount: v.optional(v.number()),
+    metadata: v.optional(v.any()),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const entry = await ctx.db.get(args.entryId);
+    if (!entry) throw new Error("Entry non trovata");
+
+    await assertRunWritableForLedger(ctx, entry.runId);
+
+    const { entryId, userId, ...fields } = args;
+    const patch: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(fields)) {
+      if (val !== undefined) patch[k] = val;
+    }
+
+    await ctx.db.patch(entryId, patch);
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "ledgerEntries",
+      entityId: entryId,
+      action: "updated",
+      userId,
+      payload: patch,
+      createdAt: Date.now(),
+    });
+  },
+});
+
+export const remove = mutation({
+  args: {
+    entryId: v.id("ledgerEntries"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const entry = await ctx.db.get(args.entryId);
+    if (!entry) throw new Error("Entry non trovata");
+
+    await assertRunWritableForLedger(ctx, entry.runId);
+
+    await ctx.db.delete(args.entryId);
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "ledgerEntries",
+      entityId: args.entryId,
+      action: "deleted",
+      userId: args.userId,
+      payload: {
+        type: entry.type,
+        amount: entry.amount,
+        runId: entry.runId,
+      },
+      createdAt: Date.now(),
+    });
+  },
+});

package/convex/lib/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Tipi di dominio condivisi per il Componente Compensi Medici.
+ * Allineati con lo schema Convex e con analisi.md.
+ */
+
+// ── Piani provvigionali ──────────────────────────────────
+
+export type PlanStatus = "draft" | "active" | "archived";
+
+export type RuleType = "percentage" | "fixed" | "token" | "combined";
+
+export type RuleOutputType = "commission" | "fixed" | "bonus";
+
+// ── Workflow mese ────────────────────────────────────────
+
+export type RunStatus =
+  | "draft"
+  | "calculated"
+  | "reviewing"
+  | "approved"
+  | "closed";
+
+export const VALID_TRANSITIONS: Record<RunStatus, RunStatus[]> = {
+  draft: ["calculated"],
+  calculated: ["reviewing", "draft"],
+  reviewing: ["approved", "calculated"],
+  approved: ["closed", "reviewing"],
+  closed: [],
+};
+
+export type ScopeType = "global" | "users" | "clinics" | "user_clinic_pairs";
+
+export type CalculationMode = "manual" | "scheduled" | "reopen";
+
+// ── Ledger ───────────────────────────────────────────────
+
+export type LedgerEntryType =
+  | "production"
+  | "storno"
+  | "commission"
+  | "fixed"
+  | "bonus"
+  | "reimbursement"
+  | "adjustment";
+
+export type SourceType = "care_plan_row" | "storno" | "manual" | "system";
+
+// ── Commissioni fisse ────────────────────────────────────
+
+export type FixedCommissionBehavior =
+  | "minimum_guaranteed"
+  | "additive"
+  | "substitutive"
+  | "substitutive_no_wdays";
+
+// ── Scope commissioni ────────────────────────────────────
+
+export type CommissionScope =
+  | "completed_rows"
+  | "confirmed_care_plan"
+  | "fixed";
+
+// ── Documenti ────────────────────────────────────────────
+
+export type InvoiceStatus = "draft" | "ready" | "sent" | "cancelled";
+
+export type OutsideCompanyType = "DS" | "Est" | "Est_forfettari" | "None";
+
+// ── Categorie ────────────────────────────────────────────
+
+export type CategoryKind = "reimbursement" | "adjustment";
+
+// ── Anomalie ─────────────────────────────────────────────
+
+export type IssueSeverity = "error" | "warning" | "info";
+
+export type IssueType =
+  | "no_active_plan"
+  | "no_matching_rule"
+  | "no_tax_profile"
+  | "multiple_tax_profiles"
+  | "inactive_tax_profile"
+  | "fiscal_anomaly"
+  | "missing_invoices";
+
+// ── Formato periodo ──────────────────────────────────────
+
+/** Formato: YYYY-MM */
+export type Period = string;
+
+// ── Production entry estesa ──────────────────────────────
+
+export interface ExtendedProductionData {
+  netPrice: number;
+  listPrice: number;
+  labCost: number;
+  labPrice: number;
+  cprPercentage: number;
+  companyId?: string;
+  carePlanTypeId?: number;
+  isInsurance: boolean;
+  conventionName?: string;
+  serviceCategoryName?: string;
+  isFirstPhase: boolean;
+  refactorRowId?: string;
+  refactorCalculated?: number;
+  refactorCalculatedConfirmedCarePlan?: number;
+  listRowId?: string;
+  listId?: string;
+  listName?: string;
+  listEnabled?: boolean;
+  listRowEnabled?: boolean;
+  carePlanRowTypeId?: number;
+  isInvoiceable: boolean;
+  isInvoiceableAt?: number;
+  completedBy?: string;
+  doctorId?: string;
+  conventionId?: string;
+  sourceId?: string;
+  serviceRegistryId?: string;
+  serviceRegistryGroupId?: string;
+  serviceCategoryId?: string;
+  commissionProfileId?: string;
+  scope: CommissionScope;
+  invoiceVat?: number;
+}