@chill-sharp/ui-core 1.1.12 → 1.1.15

package/doc/it/DateTimeSerialization.md

@@ -1,423 +0,0 @@
-# Serializzazione di data e ora ChillSharp
-
-Versione originale in inglese: [English](../DateTimeSerialization.md)
-
-
-Questo documento spiega come ChillSharp serializza e analizza i valori `DateTimeOffset`, `DateTime`, `DateOnly` e `TimeOnly` nei payload DTO.
-
-Confronta inoltre il comportamento di ChillSharp con il comportamento predefinito ASP.NET Core `System.Text.Json` in modo da poter vedere rapidamente qual è il comportamento .NET standard e qual è il comportamento specifico di ChillSharp.
-
-## Perché è importante
-
-ChillSharp sposta i dati attraverso i contenitori delle proprietà DTO anziché tramite parametri del controller fortemente tipizzati. Ciò significa che i valori di data e ora vengono convertiti esplicitamente all'interno del mappatore DTO.
-
-Per la maggior parte delle applicazioni le domande importanti sono:
-
-- quale formato di stringa lascia il server
-- quale formato di stringa il server accetta in input
-- se gli offset e i fusi orari vengono preservati, normalizzati o ignorati
-
-ChillSharp ora segue il comportamento .NET standard per `DateOnly` e `TimeOnly`, accettando comunque stringhe data-ora ISO 8601 complete durante la rilettura in tali tipi CLR.
-
-## Tabella di confronto rapido
-
-| Tipo CLR | ASP.NET Core predefinito/`System.Text.Json` | Uscita ChillSharp |
-| --- | --- | --- |
-|  | Data-ora ISO 8601 con offset | Data-ora ISO 8601 con offset |
-|  | Data-ora ISO 8601, basato su `DateTime.Kind` | Data e ora ISO 8601 convertite nel fuso orario del sistema ChillSharp |
-|  |  |  |
-|  |  |  |
-
-## Fuso orario del sistema ChillSharp
-
-ChillSharp utilizza un fuso orario di sistema configurabile solo per `DateTime` e alcuni casi di normalizzazione `DateTimeOffset`.
-
-Variabile d'ambiente:
-
-```text
-CHILLSHARP_SYSTEM_TIMEZONE
-```
-
-Predefinito:
-
-```text
-Europe/Rome
-```
-
-Valore atteso:
-
-- un ID fuso orario IANA come `Europe/Rome`
-- un altro esempio è `America/New_York`
-
-Questa impostazione **non** modifica il formato di output di `DateOnly` o `TimeOnly`.
-
-## Serializzazione in uscita
-
-La serializzazione in uscita avviene quando ChillSharp legge i valori CLR di entità/query e li scrive in DTO `Properties`.
-
-### `DateTimeOffset`
-
-ChillSharp scrive `DateTimeOffset` esattamente come data-ora ISO 8601 con offset.
-
-Esempio di valore CLR:
-
-```csharp
-new DateTimeOffset(2026, 4, 11, 14, 30, 0, TimeSpan.FromHours(2))
-```
-
-Serializzato da ChillSharp:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-Questo è effettivamente allineato con la normale serializzazione JSON ASP.NET Core.
-
-### `DateTime`
-
-ChillSharp scrive `DateTime` come data/ora ISO 8601 nel fuso orario del sistema ChillSharp configurato.
-
-Se il valore di origine è UTC, ChillSharp lo converte nel fuso orario del sistema configurato prima della scrittura.
-
-Esempio con `CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome`:
-
-```csharp
-new DateTime(2026, 4, 11, 12, 30, 0, DateTimeKind.Utc)
-```
-
-Serializzato da ChillSharp:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-Un altro esempio con un `DateTime` non specificato:
-
-```csharp
-new DateTime(2026, 4, 11, 14, 30, 0, DateTimeKind.Unspecified)
-```
-
-Serializzato da ChillSharp:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-La differenza rispetto al semplice ASP.NET Core è che ChillSharp applica in modo coerente un fuso orario di sistema configurato durante la scrittura di `DateTime`.
-
-### `DateOnly`
-
-ChillSharp ora mantiene il comportamento .NET standard per `DateOnly`.
-
-Esempio di valore CLR:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-Serializzato da ChillSharp:
-
-```json
-"2026-04-11"
-```
-
-Questo è intenzionalmente semplice. Non sono presenti offset, componenti temporali e conversioni del fuso orario sull'output.
-
-### `TimeOnly`
-
-ChillSharp ora mantiene il comportamento .NET standard per `TimeOnly`.
-
-Esempio di valore CLR:
-
-```csharp
-new TimeOnly(14, 30, 15, 123)
-```
-
-Serializzato da ChillSharp:
-
-```json
-"14:30:15.1230000"
-```
-
-Non è presente alcuna conversione di data e fuso orario sull'output.
-
-## Analisi in entrata
-
-L'analisi in entrata avviene quando ChillSharp legge DTO `Properties` e li applica a oggetti CLR entità/query.
-
-Questo è il lato più permissivo del mappatore.
-
-### `DateTimeOffset` regole di input
-
-Se il JSON in entrata contiene:
-
-- 
-- un offset UTC esplicito
-
-e il target CLR è `DateTimeOffset`, ChillSharp si comporta in questo modo:
-
-- se il valore è UTC (`Z` o `+00:00`), converte il valore nel fuso orario del sistema ChillSharp configurato
-- Se il valore ha un altro offset esplicito, mantiene l'offset così com'è
-
-Ingresso di esempio:
-
-```json
-"2026-04-11T12:30:00Z"
-```
-
-Memorizzato in una proprietà `DateTimeOffset` con fuso orario del sistema `Europe/Rome`:
-
-```csharp
-2026-04-11 14:30:00 +02:00
-```
-
-Ingresso di esempio:
-
-```json
-"2026-04-11T12:30:00+01:00"
-```
-
-Memorizzato in una proprietà `DateTimeOffset`:
-
-```csharp
-2026-04-11 12:30:00 +01:00
-```
-
-### `DateTime` regole di input
-
-Se la destinazione CLR è `DateTime`:
-
-- L'input UTC viene convertito nel fuso orario del sistema ChillSharp configurato
-- Anche l'input con un offset esplicito viene convertito nel fuso orario del sistema ChillSharp configurato
-- l'input senza offset viene analizzato come un normale valore data-ora
-
-Ingresso di esempio:
-
-```json
-"2026-04-11T12:30:00Z"
-```
-
-Memorizzato in una proprietà `DateTime` con fuso orario del sistema `Europe/Rome`:
-
-```csharp
-2026-04-11 14:30:00
-```
-
-Ingresso di esempio:
-
-```json
-"2026-04-11T12:30:00+01:00"
-```
-
-Memorizzato in una proprietà `DateTime` con fuso orario del sistema `Europe/Rome`:
-
-```csharp
-2026-04-11 13:30:00
-```
-
-### `DateOnly` regole di input
-
-Se la destinazione CLR è `DateOnly`, ChillSharp estrae solo l'anno, il mese e il giorno.
-
-Ciò significa che accetta entrambi:
-
-- una semplice stringa di data
-- una stringa data-ora ISO 8601 completa
-
-e ignora le informazioni su ora, offset e fuso orario.
-
-Ingresso di esempio:
-
-```json
-"2026-04-11"
-```
-
-Memorizzato come:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-Ingresso di esempio:
-
-```json
-"2026-04-11T23:59:58.321-05:00"
-```
-
-Memorizzato come:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-Questa regola è intenzionale. `DateOnly` rappresenta solo una data di calendario, quindi ChillSharp scarta i dettagli di ora e zona durante l'assegnazione.
-
-### `TimeOnly` regole di input
-
-Se la destinazione CLR è `TimeOnly`, ChillSharp estrae solo la parte temporale.
-
-Ciò significa che accetta entrambi:
-
-- una semplice stringa temporale
-- una stringa data-ora ISO 8601 completa
-
-e ignora le informazioni su data, offset e fuso orario.
-
-Ingresso di esempio:
-
-```json
-"14:30:15.1230000"
-```
-
-Memorizzato come:
-
-```csharp
-new TimeOnly(14, 30, 15, 123)
-```
-
-Ingresso di esempio:
-
-```json
-"2026-04-11T23:59:58.321-05:00"
-```
-
-Memorizzato come:
-
-```csharp
-new TimeOnly(23, 59, 58, 321)
-```
-
-Ciò è utile quando i client inviano un timestamp completo ma il campo di destinazione rappresenta concettualmente solo l'ora dell'orologio locale.
-
-## Esempi affiancati
-
-Assumere:
-
-```text
-CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome
-```
-
-### Esempio 1: `DateTimeOffset`
-
-Valore CLR:
-
-```csharp
-new DateTimeOffset(2026, 4, 11, 14, 30, 0, TimeSpan.FromHours(2))
-```
-
-Output ASP.NET Core predefinito:
-
-```json
-"2026-04-11T14:30:00+02:00"
-```
-
-Uscita ChillSharp:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-### Esempio 2: `DateTime` in UTC
-
-Valore CLR:
-
-```csharp
-new DateTime(2026, 4, 11, 12, 30, 0, DateTimeKind.Utc)
-```
-
-Output ASP.NET Core predefinito:
-
-```json
-"2026-04-11T12:30:00Z"
-```
-
-Uscita ChillSharp:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-### Esempio 3: `DateOnly`
-
-Valore CLR:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-Output ASP.NET Core predefinito:
-
-```json
-"2026-04-11"
-```
-
-Uscita ChillSharp:
-
-```json
-"2026-04-11"
-```
-
-### Esempio 4: `TimeOnly`
-
-Valore CLR:
-
-```csharp
-new TimeOnly(14, 30, 15, 123)
-```
-
-Output ASP.NET Core predefinito:
-
-```json
-"14:30:15.1230000"
-```
-
-Uscita ChillSharp:
-
-```json
-"14:30:15.1230000"
-```
-
-### Esempio 5: timestamp completo inviato a `DateOnly`
-
-JSON in entrata:
-
-```json
-"2026-04-11T23:59:58.321-05:00"
-```
-
-Archiviato da ChillSharp in una proprietà `DateOnly`:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-### Esempio 6: timestamp completo inviato a `TimeOnly`
-
-JSON in entrata:
-
-```json
-"2026-04-11T23:59:58.321-05:00"
-```
-
-Archiviato da ChillSharp in una proprietà `TimeOnly`:
-
-```csharp
-new TimeOnly(23, 59, 58, 321)
-```
-
-## Guida pratica
-
-- Utilizzare `DateTimeOffset` quando l'offset stesso è importante e deve sopravvivere ai viaggi di andata e ritorno.
-- Utilizzare `DateTime` quando l'applicazione considera un valore come l'ora locale nel fuso orario del sistema ChillSharp configurato.
-- Utilizza `DateOnly` per compleanni, date contabili, date lavorative, scadenze per giorno di calendario e concetti simili.
-- Utilizzare `TimeOnly` per orari di apertura, orari degli appuntamenti e altri valori che non sono intenzionalmente timestamp completi.
-
-## Configurazione correlata
-
-Per il riferimento alle variabili d'ambiente, vedere:
-
-- [Configurazione/README.md](./Configuration/README.md)
-
-Per esempi di Docker e ambiente runtime, vedere:
-
-- [HowTo/05-docker-env-variables.md](./HowTo/05-docker-env-variables.md)

