@chill-sharp/ui-core 1.1.12

package/doc/it/ComplianceGuide/README.md

@@ -0,0 +1,178 @@
+# Guida alla sicurezza e alla conformità
+
+Versione originale in inglese: [English](../../ComplianceGuide/README.md)
+
+
+Questo documento spiega come ChillSharp può supportare programmi di sicurezza e conformità come NIS2, ISO 27001, SOC 2 o policy interne di sviluppo sicuro.
+
+È intenzionalmente generico: i quadri di conformità differiscono in base alla giurisdizione e al settore, ma molti dei controlli tecnici sottostanti sono gli stessi.
+
+Importante: ChillSharp può aiutarti a implementare e applicare automaticamente diversi controlli tecnici, ma l'utilizzo di ChillSharp non rende di per sé conforme un'applicazione. La conformità dipende ancora dall'ambiente di hosting, dalle procedure operative, dal monitoraggio, dalla risposta agli incidenti, dalla strategia di backup e dall'ambito legale.
+
+## Dove ChillSharp aiuta
+
+ChillSharp è utile quando desideri che il tuo livello API applichi le stesse convenzioni di convalida, autorizzazione, metadati e controllo in modo coerente nell'intero modello invece di reimplementarle controller per controller.
+
+Questa coerenza è importante nel lavoro di conformità perché molti risultati derivano da lacune tra endpoint, controlli dimenticati in un percorso di aggiornamento o comportamento dell'interfaccia utente e dell'API che si allontana nel tempo.
+
+## Aree di controllo supportate da ChillSharp
+
+### 1. Convalida dell'input e integrità dei dati
+
+ChillSharp aiuta a ridurre i dati non validi o non sicuri che entrano nel sistema centralizzando la convalida attorno all'entità e al modello di query.
+
+- Annotazioni dati standard come `[Required]`, `[StringLength]`, `[Range]` e `[EmailAddress]` possono essere applicate ai membri `[ChillProperty]`
+- la pipeline di convalida viene eseguita durante i flussi `VALIDATE()` espliciti
+- la stessa validazione viene eseguita automaticamente anche quando il client passa direttamente alla creazione o all'aggiornamento
+- È possibile aggiungere la convalida aziendale personalizzata tramite `OnValidation()`
+
+Ciò supporta gli obiettivi di controllo generalmente descritti come:
+
+- convalida dell'input
+- applicazione della qualità dei dati
+- Convalida lato server sicura per impostazione predefinita
+- riduzione della convalida incoerente tra gli endpoint
+
+Riferimento:
+- [../ValidationModel/README.md](../ValidationModel/README.md)
+
+### 2. Autenticazione e accesso controllato
+
+Con `ChillSharp.Auth`, l'host può esporre flussi di account supportati da identità per:
+
+- registrazione
+- login
+- gestione del token di aggiornamento
+- cambio password
+- reimpostazione della password
+
+Ciò aiuta a standardizzare il livello di accesso ed evitare endpoint di autenticazione ad hoc con comportamenti incoerenti.
+
+Riferimento:
+- [../AuthenticationModel/README.md](../AuthenticationModel/README.md)
+
+### 3. Autorizzazione e privilegio minimo
+
+ChillSharp fornisce un modello di autorizzazione con rifiuto predefinito con:
+
+- autorizzazioni utente
+- autorizzazioni di ruolo
+- ambiti di modulo, entità e proprietà
+- consentire/negare le regole
+- regole di precedenza esplicite
+
+Ciò è utile per i programmi di conformità che prevedono l'accesso con privilegi minimi, la separazione dei compiti e una chiara applicazione lato server di chi può visualizzare o modificare i dati.
+
+Poiché le autorizzazioni a livello di proprietà fanno parte del modello, ChillSharp può aiutare a ridurre un rischio comune: gli utenti hanno accesso all'entità giusta ma hanno troppo accesso ai campi sensibili.
+
+Riferimento:
+- [../PermissionModel/README.md](../PermissionModel/README.md)
+
+### 4. Campi di controllo sulle modifiche dei dati
+
+`ChillEntity` mantiene automaticamente:
+
+- 
+- 
+- 
+- 
+
+Questi valori vengono aggiornati come parte del percorso di runtime utilizzato da ChillSharp durante gli aggiornamenti, il che aiuta a imporre un audit trail minimo coerente senza dipendere da ogni entità derivata per ricordarsi di farlo manualmente.
+
+Ciò supporta obiettivi di controllo comuni quali:
+
+- tracciabilità delle modifiche
+- responsabilità delle azioni dell'utente
+- controllo di integrità di base
+- evidenza che i documenti sono stati modificati, quando e da chi
+
+Il checksum è particolarmente utile come segnale di integrità leggero per scenari di sincronizzazione, confronti e rilevamento di manomissioni all'interno del modello applicativo.
+
+Riferimento:
+- [../README.md](../README.md#audit-fields)
+
+### 5. Metadati dello schema coerenti e generazione di client più sicura
+
+ChillSharp può esporre metadati dello schema e generare client dalla descrizione dell'API.
+
+Ciò non sostituisce di per sé un controllo di sicurezza, ma può ridurre la deriva dell'implementazione tra:
+
+- Convalida backend e moduli frontend
+- Autorizzazione backend e funzionalità frontend
+- Contratti API effettivi e client scritti a mano
+
+Ridurre i problemi di deriva negli audit perché client incoerenti e colla API duplicata spesso creano eccezioni nascoste al modello di controllo previsto.
+
+Riferimento:
+- [../ClientGeneration/README.md](../ClientGeneration/README.md)
+
+## Perché questo è importante per NIS2 e framework simili
+
+Framework come NIS2 di solito non certificano una libreria. Si aspettano che le organizzazioni implementino misure tecniche e organizzative basate sul rischio.
+
+In tale contesto, ChillSharp è meglio inteso come un componente di applicazione del controllo che può aiutare con:
+
+- controllo dell'identità e degli accessi
+- privilegio minimo
+- tracciabilità degli aggiornamenti
+- validazione coerente dei dati in ingresso
+- riduzione della sicurezza manuale idraulica
+
+Ciò può ridurre la probabilità di difetti di implementazione comuni e rendere l'applicazione più facile da rivedere durante gli audit interni o le valutazioni esterne.
+
+## Cosa ChillSharp non risolve da solo
+
+È ancora necessario progettare e gestire il sistema di sicurezza più ampio attorno alla biblioteca. In particolare, ChillSharp non fornisce di per sé:
+
+- una strategia SIEM completa o di registrazione di sicurezza centralizzata
+- procedure di rilevamento e risposta agli incidenti
+- gestione delle vulnerabilità e governance delle patch
+- rafforzamento delle infrastrutture
+- segmentazione della rete
+- configurazione della sicurezza del trasporto
+- gestione delle chiavi di crittografia
+- gestione dei segreti
+- processi di backup e disaster recovery
+- Politica del MAE e governance dell'identità aziendale
+- gestione del rischio fornitori
+- interpretazione giuridica di NIS2 o di qualsiasi altro regolamento
+
+Questi controlli appartengono in parte alla tua applicazione, ma soprattutto alla tua piattaforma e ai processi organizzativi.
+
+## Posizionamento consigliato nella documentazione di revisione
+
+Quando si documenta ChillSharp in una revisione della sicurezza, descriverlo come:
+
+- un framework che centralizza la convalida delle API
+- un framework che impone l'autorizzazione basata su ruoli e proprietà
+- un framework che mantiene i metadati di controllo di base sugli aggiornamenti dell'entità
+- un framework che riduce il codice CRUD personalizzato incoerente
+
+Evita affermazioni più forti come:
+
+- "l'applicazione è compatibile con NIS2 perché utilizza ChillSharp"
+- "ChillSharp garantisce la conformità normativa"
+
+L’affermazione più forte e più difendibile è:
+
+"ChillSharp aiuta a implementare e automatizzare diversi controlli tecnici comunemente richiesti dai framework di sicurezza e conformità, mentre la conformità finale dipende dalla progettazione dell'intero sistema e dal modello operativo."
+
+## Lista di controllo pratica
+
+Se desideri utilizzare ChillSharp come parte di un'architettura orientata alla conformità, la linea di base è:
+
+1. utilizzare `ChillEntity` e annotare le proprietà esposte con `[ChillProperty]`
+2. aggiungere DataAnnotations e regole `OnValidation()` personalizzate per i vincoli aziendali
+3. abilitare `ChillSharp.Auth` per i sistemi autenticati
+4. configurare ruoli e regole di autorizzazione con atteggiamento di rifiuto predefinito
+5. verifica che `GetCurrentUserName()` sia correttamente implementato nel tuo `IChillContext`
+6. preservare e monitorare `LastUpdate`, `LastUpdateUtcOffset`, `LastUpdateUser` e `Checksum`
+7. proteggere l'host con HTTPS, registrazione, backup, patch e controlli operativi esterni a ChillSharp
+
+## Documenti correlati
+
+- [../ValidationModel/README.md](../ValidationModel/README.md)
+- [../AuthenticationModel/README.md](../AuthenticationModel/README.md)
+- [../PermissionModel/README.md](../PermissionModel/README.md)
+- [../ClientGeneration/README.md](../ClientGeneration/README.md)
+- [../RegisterContext.md](../RegisterContext.md)

package/doc/it/Configuration/README.md

@@ -0,0 +1,94 @@
+# Riferimento alla configurazione di ChillSharp
+
+Versione originale in inglese: [English](../../Configuration/README.md)
+
+
+Questo documento elenca le variabili di ambiente attualmente utilizzate da ChillSharp e dall'host ChillSharp di esempio in `ChillSharp.Examples/BloggingApiService`.
+
+Utilizzalo come riferimento rapido durante la configurazione di Docker, `docker compose` o un'altra destinazione di distribuzione.
+
+All'avvio, `AddChillApi<TContext>()` scrive tutte le variabili di ambiente del processo `CHILLSHARP_` e `CHILL_SHARP_` nella console. I nomi delle variabili contenenti `PASSWORD` vengono mascherati come `********`.
+
+## Ospitalità
+
+| Opzione | Variabile ENV | Descrizione | Predefinito |
+| --- | --- | --- | --- |
+| URL di ascolto ASP.NET Core |  | URL associati dall'host ASP.NET Core. |  |
+| Ambiente ASP.NET Core |  | Nome dell'ambiente ASP.NET Core standard. | `Development` nell'esempio `.env` |
+
+## API principale
+
+| Opzione | Variabile ENV | Descrizione | Predefinito |
+| --- | --- | --- | --- |
+| Percorso del database SQLite |  | Percorso del file utilizzato dal database SQLite di esempio `BloggingContext`. |  |
+| Cultura primaria |  | Valore restituito da `IChillContext.GetPrimaryCultureName()`. |  |
+| Cultura secondaria |  | Valore restituito da `IChillContext.GetSecondaryCultureName()`. |  |
+| API principale protetta |  | Richiede l'autenticazione per l'API ChillSharp principale quando `true`. | `true` quando l'autenticazione è abilitata |
+| Fuso orario del sistema DTO |  | ID fuso orario IANA utilizzato dagli helper di analisi e serializzazione ChillSharp DTO `DateTime` e `DateTimeOffset`. | ZZGETTONE PROTETTO3ZZ |
+
+## Attiva/disattiva il modulo
+
+| Opzione | Variabile ENV | Descrizione | Predefinito |
+| --- | --- | --- | --- |
+| Abilita modulo schema |  | Registra i servizi `ChillSharp.Schema`. |  |
+| Abilita modulo di autenticazione |  | Registra l'account `ChillSharp.Auth` e i servizi di gestione dell'autenticazione. |  |
+| Abilita modulo i18n |  | Registra i servizi `ChillSharp.I18n`. |  |
+| Abilita modulo MCP |  | Registra i servizi `ChillSharp.Mcp` e mappa l'endpoint MCP quando il contesto host supporta i metadati dello schema. |  |
+| Abilita modulo allegati |  | Registra i servizi e gli endpoint `ChillSharp.Attachment` quando il contesto host supporta gli allegati. | `false` nell'host di esempio, imposta `true` quando il contesto implementa gli allegati |
+
+## Archiviazione degli allegati
+
+| Opzione | Variabile ENV | Descrizione | Predefinito |
+| --- | --- | --- | --- |
+| Radice archivio allegati |  | Cartella principale utilizzata da `ChillSharp.Attachment` per leggere e archiviare file archiviati. | `attachments` nella directory di base dell'host |
+
+## Token di autenticazione e flussi di password
+
+| Opzione | Variabile ENV | Descrizione | Predefinito |
+| --- | --- | --- | --- |
+| Durata del token di accesso |  | Minuti prima della scadenza del token di accesso portatore ChillSharp. Leggere direttamente da `ChillAuthIdentityApiOptions` e `ChillIdentityApiOptions` a meno che l'host non sovrascriva `AccessTokenLifetime` nel codice. | ZZGETTONE PROTETTO4ZZ |
+| Durata del token di aggiornamento |  | Giorni prima della scadenza del token di aggiornamento. Leggere direttamente da `ChillAuthIdentityApiOptions` e `ChillIdentityApiOptions` a meno che l'host non sovrascriva `RefreshTokenLifetime` nel codice. | ZZGETTONE PROTETTO4ZZ |
+| Restituisci il token di reimpostazione nella risposta API |  | Include `userId` e `resetToken` nella risposta `/api/chill-auth/account/request-password-reset` quando `true`. | `false` nell'host di esempio |
+| Invia e-mail di reimpostazione della password |  | Invia un'e-mail di reimpostazione della password tramite SMTP quando `true`. | `false` nel codice, `true` nell'esempio `.env` |
+| Oggetto dell'e-mail di reimpostazione della password |  | Oggetto utilizzato per le email di reimpostazione della password. |  |
+| URL di reimpostazione password |  | URL frontend facoltativo utilizzato per creare un collegamento selezionabile per la reimpostazione della password con `userId` e `resetToken`. | non impostato |
+
+## Consegna con reimpostazione password SMTP
+
+| Opzione | Variabile ENV | Descrizione | Predefinito |
+| --- | --- | --- | --- |
+| Host SMTP |  | Nome host del server SMTP utilizzato per la consegna senza risposta con reimpostazione della password. | non impostato |
+| Porta SMTP |  | Porta del server SMTP. |  |
+| SMTP SSL/TLS |  | Abilita SSL/TLS sul client SMTP quando `true`. |  |
+| Nome utente SMTP |  | Nome utente di autenticazione SMTP. | non impostato |
+| Password SMTP |  | Password di autenticazione SMTP. | non impostato |
+| E-mail del mittente senza risposta |  | Indirizzo e-mail del mittente utilizzato per le e-mail di reimpostazione della password. | non impostato |
+| Nome visualizzato del mittente senza risposta |  | Nome visualizzato del mittente utilizzato per le e-mail di reimpostazione della password. | non impostato |
+
+Quando `CHILLSHARP_AUTH_SEND_PASSWORD_RESET_EMAILS=true`, l'host SMTP e l'e-mail del mittente devono essere configurati altrimenti il ​​flusso di reimpostazione non riuscirà.
+
+## Bootstrap utente root
+
+Queste variabili vengono lette da `ChillAuthRootUserInitializer<TUser>` durante l'avvio quando è abilitata l'inizializzazione dell'utente root.
+
+| Opzione | Variabile ENV | Descrizione | Predefinito |
+| --- | --- | --- | --- |
+| Inizializza l'utente root |  | Crea l'utente identità root all'avvio quando le credenziali sono disponibili. |  |
+| Crea utente di autenticazione ChillSharp collegato |  | Crea inoltre l'oggetto ChillSharp `AuthUser` collegato con accesso alla gestione delle autorizzazioni. |  |
+| Nome utente root |  | Nome di accesso per l'amministratore bootstrap. | non impostato |
+| Password di root |  | Password per l'amministratore del bootstrap. | non impostato |
+| E-mail di root |  | E-mail facoltativa per l'amministratore bootstrap. | non impostato |
+| Nome visualizzato radice |  | Nome visualizzato copiato nel ChillSharp `AuthUser` collegato. | `Root` nel codice |
+
+## Note
+
+- La maggior parte delle variabili elencate qui utilizzano il prefisso `CHILLSHARP_*` dell'host di esempio. `CHILLSHARP_SYSTEM_TIMEZONE` è una variabile di runtime ChillSharp principale utilizzata direttamente dalla mappatura data/ora DTO.
+- L'output della console di avvio include entrambe le variabili `CHILLSHARP_*` e `CHILL_SHARP_*`. I valori `PASSWORD` vengono mascherati, ma gli altri valori vengono stampati così come sono.
+- `CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES` e `CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS` sono impostazioni predefinite di autenticazione ChillSharp integrate. Sono accettati valori interi positivi; i valori non validi, zero o negativi rientrano nei valori predefiniti del codice.
+- `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT` viene letto direttamente da `ChillSharp.Attachment` e dovrebbe puntare a un volume persistente in Docker.
+- `CHILLSHARP_SYSTEM_TIMEZONE` prevede un ID fuso orario IANA come `Europe/Rome` o `America/New_York`.
+- `CHILLSHARP_SYSTEM_TIMEZONE` influisce su `DateTime` e alcuni percorsi di normalizzazione `DateTimeOffset`. `DateOnly` e `TimeOnly` mantengono l'output di stringa .NET standard.
+- Le variabili `CHILLSHARP_*` elencate qui vengono utilizzate da ChillSharp stesso o dal codice di avvio dell'host di esempio.
+- Se crei la tua applicazione host, puoi mantenere questi nomi o la configurazione della mappa in modo diverso nel tuo codice di avvio.
+- Per esempi di distribuzione, vedere anche [doc/HowTo/05-docker-env-variables.md](../HowTo/05-docker-env-variables.md).
+- Per riferimenti ed esempi completi sulla serializzazione di data/ora, vedere [doc/DateTimeSerialization.md](../DateTimeSerialization.md).

package/doc/it/CurrentUserPreferences.md

@@ -0,0 +1,114 @@
+# Preferenze Dell'Utente Corrente
+
+English version: [English](../CurrentUserPreferences.md)
+
+`ChillSharp.Auth` puo rendere disponibili agli hook del ciclo di vita delle entita le preferenze di visualizzazione dell'utente autenticato senza interrogare `AuthUser` a ogni salvataggio.
+
+Lo snapshot immutabile `ChillUserPreferences` contiene:
+
+- `DisplayCultureName`
+- `DisplayTimeZone`
+- `DisplayDateFormat`
+- `DisplayNumberFormat`
+- `PreferredTheme`
+
+## Registrazione E Ciclo Di Vita Della Cache
+
+`AddChillAuthApi<TContext>()` registra il singleton `IChillAuthUserPreferencesCache` e lo scoped `IChillAuthUserPreferencesAccessor`.
+
+Quando l'utente esegue il login o rinnova un token, ChillSharp carica una volta l'`AuthUser` corrispondente e inizializza uno snapshot associato al suo `ExternalId`. L'accessor legge solo quello snapshot in memoria durante le richieste; non interroga la tabella utenti.
+
+`ChillAuthService` aggiorna lo snapshot in cache dopo la creazione o l'aggiornamento di un `AuthUser`. Invalida lo snapshot di un utente eliminato ed entrambe le chiavi, precedente e nuova, quando cambia `ExternalId`.
+
+La cache memorizza valori scalari delle preferenze, mai un'istanza EF Core tracciata di `AuthUser`.
+
+## API delle preferenze dell'utente corrente
+
+I client autenticati possono recuperare lo stesso snapshot utilizzato dal codice server con:
+
+```http
+GET /api/chill-auth/current-user-preferences
+Authorization: Bearer <access token>
+```
+
+La risposta e un oggetto JSON `ChillUserPreferences`:
+
+```json
+{
+  "displayCultureName": "it-IT",
+  "displayTimeZone": "Europe/Rome",
+  "displayDateFormat": "dd/MM/yyyy",
+  "displayNumberFormat": "N2",
+  "preferredTheme": "cini"
+}
+```
+
+Usa questo endpoint dopo il login e durante il ripristino di una sessione UI autenticata. E la fonte autorevole per lingua/cultura, fuso orario, formato data e formato numerico usati dal client API e dalla UI; non ricavare tali valori dal browser, dal sistema operativo, dalle claim del token o da un endpoint di gestione dell'autenticazione.
+
+Il client C# espone `GetCurrentUserPreferences()`. Il client Python espone `get_current_user_preferences()`, mentre il client TypeScript e il wrapper Angular espongono `getCurrentUserPreferences()`. I pacchetti Vue e React forniscono inoltre `useCurrentUserPreferences()`.
+
+Nel pacchetto Angular UI Core, inietta `ChillService` e usa il signal `userPreferences` oppure le singole proiezioni `displayCultureName`, `displayTimeZone`, `displayDateFormat`, `displayNumberFormat` e `preferredTheme`. Usali per la cultura dei testi UI, le operazioni di formato/analisi di date e numeri, la conversione degli orari UTC in locali e il tema selezionato.
+
+`PreferredTheme` e una stringa opaca: il backend la salva e la restituisce senza conoscere i temi forniti dal client. UI Core usa la scelta del browser `prefers-color-scheme` (`bright` o `dark`) quando non esiste una preferenza autenticata. Le applicazioni client possono dichiarare temi aggiuntivi selezionabili durante la registrazione di UI Core:
+
+```ts
+provideChillSharpUiCore({ additionalThemes: ['cini'] })
+```
+
+Le scelte integrate sono `bright`, `dark` e `soft`. Se il valore salvato di un utente autenticato non e disponibile nel client, UI Core torna alla preferenza chiara/scura del browser.
+
+## DbContext Host
+
+Per impostazione predefinita `IChillContext.GetCurrentUserPreferences()` restituisce `ChillUserPreferences.Empty`. In un contesto host personalizzato con auth abilitata, inietta `IChillAuthUserPreferencesAccessor` e delega a esso:
+
+```csharp
+using ChillSharp;
+using ChillSharp.Auth.Services;
+
+public class AppDbContext : DbContext, IChillContext, IChillAuthDbContext
+{
+    private readonly IChillAuthUserPreferencesAccessor? _userPreferencesAccessor;
+
+    public AppDbContext(
+        DbContextOptions<AppDbContext> options,
+        IChillAuthUserPreferencesAccessor? userPreferencesAccessor = null)
+        : base(options)
+    {
+        _userPreferencesAccessor = userPreferencesAccessor;
+    }
+
+    public ChillUserPreferences GetCurrentUserPreferences() =>
+        _userPreferencesAccessor?.Current ?? ChillUserPreferences.Empty;
+
+    public string GetDefaultUserCultureName()
+    {
+        var cultureName = GetCurrentUserPreferences().DisplayCultureName;
+        return string.IsNullOrWhiteSpace(cultureName)
+            ? GetPrimaryCultureName()
+            : cultureName;
+    }
+}
+```
+
+Il parametro opzionale del costruttore mantiene compatibile la creazione a design-time e i test che costruiscono direttamente il contesto. Un contesto creato normalmente dalla dependency injection riceve l'accessor.
+
+`ChillAuthDbContext` implementa gia questo schema.
+
+## Hook Del Ciclo Di Vita Delle Entita
+
+Usa lo snapshot direttamente dall'`IChillContext` fornito. Nell'hook non e necessario alcun accesso al database.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var preferences = context.GetCurrentUserPreferences();
+    var timeZone = preferences.DisplayTimeZone;
+
+    if (!string.IsNullOrWhiteSpace(timeZone))
+    {
+        // Applica il comportamento relativo al fuso orario dell'applicazione.
+    }
+}
+```
+
+Tutti i valori possono essere vuoti per job in background, chiamate non autenticate o un utente senza un `AuthUser` corrispondente. Considerali opzionali e scegli un fallback dell'applicazione. Valida `DisplayTimeZone` prima di usarlo come identificatore di fuso orario.

package/doc/it/DateTimePolicy/README.md

@@ -0,0 +1,154 @@
+# Politica DateTime di ChillSharp
+
+Versione originale in inglese: [English](../../DateTimePolicy/README.md)
+
+
+Questo documento definisce la policy DTO di ChillSharp per i valori `DateTime` e `DateTimeOffset`.
+
+La policy si applica quando ChillSharp legge o scrive valori tramite contenitori di proprietà DTO, come `ChillDtoEntity.Properties` e `ChillDtoQuery.Properties`.
+
+## Fuso orario del sistema
+
+ChillSharp utilizza un fuso orario di sistema configurato quando un valore DTO non presenta un offset esplicito.
+
+Variabile d'ambiente:
+
+```text
+CHILLSHARP_SYSTEM_TIMEZONE
+```
+
+Predefinito:
+
+```text
+Europe/Rome
+```
+
+Utilizza un ID fuso orario IANA, ad esempio:
+
+```text
+Europe/Rome
+America/New_York
+UTC
+```
+
+Questo fuso orario configurato non è la stessa cosa di `DateTimeKind.Local`. `DateTimeKind.Local` indica il fuso orario locale del sistema operativo. ChillSharp utilizza esplicitamente il proprio fuso orario configurato.
+
+## Valori DTO in entrata
+
+I valori in ingresso sono valori ricevuti da un client e applicati alle proprietà CLR.
+
+### DateTimeOffset
+
+`DateTimeOffset` conserva un offset esplicito quando il client ne invia uno.
+
+Esempi:
+
+```text
+2026-04-11T14:30:00.0000000+02:00
+2026-04-11T12:30:00.0000000Z
+```
+
+Politica:
+
+- se il valore in ingresso ha `Z`, conservalo come UTC `DateTimeOffset`
+- se il valore in entrata ha un offset esplicito, preserva tale offset
+- se il valore in ingresso non ha offset, interpretarlo come ora locale in `CHILLSHARP_SYSTEM_TIMEZONE`
+- memorizzare il valore risultante come `DateTimeOffset` con l'offset risolto
+
+Esempio con `CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome`:
+
+```text
+Incoming: 2026-04-11T14:30:00
+Stored:   2026-04-11T14:30:00+02:00
+```
+
+### Data e ora
+
+`DateTime` rappresenta un istante ed è normalizzato in UTC quando letto dall'ingresso DTO.
+
+Politica:
+
+- se il valore in ingresso ha `Z`, analizzalo come UTC
+- se il valore in entrata ha un offset esplicito, analizzalo come quell'istante
+- se il valore in ingresso non ha offset, interpretarlo come ora locale in `CHILLSHARP_SYSTEM_TIMEZONE`
+- memorizzare il valore risultante come UTC `DateTime`
+- imposta `DateTime.Kind` su `DateTimeKind.Utc`
+
+Esempio con `CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome`:
+
+```text
+Incoming: 2026-04-11T14:30:00
+Stored:   2026-04-11T12:30:00Z
+Kind:     Utc
+```
+
+Esempio con un offset esplicito:
+
+```text
+Incoming: 2026-04-11T14:30:00+02:00
+Stored:   2026-04-11T12:30:00Z
+Kind:     Utc
+```
+
+## Valori DTO in uscita
+
+I valori in uscita sono valori CLR serializzati nei contenitori delle proprietà DTO prima di restituire i dati a un client.
+
+### DateTimeOffset
+
+ChillSharp serializza `DateTimeOffset` come stringa ISO 8601 con il relativo offset.
+
+```text
+2026-04-11T14:30:00.0000000+02:00
+```
+
+### Data e ora
+
+ChillSharp serializza `DateTime` come stringa ISO 8601 con un offset esplicito.
+
+Politica:
+
+- se il valore di origine è UTC, convertirlo in `CHILLSHARP_SYSTEM_TIMEZONE` per l'output DTO
+- se il valore di origine non è specificato, interpretarlo come ora locale in `CHILLSHARP_SYSTEM_TIMEZONE`
+- emettere una stringa ISO 8601 con l'offset risolto
+
+Esempio con `CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome`:
+
+```text
+CLR:      2026-04-11T12:30:00Z
+DTO:      2026-04-11T14:30:00.0000000+02:00
+```
+
+A seconda del serializzatore JSON, il carattere `+` potrebbe apparire come `\u002B` sul cavo:
+
+```json
+"2026-04-11T14:30:00.0000000\u002B02:00"
+```
+
+Questo è un JSON valido e i client lo rileggono come `+02:00`.
+
+## Guida al database
+
+Questa policy è progettata per funzionare in modo pulito con provider come PostgreSQL/Npgsql.
+
+Mappatura consigliata:
+
+- utilizzare `DateTime` per valori istantanei che devono essere mantenuti come UTC
+- utilizzare `DateTimeOffset` quando si preservano le questioni di offset in entrata
+- utilizzare `DateOnly` e `TimeOnly` per date di calendario o ore del giorno che non siano istantanee
+
+Per PostgreSQL:
+
+- I valori `DateTime` prodotti dall'analisi DTO sono UTC e sono adatti per `timestamp with time zone`
+- i valori dell'orologio locale non devono essere modellati come `DateTime` a meno che non si intenda convertirli in UTC
+
+## Campi di controllo gestiti dal server
+
+I campi di controllo gestiti dal server ChillSharp vengono ignorati quando si applicano i valori DTO dell'entità in entrata:
+
+- 
+- 
+- 
+- 
+
+I client possono ricevere questi valori dall'output DTO, ma il loro invio non sovrascrive lo stato dell'entità gestita dal server.