@primocaredentgroup/compensi-medici-core 0.1.0

package/convex/schema.ts

@@ -0,0 +1,611 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+// ─────────────────────────────────────────────────────────
+// Validators riutilizzabili (esportati per le funzioni backend)
+// ─────────────────────────────────────────────────────────
+
+export const planStatus = v.union(
+  v.literal("draft"),
+  v.literal("active"),
+  v.literal("archived"),
+);
+
+export const ruleType = v.union(
+  v.literal("percentage"),
+  v.literal("fixed"),
+  v.literal("token"),
+  v.literal("combined"),
+);
+
+export const ruleOutputType = v.union(
+  v.literal("commission"),
+  v.literal("fixed"),
+  v.literal("bonus"),
+);
+
+export const runStatus = v.union(
+  v.literal("draft"),
+  v.literal("calculated"),
+  v.literal("reviewing"),
+  v.literal("approved"),
+  v.literal("closed"),
+);
+
+export const scopeType = v.union(
+  v.literal("global"),
+  v.literal("users"),
+  v.literal("clinics"),
+  v.literal("user_clinic_pairs"),
+);
+
+export const calculationMode = v.union(
+  v.literal("manual"),
+  v.literal("scheduled"),
+  v.literal("reopen"),
+);
+
+export const ledgerEntryType = v.union(
+  v.literal("production"),
+  v.literal("storno"),
+  v.literal("commission"),
+  v.literal("fixed"),
+  v.literal("bonus"),
+  v.literal("reimbursement"),
+  v.literal("adjustment"),
+);
+
+export const sourceType = v.union(
+  v.literal("care_plan_row"),
+  v.literal("storno"),
+  v.literal("manual"),
+  v.literal("system"),
+);
+
+export const invoiceStatus = v.union(
+  v.literal("draft"),
+  v.literal("ready"),
+  v.literal("sent"),
+  v.literal("cancelled"),
+);
+
+export const categoryKind = v.union(
+  v.literal("reimbursement"),
+  v.literal("adjustment"),
+);
+
+export const issueSeverity = v.union(
+  v.literal("error"),
+  v.literal("warning"),
+  v.literal("info"),
+);
+
+export const issueType = v.union(
+  v.literal("no_active_plan"),
+  v.literal("no_matching_rule"),
+  v.literal("no_tax_profile"),
+  v.literal("multiple_tax_profiles"),
+  v.literal("inactive_tax_profile"),
+  v.literal("fiscal_anomaly"),
+  v.literal("missing_invoices"),
+);
+
+// ─────────────────────────────────────────────────────────
+// Schema
+// ─────────────────────────────────────────────────────────
+
+export default defineSchema({
+  // ── CONFIG ──────────────────────────────────────────────
+
+  /**
+   * Template di piani provvigionali.
+   * Da analisi.md: "basato su template", "importabile da CSV/Excel".
+   * I template servono come modello per creare nuovi piani velocemente.
+   */
+  commissionPlanTemplates: defineTable({
+    code: v.string(),
+    name: v.string(),
+    description: v.optional(v.string()),
+    /** Struttura di regole predefinite incluse nel template */
+    defaultRules: v.optional(v.any()),
+    isActive: v.boolean(),
+    createdBy: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_code", ["code"])
+    .index("by_active", ["isActive"]),
+
+  /**
+   * Piano provvigionale associato a un medico.
+   * Da analisi.md: "ogni piano è associato a un medico,
+   * può variare per clinica, categoria, prestazione, convenzione".
+   *
+   * Ciclo di vita: draft → active → archived.
+   * Validità temporale tramite effectiveFrom / effectiveTo.
+   */
+  commissionPlans: defineTable({
+    userId: v.string(),
+    code: v.string(),
+    name: v.string(),
+    description: v.optional(v.string()),
+    status: planStatus,
+    effectiveFrom: v.number(),
+    effectiveTo: v.optional(v.number()),
+    templateId: v.optional(v.id("commissionPlanTemplates")),
+    notes: v.optional(v.string()),
+    createdBy: v.string(),
+    createdAt: v.number(),
+    updatedBy: v.string(),
+    updatedAt: v.number(),
+  })
+    .index("by_user", ["userId"])
+    .index("by_user_status", ["userId", "status"])
+    .index("by_code", ["code"])
+    .index("by_status", ["status"]),
+
+  /**
+   * Regola di calcolo all'interno di un piano.
+   * Struttura logica da analisi.md:
+   *   1. Matching (conditions) — quando si applica
+   *   2. Formula — percentuale / fisso / gettone / combinazioni
+   *   3. Trattamenti economici — deduzioni, esclusioni, moltiplicatori
+   *
+   * conditions e formula restano JSON per flessibilità massima,
+   * ma i campi espliciti (ruleType, outputType, ecc.) danno
+   * semantica leggibile senza dover ispezionare il JSON.
+   */
+  commissionRules: defineTable({
+    planId: v.id("commissionPlans"),
+    name: v.string(),
+    ruleType: ruleType,
+    priority: v.number(),
+    isActive: v.boolean(),
+    /** Tipo di riga ledger prodotta dall'applicazione di questa regola */
+    outputType: ruleOutputType,
+    /** Etichetta leggibile che appare nel prospetto / spiegazione */
+    explanationLabel: v.string(),
+    conditions: v.any(),
+    formula: v.any(),
+    validFrom: v.optional(v.number()),
+    validTo: v.optional(v.number()),
+    createdBy: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_plan", ["planId", "priority"])
+    .index("by_plan_active", ["planId", "isActive"]),
+
+  /**
+   * Categorie per rimborsi e rettifiche — configurabili da DB.
+   * Da analisi.md: rimborsi e rettifiche hanno "categoria, importo,
+   * segno (+/-), autore, motivazione".
+   * Le categorie sono entità a sé, non costanti hardcoded.
+   */
+  reimbursementCategories: defineTable({
+    code: v.string(),
+    label: v.string(),
+    description: v.optional(v.string()),
+    isActive: v.boolean(),
+    sortOrder: v.number(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_code", ["code"])
+    .index("by_active", ["isActive", "sortOrder"]),
+
+  adjustmentCategories: defineTable({
+    code: v.string(),
+    label: v.string(),
+    description: v.optional(v.string()),
+    isActive: v.boolean(),
+    sortOrder: v.number(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_code", ["code"])
+    .index("by_active", ["isActive", "sortOrder"]),
+
+  taxProfiles: defineTable({
+    code: v.string(),
+    name: v.string(),
+    description: v.optional(v.string()),
+    vatRatePercent: v.number(),
+    withholdingRatePercent: v.number(),
+    withholdingOnPercent: v.number(),
+    contributionRatePercent: v.number(),
+    contributionWithholding: v.boolean(),
+    contributionText: v.optional(v.string()),
+    stampDutyEnabled: v.boolean(),
+    stampDutyAmount: v.number(),
+    stampDutyThreshold: v.number(),
+    is104: v.boolean(),
+    isBolloCompreso: v.boolean(),
+    footerText: v.optional(v.string()),
+    additionalRules: v.optional(v.any()),
+    isActive: v.boolean(),
+    createdBy: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_code", ["code"])
+    .index("by_active", ["isActive"]),
+
+  /**
+   * Assegnazione profilo fiscale a un medico nel tempo.
+   * Un medico può cambiare regime fiscale; questa tabella
+   * traccia quale profilo è valido in quale periodo.
+   */
+  userTaxProfiles: defineTable({
+    userId: v.string(),
+    taxProfileId: v.id("taxProfiles"),
+    effectiveFrom: v.number(),
+    effectiveTo: v.optional(v.number()),
+    notes: v.optional(v.string()),
+    createdBy: v.string(),
+    createdAt: v.number(),
+  })
+    .index("by_user", ["userId"])
+    .index("by_user_effective", ["userId", "effectiveFrom"]),
+
+  // ── DEDUCTION RULES ─────────────────────────────────────
+
+  deductionRules: defineTable({
+    code: v.string(),
+    label: v.string(),
+    description: v.optional(v.string()),
+    conditions: v.object({
+      companyIds: v.optional(v.array(v.string())),
+      carePlanTypeIds: v.optional(v.array(v.number())),
+      isInsurance: v.optional(v.boolean()),
+      isSinistro: v.optional(v.boolean()),
+      percentageThreshold: v.optional(v.number()),
+      percentageAboveThreshold: v.optional(v.boolean()),
+      conventionNameContains: v.optional(v.string()),
+      serviceCategoryNames: v.optional(v.array(v.string())),
+    }),
+    deductionPercent: v.number(),
+    priority: v.number(),
+    isActive: v.boolean(),
+    createdBy: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_code", ["code"])
+    .index("by_active_priority", ["isActive", "priority"]),
+
+  // ── COMPANY MAPPINGS ───────────────────────────────────
+
+  companyMappings: defineTable({
+    fromCompanyId: v.string(),
+    toCompanyId: v.string(),
+    category: v.union(
+      v.literal("DS"),
+      v.literal("Est"),
+      v.literal("Est_forfettari"),
+    ),
+    isActive: v.boolean(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_category", ["category", "isActive"])
+    .index("by_from", ["fromCompanyId"]),
+
+  // ── GLOBAL SETTINGS ────────────────────────────────────
+
+  globalSettings: defineTable({
+    key: v.string(),
+    value: v.string(),
+    description: v.optional(v.string()),
+    updatedBy: v.optional(v.string()),
+    updatedAt: v.number(),
+  })
+    .index("by_key", ["key"]),
+
+  // ── FIXED COMMISSION TYPES ─────────────────────────────
+
+  fixedCommissionTypes: defineTable({
+    code: v.string(),
+    name: v.string(),
+    description: v.optional(v.string()),
+    behavior: v.union(
+      v.literal("minimum_guaranteed"),
+      v.literal("additive"),
+      v.literal("substitutive"),
+      v.literal("substitutive_no_wdays"),
+    ),
+    multipliedByWdays: v.boolean(),
+    isActive: v.boolean(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_code", ["code"])
+    .index("by_active", ["isActive"]),
+
+  // ── INVISALIGN CONFIG ──────────────────────────────────
+
+  invisalignConfig: defineTable({
+    listRowId: v.string(),
+    firstPhasePercentage: v.number(),
+    otherPhasesPercentage: v.number(),
+    firstPhaseMin: v.number(),
+    otherPhasesMin: v.number(),
+    isActive: v.boolean(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_listRowId", ["listRowId"])
+    .index("by_active", ["isActive"]),
+
+  invisalignMinUsers: defineTable({
+    userId: v.string(),
+    isActive: v.boolean(),
+    createdAt: v.number(),
+  })
+    .index("by_userId", ["userId"]),
+
+  // ── WORKFLOW ────────────────────────────────────────────
+
+  /**
+   * Run mensile — ciclo di calcolo compensi per un periodo.
+   * Da analisi.md:
+   *   - Mese aperto: sempre ricalcolabile, modificabile
+   *   - Mese chiuso: snapshot immutabile, riapertura crea nuova versione
+   *
+   * Shadow mode (Fase 2 migrazione):
+   *   "Convex in shadow mode: stesso input, stessi mesi, nessun impatto operativo"
+   *
+   * scopeType + scopePayload definiscono il perimetro del run:
+   * può essere globale o ristretto a specifici medici/cliniche.
+   */
+  compensationRuns: defineTable({
+    period: v.string(),
+    status: runStatus,
+    version: v.number(),
+    isShadowRun: v.boolean(),
+    basedOnRunId: v.optional(v.id("compensationRuns")),
+    scopeType: scopeType,
+    scopePayload: v.optional(v.any()),
+    calculationMode: calculationMode,
+    triggeredBy: v.string(),
+    notes: v.optional(v.string()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+    closedAt: v.optional(v.number()),
+    closedBy: v.optional(v.string()),
+    /**
+     * Snapshot dei totali al momento della chiusura.
+     * Da analisi.md: "snapshot immutabile" alla chiusura del mese.
+     * Garantisce accesso rapido ai dati ufficiali senza ricalcolo.
+     */
+    closureSummary: v.optional(v.any()),
+  })
+    .index("by_period", ["period"])
+    .index("by_period_version", ["period", "version"])
+    .index("by_status", ["status"])
+    .index("by_shadow", ["isShadowRun", "period"]),
+
+  // ── LEDGER ─────────────────────────────────────────────
+
+  /**
+   * Riga del ledger compensi — CORE del sistema.
+   * Da analisi.md: "il sistema NON salva solo totali.
+   * Ogni mese per medico viene costruito un ledger di righe."
+   *
+   * Fonte di verità per: prospetto, fattura, audit, storico.
+   *
+   * Campi espliciti per gli aspetti chiave del dominio:
+   * - sourceType + sourceId: da dove arriva la riga
+   * - planId + ruleId: quale piano/regola l'ha generata (se calcolata)
+   * - quantity + unitAmount: dettaglio importo (es. 3 prestazioni × 50€)
+   * - isManual: distingue righe inserite a mano da quelle calcolate
+   * - effectiveDate: data di competenza economica
+   * - period: periodo di riferimento (ridondante col run, ma utile per query dirette)
+   *
+   * metadata resta per informazioni accessorie non strutturate.
+   */
+  ledgerEntries: defineTable({
+    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")),
+    scope: v.optional(v.string()),
+    fixedCommissionTypeId: v.optional(v.id("fixedCommissionTypes")),
+    companyId: v.optional(v.string()),
+    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(),
+    createdAt: v.number(),
+  })
+    .index("by_run", ["runId"])
+    .index("by_run_user", ["runId", "userId"])
+    .index("by_run_user_clinic", ["runId", "userId", "clinicId"])
+    .index("by_run_type", ["runId", "type"])
+    .index("by_period_user", ["period", "userId"])
+    .index("by_source", ["sourceType", "sourceId"]),
+
+  // ── DOCUMENTS ──────────────────────────────────────────
+
+  /**
+   * Bozza fattura generata per un medico in un run.
+   * Da analisi.md: "generazione bozza fattura".
+   *
+   * Campi fiscali predisposti per il futuro motore fiscale.
+   * Da analisi.md: "il piano dice quanto guadagni,
+   * il profilo fiscale dice come lo fatturi".
+   * Gestisce: IVA, ritenuta, contributi, bollo.
+   */
+  draftInvoices: defineTable({
+    runId: v.id("compensationRuns"),
+    userId: v.string(),
+    clinicId: v.string(),
+    companyId: v.optional(v.string()),
+    period: v.string(),
+    status: invoiceStatus,
+    isAutoGenerated: v.boolean(),
+    outsideCompanyType: v.optional(v.string()),
+    isCompanyGrouped: v.boolean(),
+    taxProfileId: v.optional(v.id("taxProfiles")),
+    taxProfileSnapshot: v.optional(v.any()),
+    lineItemCount: v.number(),
+    netPrice: v.number(),
+    subtotal: v.number(),
+    vatRate: v.number(),
+    vatAmount: v.number(),
+    withholdingRate: v.number(),
+    withholdingOnRate: v.number(),
+    withholdingAmount: v.number(),
+    contributionRate: v.number(),
+    contributionAmount: v.number(),
+    stampDutyAmount: v.number(),
+    total: v.number(),
+    netToPay: v.number(),
+    commissionIds: v.optional(v.array(v.string())),
+    cprIds: v.optional(v.array(v.string())),
+    notes: v.optional(v.string()),
+    createdBy: v.string(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_run", ["runId"])
+    .index("by_run_user", ["runId", "userId"])
+    .index("by_run_user_clinic", ["runId", "userId", "clinicId"])
+    .index("by_period_user", ["period", "userId"])
+    .index("by_status", ["status"]),
+
+  // ── EXPLAINABILITY ─────────────────────────────────────
+
+  /**
+   * Applicazione di una regola a una riga del ledger.
+   * Tabella dedicata per la spiegabilità del calcolo.
+   *
+   * Da analisi.md:
+   * - "spiegazione delle regole applicate"
+   * - "tutto spiegabile"
+   * - "differenze spiegabili" (criterio di successo)
+   *
+   * Salva per ogni riga calcolata:
+   * - quale piano è stato usato
+   * - quale regola è stata applicata
+   * - le condizioni che hanno matchato
+   * - il risultato della formula
+   * - una spiegazione leggibile
+   */
+  ruleApplications: defineTable({
+    runId: v.id("compensationRuns"),
+    /** Riga sorgente di produzione/storno che ha innescato il calcolo */
+    sourceLedgerEntryId: v.id("ledgerEntries"),
+    /** Riga compenso generata dal motore */
+    generatedLedgerEntryId: v.id("ledgerEntries"),
+    planId: v.id("commissionPlans"),
+    ruleId: v.id("commissionRules"),
+    /** Condizioni che hanno matchato (snapshot delle conditions della regola) */
+    matchedConditions: v.any(),
+    /** Snapshot della formula applicata */
+    formulaSnapshot: v.any(),
+    /** Input della formula: base di calcolo e parametri */
+    formulaInput: v.any(),
+    /** Output della formula: risultato e dettagli */
+    formulaOutput: v.any(),
+    resultAmount: v.number(),
+    /** Etichetta leggibile da analisi.md: "spiegazione delle regole applicate" */
+    explanationLabel: v.string(),
+    createdAt: v.number(),
+  })
+    .index("by_run", ["runId"])
+    .index("by_source_entry", ["sourceLedgerEntryId"])
+    .index("by_generated_entry", ["generatedLedgerEntryId"])
+    .index("by_run_rule", ["runId", "ruleId"]),
+
+  // ── ISSUES ─────────────────────────────────────────────
+
+  /**
+   * Anomalie strutturate di un run — tracciamento interrogabile.
+   *
+   * A differenza degli auditLogs (immutabili, append-only),
+   * le runIssues vengono rigenerate ad ogni ciclo di verifica
+   * e rappresentano lo stato corrente delle anomalie del run.
+   *
+   * Tipi di anomalie:
+   * - no_active_plan: medico senza piano provvigionale attivo
+   * - no_matching_rule: riga produzione senza regola matchata
+   * - no_tax_profile: medico senza profilo fiscale valido
+   * - multiple_tax_profiles: ambiguità profilo fiscale
+   * - inactive_tax_profile: profilo fiscale non attivo
+   * - fiscal_anomaly: importi sospetti nella bozza fattura
+   * - missing_invoices: medici con commissioni ma senza bozza
+   */
+  runIssues: defineTable({
+    runId: v.id("compensationRuns"),
+    issueType: issueType,
+    severity: issueSeverity,
+    userId: v.optional(v.string()),
+    clinicId: v.optional(v.string()),
+    message: v.string(),
+    details: v.optional(v.any()),
+    createdAt: v.number(),
+  })
+    .index("by_run", ["runId"])
+    .index("by_run_severity", ["runId", "severity"])
+    .index("by_run_type", ["runId", "issueType"]),
+
+  // ── PENDING COMPLETIONS ──────────────────────────────────
+
+  /**
+   * Coda di eseguiti in attesa di elaborazione.
+   *
+   * Ogni volta che una prestazione di un PdC viene completata,
+   * PrimoUpCore registra qui l'evento. Un cron orario raccoglie
+   * tutti i pending e lancia il calcolo batch tramite il Python Worker.
+   *
+   * Dopo l'elaborazione, le righe vengono marcate come processed.
+   */
+  pendingCompletions: defineTable({
+    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(),
+    isProcessed: v.boolean(),
+    processedAt: v.optional(v.number()),
+    processedRunId: v.optional(v.string()),
+    createdAt: v.number(),
+  })
+    .index("by_processed", ["isProcessed"])
+    .index("by_period_processed", ["period", "isProcessed"])
+    .index("by_cpr_id", ["carePlanRowId"]),
+
+  // ── AUDIT ──────────────────────────────────────────────
+
+  /**
+   * Log di audit — tracciamento completo delle operazioni.
+   * Da analisi.md: "audit base (chi, cosa, quando)" e "tutto spiegabile".
+   * Immutabili — una volta scritti non vengono mai modificati.
+   */
+  auditLogs: defineTable({
+    entityType: v.string(),
+    entityId: v.string(),
+    action: v.string(),
+    userId: v.string(),
+    payload: v.optional(v.any()),
+    createdAt: v.number(),
+  })
+    .index("by_entity", ["entityType", "entityId"])
+    .index("by_user", ["userId"])
+    .index("by_action", ["action"]),
+});

package/convex/seedHelpers.ts

@@ -0,0 +1,41 @@
+import { mutation } from "./_generated/server";
+
+const COMPONENT_TABLES = [
+  "pendingCompletions",
+  "runIssues",
+  "ruleApplications",
+  "draftInvoices",
+  "ledgerEntries",
+  "compensationRuns",
+  "commissionRules",
+  "commissionPlans",
+  "commissionPlanTemplates",
+  "userTaxProfiles",
+  "taxProfiles",
+  "fixedCommissionTypes",
+  "deductionRules",
+  "companyMappings",
+  "reimbursementCategories",
+  "adjustmentCategories",
+  "invisalignConfig",
+  "invisalignMinUsers",
+  "globalSettings",
+  "auditLogs",
+] as const;
+
+export const clearAll = mutation({
+  args: {},
+  handler: async (ctx) => {
+    let totalDeleted = 0;
+
+    for (const table of COMPONENT_TABLES) {
+      const rows = await ctx.db.query(table).collect();
+      for (const row of rows) {
+        await ctx.db.delete(row._id);
+        totalDeleted++;
+      }
+    }
+
+    return { deleted: totalDeleted };
+  },
+});