Dominio inv — Panoramica sviluppatore

🎯 Cosa fa

Il dominio inv gestisce la fatturazione elettronica FatturaPA: emissione, trasmissione via Aruba al Sistema di Interscambio, tracciamento stati, piano rate e convenzioni commerciali.

🗺️ Mappa moduli

Database — TrainingHub.Database/inv/

File	Ruolo
Tables/issuers.sql	Emittenti (cedente/prestatore + credenziali Aruba)
Tables/bankAccounts.sql	Anagrafica conti bancari per emittente
Tables/invoices.sql	Intestazione fattura
Tables/invoiceLines.sql	Righe di dettaglio
Tables/invoicePayments.sql	Piano rate
Tables/invoiceAppointments.sql	Associazione N:N fattura ↔ appuntamenti formativi
Tables/invoiceStatusHistory.sql	Storico cambi di stato
Tables/conventions.sql	Convenzioni (sconto per categoria corso)
Tables/companyConventions.sql	Associazione N:N azienda ↔ convenzione
Tables/vatCodes.sql	Codici IVA riutilizzabili
Tables/paymentMethods.sql	Lookup codici metodo pagamento SDI (MP01–MP23)
Tables/documentTypes.sql	Lookup codici tipo documento SDI (TD01–TD28)
Functions/fn_activeConventions.sql	TVF: convenzioni attive per (companyId, issueDate)

Service layer — TrainingHub.BackOffice/Services/Invoicing/

File	Ruolo
IInvoiceService.cs	Interfaccia servizio fattura
InvoiceService.cs	Implementazione + integrazione Aruba

UI CRUD — TrainingHub.BackOffice/Components/CRUD/inv/

Nove entità CRUD auto-generate. Pattern per ciascuna:

• <Entity>.razor + .razor.tt.cs (grid autogenerata)
• <Entity>.razor.cs (code-behind custom)
• Forms/<Entity>Form.razor + .razor.cs + .razor.tt.cs
• FormPopups/<Entity>FormPopup.razor + .razor.cs + .razor.tt.cs

Entità presenti:

• Invoice (con wizard 5 passi in FormPopups/InvoiceFormPopup.razor.cs)
• InvoiceLine, InvoicePayment, InvoiceAppointment, InvoiceStatusHistory
• Issuer, VatCode, PaymentMethod, DocumentType
• BankAccount
• Convention, CompanyConvention

Configurazione CRUD — _conf/*.dxgrid.conf.json

Un file JSON per entità che guida la generazione. Modificare qui per cambi persistenti; i file .razor e .razor.tt.cs vengono rigenerati dal tool MCP 3sd-generator.

Test — TrainingHub.Tests/Services/Invoicing/

InvoiceServiceTests.cs — copertura InvoiceService (numerazione, invio, storico, piano rate).

🔧 API pubblica — IInvoiceService

Task<int> GetNextInvoiceNumberAsync(Guid issuerId, int year, CancellationToken ct);
static string BuildInvoiceCode(int year, int number, string? sezionale = null);
Task SendToArubaAsync(Guid invoiceId, CancellationToken ct);
Task RefreshStatusFromArubaAsync(Guid invoiceId, CancellationToken ct);
Task AddStatusHistoryAsync(Guid invoiceId, InvoiceStatus status, string? arubaStatus, string? notes, string? createdBy, CancellationToken ct);
Task<IEnumerable<invoiceStatusHistory>> GetStatusHistoryAsync(Guid invoiceId, CancellationToken ct);
Task<IEnumerable<invoicePayment>> GetPaymentsAsync(Guid invoiceId, CancellationToken ct);
Task SavePaymentsAsync(Guid invoiceId, IEnumerable<invoicePayment> payments, CancellationToken ct);

Registrato in Program.cs nella sezione DI.

🧩 Pattern chiave

Wizard fattura

Il form di edit della fattura è un wizard a 5 step realizzato in FormPopups/InvoiceFormPopup.razor + .razor.cs, usando Tabiot.Blazor.Wizard.Wizard. Sequenza step e hook OnStepChange:

Step	Titolo	Hook
1	Dati fattura	SaveInvoiceDraft
2	Appuntamenti	CreateLinesFromAppointments
3	Righe	—
4	Pagamenti	SavePayments (valida somma = 100%)
5	Riepilogo	LoadSummary (totali + storico + pulsanti SDI)

Generazione CRUD

I file .razor e .razor.tt.cs sono rigenerati dal tool MCP 3sd-generator a partire dallo schema DB e dal conf.json. Modifiche dirette in questi file vanno perse alla rigenerazione: per rendere persistenti le modifiche aggiornare il conf.json e rigenerare.

Il code-behind .razor.cs contiene il codice custom e non viene toccato dalla generazione.

Applicazione convenzioni

Al momento dell'emissione fattura, CreateLinesFromAppointments (in InvoiceFormPopup.razor.cs) usa inv.fn_activeConventions(companyId, issueDate) per recuperare lo sconto attivo e pre-popolare la riga con il discountPercentage corretto.

Numerazione

GetNextInvoiceNumberAsync calcola il prossimo progressivo con un SELECT MAX(invoiceNumber) + 1 filtrato per issuerId e invoiceYear. Il vincolo unique UQ_invoices_number(issuerId, invoiceYear, invoiceNumber) garantisce unicità anche sotto race condition (il secondo insert fallisce).

📦 Dipendenze

• Brighela.SimpleCRUD.Service.ISimpleCRUDService — CRUD di base
• Oss.Filters — filtri su grid
• Tabiot.Blazor.* — wizard, grid, popup, combo
• DevExpress.Blazor — componenti UI
• Microsoft.Extensions.Localization.IStringLocalizer<T> — etichette localizzate
• Ecosistema 3SD: Scarnas, Brighela, Servel, Ploc, Tabiot, Mulet

⚠️ Domande aperte / debito tecnico

• Credenziali Aruba in chiaro. inv.issuers.arubaPassword è memorizzata in chiaro. Decisione esplicita a design (back-office interno), ma valutare cifratura simmetrica con chiave da config per compliance futura.
• Job schedulato di refresh stato fatture inviate. Oggi il refresh è solo manuale via pulsante. Da implementare come hosted service.
• Tipo documento (fattura / nota di credito / acconto) non presente in inv.invoices. Oggi distinzione solo per segno importi. Aggiungere campo esplicito per allineamento FatturaPA.

🔗 Vedi anche

• Schema DB — dettaglio tabelle, FK, indici
• Componenti UI — struttura Blazor CRUD
• Servizi — logica InvoiceService
• Aggiungere un campo — tutorial
• Guida utente: Panoramica fatturazione (docs-site-user)