@primocaredentgroup/compensi-medici-core 0.1.0

package/convex/calculation/ruleApplications.ts

@@ -0,0 +1,121 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+
+/**
+ * CRUD e query per ruleApplications — spiegabilità del calcolo.
+ *
+ * Da analisi.md:
+ * - "spiegazione delle regole applicate"
+ * - "tutto spiegabile"
+ * - "differenze spiegabili" (criterio di successo)
+ * - Alla chiusura: "salvataggio delle regole applicate"
+ *
+ * Ogni ruleApplication collega:
+ * - sourceLedgerEntryId → riga di produzione/storno che ha innescato il calcolo
+ * - generatedLedgerEntryId → riga commission generata
+ * - planId, ruleId → configurazione usata
+ * - matchedConditions → snapshot delle condizioni che hanno matchato
+ * - formulaSnapshot → snapshot della formula applicata
+ * - formulaInput/Output → dettaglio del calcolo
+ * - explanationLabel → etichetta leggibile per HR/medici
+ *
+ * Le ruleApplications vengono scritte da commissions.ts (refreshCommissions).
+ * Le funzioni qui sotto servono per query e manutenzione.
+ */
+
+export const create = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+    sourceLedgerEntryId: v.id("ledgerEntries"),
+    generatedLedgerEntryId: v.id("ledgerEntries"),
+    planId: v.id("commissionPlans"),
+    ruleId: v.id("commissionRules"),
+    matchedConditions: v.any(),
+    formulaSnapshot: v.any(),
+    formulaInput: v.any(),
+    formulaOutput: v.any(),
+    resultAmount: v.number(),
+    explanationLabel: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("ruleApplications", {
+      ...args,
+      createdAt: Date.now(),
+    });
+  },
+});
+
+/** Tutte le ruleApplications per una riga sorgente (produzione/storno) */
+export const listBySourceEntry = query({
+  args: { sourceLedgerEntryId: v.id("ledgerEntries") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_source_entry", (q) =>
+        q.eq("sourceLedgerEntryId", args.sourceLedgerEntryId),
+      )
+      .collect();
+  },
+});
+
+/** Tutte le ruleApplications per una riga commission generata */
+export const listByGeneratedEntry = query({
+  args: { generatedLedgerEntryId: v.id("ledgerEntries") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_generated_entry", (q) =>
+        q.eq("generatedLedgerEntryId", args.generatedLedgerEntryId),
+      )
+      .collect();
+  },
+});
+
+/** Tutte le ruleApplications in un run */
+export const listByRun = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+  },
+});
+
+/** Applicazioni di una specifica regola in un run */
+export const listByRunAndRule = query({
+  args: {
+    runId: v.id("compensationRuns"),
+    ruleId: v.id("commissionRules"),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_run_rule", (q) =>
+        q.eq("runId", args.runId).eq("ruleId", args.ruleId),
+      )
+      .collect();
+  },
+});
+
+/**
+ * Cancella tutte le ruleApplications di un run.
+ * Usato dal refreshCommissions prima del ricalcolo.
+ */
+export const deleteByRun = mutation({
+  args: {
+    runId: v.id("compensationRuns"),
+  },
+  handler: async (ctx, args) => {
+    const applications = await ctx.db
+      .query("ruleApplications")
+      .withIndex("by_run", (q) => q.eq("runId", args.runId))
+      .collect();
+
+    for (const app of applications) {
+      await ctx.db.delete(app._id);
+    }
+
+    return { deletedCount: applications.length };
+  },
+});

package/convex/config/categories.ts

