@primocaredentgroup/compensi-medici-core 0.1.0

package/convex/documents/draftInvoices.ts

@@ -0,0 +1,164 @@
+import { v } from "convex/values";
+import { mutation, query } from "../_generated/server";
+import { invoiceStatus } from "../schema";
+
+/**
+ * CRUD base per le bozze fattura.
+ * Da analisi.md: "generazione bozza fattura" come output del componente.
+ *
+ * Separato dalla pipeline di generazione (invoiceGeneration.ts) che
+ * gestisce il refresh idempotente a partire dalle commission entries.
+ *
+ * Da analisi.md: "il piano dice quanto guadagni,
+ * il profilo fiscale dice come lo fatturi".
+ *
+ * Immutabilità: run closed/approved non ammettono modifiche alle bozze.
+ */
+
+async function assertRunWritableForInvoices(
+  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 bozze di un run chiuso. " +
+        "I documenti di un run chiuso sono congelati.",
+    );
+  }
+  if (run.status === "approved") {
+    throw new Error(
+      "Impossibile modificare bozze 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(),
+    period: v.string(),
+    isAutoGenerated: v.boolean(),
+    taxProfileId: v.optional(v.id("taxProfiles")),
+    taxProfileSnapshot: v.optional(v.any()),
+    lineItemCount: v.number(),
+    subtotal: v.number(),
+    vatAmount: v.number(),
+    withholdingAmount: v.number(),
+    contributionAmount: v.number(),
+    stampDutyAmount: v.number(),
+    total: v.number(),
+    netToPay: v.number(),
+    notes: v.optional(v.string()),
+    createdBy: v.string(),
+  },
+  handler: async (ctx, args) => {
+    await assertRunWritableForInvoices(ctx, args.runId);
+
+    const now = Date.now();
+    const { createdBy, ...fields } = args;
+
+    const invoiceId = await ctx.db.insert("draftInvoices", {
+      ...fields,
+      status: "draft",
+      createdBy,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "draftInvoices",
+      entityId: invoiceId,
+      action: "created",
+      userId: createdBy,
+      payload: {
+        total: args.total,
+        netToPay: args.netToPay,
+        clinicId: args.clinicId,
+        isAutoGenerated: args.isAutoGenerated,
+      },
+      createdAt: now,
+    });
+
+    return invoiceId;
+  },
+});
+
+export const updateStatus = mutation({
+  args: {
+    invoiceId: v.id("draftInvoices"),
+    newStatus: invoiceStatus,
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const invoice = await ctx.db.get(args.invoiceId);
+    if (!invoice) throw new Error("Fattura non trovata");
+
+    await assertRunWritableForInvoices(ctx, invoice.runId);
+
+    const now = Date.now();
+    await ctx.db.patch(args.invoiceId, {
+      status: args.newStatus,
+      updatedAt: now,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      entityType: "draftInvoices",
+      entityId: args.invoiceId,
+      action: "status_changed",
+      userId: args.userId,
+      payload: { from: invoice.status, to: args.newStatus },
+      createdAt: now,
+    });
+  },
+});
+
+export const get = query({
+  args: { invoiceId: v.id("draftInvoices") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.invoiceId);
+  },
+});
+
+export const listByRun = query({
+  args: { runId: v.id("compensationRuns") },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("draftInvoices")
+      .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("draftInvoices")
+      .withIndex("by_run_user", (q) =>
+        q.eq("runId", args.runId).eq("userId", args.userId),
+      )
+      .collect();
+  },
+});
+
+export const listByPeriodAndUser = query({
+  args: {
+    period: v.string(),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("draftInvoices")
+      .withIndex("by_period_user", (q) =>
+        q.eq("period", args.period).eq("userId", args.userId),
+      )
+      .collect();
+  },
+});

package/convex/documents/invoiceEngine.ts

