@chill-sharp/ui-core 1.1.12

package/doc/it/MenuGuide/README.md

@@ -0,0 +1,49 @@
+# Guida ai menu di ChillSharp
+
+Versione originale in inglese: [English](../../MenuGuide/README.md)
+
+ChillSharp può memorizzare un albero dei menu dell'applicazione nel modulo schema invece di codificarlo nel frontend. La gestione dei menu è esposta sotto `/api/chill-schema`.
+
+## Modello di voce di menu
+
+Ogni voce dispone di `Guid` stabile, `PositionNo`, `Title`, `Description` facoltativa, `Parent` facoltativo, `ComponentName`, `ComponentConfigurationJson` facoltativo e `MenuHierarchy` facoltativo.
+
+- `Parent = null` identifica una voce radice.
+- Le voci figlie fanno riferimento al proprio genitore diretto.
+- Le voci sullo stesso livello sono ordinate per `PositionNo`, poi `Title`, poi `Guid`.
+- `ComponentName` identifica il componente client da aprire, ad esempio `CRUD`.
+
+```json
+{
+  "Guid": "00000000-0000-0000-0000-000000000000",
+  "PositionNo": 10,
+  "Title": "Posts",
+  "Description": "Open the post management screen",
+  "Parent": null,
+  "ComponentName": "CRUD",
+  "ComponentConfigurationJson": "{\"ChillType\":\"Model.Post\"}",
+  "MenuHierarchy": "CONTENT.POSTS"
+}
+```
+
+## Endpoint
+
+- `GET /api/chill-schema/get-menu` restituisce le voci radice.
+- `GET /api/chill-schema/get-menu?parentGuid={guid}` restituisce i figli diretti di una voce.
+- `POST /api/chill-schema/set-menu` crea una voce quando `Guid` è vuoto oppure aggiorna la voce corrispondente. Un genitore fornito deve già esistere e una voce non può essere il proprio genitore. L'aggiornamento di una voce esistente con `MenuHierarchy` vuoto conserva il valore memorizzato.
+- `DELETE /api/chill-schema/delete-menu?menuItemGuid={guid}` elimina la voce selezionata e l'intero sottoalbero dei suoi discendenti.
+
+Carica l'albero un livello alla volta: prima richiedi le radici, poi i figli quando un ramo viene espanso.
+
+## Visibilità con `MenuHierarchy`
+
+`MenuHierarchy` accetta un codice oppure codici separati da virgola. ChillSharp unisce i valori separati da virgola dell'utente corrente e di tutti i ruoli attivi in un insieme effettivo di prefissi.
+
+- `*` concede l'accesso a ogni voce di menu.
+- Senza alcun prefisso effettivo non viene restituita alcuna voce, comprese quelle con gerarchia vuota.
+- Con almeno un prefisso effettivo sono visibili le voci con gerarchia vuota.
+- Una voce con gerarchia valorizzata è visibile quando inizia con almeno un prefisso effettivo.
+
+Per esempio, `CONTENT` concede `CONTENT`, `CONTENT.POSTS` e `CONTENT.REPORTS.MONTHLY`, ma non `ADMIN`. Una voce può esporre più rami con `CONTENT, REPORTS.MONTHLY`.
+
+Usa codici stabili separati da punti, quali `ADMIN.USERS`, `CONTENT.POSTS` e `REPORTS.MONTHLY`.

package/doc/it/ModelPreparation.md