package/doc/it/Endpoints.md

@@ -1,260 +0,0 @@
-# Endpoint ChillSharp
-
-Versione originale in inglese: [English](../Endpoints.md)
-
-
-Questo documento elenca gli endpoint HTTP, SignalR e MCP esposti dai moduli API ChillSharp integrati.
-
-## Percorso base
-
-Gli endpoint ChillSharp sono montati in un percorso base API configurabile.
-
-Predefinito:
-
-```text
-/api
-```
-
-Configurazione:
-
-```text
-CHILLSHARP_API_BASE_PATH=/api
-```
-
-o nel codice:
-
-```csharp
-builder.Services.AddChillApi<MyDbContext>(options =>
-{
-    options.ApiBasePath = "/api";
-});
-
-app.MapChillApi();
-```
-
-Gli esempi seguenti utilizzano il percorso di base predefinito `/api`. Se imposti `CHILLSHARP_API_BASE_PATH=/backend`, sostituisci `/api` con `/backend`.
-
-## Radice e diagnostica
-
-Questi endpoint sono registrati da `MapChillApi()`.
-
-| Metodo | Percorso | Descrizione |
-| --- | --- | --- |
-| OTTIENI |  | Risposta sanitaria di base di ChillSharp, abbinata anche quando i chiamanti richiedono `/api/`. |
-| OTTIENI |  | Risposta sanitaria di base di ChillSharp. |
-| OTTIENI |  | Restituisce la licenza ChillSharp e i metadati del progetto. |
-
-## API DTO principale
-
-Questi endpoint sono abilitati da `AddChillApi<TContext>()` e sono disponibili quando viene registrata l'API Chill di base.
-
-Itinerario base:
-
-```text
-/api/chill
-```
-
-| Metodo | Percorso | Descrizione |
-| --- | --- | --- |
-| POST |  | Esegue un `ChillDtoQuery` dinamico. |
-| POST |  | Esegue una ricerca full-text rispetto al tipo di entità richiesto. |
-| POST |  | Trova un'entità per tipo e GUID. |
-| POST |  | Crea un'entità da `ChillDtoEntity`. |
-| POST |  | Aggiorna un'entità da `ChillDtoEntity`. |
-| POST |  | Elimina un'entità identificata da `ChillDtoEntity`. |
-| POST |  | Esegue la logica di completamento automatico per un'entità o una query DTO. |
-| POST |  | Esegue la convalida per un'entità o una query DTO. |
-| POST |  | Esegue un elenco di operazioni di raffreddamento in una richiesta. |
-
-Quando i servizi ACL dell'entità vengono registrati e il chiamante viene autenticato, questi endpoint possono anche applicare autorizzazioni a livello di entità.
-
-## Notifiche SignalR
-
-L'hub di notifica è registrato da `MapChillApi()`.
-
-| Protocollo | Percorso | Descrizione |
-| --- | --- | --- |
-| SegnaleR |  | Hub per le notifiche di modifica dell'entità. |
-
-Metodi dell'hub:
-
-| Metodo | Parametri | Descrizione |
-| --- | --- | --- |
-|  | `chillType`, opzionale `guid` | Sottoscrive la connessione a tutte le modifiche per un tipo o un'entità. |
-|  | `chillType`, opzionale `guid` | Rimuove un abbonamento precedente. |
-
-Metodo da server a client:
-
-| Metodo | Descrizione |
-| --- | --- |
-|  | Inviato quando le entità sottoscritte cambiano. |
-
-## API di autenticazione
-
-Abilitato quando `ChillApiOptions.EnableAuthApi` è `true` e il contesto implementa `IChillAuthDbContext`.
-
-Itinerario base:
-
-```text
-/api/chill-auth
-```
-
-### Endpoint dell'account
-
-| Metodo | Percorso | Aut. | Descrizione |
-| --- | --- | --- | --- |
-| POST |  | Anonimo | Registra un nuovo account di identità e restituisce i token. |
-| POST |  | Anonimo | Autentica e restituisce token. |
-| POST |  | Anonimo | Scambia un token di aggiornamento con nuovi token. |
-| POST |  | Obbligatorio | Revoca la sessione corrente. |
-| POST |  | Obbligatorio | Modifica la password dell'utente corrente. |
-| POST |  | Anonimo | Richiede o genera un token di reimpostazione della password. |
-| POST |  | Anonimo | Reimposta una password con un token di reimpostazione. |
-
-### Utente corrente e metadati
-
-| Metodo | Percorso | Aut. | Descrizione |
-| --- | --- | --- | --- |
-| OTTIENI |  | Facoltativo | Restituisce le autorizzazioni dirette, di ruolo e derivate dal ruolo per l'utente corrente. |
-| OTTIENI |  | Gestione | Restituisce un elenco utenti semplificato per le interfacce utente di gestione. |
-| OTTIENI |  | Gestione | Restituisce un elenco di ruoli semplificato per le interfacce utente di gestione. |
-| OTTIENI |  | Gestione | Restituisce i moduli logici disponibili. |
-| OTTIENI |  | Gestione | Restituisce le entità per un modulo. |
-| OTTIENI |  | Gestione | Restituisce le query per un modulo. |
-| OTTIENI |  | Gestione | Restituisce le proprietà per un tipo Chill. |
-
-### Utenti
-
-| Metodo | Percorso | Aut. | Descrizione |
-| --- | --- | --- | --- |
-| OTTIENI |  | Gestione | Elenca gli utenti autorizzati. |
-| OTTIENI |  | Gestione | Ottiene un utente con autorizzazione. |
-| POST |  | Gestione | Crea un utente di autorizzazione. |
-| METTERE |  | Gestione | Aggiorna un utente di autorizzazione. |
-| ELIMINA |  | Gestione | Elimina un utente autorizzato. |
-| OTTIENI |  | Gestione | Elenca i ruoli assegnati a un utente. |
-| METTERE |  | Gestione | Assegna un ruolo a un utente. |
-| ELIMINA |  | Gestione | Rimuove un ruolo da un utente. |
-
-### Ruoli
-
-| Metodo | Percorso | Aut. | Descrizione |
-| --- | --- | --- | --- |
-| OTTIENI |  | Gestione | Elenca i ruoli. |
-| OTTIENI |  | Gestione | Ottiene un ruolo. |
-| POST |  | Gestione | Crea un ruolo. |
-| METTERE |  | Gestione | Aggiorna un ruolo. |
-| ELIMINA |  | Gestione | Elimina un ruolo. |
-
-### Regole di autorizzazione
-
-| Metodo | Percorso | Aut. | Descrizione |
-| --- | --- | --- | --- |
-| OTTIENI |  | Gestione | Elenca le regole di autorizzazione, facoltativamente filtrate da `userGuid` o `roleGuid`. |
-| OTTIENI |  | Gestione | Ottiene una regola di autorizzazione. |
-| POST |  | Gestione | Crea una regola di autorizzazione. |
-| METTERE |  | Gestione | Aggiorna una regola di autorizzazione. |
-| ELIMINA |  | Gestione | Elimina una regola di autorizzazione. |
-
-`Management` significa che l'endpoint è protetto da `ChillAuthManagementAccessFilter`.
-
-## API dello schema
-
-Abilitato quando `ChillApiOptions.EnableSchemaApi` è `true` e il contesto implementa `IChillSchemaDbContext`.
-
-Itinerario base:
-
-```text
-/api/chill-schema
-```
-
-| Metodo | Percorso | Aut. | Descrizione |
-| --- | --- | --- | --- |
-| OTTIENI |  | Dipende dalla protezione API globale | Ottiene uno schema. |
-| OTTIENI |  | Dipende dalla protezione API globale | Elenca i riepiloghi delle entità e degli schemi di query. |
-| POST |  | Gestione dello schema | Crea o aggiorna uno schema. |
-| OTTIENI |  | Gestione dello schema | Ottiene le opzioni dello schema per un tipo di entità. |
-| POST |  | Gestione dello schema | Crea o aggiorna le opzioni dell'entità. |
-| OTTIENI |  | Dipende dalla protezione API globale | Restituisce le voci del menu, filtrate in base ai metadati di autenticazione quando disponibili. |
-| POST |  | Gestione dello schema | Crea o aggiorna una voce di menu. |
-| ELIMINA |  | Gestione dello schema | Elimina una voce di menu. |
-
-`Schema management` significa che l'endpoint è protetto da `ChillSchemaManagementAccessFilter`.
-
-## API I18n
-
-Abilitato quando `ChillApiOptions.EnableI18nApi` è `true` e il contesto implementa `IChillI18nDbContext`.
-
-Itinerario base:
-
-```text
-/api/chill-i18n
-```
-
-| Metodo | Percorso | Aut. | Descrizione |
-| --- | --- | --- | --- |
-| POST |  | Anonimo | Ottiene un testo localizzato. |
-| POST |  | Anonimo | Ottiene più testi localizzati. |
-| METTERE |  | Dipende dalla protezione API globale | Crea o aggiorna il testo localizzato. |
-
-## API per gli allegati
-
-Abilitato quando `ChillApiOptions.EnableAttachmentApi` è `true` e il contesto implementa `IChillAttachmentDbContext`.
-
-Itinerario base:
-
-```text
-/api/chill-attachment
-```
-
-| Metodo | Percorso | Aut. | Descrizione |
-| --- | --- | --- | --- |
-| OTTIENI |  | Anonimo per i file pubblici; autenticato per file privati ​​| Scarica un allegato archiviato. |
-| POST |  | Dipende dalla protezione API globale | Carica uno o più file come dati del modulo multiparte. |
-
-Carica i campi del modulo:
-
-| Campo | Obbligatorio | Descrizione |
-| --- | --- | --- |
-|  | Sì | Tipo di raffreddamento dell'entità a cui appartiene l'allegato. |
-|  | Sì | GUID dell'entità a cui appartiene l'allegato. |
-|  | Sì | Uno o più file caricati. |
-|  | No | Visualizza il titolo. Il valore predefinito è il nome file senza estensione. |
-|  | No | Descrizione dell'allegato facoltativa. |
-|  | No | Se i chiamanti anonimi possono scaricare il file. |
-
-## API MCP
-
-Abilitato quando `ChillApiOptions.EnableMcpApi` è `true`, `ChillMcpOptions.Enabled` è `true` e il contesto implementa `IChillSchemaDbContext`.
-
-Percorso predefinito:
-
-```text
-/api/chill-mcp
-```
-
-L'endpoint MCP viene registrato tramite `MapMcp(...)` dal Model Context Protocol ASP.NET Core SDK. Il suo comportamento HTTP segue il contratto di trasporto dell'SDK MCP.
-
-Puoi sovrascrivere direttamente il percorso MCP:
-
-```csharp
-builder.Services.AddChillMcpApi<MyDbContext>(options =>
-{
-    options.RoutePattern = "/api/chill-mcp";
-});
-```
-
-Se `RoutePattern` è relativo, ad esempio `chill-mcp`, ChillSharp lo inserisce nel percorso base API configurato.
-
-## Regole di protezione
-
-`ChillApiOptions.ProtectedApi` applica l'autorizzazione agli endpoint del controller mappato e all'hub SignalR. Alcuni endpoint consentono esplicitamente l'accesso anonimo, ad esempio login/registrazione di autenticazione, endpoint di lettura i18n e download di allegati pubblici.
-
-Gli endpoint di gestione specifici del modulo aggiungono filtri più rigidi:
-
-| Filtra | Utilizzato da |
-| --- | --- |
-|  | Utenti di autenticazione, ruoli, autorizzazioni e metadati di gestione. |
-|  | Operazioni di scrittura di schemi e menu. |
-
-I controlli ACL dell'entità possono essere applicati anche alle operazioni DTO principali e agli allegati quando è registrato un `IChillEntityAclService`.