@@ -0,0 +1,468 @@
+/**
+ * Motore fiscale avanzato — traduzione da create_commission_invoices.py
+ *
+ * Formula dal Python:
+ *
+ * Per profili con "(bollo compreso nei calcoli)":
+ *   1. Se stamp_duty e calculated > soglia e isCompanyGrouped:
+ *      calculated += costo_bollo (il bollo viene aggiunto alla base)
+ *   2. contribution = calculated * contribution_percentage / 100
+ *   3. withholding = withholding% * withholding_on% * (calculated + contribution se "(104%)")
+ *   4. total = calculated + vat_amount + contribution
+ *   5. netToPay = total - withholding
+ *
+ * Per profili normali:
+ *   1. contribution = calculated * contribution_percentage / 100
+ *   2. withholding = withholding% * withholding_on% * (calculated + contribution se "(104%)")
+ *   3. total = calculated + vat_amount + contribution
+ *   4. netToPay = total - withholding
+ *   5. Se stamp_duty e total > soglia e isCompanyGrouped:
+ *      total += costo_bollo, netToPay += costo_bollo
+ *
+ * IVA per tipo società:
+ *   DS = 22%, Est forfettari = 0%, Est = IVA dalla fattura, default = profilo
+ *
+ * Company mapping:
+ *   Le commissioni per DS, Est, Est_forfettari vengono rimappate su società diverse.
+ */
+
+import type { Id } from "../_generated/dataModel";
+import type { OutsideCompanyType } from "../lib/types";
+
+// ── Tipi ─────────────────────────────────────────────────
+
+export interface ResolvedTaxProfile {
+  _id: Id<"taxProfiles">;
+  code: string;
+  name: string;
+  vatRatePercent: number;
+  withholdingRatePercent: number;
+  withholdingOnPercent: number;
+  contributionRatePercent: number;
+  contributionWithholding: boolean;
+  contributionText?: string;
+  stampDutyEnabled: boolean;
+  stampDutyAmount: number;
+  stampDutyThreshold: number;
+  is104: boolean;
+  isBolloCompreso: boolean;
+  footerText?: string;
+  additionalRules?: Record<string, unknown>;
+}
+
+export interface ResolvedUserTaxAssignment {
+  _id: Id<"userTaxProfiles">;
+  userId: string;
+  taxProfileId: Id<"taxProfiles">;
+  effectiveFrom: number;
+  effectiveTo?: number;
+}
+
+export interface TaxProfileSnapshot {
+  taxProfileId: string;
+  code: string;
+  name: string;
+  vatRatePercent: number;
+  withholdingRatePercent: number;
+  withholdingOnPercent: number;
+  contributionRatePercent: number;
+  contributionWithholding: boolean;
+  is104: boolean;
+  isBolloCompreso: boolean;
+  stampDutyEnabled: boolean;
+  stampDutyThreshold: number;
+}
+
+export interface CompanyMapping {
+  fromCompanyId: string;
+  toCompanyId: string;
+  category: "DS" | "Est" | "Est_forfettari";
+}
+
+export interface CommissionForInvoice {
+  id: string;
+  userId: string;
+  clinicId: string;
+  companyId: string;
+  period: string;
+  calculated: number;
+  netPrice: number;
+  scope: string;
+  fixedCommissionTypeId?: string;
+  carePlanTypeId?: number;
+  carePlanRowId?: string;
+  invoiceVat?: number;
+  taxProfileName: string;
+  isInvoiceable: boolean;
+}
+
+export interface FiscalCalculationResult {
+  subtotal: number;
+  netPrice: number;
+  contributionAmount: number;
+  vatRate: number;
+  vatAmount: number;
+  withholdingRate: number;
+  withholdingOnRate: number;
+  withholdingAmount: number;
+  stampDutyAmount: number;
+  total: number;
+  netToPay: number;
+}
+
+export interface AggregatedInvoiceGroup {
+  userId: string;
+  clinicId: string;
+  companyId: string;
+  period: string;
+  outsideCompanyType: OutsideCompanyType;
+  netPrice: number;
+  calculated: number;
+  lineItemCount: number;
+  commissionIds: string[];
+  cprIds: string[];
+  vatRate: number;
+  profile: ResolvedTaxProfile;
+}
+
+export interface DraftInvoiceData {
+  userId: string;
+  clinicId: string;
+  companyId: string;
+  period: string;
+  outsideCompanyType: OutsideCompanyType;
+  isCompanyGrouped: boolean;
+  taxProfileId: string;
+  taxProfileSnapshot: TaxProfileSnapshot;
+  lineItemCount: number;
+  fiscal: FiscalCalculationResult;
+  commissionIds: string[];
+  cprIds: string[];
+}
+
+export type TaxProfileResolution =
+  | { status: "found"; profile: ResolvedTaxProfile; assignment: ResolvedUserTaxAssignment }
+  | { status: "no_assignment"; userId: string }
+  | { status: "multiple_assignments"; userId: string; count: number }
+  | { status: "profile_not_found"; userId: string; taxProfileId: string }
+  | { status: "profile_inactive"; userId: string; profileCode: string };
+
+// ── 1. Risoluzione profilo fiscale ───────────────────────
+
+export function resolveUserTaxProfile(
+  assignments: ResolvedUserTaxAssignment[],
+  profiles: Map<string, ResolvedTaxProfile>,
+  userId: string,
+  period: string,
+): TaxProfileResolution {
+  const { periodStart, periodEnd } = parsePeriodBounds(period);
+
+  const matching = assignments.filter((a) => {
+    if (a.userId !== userId) return false;
+    if (a.effectiveFrom > periodEnd) return false;
+    if (a.effectiveTo !== undefined && a.effectiveTo <= periodStart) return false;
+    return true;
+  });
+
+  if (matching.length === 0) return { status: "no_assignment", userId };
+  if (matching.length > 1) return { status: "multiple_assignments", userId, count: matching.length };
+
+  const assignment = matching[0];
+  const profile = profiles.get(assignment.taxProfileId);
+
+  if (!profile) return { status: "profile_not_found", userId, taxProfileId: assignment.taxProfileId };
+  if (!("isActive" in profile) || (profile as any).isActive === false) {
+    return { status: "profile_inactive", userId, profileCode: profile.code };
+  }
+
+  return { status: "found", profile, assignment };
+}
+
+// ── 2. Company mapping ───────────────────────────────────
+
+export function determineOutsideCompanyType(
+  entry: CommissionForInvoice,
+): OutsideCompanyType {
+  if (entry.scope === "fixed" && entry.fixedCommissionTypeId === "16") {
+    return "DS";
+  }
+  if (entry.carePlanTypeId === 5) {
+    const tpName = entry.taxProfileName.toLowerCase();
+    if (tpName.includes("forfettar")) return "Est_forfettari";
+    if (entry.invoiceVat) return "Est";
+  }
+  return "None";
+}
+
+export function applyCompanyMapping(
+  companyId: string,
+  outsideCompanyType: OutsideCompanyType,
+  mappings: CompanyMapping[],
+): string {
+  if (outsideCompanyType === "None") return companyId;
+
+  const mapping = mappings.find(
+    (m) => m.category === outsideCompanyType && m.fromCompanyId === companyId,
+  );
+
+  return mapping ? mapping.toCompanyId : companyId;
+}
+
+// ── 3. IVA per tipo ──────────────────────────────────────
+
+export function calculateVatRate(
+  outsideCompanyType: OutsideCompanyType,
+  profile: ResolvedTaxProfile,
+  invoiceVat?: number,
+): number {
+  switch (outsideCompanyType) {
+    case "DS": return 22;
+    case "Est_forfettari": return 0;
+    case "Est": return invoiceVat ?? profile.vatRatePercent;
+    default: return profile.vatRatePercent;
+  }
+}
+
+// ── 4. Aggregazione commissioni per fattura ──────────────
+
+export function aggregateForInvoices(
+  entries: CommissionForInvoice[],
+  mappings: CompanyMapping[],
+  profiles: Map<string, ResolvedTaxProfile>,
+  profileByUser: Map<string, ResolvedTaxProfile>,
+): AggregatedInvoiceGroup[] {
+  const groups = new Map<string, AggregatedInvoiceGroup>();
+
+  for (const entry of entries) {
+    if (!entry.isInvoiceable) continue;
+
+    const profile = profileByUser.get(entry.userId);
+    if (!profile) continue;
+
+    const outsideType = determineOutsideCompanyType(entry);
+    const mappedCompanyId = applyCompanyMapping(entry.companyId, outsideType, mappings);
+    const vatRate = calculateVatRate(outsideType, profile, entry.invoiceVat);
+
+    const key = `${entry.userId}|${entry.clinicId}|${entry.period}|${outsideType}`;
+
+    const existing = groups.get(key);
+    if (existing) {
+      existing.netPrice += entry.netPrice;
+      existing.calculated += entry.calculated;
+      existing.lineItemCount++;
+      if (entry.id) existing.commissionIds.push(entry.id);
+      if (entry.carePlanRowId) existing.cprIds.push(entry.carePlanRowId);
+    } else {
+      groups.set(key, {
+        userId: entry.userId,
+        clinicId: entry.clinicId,
+        companyId: mappedCompanyId,
+        period: entry.period,
+        outsideCompanyType: outsideType,
+        netPrice: entry.netPrice,
+        calculated: entry.calculated,
+        lineItemCount: 1,
+        commissionIds: entry.id ? [entry.id] : [],
+        cprIds: entry.carePlanRowId ? [entry.carePlanRowId] : [],
+        vatRate,
+        profile,
+      });
+    }
+  }
+
+  return Array.from(groups.values());
+}
+
+// ── 5. Calcoli fiscali completi ──────────────────────────
+
+export function calculateFiscalAmounts(
+  subtotal: number,
+  profile: ResolvedTaxProfile,
+  vatRate: number,
+  isCompanyGrouped: boolean,
+  outsideCompanyType: OutsideCompanyType,
+  stampDutyThreshold: number,
+  stampDutyCost: number,
+): FiscalCalculationResult {
+  let calculated = round(subtotal);
+  let stampDutyAmount = 0;
+
+  const stampDutyEnabled = profile.stampDutyEnabled && outsideCompanyType !== "Est";
+
+  if (profile.isBolloCompreso) {
+    if (stampDutyEnabled && calculated > stampDutyThreshold && isCompanyGrouped) {
+      calculated += stampDutyCost;
+      stampDutyAmount = stampDutyCost;
+    }
+
+    const contributionAmount = round(calculated * profile.contributionRatePercent / 100);
+
+    const withholdingBase = profile.is104
+      ? calculated + contributionAmount
+      : calculated;
+    const withholdingAmount = round(
+      profile.withholdingRatePercent / 100 * profile.withholdingOnPercent / 100 * withholdingBase,
+    );
+
+    const vatAmount = round(Math.max(vatRate * subtotal / 100, 0));
+    const total = round(calculated + vatAmount + contributionAmount);
+    const netToPay = round(total - withholdingAmount);
+
+    return {
+      subtotal: round(subtotal),
+      netPrice: round(subtotal),
+      contributionAmount,
+      vatRate,
+      vatAmount,
+      withholdingRate: profile.withholdingRatePercent,
+      withholdingOnRate: profile.withholdingOnPercent,
+      withholdingAmount,
+      stampDutyAmount,
+      total,
+      netToPay,
+    };
+  }
+
+  const contributionAmount = round(calculated * profile.contributionRatePercent / 100);
+
+  const withholdingBase = profile.is104
+    ? calculated + contributionAmount
+    : calculated;
+  const withholdingAmount = round(
+    profile.withholdingRatePercent / 100 * profile.withholdingOnPercent / 100 * withholdingBase,
+  );
+
+  const vatAmount = round(Math.max(vatRate * subtotal / 100, 0));
+  let total = round(calculated + vatAmount + contributionAmount);
+  let netToPay = round(total - withholdingAmount);
+
+  if (stampDutyEnabled && total > stampDutyThreshold && isCompanyGrouped) {
+    total += stampDutyCost;
+    netToPay += stampDutyCost;
+    stampDutyAmount = stampDutyCost;
+  }
+
+  return {
+    subtotal: round(subtotal),
+    netPrice: round(subtotal),
+    contributionAmount,
+    vatRate,
+    vatAmount,
+    withholdingRate: profile.withholdingRatePercent,
+    withholdingOnRate: profile.withholdingOnPercent,
+    withholdingAmount,
+    stampDutyAmount,
+    total,
+    netToPay,
+  };
+}
+
+// ── 6. Company grouping ──────────────────────────────────
+
+/**
+ * Determina quale fattura è la "prima" per una combinazione userId+companyId+period.
+ * Solo la prima fattura riceve isCompanyGrouped=true (per il bollo).
+ */
+export function determineCompanyGrouping(
+  groups: AggregatedInvoiceGroup[],
+  existingGroupedKeys: Set<string>,
+): Map<string, boolean> {
+  const sorted = [...groups].sort((a, b) => b.calculated - a.calculated);
+  const seenKeys = new Set<string>(existingGroupedKeys);
+  const result = new Map<string, boolean>();
+
+  for (const group of sorted) {
+    const companyKey = `${group.userId}|${group.companyId}|${group.period}`;
+    const groupKey = `${group.userId}|${group.clinicId}|${group.period}|${group.outsideCompanyType}`;
+
+    if (!seenKeys.has(companyKey)) {
+      seenKeys.add(companyKey);
+      result.set(groupKey, true);
+    } else {
+      result.set(groupKey, false);
+    }
+  }
+
+  return result;
+}
+
+// ── 7. Pipeline completa ─────────────────────────────────
+
+export function generateDraftInvoices(
+  groups: AggregatedInvoiceGroup[],
+  existingGroupedKeys: Set<string>,
+  stampDutyThreshold: number,
+  stampDutyCost: number,
+): DraftInvoiceData[] {
+  const companyGrouping = determineCompanyGrouping(groups, existingGroupedKeys);
+  const results: DraftInvoiceData[] = [];
+
+  for (const group of groups) {
+    const groupKey = `${group.userId}|${group.clinicId}|${group.period}|${group.outsideCompanyType}`;
+    const isCompanyGrouped = companyGrouping.get(groupKey) ?? false;
+
+    const fiscal = calculateFiscalAmounts(
+      group.calculated,
+      group.profile,
+      group.vatRate,
+      isCompanyGrouped,
+      group.outsideCompanyType,
+      stampDutyThreshold,
+      stampDutyCost,
+    );
+
+    const snapshot = createTaxProfileSnapshot(group.profile);
+
+    results.push({
+      userId: group.userId,
+      clinicId: group.clinicId,
+      companyId: group.companyId,
+      period: group.period,
+      outsideCompanyType: group.outsideCompanyType,
+      isCompanyGrouped,
+      taxProfileId: group.profile._id,
+      taxProfileSnapshot: snapshot,
+      lineItemCount: group.lineItemCount,
+      fiscal,
+      commissionIds: group.commissionIds,
+      cprIds: group.cprIds,
+    });
+  }
+
+  return results;
+}
+
+// ── Snapshot ─────────────────────────────────────────────
+
+export function createTaxProfileSnapshot(profile: ResolvedTaxProfile): TaxProfileSnapshot {
+  return {
+    taxProfileId: profile._id,
+    code: profile.code,
+    name: profile.name,
+    vatRatePercent: profile.vatRatePercent,
+    withholdingRatePercent: profile.withholdingRatePercent,
+    withholdingOnPercent: profile.withholdingOnPercent,
+    contributionRatePercent: profile.contributionRatePercent,
+    contributionWithholding: profile.contributionWithholding,
+    is104: profile.is104,
+    isBolloCompreso: profile.isBolloCompreso,
+    stampDutyEnabled: profile.stampDutyEnabled,
+    stampDutyThreshold: profile.stampDutyThreshold,
+  };
+}
+
+// ── Helpers ──────────────────────────────────────────────
+
+function parsePeriodBounds(period: string): { periodStart: number; periodEnd: number } {
+  const [yearStr, monthStr] = period.split("-");
+  const year = parseInt(yearStr, 10);
+  const month = parseInt(monthStr, 10);
+  return {
+    periodStart: new Date(year, month - 1, 1).getTime(),
+    periodEnd: new Date(year, month, 0, 23, 59, 59, 999).getTime(),
+  };
+}
+
+function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}