@@ -0,0 +1,254 @@
+# Preparare Un Modello Per ChillSharp
+
+Versione originale in inglese: [English](../ModelPreparation.md)
+
+Questo documento descrive i requisiti lato modello per esporre un dominio EF Core tramite ChillSharp.
+
+## Obiettivi
+
+Dopo la preparazione, il modello puo:
+
+- essere attivato dinamicamente tramite Chill type name
+- essere interrogato e modificato tramite Chill DTO
+- esporre metadati di schema ai client
+- partecipare alla manutenzione dei campi di audit
+- usare culture label e informazioni utente specifiche del contesto
+
+## 1. Implementare `IChillContext`
+
+Il tuo `DbContext` deve implementare `IChillContext`.
+
+Comportamento richiesto:
+
+```csharp
+public class AppDbContext : DbContext, IChillContext
+{
+    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
+
+    public string GetChillTypePrefix()
+    {
+        return "MyCompany.MyProduct.Data";
+    }
+
+    public string GetPrimaryCultureName()
+    {
+        return "en-US";
+    }
+
+    public string GetSecondaryCultureName()
+    {
+        return "it-IT";
+    }
+
+    public string GetCurrentUserName()
+    {
+        return Environment.UserName;
+    }
+}
+```
+
+### A cosa serve ogni metodo
+
+- `GetChillTypePrefix()`
+  Espande nomi brevi come `Model.Blog` in tipi CLR completamente qualificati.
+
+- `GetPrimaryCultureName()`
+  Definisce quale cultura deve usare `PrimaryLanguageLabel`.
+
+- `GetSecondaryCultureName()`
+  Definisce quale cultura deve usare `SecondaryLanguageLabel`.
+
+- `GetCurrentUserName()`
+  Alimenta il tracciamento audit delle entita.
+
+Ogni istanza di contesto puo restituire valori diversi. Questo e importante in host multi-tenant o multi-modulo dove possono coesistere piu contesti Chill con impostazioni linguistiche o utente differenti.
+
+## 2. Usare `ChillEntity` Per Le Entita Esposte
+
+Il pattern consigliato e ereditare da `ChillSharp.EF.ChillEntity`.
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+using System.ComponentModel.DataAnnotations;
+
+[ChillEntity(
+    UniquePropertyKeyString: "4E16F6C0-6B95-4D67-98BC-9F4D0D63EAF1",
+    PrimaryLanguageLabel: "Blog",
+    SecondaryLanguageLabel: "Blog")]
+public class Blog : ChillEntity
+{
+    [Key]
+    public override Guid Guid { get; set; }
+
+    [ChillProperty(
+        UniquePropertyKeyString: "50B1BB6C-D794-41E4-A85C-D4F9D7A6FA7E",
+        PrimaryLanguageLabel: "Blog title",
+        SecondaryLanguageLabel: "Titolo del blog")]
+    public string Title { get; set; } = string.Empty;
+
+    [ChillProperty(
+        UniquePropertyKeyString: "A18E7754-D8F7-45FE-B8A8-EA762A4EC9E6",
+        PrimaryLanguageLabel: "Blog url",
+        SecondaryLanguageLabel: "Url del blog")]
+    public string Url { get; set; } = string.Empty;
+
+    public override string GetLabel(IChillContext context) => Title;
+}
+```
+
+`ChillEntity` fornisce gia:
+
+- `Guid`
+- `Label`
+- `ShortLabel`
+- `FullTextContent`
+- `Checksum`
+- `LastUpdateUser`
+- `LastUpdate`
+- `LastUpdateUtcOffset`
+
+## 3. Annotare Le Proprieta Esposte
+
+ChillSharp considera parte della superficie metadata soltanto le proprieta decorate con `[ChillProperty]`.
+
+Questo influenza:
+
+- mapping DTO
+- generazione schema
+- calcolo checksum
+- metadati label
+
+Se una proprieta non e marcata con `[ChillProperty]`, non fa parte della superficie proprieta standard di Chill.
+
+## 4. Capire Gli Hook Del Ciclo Di Vita
+
+`ChillEngine` guida i metodi del ciclo di vita delle entita.
+
+### Flusso di creazione
+
+Durante la creazione, ChillSharp esegue:
+
+1. `OnCreate(context)`
+2. `OnUpdate(context)`
+3. save
+4. aggiornamento audit interno + `OnAfterUpdate(context)`
+5. ricalcolo di `Label`, `ShortLabel`, `FullTextContent`
+6. save
+
+### Flusso di aggiornamento
+
+Durante l'update, ChillSharp esegue:
+
+1. `OnUpdate(context)`
+2. save
+3. aggiornamento audit interno + `OnAfterUpdate(context)`
+4. ricalcolo di `Label`, `ShortLabel`, `FullTextContent`
+5. save
+
+### Flusso di eliminazione
+
+Durante il delete, ChillSharp esegue:
+
+1. `OnDelete(context)`
+2. save delete
+3. `OnAfterDelete(context)`
+4. save
+
+## 5. Comportamento Dei Campi Di Audit
+
+`ChillEntity` mantiene automaticamente:
+
+- `Checksum`
+- `LastUpdateUser`
+- `LastUpdate`
+- `LastUpdateUtcOffset`
+
+Il checksum viene calcolato da tutti i valori `[ChillProperty]` tranne i campi di audit stessi.
+
+Note:
+
+- i valori scalari vengono serializzati usando cultura invariata
+- i riferimenti `IChillEntity` contribuiscono con il loro `Guid`
+- le collezioni vengono appiattite in una sequenza deterministica prima di sommare i byte
+
+### Perche ridefinire `OnAfterUpdate()` e sicuro
+
+`ChillEntity` usa un'implementazione esplicita di interfaccia per `IChillEntity.OnAfterUpdate(...)`.
+
+`ChillEngine` chiama `OnAfterUpdate()` tramite l'interfaccia, quindi il flusso runtime e:
+
+1. aggiornare i campi di audit
+2. chiamare l'override derivato di `public virtual OnAfterUpdate(...)`
+
+In questo modo le entita derivate hanno una superficie di override pulita, mentre la logica audit di base non puo essere saltata accidentalmente.
+
+## 6. Label E Culture
+
+`PrimaryLanguageLabel` e `SecondaryLanguageLabel` non sono solo commenti. Vengono interpretati usando la UI culture attiva e il `IChillContext` attivo.
+
+Comportamento corrente:
+
+- se la UI culture corrente corrisponde alla cultura secondaria del contesto, ChillSharp preferisce `SecondaryLanguageLabel`
+- se corrisponde alla cultura primaria, ChillSharp preferisce `PrimaryLanguageLabel`
+- altrimenti fa fallback prima su primaria e poi su secondaria
+
+Questa logica viene usata quando vengono generati i metadati di schema.
+
+## 7. Query
+
+Le query dovrebbero implementare `IChillQuery<IChillEntity>` e possono essere decorate anch'esse con `ChillEntityAttribute` e `ChillPropertyAttribute`.
+
+Questo consente di generare lo schema delle query esattamente come quello delle entita.
+
+## 8. Requisiti Per La Persistenza Dello Schema
+
+Se vuoi metadati di schema persistiti e cache dello schema, il contesto deve anche implementare `IChillSchemaDbContext` e includere:
+
+```csharp
+modelBuilder.AddChillSchemaModel();
+```
+
+Poi registra:
+
+```csharp
+builder.Services.AddChillSchema<AppDbContext>();
+```
+
+## 9. Requisiti Per Auth
+
+Se vuoi autenticazione e permessi ChillSharp, il contesto deve implementare `IChillAuthDbContext` e includere:
+
+```csharp
+modelBuilder.AddChillAuthModel();
+```
+
+Poi registra uno tra:
+
+```csharp
+builder.Services.AddChillAuthApi<AppDbContext>();
+builder.Services.AddChillAuthIdentityApi<AppDbContext, IdentityUser>();
+```
+
+## 10. Requisiti Per I18n
+
+Se vuoi storage e lookup di testi localizzati, il contesto deve implementare `IChillI18nDbContext` e includere:
+
+```csharp
+modelBuilder.AddChillI18nModel();
+```
+
+Poi registra:
+
+```csharp
+builder.Services.AddChillI18nApi<AppDbContext>();
+```
+
+## 11. Raccomandazioni
+
+- Preferisci ereditare da `ChillEntity` invece di implementare `IChillEntity` da zero.
+- Usa GUID stabili in `UniquePropertyKeyString` e `UniqueEntityKeyString`.
+- Marca solo le proprieta che vuoi davvero esporre nella superficie DTO/schema di Chill.
+- Mantieni `GetLabel()` e `GetFullTextContent()` abbastanza economici da eseguire nei normali flussi CRUD.
+- Restituisci una vera identita di richiesta da `GetCurrentUserName()` negli host API.
+- Mantieni le impostazioni cultura specifiche del contesto nel contesto, non in global statici.

package/doc/it/PermissionModel/README.md

@@ -0,0 +1,190 @@
+# Modello Dei Permessi
+
+Versione originale in inglese: [English](../../PermissionModel/README.md)
+
+Questo documento descrive il modello di autorizzazione implementato da `ChillSharp.Auth`.
+
+## Scopo
+
+Il modello di permessi e progettato per rispondere in modo coerente a due domande:
+
+- l'utente corrente puo eseguire un'operazione a livello entita?
+- l'utente corrente puo vedere o modificare una specifica proprieta?
+
+Lo stesso modello supporta sia:
+
+- enforcement lato server
+- filtraggio delle capability lato client
+
+## Soggetti
+
+I permessi possono essere assegnati a:
+
+- un utente
+- un ruolo
+
+Un utente puo appartenere a piu ruoli.
+
+## Gerarchia Della Risorsa
+
+I permessi vengono valutati su una gerarchia a tre livelli:
+
+```text
+Module -> Entity -> Property
+```
+
+### Module
+
+Un modulo e un'area logica dell'applicazione, per esempio:
+
+- `Accounting`
+- `Accounting.General`
+- `Blog`
+- `Blog.Admin`
+
+I nomi modulo possono essere gerarchici.
+
+### Entity
+
+Un'entita e un nome Chill entity dentro un modulo, per esempio:
+
+- `Blog`
+- `Post`
+- `AuthUser`
+
+### Property
+
+Una proprieta e un campo di un'entita, per esempio:
+
+- `Title`
+- `Author`
+- `CanManagePermissions`
+
+## Azioni
+
+### Azioni entita
+
+- `Query`
+- `Create`
+- `Update`
+- `Delete`
+
+### Azioni proprieta
+
+- `See`
+- `Modify`
+
+I permessi proprieta raffinano un'operazione entita gia consentita. Non sostituiscono i permessi entita.
+
+## Effetti
+
+Ogni regola ha un effetto:
+
+- `Allow`
+- `Deny`
+
+Allo stesso livello di valutazione, `Deny` vince su `Allow`.
+
+## Precedenza
+
+ChillSharp risolve le regole in questo ordine:
+
+1. regole proprieta utente
+2. regole entita utente
+3. regole modulo utente
+4. regole proprieta ruolo
+5. regole entita ruolo
+6. regole modulo ruolo
+7. deny di default
+
+Questo combina due principi:
+
+- le regole utente sovrascrivono quelle dei ruoli
+- le regole piu specifiche sovrascrivono quelle piu ampie
+
+## Come Vengono Valutate Le Operazioni
+
+### Query
+
+Per interrogare un'entita:
+
+1. l'utente deve avere `Query` a livello entita
+2. ogni proprieta restituita deve avere anche `See`
+
+Se una proprieta non e consentita, il server puo rimuoverla, impostarla a null o mascherarla a seconda della superficie chiamante e dell'implementazione.
+
+### Create
+
+Per creare un'entita:
+
+1. l'utente deve avere `Create` a livello entita
+2. ogni proprieta fornita deve avere `Modify`
+
+### Update
+
+Per aggiornare un'entita:
+
+1. l'utente deve avere `Update` a livello entita
+2. ogni proprieta modificata deve avere `Modify`
+
+### Delete
+
+Per eliminare un'entita:
+
+1. l'utente deve avere `Delete` a livello entita
+
+I permessi proprieta non contano nel delete.
+
+## Postura Di Sicurezza Predefinita
+
+Il modello e default-deny.
+
+Se nessuna regola concede accesso, l'accesso viene negato.
+
+Questo e intenzionale. Evita che nuove entita o proprieta diventino visibili solo perche sono state aggiunte al modello.
+
+## Esempi Tipici Di Regole
+
+Consentire la query di tutte le entita blog in un modulo:
+
+```text
+Allow Query Module=Blog
+```
+
+Consentire l'update dei post:
+
+```text
+Allow Update Module=Blog Entity=Post
+```
+
+Bloccare l'editing di una proprieta sensibile pur consentendo update piu ampi:
+
+```text
+Allow Update Module=Blog Entity=Post
+Deny Modify Module=Blog Entity=Post Property=InternalNotes
+```
+
+## Perche Questo Conta Per I Client
+
+I client possono usare gli endpoint di valutazione permessi per:
+
+- disabilitare azioni UI
+- nascondere campi
+- decidere quali editor di proprieta renderizzare
+
+Ma il server resta la fonte di verita. Il filtraggio lato client e comodita, non sicurezza.
+
+## Componenti Runtime Correlati
+
+Il modello di permessi e supportato da:
+
+- `AuthUser`
+- `AuthRole`
+- `AuthUserRole`
+- `AuthPermissionRule`
+
+Gli endpoint di gestione sono esposti tramite `ChillSharp.Auth`.
+
+Per registrazione e flussi account, vedi:
+
+- [AuthenticationModel/README.md](../AuthenticationModel/README.md)

package/doc/it/README.md

@@ -0,0 +1,172 @@
+# Documentazione ChillSharp
+
+Versione originale in inglese: [English](../README.md)
+
+Questa cartella contiene la documentazione di riferimento di ChillSharp.
+
+`doc/HowTo` resta intenzionalmente la sezione tutorial. Usala per esempi guidati e incrementali. Il resto di questa cartella e la versione di riferimento: concetti, registrazione, permessi, autenticazione e workflow di generazione client.
+
+## Mappa Della Documentazione
+
+- [ModelPreparation.md](./ModelPreparation.md)
+  Prepara un modello EF Core in modo che ChillSharp possa attivare le entita, eseguire gli hook del ciclo di vita, generare metadati di schema e salvare i campi di audit.
+
+- [ReferenceExistence.md](./ReferenceExistence.md)
+  Verifica se un riferimento EF Core ha valori di chiave esterna senza caricare l'entita correlata, anche con database senza vincoli FK applicati.
+
+- [RegisterContext.md](./RegisterContext.md)
+  Registra i moduli ChillSharp su un `DbContext` host e mappa la superficie API.
+
+- [AuthenticationModel/README.md](./AuthenticationModel/README.md)
+  Flussi account basati su Identity, endpoint di gestione auth, strategie di bootstrap e configurazione di API protette.
+
+- [CurrentUserPreferences.md](./CurrentUserPreferences.md)
+  Preferenze in cache di cultura, fuso orario e formati dell'utente autenticato per `IChillContext` e gli hook del ciclo di vita delle entita.
+
+- [PermissionModel/README.md](./PermissionModel/README.md)
+  Il modello di permessi usato da `ChillSharp.Auth`, incluse precedenza, scope e modalita di risoluzione dell'accesso a entita e proprieta.
+
+- [ClientGeneration/README.md](./ClientGeneration/README.md)
+  Genera librerie client da un host ChillSharp per TypeScript e Python usando un documento OpenAPI esposto dall'applicazione host.
+
+- [../../ext/chill-sharp-ts-client/README.md](../../ext/chill-sharp-ts-client/README.md)
+  Client TypeScript generico per servizi ChillSharp.
+
+- [../../ext/chill-sharp-react-client/README.md](../../ext/chill-sharp-react-client/README.md)
+  Provider e hook React costruiti sopra il client TypeScript generico.
+
+- [../../ext/chill-sharp-vue-client/README.md](../../ext/chill-sharp-vue-client/README.md)
+  Plugin e composable Vue costruiti sopra il client TypeScript generico.
+
+- [../../ext/chill-sharp-ng-client/README.md](../../ext/chill-sharp-ng-client/README.md)
+  Helper DI Angular e servizio RxJS costruiti sopra il client TypeScript generico.
+
+- [../../ext/chill-sharp-py-client/README.md](../../ext/chill-sharp-py-client/README.md)
+  Client Python generico per servizi ChillSharp.
+
+## Moduli Principali
+
+- `ChillSharp`
+  Motore core per entita, motore DTO e superficie HTTP API.
+
+- `ChillSharp.Schema`
+  Generazione schema, persistenza e cache dello schema.
+
+- `ChillSharp.Auth`
+  Modello di autorizzazione, regole di permesso, gestione ruoli/utenti e integrazione opzionale con ASP.NET Core Identity.
+
+- `ChillSharp.I18n`
+  Endpoint di lookup per label e testi piu cache i18n in memoria.
+
+- `ChillSharp.Client`
+  Client .NET per gli endpoint ChillSharp e ChillSharp.Auth.
+
+- `ext/chill-sharp-ts-client`
+  Pacchetto client TypeScript generico.
+
+- `ext/chill-sharp-react-client`
+  Pacchetto di integrazione React sopra il client TypeScript.
+
+- `ext/chill-sharp-vue-client`
+  Pacchetto di integrazione Vue sopra il client TypeScript.
+
+- `ext/chill-sharp-ng-client`
+  Pacchetto di integrazione Angular sopra il client TypeScript.
+
+- `ext/chill-sharp-py-client`
+  Pacchetto client Python generico.
+
+## Concetti Base
+
+### `IChillContext`
+
+Il tuo contesto EF Core deve implementare `IChillContext`. Definisce:
+
+- il prefisso Chill type usato per l'attivazione dinamica
+- le culture primaria e secondaria usate per interpretare le label di schema
+- il nome utente corrente usato dal tracciamento di audit delle entita
+
+Possono coesistere contesti diversi con valori diversi. ChillSharp non assume una singola configurazione globale.
+
+### `ChillEntity`
+
+`ChillEntity` e la classe base consigliata per i tipi di modello esposti tramite ChillSharp. Fornisce gia:
+
+- `Guid`
+- `Label`, `ShortLabel`, `FullTextContent`
+- `Checksum`, `LastUpdateUser`, `LastUpdate`, `LastUpdateUtcOffset`
+- comportamento di ciclo di vita predefinito
+
+Gli hook disponibili sono:
+
+- `OnCreate`
+- `OnUpdate`
+- `OnAfterUpdate`
+- `OnDelete`
+- `OnAfterDelete`
+- `OnSelect`
+- `OnInflate`
+- `OnAutocomplete`
+
+### Metadati Di Schema
+
+`ChillEntityAttribute` e `ChillPropertyAttribute` forniscono:
+
+- chiavi univoche stabili
+- `PrimaryLanguageLabel`
+- `SecondaryLanguageLabel`
+
+Quando ChillSharp costruisce uno schema, risolve quelle label usando:
+
+- `CultureInfo.CurrentUICulture`
+- `IChillContext.GetPrimaryCultureName()`
+- `IChillContext.GetSecondaryCultureName()`
+
+### Campi Di Audit
+
+Dopo gli aggiornamenti, ChillSharp salva automaticamente:
+
+- `Checksum`
+- `LastUpdateUser`
+- `LastUpdate`
+- `LastUpdateUtcOffset`
+
+La logica di audit e applicata tramite il percorso `IChillEntity` usato da `ChillEngine`, quindi una classe derivata puo ridefinire `OnAfterUpdate()` senza saltare l'aggiornamento di audit della base.
+
+## Superficie API
+
+La superficie API core viene esposta da:
+
+- `app.MapChillApi()`
+
+Questo mappa i controller Chill API e include anche:
+
+- `/api/chill/test`
+- `/api/chill/license`
+
+A seconda dei moduli registrati, lo stesso host puo esporre anche:
+
+- servizi schema tramite `ChillSharp.Schema`
+- servizi auth/account e di gestione permessi tramite `ChillSharp.Auth`
+- endpoint testo i18n tramite `ChillSharp.I18n`
+
+## Riferimento Vs How-To
+
+Usa questa separazione in modo coerente:
+
+- `doc/HowTo`
+  Tutorial passo-passo. Mantienili focalizzati e orientati al task.
+
+- il resto di `doc/`
+  Documentazione di riferimento. Usa questi file quando ti servono modello, registrazione, architettura, regole di permesso o dettagli di integrazione.
+
+## How-To
+
+I tutorial esistenti sono disponibili anche in italiano:
+
+- [HowTo/01-simple-blog-sqlite.md](./HowTo/01-simple-blog-sqlite.md)
+- [HowTo/02-blog-schema-labels.md](./HowTo/02-blog-schema-labels.md)
+- [HowTo/03-authentication.md](./HowTo/03-authentication.md)
+- [HowTo/04-blog-posts-one-to-many.md](./HowTo/04-blog-posts-one-to-many.md)
+- [HowTo/05-docker-env-variables.md](./HowTo/05-docker-env-variables.md)
+- [HowTo/06-chunk-transactions-autocomplete.md](./HowTo/06-chunk-transactions-autocomplete.md)