@chill-sharp/ui-core 1.1.12

package/doc/it/ReferenceExistence.md

@@ -0,0 +1,130 @@
+# Verificare La Presenza Di Un Riferimento EF Core Senza Caricarlo
+
+English version: [English](../ReferenceExistence.md)
+
+`ChillSharp.EF.ChillEntryExtension.Exist()` risponde a una domanda piccola ma utile: questa navigazione di riferimento ha attualmente tutti i valori della chiave esterna configurata?
+
+```csharp
+using ChillSharp.EF;
+
+var hasCustomerReference = context.Entry(order)
+    .Reference(x => x.Customer)
+    .Exist();
+```
+
+La chiamata legge i valori correnti delle proprieta FK dal change tracker di EF Core. Con l'argomento predefinito non esegue query sul database e non carica `order.Customer`.
+
+> L'estensione si chiama `Exist`, non `Exists`. La sua firma e `Exist(bool loadIfExist = false)`.
+
+## Quando Usarla
+
+Usa `Exist()` nella logica del modello che deve distinguere una relazione opzionale assente da una relazione assegnata, evitando un caricamento non necessario dell'entita principale. E utile in particolare in `OnUpdate`, `OnSelect` o nella logica di elaborazione dei DTO quando serve soltanto decidere quale ramo eseguire.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var db = (AppDbContext)context;
+
+    if (db.Entry(this).Reference(x => x.Customer).Exist())
+    {
+        // E stato assegnato un valore FK Customer. Customer non e ancora caricato.
+        CustomerSummaryRequired = true;
+    }
+    else
+    {
+        CustomerSummaryRequired = false;
+    }
+}
+```
+
+Questo e preferibile a controllare `Customer != null` quando la navigazione puo essere semplicemente non caricata. Una navigazione null non distingue tra “nessuna relazione” e “relazione non caricata”.
+
+## Caricamento Opzionale
+
+Passa `true` soltanto quando l'operazione successiva ha davvero bisogno dell'entita correlata:
+
+```csharp
+var customerReference = context.Entry(order).Reference(x => x.Customer);
+
+if (customerReference.Exist(loadIfExist: true) && order.Customer is { } customer)
+{
+    // EF Core ha caricato Customer se non era gia caricato.
+    var customerName = customer.Name;
+}
+```
+
+Il comportamento e:
+
+| Chiamata | Valori FK incompleti o null | Valori FK presenti e navigazione non caricata | Navigazione caricata? |
+| --- | --- | --- | --- |
+| `Exist()` | Restituisce `false` | Restituisce `true` | Nessun nuovo caricamento |
+| `Exist(true)` | Restituisce `false` | Restituisce `true` | Prova a caricare il riferimento |
+
+Se la navigazione era gia caricata, nessuna delle due forme la carica di nuovo. Poiche il risultato descrive comunque i valori FK, `Exist(true)` puo restituire `true` mentre la navigazione caricata e null se un database senza FK contiene un valore orfano.
+
+## Database Senza FK Non Significa Modello Senza Relazione
+
+Questa estensione funziona con un'implementazione legacy o con database senza FK solo se EF Core conosce ancora la relazione e le relative proprieta FK del dipendente. Un vincolo fisico nel database e i metadati di relazione di EF Core sono aspetti separati.
+
+Per esempio, il database puo non applicare un vincolo da `Order.CustomerGuid` a `Customer.Guid`, ma il modello EF deve comunque avere la FK scalare e il mapping della relazione:
+
+```csharp
+public sealed class Order : ChillEntity
+{
+    public Guid? CustomerGuid { get; set; }
+    public Customer? Customer { get; set; }
+}
+
+protected override void OnModelCreating(ModelBuilder modelBuilder)
+{
+    modelBuilder.Entity<Order>()
+        .HasOne(x => x.Customer)
+        .WithMany()
+        .HasForeignKey(x => x.CustomerGuid);
+}
+```
+
+`Exist()` legge `CustomerGuid` tramite questo mapping. Una relazione non configurata in EF Core non ha metadati FK di `ReferenceEntry` che l'estensione possa ispezionare; in quel caso usa direttamente la chiave scalare oppure configura la relazione.
+
+Le proprieta FK shadow sono supportate finche EF Core ha mappato la navigazione. L'estensione ottiene i metadati della proprieta FK dalla navigazione, senza richiedere una proprieta FK CLR pubblica.
+
+## Significato Del Risultato
+
+`Exist()` e un test locale di presenza dei valori FK. Non esegue una query di esistenza per la riga principale.
+
+Di conseguenza:
+
+- `true` significa che ogni componente FK configurato non e null nell'entry dipendente tracciata.
+- `false` significa che almeno un componente FK e null.
+- `true` non garantisce che la riga correlata esista, soprattutto quando il database non applica vincoli FK oppure contiene valori orfani legacy.
+- `true` non significa che la navigazione sia caricata.
+
+Se la regola di business richiede la prova che una riga principale esista, esegui una query esplicita, per esempio con `AnyAsync`, oppure usa `Exist(true)` e gestisci poi una navigazione caricata null. Preferisci la query esplicita quando serve un controllo di esistenza lato server senza materializzare il principale.
+
+```csharp
+var customerRowExists = await context.Set<Customer>()
+    .AnyAsync(x => x.Guid == order.CustomerGuid, cancellationToken);
+```
+
+## Chiavi Composte E Convenzioni Sui Valori
+
+Per una FK composta, `Exist()` restituisce `true` soltanto quando ogni componente non e null. Una chiave composta parzialmente popolata restituisce `false`.
+
+L'estensione controlla `null`; non valida valori sentinella. Per esempio, `Guid.Empty`, `0` o una stringa vuota non sono null e quindi possono produrre `true` se sono i valori attualmente memorizzati. Usa la validazione appropriata al dominio quando tali valori significano “non assegnato”.
+
+## Prerequisiti E Modalita Di Errore
+
+L'entita deve essere collegata allo stesso `DbContext` EF Core usato per ottenere la sua entry. Chiama l'estensione sulla navigazione di riferimento dal lato dipendente: l'entita nel `ReferenceEntry` deve possedere le proprieta FK riportate da EF Core per quella navigazione. Chiamarla per un membro che non e un riferimento, per una navigazione senza metadati di relazione FK utilizzabili oppure per la navigazione lato principale di una relazione uno-a-uno puo generare `InvalidOperationException`, poiche le proprieta FK non appartengono all'entry ispezionata.
+
+Non usarla per le navigazioni collection. Una collection richiede una domanda diversa—se esiste almeno una riga correlata—che normalmente richiede una query al database.
+
+## Guida Alla Scelta
+
+| Necessita | Usa |
+| --- | --- |
+| Determinare se un riferimento opzionale ha valori FK assegnati senza caricarlo | `Reference(...).Exist()` |
+| Caricare il riferimento soltanto se i valori FK sono assegnati | `Reference(...).Exist(true)` |
+| Provare che la riga principale esiste | Una query esplicita `Any`/`AnyAsync` |
+| Determinare se una collection ha elementi | Una query sul set dipendente |
+
+Mantieni `Exist()` per la decisione circoscritta di presenza FK. Il suo valore e rendere esplicito questo intento ed evitare il caricamento di un'entita correlata quando non necessario.

package/doc/it/RegisterContext.md

@@ -0,0 +1,218 @@
+# Registrare Un Contesto ChillSharp
+
+Versione originale in inglese: [English](../RegisterContext.md)
+
+Questo documento mostra come collegare i moduli ChillSharp dentro un host ASP.NET Core.
+
+## API Core Minima
+
+Per usare solo la Chill API core:
+
+```csharp
+using ChillSharp.Api;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseSqlite("Data Source=app.db"));
+
+builder.Services.AddChillApi<AppDbContext>();
+
+var app = builder.Build();
+app.MapChillApi();
+app.Run();
+```
+
+Requisiti:
+
+- `AppDbContext` deve ereditare `DbContext`
+- `AppDbContext` deve implementare `IChillContext`
+
+## Cosa Registra `AddChillApi<TContext>()`
+
+La registrazione core configura:
+
+- controller ChillSharp
+- risoluzione di `IChillContext` dal contesto host
+- `IChillDtoEngine`
+- comportamento opzionale di API protetta tramite `ChillApiOptions`
+
+## Proteggere La Core API
+
+Se l'host configura gia autenticazione e autorizzazione, puoi richiedere auth sulla Chill API:
+
+```csharp
+builder.Services.AddChillApi<AppDbContext>(options =>
+{
+    options.ProtectedApi = true;
+});
+```
+
+Poi usa il middleware standard ASP.NET Core:
+
+```csharp
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapChillApi();
+```
+
+## Aggiungere Servizi Schema
+
+Per persistere e servire metadati di schema:
+
+```csharp
+using ChillSharp.Schema;
+
+builder.Services.AddChillSchema<AppDbContext>();
+```
+
+Requisiti del contesto:
+
+- `AppDbContext : IChillSchemaDbContext`
+- `modelBuilder.AddChillSchemaModel()`
+
+`ChillSharp.Schema` possiede anche la registrazione della schema cache.
+
+## Aggiungere Gestione Auth
+
+Per esporre gli endpoint di gestione auth senza i flussi account di ASP.NET Core Identity:
+
+```csharp
+using ChillSharp.Auth.Api;
+
+builder.Services.AddChillAuthApi<AppDbContext>();
+```
+
+Requisiti del contesto:
+
+- `AppDbContext : IChillAuthDbContext`
+- `modelBuilder.AddChillAuthModel()`
+
+Questo aggiunge endpoint per:
+
+- auth users
+- ruoli
+- assegnazioni utente-ruolo
+- regole di permesso
+- valutazione dei permessi
+
+## Aggiungere I Flussi Account Identity
+
+Per esporre registrazione account, login, refresh token, cambio password e reset password:
+
+```csharp
+using ChillSharp.Auth;
+using ChillSharp.Auth.Api;
+using Microsoft.AspNetCore.Identity;
+
+builder.Services.AddIdentityCore<IdentityUser>()
+    .AddEntityFrameworkStores<AppDbContext>()
+    .AddSignInManager()
+    .AddDefaultTokenProviders();
+
+builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
+    .AddChillAuthBearer();
+
+builder.Services.AddAuthorization();
+
+builder.Services.AddChillAuthIdentityApi<AppDbContext, IdentityUser>();
+```
+
+Questo si appoggia a `AddChillAuthApi<TContext>()`.
+
+## Aggiungere I Servizi I18n
+
+Per esporre endpoint i18n:
+
+```csharp
+using ChillSharp.I18n.Api;
+
+builder.Services.AddChillI18nApi<AppDbContext>();
+```
+
+Requisiti del contesto:
+
+- `AppDbContext : IChillI18nDbContext`
+- `modelBuilder.AddChillI18nModel()`
+
+Il modulo attualmente espone:
+
+- `GET /api/chill-i18n/text/{labelGuid}/{cultureName}`
+- `PUT /api/chill-i18n/text`
+
+## Esempio Completo Di Host
+
+```csharp
+using ChillSharp.Api;
+using ChillSharp.Auth;
+using ChillSharp.Auth.Api;
+using ChillSharp.I18n.Api;
+using ChillSharp.Schema;
+using Microsoft.AspNetCore.Identity;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseSqlite("Data Source=app.db"));
+
+builder.Services.AddIdentityCore<IdentityUser>()
+    .AddEntityFrameworkStores<AppDbContext>()
+    .AddSignInManager()
+    .AddDefaultTokenProviders();
+
+builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
+    .AddChillAuthBearer();
+builder.Services.AddAuthorization();
+
+builder.Services.AddChillApi<AppDbContext>(options =>
+{
+    options.ProtectedApi = true;
+});
+builder.Services.AddChillSchema<AppDbContext>();
+builder.Services.AddChillAuthIdentityApi<AppDbContext, IdentityUser>();
+builder.Services.AddChillI18nApi<AppDbContext>();
+
+var app = builder.Build();
+
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapChillApi();
+app.Run();
+```
+
+## Comportamento Del Mapping
+
+`app.MapChillApi()` mappa i controller ChillSharp e gli endpoint di supporto. Non sostituisce il setup standard del middleware ASP.NET Core. Ti servono comunque:
+
+- `UseAuthentication()` se auth e abilitata
+- `UseAuthorization()` se authorization e abilitata
+
+I controller i18n e auth vengono aggiunti tramite controller discovery quando i relativi moduli sono registrati.
+
+## Ordine Di Startup Consigliato
+
+1. registrare il contesto EF Core
+2. registrare Identity se necessario
+3. registrare authentication e authorization se necessario
+4. registrare `AddChillApi<TContext>()`
+5. registrare i moduli opzionali (`Schema`, `Auth`, `I18n`)
+6. build dell'app
+7. applicare il middleware
+8. mappare la Chill API
+
+## OpenAPI / Swagger
+
+ChillSharp non forza Swagger nel tuo host. Se vuoi output OpenAPI per documentazione o generazione client, aggiungilo nell'app host:
+
+```csharp
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+
+var app = builder.Build();
+app.UseSwagger();
+app.UseSwaggerUI();
+```
+
+Questa e la base consigliata per generare client TypeScript e Python da un host ChillSharp.

package/doc/it/UiCore/CRUD.md

@@ -0,0 +1,170 @@
+# Configurazione del menu CRUD
+
+Versione originale in inglese: [English](../../UiCore/CRUD.md)
+
+Crea una voce di menu con `ComponentName` impostato a `CRUD`. Il suo `ComponentConfigurationJson` deve essere un oggetto JSON; le chiavi non distinguono maiuscole e minuscole. `chillType` è obbligatorio. Normalmente è il Chill type dell'entità e `chillQuery` è il Chill type della query che restituisce l'entità.
+
+```json
+{
+  "chillType": "Model.Post",
+  "chillQuery": "Query.PostQuery",
+  "viewCode": "default",
+  "disableAdd": false,
+  "disableCreate": false,
+  "disableEdit": false,
+  "disableInlineEdit": false,
+  "disableDelete": false,
+  "defaultValues": {},
+  "fixedValues": {},
+  "fixedQueryValues": {},
+  "defaultQueryValues": {},
+  "relations": []
+}
+```
+
+## Opzioni
+
+| Chiave | Tipo | Predefinito | Effetto |
+| --- | --- | --- | --- |
+| `chillType` | stringa | obbligatorio | Chill type dell'entità mostrata e modificata dal task. |
+| `chillQuery` | stringa o `null` | `null` | Chill type della query; configuralo quando l'entità richiede una query dedicata. |
+| `viewCode` | stringa | `default` | Codice della vista di schema usato dal task. |
+| `disableAdd` | booleano | `false` | Nasconde il comando Aggiungi. |
+| `disableCreate` | booleano | `false` | Impedisce la creazione di nuovi record. |
+| `disableEdit` | booleano | `false` | Impedisce la modifica nel dialogo. |
+| `disableInlineEdit` | booleano | `false` | Impedisce la modifica inline nella tabella. |
+| `disableDelete` | booleano | `false` | Impedisce l'eliminazione. |
+| `defaultValues` | oggetto | `{}` | Valori iniziali del form di creazione, modificabili dall'utente. |
+| `fixedValues` | oggetto | `{}` | Valori di creazione resi di sola lettura nel form e nell'editor inline. |
+| `fixedQueryValues` | oggetto | `{}` | Filtri query obbligatori che l'utente non può modificare. |
+| `defaultQueryValues` | oggetto | `{}` | Valori iniziali della query che l'utente può modificare. |
+| `relationLabel` | stringa o oggetto | omesso | Etichetta del CRUD aperto come relazione. La forma oggetto è `{ "labelGuid", "primaryDefaultText", "secondaryDefaultText" }`. |
+| `relations` | array | `[]` | Definizioni CRUD figlie disponibili nel menu azioni di ogni riga. |
+
+Le proprietà JSON sconosciute sono mantenute dall'editor del menu ma non sono opzioni CRUD standard.
+
+## Valori e segnaposto delle relazioni
+
+I valori nei quattro oggetti di valori sono valori JSON. In una relazione annidata, la stringa `@{FieldName}` legge quella proprietà dalla riga padre selezionata e `@{mock}` fornisce un oggetto entità leggero per tale riga padre.
+
+### Quale contenitore viene applicato e quando
+
+Esistono due flussi indipendenti:
+
+| Flusso | Valori iniziali modificabili | Valori con precedenza |
+| --- | --- | --- |
+| Ricerca/query | `defaultQueryValues` | `fixedQueryValues` |
+| Creazione entità | `defaultValues` | `fixedValues` |
+
+UI Core unisce ogni flusso in questo ordine. Se la stessa proprietà compare in entrambi i contenitori, prevale il valore nel contenitore `fixed...`. Usa solo il contenitore fixed quando un valore non deve essere modificato; usa solo quello default quando è soltanto un valore iniziale utile.
+
+`fixedQueryValues` vincola i record restituiti dal CRUD figlio. `fixedValues` vincola l'entità inviata dal flusso di creazione e rende tali proprietà di sola lettura nel form e nell'editor inline. I contenitori fixed sono configurazione, non sostituiscono autorizzazione o validazione lato server: l'API deve continuare a imporre tenant, proprietà e autorizzazioni.
+
+### Valori statici compatibili con CLR
+
+Il letterale JSON viene passato come valore della proprietà; UI Core non lo valuta né lo converte prima della normale serializzazione di entità/query. Usa la rappresentazione JSON attesa dall'API ChillSharp per la proprietà CLR.
+
+```json
+{
+  "defaultQueryValues": {
+    "IsPublished": true,
+    "MinimumScore": 50,
+    "Category": "News",
+    "From": "2026-01-01T00:00:00+01:00"
+  },
+  "fixedValues": {
+    "TenantCode": "acme",
+    "Priority": 10,
+    "IsInternal": false,
+    "ArchivedAt": null
+  }
+}
+```
+
+Usa stringhe JSON per `string`, `Guid`, `DateTime`, `DateTimeOffset`, `DateOnly` CLR e per gli enum che il server espone come stringhe. Usa numeri JSON per valori CLR numerici e booleani JSON per `bool`. Date e GUID devono essere stringhe JSON, non espressioni JavaScript: `"2026-01-01"` e `"8d0946dc-fc2b-4d95-b5ca-6f12d9618a5b"`, non `new Date(...)` o `Guid.NewGuid()`.
+
+### Valori statici di riferimento a entità
+
+Sì: un riferimento a entità può essere statico poiché un oggetto JSON è un valore ammesso. Fornisci la stessa forma di riferimento accettata dalla proprietà destinazione, normalmente almeno identificatore e tipo dell'entità riferita:
+
+```json
+{
+  "fixedQueryValues": {
+    "Customer": {
+      "guid": "8d0946dc-fc2b-4d95-b5ca-6f12d9618a5b",
+      "chillType": "Model.Customer"
+    }
+  },
+  "fixedValues": {
+    "Status": {
+      "guid": "7d8af0dd-d20d-4bb7-9a4d-f3b9d2f9c2b4",
+      "chillType": "Model.OrderStatus",
+      "label": "Approved"
+    }
+  }
+}
+```
+
+`label` è metadato UI facoltativo. Non usarlo come identità: l'entità è identificata da `guid`. Includi `chillType` quando il riferimento può essere polimorfico o quando server/client richiedono informazioni di tipo esplicite. Il nome della proprietà e la forma dell'oggetto devono corrispondere allo schema query o entità destinazione; una proprietà di chiave esterna scalare richiede invece la stringa GUID scalare, ad esempio `"CustomerGuid": "8d0946dc-fc2b-4d95-b5ca-6f12d9618a5b"`.
+
+### Valori dinamici: `@{FieldName}` e `@{mock}`
+
+I segnaposto vengono risolti solo aprendo una relazione dalla riga padre selezionata. Non sono espressioni e non vengono valutati in un CRUD menu radice, perché non esiste un'entità padre. In quel caso la stringa del segnaposto rimane invariata.
+
+- `@{Guid}` copia il valore `Guid`/`guid` della riga selezionata.
+- `@{CustomerCode}` copia un campo dall'oggetto `properties` della riga selezionata o dalle proprietà dirette dell'oggetto. Un token camel-case usa anche come fallback il nome della proprietà Pascal-case.
+- Un campo mancante viene risolto a `null`.
+- `@{mock}` crea una copia leggera dell'entità padre selezionata. Contiene `guid`, `chillType`, `label` e una copia di `properties`; non recupera nuovamente l'entità.
+
+Usa `@{mock}` per una proprietà di riferimento figlia come `Order` e `@{Guid}` per una chiave esterna scalare come `OrderGuid`:
+
+```json
+{
+  "relations": [
+    {
+      "chillType": "Model.OrderRow",
+      "chillQuery": "Query.OrderRowQuery",
+      "fixedQueryValues": { "Order": "@{mock}" },
+      "defaultQueryValues": { "Order": "@{mock}" },
+      "fixedValues": { "Order": "@{mock}" },
+      "defaultValues": { "Order": "@{mock}" }
+    },
+    {
+      "chillType": "Model.OrderRow",
+      "chillQuery": "Query.OrderRowQuery",
+      "fixedQueryValues": { "OrderGuid": "@{Guid}" },
+      "fixedValues": { "OrderGuid": "@{Guid}" }
+    }
+  ]
+}
+```
+
+Usa la prima forma solo quando lo schema query/entità espone una proprietà riferimento-entità `Order`. Usa la seconda solo quando espone una proprietà scalare `OrderGuid`. Non inviare `@{mock}` a una proprietà GUID scalare.
+
+```json
+{
+  "chillType": "Model.Order",
+  "chillQuery": "Query.OrderQuery",
+  "relations": [
+    {
+      "chillType": "Model.OrderRow",
+      "chillQuery": "Query.OrderRowQuery",
+      "relationLabel": {
+        "labelGuid": "ORDER-ROWS-LABEL",
+        "primaryDefaultText": "Rows",
+        "secondaryDefaultText": "Righe"
+      },
+      "fixedQueryValues": { "Order": "@{mock}" },
+      "defaultQueryValues": { "Order": "@{mock}" },
+      "defaultValues": { "Order": "@{mock}" },
+      "fixedValues": { "Order": "@{mock}" }
+    }
+  ]
+}
+```
+
+Usa `fixedQueryValues` per un filtro padre non modificabile e `defaultQueryValues` per un filtro iniziale modificabile. Usa `fixedValues` per un valore di creazione di sola lettura e `defaultValues` per un valore iniziale di creazione modificabile. Le relazioni possono contenere ulteriori array `relations`.
+
+## Persistenza della voce di menu
+
+L'API menu memorizza il JSON come stringa. Per esempio, usa `ComponentName: "CRUD"` e serializza l'oggetto in `ComponentConfigurationJson` quando chiami `set-menu`. JSON non valido, oppure un array JSON al posto di un oggetto, non può configurare il task.

package/doc/it/UiCore/README.md

@@ -0,0 +1,13 @@
+# ChillSharp UI Core
+
+Versione originale in inglese: [English](../../UiCore/README.md)
+
+`@chill-sharp/ui-core` è l'interfaccia Angular condivisa a workspace per le applicazioni ChillSharp. Fornisce il contenitore del workspace, la navigazione autenticata, form e tabelle guidati dallo schema, task CRUD, schermate dei permessi e il registro dei task di menu. I repository applicativi mantengono fuori da questo pacchetto branding del tenant, route, configurazione runtime ed estensioni di proprietà del client.
+
+Il pacchetto legge i metadati di schema e menu dall'API ChillSharp. Il server controlla i metadati delle entità e le voci di menu persistite; UI Core visualizza l'esperienza standard a partire da tali metadati. Usa JSON di configurazione per personalizzare un singolo task di menu senza copiare il codice UI condiviso.
+
+## Guide
+
+- [Configurazione del menu CRUD](./CRUD.md): configurare una voce menu `CRUD` e le relative opzioni JSON.
+- [Guida ai menu](../MenuGuide/README.md): voci di menu persistite e visibilità `MenuHierarchy`.
+- [Configurazione delle relazioni](../MenuGuide/Relations.md): relazioni di schema che UI Core può trasformare in task CRUD annidati.

package/doc/it/ValidationModel/README.md

@@ -0,0 +1,117 @@
+# Modello di convalida
+
+Versione originale in inglese: [English](../../ValidationModel/README.md)
+
+
+ChillSharp supporta gli attributi di convalida ASP.NET Core/.NET standard sulle proprietà di entità e query, purché tali proprietà siano contrassegnate anche con `[ChillProperty]`.
+
+## Convalida standard sulle proprietà Chill
+
+Decora le tue proprietà `ChillEntity` o `ChillQuery` sia con `[ChillProperty]` che con i consueti attributi DataAnnotations come `[Required]`, `[StringLength]`, `[Range]`, `[EmailAddress]` e così via.
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+using System.ComponentModel.DataAnnotations;
+
+public class Customer : ChillEntity
+{
+    [Key]
+    public override Guid Guid { get; set; }
+
+    [ChillProperty(
+        UniquePropertyKeyString: "2F262D7E-F676-4857-B41D-D31C766AA38F",
+        PrimaryLanguageLabel: "Name",
+        SecondaryLanguageLabel: "Nome")]
+    [Required(ErrorMessage = "Customer name is required.")]
+    [StringLength(80, ErrorMessage = "Customer name must be 80 characters or less.")]
+    public string Name { get; set; } = string.Empty;
+}
+```
+
+In fase di esecuzione ChillSharp convalida solo le proprietà decorate con `[ChillProperty]`.
+
+Se una proprietà ha attributi DataAnnotations ma non è una proprietà Chill, ChillSharp la ignora nella pipeline di convalida Chill.
+
+## Combinazione di DataAnnotations con `OnValidation()`
+
+È comunque possibile aggiungere una convalida ChillSharp personalizzata sovrascrivendo `OnValidation()`.
+
+```csharp
+public override IEnumerable<ChillValidationError> OnValidation(IChillContext context)
+{
+    if (Name == "admin")
+    {
+        return
+        [
+            new ChillValidationError
+            {
+                FieldName = nameof(Name),
+                Message = "The name 'admin' is reserved."
+            }
+        ];
+    }
+
+    return [];
+}
+```
+
+Il comportamento in fase di esecuzione è:
+
+1. ChillSharp esegue la convalida DataAnnotations standard sui membri `[ChillProperty]`.
+2. ChillSharp esegue quindi la logica `OnValidation()` personalizzata.
+3. Gli errori restituiti vengono esposti come `ChillValidationError` utilizzando le DataAnnotations leggibili dall'uomo `ErrorMessage`.
+
+## Aggiorna il comportamento
+
+La stessa pipeline di convalida viene eseguita automaticamente anche all'inizio dell'hook runtime post-aggiornamento interno utilizzato da ChillSharp.
+
+Ciò significa:
+
+-Se il client chiama la convalida in modo esplicito, riceve voci `ChillValidationError` per errori di convalida personalizzati e basati su annotazioni.
+- Se il client salta la convalida esplicita e passa direttamente alla creazione o all'aggiornamento, ChillSharp convalida comunque l'entità durante il ciclo di vita dell'aggiornamento e genera un `ChillValidationException` con gli stessi messaggi leggibili dall'uomo.
+
+## Note
+
+- Utilizza DataAnnotations standard per semplici regole di campo.
+- Utilizzare `OnValidation()` per regole che dipendono da più campi, logica aziendale o ricerche nel database.
+- Per rendere una proprietà parte della convalida ChillSharp, aggiungere sempre `[ChillProperty]`.
+
+## Appendice: messaggi di convalida basati su GUID
+
+Come hack di flessibilità opzionale, un DataAnnotations `ErrorMessage` può contenere una stringa GUID invece del testo dell'utente finale.
+
+Quindi puoi fornire i testi primari e secondari effettivi sovrascrivendo `GetValidationMessageDefinitions()`.
+
+```csharp
+public class Customer : ChillEntity
+{
+    [ChillProperty(
+        UniquePropertyKeyString: "B2AB35A8-6A89-4D39-8F1D-183F686811A9",
+        PrimaryLanguageLabel: "Code",
+        SecondaryLanguageLabel: "Codice")]
+    [Required(ErrorMessage = "4F880CC1-5C7A-4E23-982A-5F0C490B44DE")]
+    public string Code { get; set; } = string.Empty;
+
+    public override IEnumerable<ChillValidationMessageDefinition> GetValidationMessageDefinitions(IChillContext context)
+    {
+        return
+        [
+            new ChillValidationMessageDefinition
+            {
+                MessageGuid = Guid.Parse("4F880CC1-5C7A-4E23-982A-5F0C490B44DE"),
+                PrimaryLanguageMessage = "Code is required.",
+                SecondaryLanguageMessage = "Il codice e obbligatorio."
+            }
+        ];
+    }
+}
+```
+
+Quando ChillSharp vede il GUID in `ErrorMessage`, risolve il messaggio finale attraverso la stessa convenzione di lingua primaria/secondaria utilizzata altrove nei metadati di ChillSharp.
+
+Note:
+
+- Questo è facoltativo. I semplici valori `ErrorMessage` leggibili dall'uomo funzionano ancora normalmente.
+- Utilizzalo solo quando desideri un identificatore stabile per un testo di convalida.
+- Se il GUID non viene trovato in `GetValidationMessageDefinitions()`, ChillSharp torna alla stringa grezza `ErrorMessage`.