@@ -0,0 +1,114 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+
+/**
+ * Categorie rimborsi e rettifiche — gestite come entità DB.
+ * Da analisi.md: rimborsi e rettifiche hanno "categoria, importo,
+ * segno (+/-), autore, motivazione".
+ *
+ * Le categorie sono configurabili da UI, non hardcoded.
+ * Separate in due tabelle (reimbursementCategories, adjustmentCategories)
+ * per semantica chiara, ma con CRUD identico.
+ */
+
+// ── Reimbursement Categories ─────────────────────────────
+
+export const createReimbursementCategory = mutation({
+  args: {
+    code: v.string(),
+    label: v.string(),
+    description: v.optional(v.string()),
+    sortOrder: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    return await ctx.db.insert("reimbursementCategories", {
+      ...args,
+      isActive: true,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const listReimbursementCategories = query({
+  args: { activeOnly: v.optional(v.boolean()) },
+  handler: async (ctx, args) => {
+    if (args.activeOnly) {
+      return await ctx.db
+        .query("reimbursementCategories")
+        .withIndex("by_active", (q) => q.eq("isActive", true))
+        .collect();
+    }
+    return await ctx.db.query("reimbursementCategories").collect();
+  },
+});
+
+export const updateReimbursementCategory = mutation({
+  args: {
+    categoryId: v.id("reimbursementCategories"),
+    label: v.optional(v.string()),
+    description: v.optional(v.string()),
+    isActive: v.optional(v.boolean()),
+    sortOrder: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { categoryId, ...fields } = args;
+    const patch: Record<string, unknown> = { updatedAt: Date.now() };
+    for (const [k, val] of Object.entries(fields)) {
+      if (val !== undefined) patch[k] = val;
+    }
+    await ctx.db.patch(categoryId, patch);
+  },
+});
+
+// ── Adjustment Categories ────────────────────────────────
+
+export const createAdjustmentCategory = mutation({
+  args: {
+    code: v.string(),
+    label: v.string(),
+    description: v.optional(v.string()),
+    sortOrder: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    return await ctx.db.insert("adjustmentCategories", {
+      ...args,
+      isActive: true,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const listAdjustmentCategories = query({
+  args: { activeOnly: v.optional(v.boolean()) },
+  handler: async (ctx, args) => {
+    if (args.activeOnly) {
+      return await ctx.db
+        .query("adjustmentCategories")
+        .withIndex("by_active", (q) => q.eq("isActive", true))
+        .collect();
+    }
+    return await ctx.db.query("adjustmentCategories").collect();
+  },
+});
+
+export const updateAdjustmentCategory = mutation({
+  args: {
+    categoryId: v.id("adjustmentCategories"),
+    label: v.optional(v.string()),
+    description: v.optional(v.string()),
+    isActive: v.optional(v.boolean()),
+    sortOrder: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { categoryId, ...fields } = args;
+    const patch: Record<string, unknown> = { updatedAt: Date.now() };
+    for (const [k, val] of Object.entries(fields)) {
+      if (val !== undefined) patch[k] = val;
+    }
+    await ctx.db.patch(categoryId, patch);
+  },
+});

package/convex/config/commissionPlans.ts

@@ -0,0 +1,166 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+import { planStatus } from "../schema";
+
+/**
+ * Gestione piani provvigionali.
+ * Da analisi.md: "ogni piano è associato a un medico,
+ * può variare per clinica, categoria, prestazione, convenzione".
+ *
+ * Requisiti: nessun hardcoded, configurabile via UI,
+ * importabile da CSV/Excel, basato su template, spiegabile.
+ */
+
+export const create = mutation({
+  args: {
+    userId: v.string(),
+    code: v.string(),
+    name: v.string(),
+    description: v.optional(v.string()),
+    effectiveFrom: v.number(),
+    effectiveTo: v.optional(v.number()),
+    templateId: v.optional(v.id("commissionPlanTemplates")),
+    notes: v.optional(v.string()),
+    createdBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const { createdBy, ...fields } = args;
+
+    const planId = await ctx.db.insert("commissionPlans", {
+      ...fields,
+      status: "draft",
+      createdBy,
+      createdAt: now,
+      updatedBy: createdBy,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "commissionPlans",
+      entityId: planId,
+      action: "created",
+      userId: createdBy,
+      payload: { code: args.code, name: args.name, userId: args.userId },
+      createdAt: now,
+    });
+
+    return planId;
+  },
+});
+
+export const update = mutation({
+  args: {
+    planId: v.id("commissionPlans"),
+    name: v.optional(v.string()),
+    description: v.optional(v.string()),
+    effectiveFrom: v.optional(v.number()),
+    effectiveTo: v.optional(v.number()),
+    notes: v.optional(v.string()),
+    updatedBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const { planId, updatedBy, ...fields } = args;
+    const now = Date.now();
+
+    const patch: Record<string, unknown> = { updatedBy, updatedAt: now };
+    for (const [k, val] of Object.entries(fields)) {
+      if (val !== undefined) patch[k] = val;
+    }
+
+    await ctx.db.patch(planId, patch);
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "commissionPlans",
+      entityId: planId,
+      action: "updated",
+      userId: updatedBy,
+      payload: patch,
+      createdAt: now,
+    });
+  },
+});
+
+/** Cambia stato del piano: draft → active → archived */
+export const changeStatus = mutation({
+  args: {
+    planId: v.id("commissionPlans"),
+    newStatus: planStatus,
+    updatedBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const plan = await ctx.db.get(args.planId);
+    if (!plan) throw new Error("Piano non trovato");
+
+    const VALID: Record<string, string[]> = {
+      draft: ["active"],
+      active: ["archived", "draft"],
+      archived: ["draft"],
+    };
+
+    if (!VALID[plan.status]?.includes(args.newStatus)) {
+      throw new Error(
+        `Transizione piano non valida: ${plan.status} → ${args.newStatus}`,
+      );
+    }
+
+    const now = Date.now();
+    await ctx.db.patch(args.planId, {
+      status: args.newStatus,
+      updatedBy: args.updatedBy,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "commissionPlans",
+      entityId: args.planId,
+      action: "status_changed",
+      userId: args.updatedBy,
+      payload: { from: plan.status, to: args.newStatus },
+      createdAt: now,
+    });
+  },
+});
+
+export const get = query({
+  args: { planId: v.id("commissionPlans") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.planId);
+  },
+});
+
+export const listByUser = query({
+  args: {
+    userId: v.string(),
+    status: v.optional(planStatus),
+  },
+  handler: async (ctx, args) => {
+    if (args.status) {
+      return await ctx.db
+        .query("commissionPlans")
+        .withIndex("by_user_status", (q) =>
+          q.eq("userId", args.userId).eq("status", args.status!),
+        )
+        .collect();
+    }
+    return await ctx.db
+      .query("commissionPlans")
+      .withIndex("by_user", (q) => q.eq("userId", args.userId))
+      .collect();
+  },
+});
+
+export const listActive = query({
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("commissionPlans")
+      .withIndex("by_status", (q) => q.eq("status", "active"))
+      .collect();
+  },
+});
+
+export const listAll = query({
+  handler: async (ctx) => {
+    return await ctx.db.query("commissionPlans").collect();
+  },
+});

package/convex/config/commissionRules.ts

@@ -0,0 +1,154 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+import { ruleType, ruleOutputType } from "../schema";
+
+/**
+ * Gestione regole di calcolo all'interno di un piano provvigionale.
+ * Da analisi.md ogni regola ha:
+ *   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à,
+ * ma i campi espliciti (ruleType, outputType, explanationLabel)
+ * danno semantica leggibile al dominio.
+ */
+
+export const create = mutation({
+  args: {
+    planId: v.id("commissionPlans"),
+    name: v.string(),
+    ruleType: ruleType,
+    priority: v.number(),
+    outputType: ruleOutputType,
+    explanationLabel: v.string(),
+    conditions: v.any(),
+    formula: v.any(),
+    validFrom: v.optional(v.number()),
+    validTo: v.optional(v.number()),
+    createdBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const { createdBy, ...fields } = args;
+
+    const ruleId = await ctx.db.insert("commissionRules", {
+      ...fields,
+      isActive: true,
+      createdBy,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "commissionRules",
+      entityId: ruleId,
+      action: "created",
+      userId: createdBy,
+      payload: { planId: args.planId, name: args.name, ruleType: args.ruleType },
+      createdAt: now,
+    });
+
+    return ruleId;
+  },
+});
+
+export const update = mutation({
+  args: {
+    ruleId: v.id("commissionRules"),
+    name: v.optional(v.string()),
+    ruleType: v.optional(ruleType),
+    priority: v.optional(v.number()),
+    outputType: v.optional(ruleOutputType),
+    explanationLabel: v.optional(v.string()),
+    conditions: v.optional(v.any()),
+    formula: v.optional(v.any()),
+    validFrom: v.optional(v.number()),
+    validTo: v.optional(v.number()),
+    updatedBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const { ruleId, updatedBy, ...fields } = args;
+    const now = Date.now();
+
+    const patch: Record<string, unknown> = { updatedAt: now };
+    for (const [k, val] of Object.entries(fields)) {
+      if (val !== undefined) patch[k] = val;
+    }
+
+    await ctx.db.patch(ruleId, patch);
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "commissionRules",
+      entityId: ruleId,
+      action: "updated",
+      userId: updatedBy,
+      payload: patch,
+      createdAt: now,
+    });
+  },
+});
+
+export const setActive = mutation({
+  args: {
+    ruleId: v.id("commissionRules"),
+    isActive: v.boolean(),
+    updatedBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    await ctx.db.patch(args.ruleId, {
+      isActive: args.isActive,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "commissionRules",
+      entityId: args.ruleId,
+      action: args.isActive ? "activated" : "deactivated",
+      userId: args.updatedBy,
+      createdAt: now,
+    });
+  },
+});
+
+export const remove = mutation({
+  args: {
+    ruleId: v.id("commissionRules"),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const rule = await ctx.db.get(args.ruleId);
+    await ctx.db.delete(args.ruleId);
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "commissionRules",
+      entityId: args.ruleId,
+      action: "deleted",
+      userId: args.userId,
+      payload: rule ? { planId: rule.planId, name: rule.name } : undefined,
+      createdAt: Date.now(),
+    });
+  },
+});
+
+export const listByPlan = query({
+  args: {
+    planId: v.id("commissionPlans"),
+    activeOnly: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    if (args.activeOnly) {
+      return await ctx.db
+        .query("commissionRules")
+        .withIndex("by_plan_active", (q) =>
+          q.eq("planId", args.planId).eq("isActive", true),
+        )
+        .collect();
+    }
+    return await ctx.db
+      .query("commissionRules")
+      .withIndex("by_plan", (q) => q.eq("planId", args.planId))
+      .collect();
+  },
+});

package/convex/config/companyMappings.ts

@@ -0,0 +1,77 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+
+const categoryValidator = v.union(
+  v.literal("DS"),
+  v.literal("Est"),
+  v.literal("Est_forfettari"),
+);
+
+export const create = mutation({
+  args: {
+    fromCompanyId: v.string(),
+    toCompanyId: v.string(),
+    category: categoryValidator,
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    return await ctx.db.insert("companyMappings", {
+      ...args,
+      isActive: true,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const update = mutation({
+  args: {
+    mappingId: v.id("companyMappings"),
+    toCompanyId: v.optional(v.string()),
+    category: v.optional(categoryValidator),
+    isActive: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const { mappingId, ...fields } = args;
+    const patch: Record<string, unknown> = { updatedAt: Date.now() };
+    for (const [k, val] of Object.entries(fields)) {
+      if (val !== undefined) patch[k] = val;
+    }
+    await ctx.db.patch(mappingId, patch);
+  },
+});
+
+export const get = query({
+  args: { mappingId: v.id("companyMappings") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.mappingId);
+  },
+});
+
+export const listByCategory = query({
+  args: { category: categoryValidator },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("companyMappings")
+      .withIndex("by_category", (q) =>
+        q.eq("category", args.category).eq("isActive", true),
+      )
+      .collect();
+  },
+});
+
+export const listAll = query({
+  handler: async (ctx) => {
+    return await ctx.db.query("companyMappings").collect();
+  },
+});
+
+export const getByFromCompany = query({
+  args: { fromCompanyId: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("companyMappings")
+      .withIndex("by_from", (q) => q.eq("fromCompanyId", args.fromCompanyId))
+      .collect();
+  },
+});