@chill-sharp/ui-core 1.1.12 → 1.1.15

package/doc/DateTimeSerialization.md

@@ -1,423 +0,0 @@
-# ChillSharp Date And Time Serialization
-
-Versione italiana: [Italiano](it/DateTimeSerialization.md)
-
-
-This document explains how ChillSharp serializes and parses `DateTimeOffset`, `DateTime`, `DateOnly`, and `TimeOnly` values in DTO payloads.
-
-It also compares ChillSharp behavior with the default ASP.NET Core `System.Text.Json` behavior so you can quickly see what is standard .NET behavior and what is ChillSharp-specific behavior.
-
-## Why This Matters
-
-ChillSharp moves data through DTO property bags rather than strongly typed controller parameters. That means date and time values are converted explicitly inside the DTO mapper.
-
-For most applications the important questions are:
-
-- what string format leaves the server
-- what string format the server accepts on input
-- whether offsets and time zones are preserved, normalized, or ignored
-
-ChillSharp now follows standard .NET behavior for `DateOnly` and `TimeOnly`, while still accepting full ISO 8601 date-time strings when reading them back into those CLR types.
-
-## Quick Comparison Table
-
-| CLR type | Default ASP.NET Core / `System.Text.Json` | ChillSharp output |
-| --- | --- | --- |
-| `DateTimeOffset` | ISO 8601 date-time with offset | ISO 8601 date-time with offset |
-| `DateTime` | ISO 8601 date-time, based on `DateTime.Kind` | ISO 8601 date-time converted to ChillSharp system time zone |
-| `DateOnly` | `yyyy-MM-dd` | `yyyy-MM-dd` |
-| `TimeOnly` | `HH:mm:ss[.fffffff]` | `HH:mm:ss.fffffff` |
-
-## ChillSharp System Time Zone
-
-ChillSharp uses a configurable system time zone only for `DateTime` and some `DateTimeOffset` normalization cases.
-
-Environment variable:
-
-```text
-CHILLSHARP_SYSTEM_TIMEZONE
-```
-
-Default:
-
-```text
-Europe/Rome
-```
-
-Expected value:
-
-- an IANA time-zone id such as `Europe/Rome`
-- another example is `America/New_York`
-
-This setting does **not** change the output format of `DateOnly` or `TimeOnly`.
-
-## Outgoing Serialization
-
-Outgoing serialization happens when ChillSharp reads entity/query CLR values and writes them into DTO `Properties`.
-
-### `DateTimeOffset`
-
-ChillSharp writes `DateTimeOffset` exactly as an ISO 8601 date-time with offset.
-
-Example CLR value:
-
-```csharp
-new DateTimeOffset(2026, 4, 11, 14, 30, 0, TimeSpan.FromHours(2))
-```
-
-Serialized by ChillSharp:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-This is effectively aligned with normal ASP.NET Core JSON serialization.
-
-### `DateTime`
-
-ChillSharp writes `DateTime` as an ISO 8601 date-time in the configured ChillSharp system time zone.
-
-If the source value is UTC, ChillSharp converts it into the configured system time zone before writing.
-
-Example with `CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome`:
-
-```csharp
-new DateTime(2026, 4, 11, 12, 30, 0, DateTimeKind.Utc)
-```
-
-Serialized by ChillSharp:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-Another example with an unspecified `DateTime`:
-
-```csharp
-new DateTime(2026, 4, 11, 14, 30, 0, DateTimeKind.Unspecified)
-```
-
-Serialized by ChillSharp:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-The difference from plain ASP.NET Core is that ChillSharp applies a configured system time zone consistently when writing `DateTime`.
-
-### `DateOnly`
-
-ChillSharp now keeps standard .NET behavior for `DateOnly`.
-
-Example CLR value:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-Serialized by ChillSharp:
-
-```json
-"2026-04-11"
-```
-
-This is intentionally simple. There is no offset, no time component, and no time-zone conversion on output.
-
-### `TimeOnly`
-
-ChillSharp now keeps standard .NET behavior for `TimeOnly`.
-
-Example CLR value:
-
-```csharp
-new TimeOnly(14, 30, 15, 123)
-```
-
-Serialized by ChillSharp:
-
-```json
-"14:30:15.1230000"
-```
-
-There is no date and no time-zone conversion on output.
-
-## Incoming Parsing
-
-Incoming parsing happens when ChillSharp reads DTO `Properties` and applies them onto entity/query CLR objects.
-
-This is the more permissive side of the mapper.
-
-### `DateTimeOffset` input rules
-
-If the incoming JSON contains:
-
-- `Z`
-- an explicit UTC offset
-
-and the CLR target is `DateTimeOffset`, ChillSharp behaves like this:
-
-- if the value is UTC (`Z` or `+00:00`), it converts the value into the configured ChillSharp system time zone
-- if the value has another explicit offset, it keeps that offset as-is
-
-Example input:
-
-```json
-"2026-04-11T12:30:00Z"
-```
-
-Stored in a `DateTimeOffset` property with `Europe/Rome` system time zone:
-
-```csharp
-2026-04-11 14:30:00 +02:00
-```
-
-Example input:
-
-```json
-"2026-04-11T12:30:00+01:00"
-```
-
-Stored in a `DateTimeOffset` property:
-
-```csharp
-2026-04-11 12:30:00 +01:00
-```
-
-### `DateTime` input rules
-
-If the CLR target is `DateTime`:
-
-- UTC input is converted into the configured ChillSharp system time zone
-- input with an explicit offset is also converted into the configured ChillSharp system time zone
-- input without offset is parsed as a normal date-time value
-
-Example input:
-
-```json
-"2026-04-11T12:30:00Z"
-```
-
-Stored in a `DateTime` property with `Europe/Rome` system time zone:
-
-```csharp
-2026-04-11 14:30:00
-```
-
-Example input:
-
-```json
-"2026-04-11T12:30:00+01:00"
-```
-
-Stored in a `DateTime` property with `Europe/Rome` system time zone:
-
-```csharp
-2026-04-11 13:30:00
-```
-
-### `DateOnly` input rules
-
-If the CLR target is `DateOnly`, ChillSharp extracts only the year, month, and day.
-
-That means it accepts both:
-
-- a plain date string
-- a full ISO 8601 date-time string
-
-and ignores the time, offset, and timezone information.
-
-Example input:
-
-```json
-"2026-04-11"
-```
-
-Stored as:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-Example input:
-
-```json
-"2026-04-11T23:59:58.321-05:00"
-```
-
-Stored as:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-This rule is deliberate. `DateOnly` represents only a calendar date, so ChillSharp discards time and zone details when assigning it.
-
-### `TimeOnly` input rules
-
-If the CLR target is `TimeOnly`, ChillSharp extracts only the time part.
-
-That means it accepts both:
-
-- a plain time string
-- a full ISO 8601 date-time string
-
-and ignores the date, offset, and timezone information.
-
-Example input:
-
-```json
-"14:30:15.1230000"
-```
-
-Stored as:
-
-```csharp
-new TimeOnly(14, 30, 15, 123)
-```
-
-Example input:
-
-```json
-"2026-04-11T23:59:58.321-05:00"
-```
-
-Stored as:
-
-```csharp
-new TimeOnly(23, 59, 58, 321)
-```
-
-This is useful when clients send a full timestamp but the target field conceptually represents only a local clock time.
-
-## Side-By-Side Examples
-
-Assume:
-
-```text
-CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome
-```
-
-### Example 1: `DateTimeOffset`
-
-CLR value:
-
-```csharp
-new DateTimeOffset(2026, 4, 11, 14, 30, 0, TimeSpan.FromHours(2))
-```
-
-Default ASP.NET Core output:
-
-```json
-"2026-04-11T14:30:00+02:00"
-```
-
-ChillSharp output:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-### Example 2: `DateTime` in UTC
-
-CLR value:
-
-```csharp
-new DateTime(2026, 4, 11, 12, 30, 0, DateTimeKind.Utc)
-```
-
-Default ASP.NET Core output:
-
-```json
-"2026-04-11T12:30:00Z"
-```
-
-ChillSharp output:
-
-```json
-"2026-04-11T14:30:00.0000000+02:00"
-```
-
-### Example 3: `DateOnly`
-
-CLR value:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-Default ASP.NET Core output:
-
-```json
-"2026-04-11"
-```
-
-ChillSharp output:
-
-```json
-"2026-04-11"
-```
-
-### Example 4: `TimeOnly`
-
-CLR value:
-
-```csharp
-new TimeOnly(14, 30, 15, 123)
-```
-
-Default ASP.NET Core output:
-
-```json
-"14:30:15.1230000"
-```
-
-ChillSharp output:
-
-```json
-"14:30:15.1230000"
-```
-
-### Example 5: full timestamp sent into `DateOnly`
-
-Incoming JSON:
-
-```json
-"2026-04-11T23:59:58.321-05:00"
-```
-
-Stored by ChillSharp in a `DateOnly` property:
-
-```csharp
-new DateOnly(2026, 4, 11)
-```
-
-### Example 6: full timestamp sent into `TimeOnly`
-
-Incoming JSON:
-
-```json
-"2026-04-11T23:59:58.321-05:00"
-```
-
-Stored by ChillSharp in a `TimeOnly` property:
-
-```csharp
-new TimeOnly(23, 59, 58, 321)
-```
-
-## Practical Guidance
-
-- Use `DateTimeOffset` when the offset itself matters and should survive round-trips.
-- Use `DateTime` when your application treats a value as local wall-clock time in the configured ChillSharp system time zone.
-- Use `DateOnly` for birthdays, accounting dates, business dates, deadlines by calendar day, and similar concepts.
-- Use `TimeOnly` for opening hours, appointment clock times, and other values that are intentionally not full timestamps.
-
-## Related Configuration
-
-For the environment variable reference, see:
-
-- [Configuration/README.md](./Configuration/README.md)
-
-For Docker and runtime environment examples, see:
-
-- [HowTo/05-docker-env-variables.md](./HowTo/05-docker-env-variables.md)

package/doc/Endpoints.md

@@ -1,260 +0,0 @@
-# ChillSharp Endpoints
-
-Versione italiana: [Italiano](it/Endpoints.md)
-
-
-This document lists the HTTP, SignalR, and MCP endpoints exposed by the built-in ChillSharp API modules.
-
-## Base Path
-
-ChillSharp endpoints are mounted under a configurable API base path.
-
-Default:
-
-```text
-/api
-```
-
-Configuration:
-
-```text
-CHILLSHARP_API_BASE_PATH=/api
-```
-
-or in code:
-
-```csharp
-builder.Services.AddChillApi<MyDbContext>(options =>
-{
-    options.ApiBasePath = "/api";
-});
-
-app.MapChillApi();
-```
-
-The examples below use the default `/api` base path. If you set `CHILLSHARP_API_BASE_PATH=/backend`, replace `/api` with `/backend`.
-
-## Root And Diagnostics
-
-These endpoints are registered by `MapChillApi()`.
-
-| Method | Path | Description |
-| --- | --- | --- |
-| GET | `/api` | Basic ChillSharp health response, also matched when callers request `/api/`. |
-| GET | `/api/test` | Basic ChillSharp health response. |
-| GET | `/api/license` | Returns ChillSharp license and project metadata. |
-
-## Core DTO API
-
-These endpoints are enabled by `AddChillApi<TContext>()` and are available when the base Chill API is registered.
-
-Base route:
-
-```text
-/api/chill
-```
-
-| Method | Path | Description |
-| --- | --- | --- |
-| POST | `/api/chill/query` | Executes a dynamic `ChillDtoQuery`. |
-| POST | `/api/chill/lookup` | Performs a full-text lookup against the requested entity type. |
-| POST | `/api/chill/find` | Finds one entity by type and GUID. |
-| POST | `/api/chill/create` | Creates one entity from a `ChillDtoEntity`. |
-| POST | `/api/chill/update` | Updates one entity from a `ChillDtoEntity`. |
-| POST | `/api/chill/delete` | Deletes one entity identified by a `ChillDtoEntity`. |
-| POST | `/api/chill/autocomplete` | Runs autocomplete logic for an entity or query DTO. |
-| POST | `/api/chill/validate` | Runs validation for an entity or query DTO. |
-| POST | `/api/chill/chunk` | Executes a list of Chill operations in one request. |
-
-When entity ACL services are registered and the caller is authenticated, these endpoints can also enforce entity-level permissions.
-
-## SignalR Notifications
-
-The notification hub is registered by `MapChillApi()`.
-
-| Protocol | Path | Description |
-| --- | --- | --- |
-| SignalR | `/api/notify` | Hub for entity change notifications. |
-
-Hub methods:
-
-| Method | Parameters | Description |
-| --- | --- | --- |
-| `Register` | `chillType`, optional `guid` | Subscribes the connection to all changes for a type or one entity. |
-| `Unregister` | `chillType`, optional `guid` | Removes a previous subscription. |
-
-Server-to-client method:
-
-| Method | Description |
-| --- | --- |
-| `EntitiesChanged` | Sent when subscribed entities change. |
-
-## Auth API
-
-Enabled when `ChillApiOptions.EnableAuthApi` is `true` and the context implements `IChillAuthDbContext`.
-
-Base route:
-
-```text
-/api/chill-auth
-```
-
-### Account Endpoints
-
-| Method | Path | Auth | Description |
-| --- | --- | --- | --- |
-| POST | `/api/chill-auth/register` | Anonymous | Registers a new Identity account and returns tokens. |
-| POST | `/api/chill-auth/login` | Anonymous | Authenticates and returns tokens. |
-| POST | `/api/chill-auth/refresh` | Anonymous | Exchanges a refresh token for new tokens. |
-| POST | `/api/chill-auth/logout` | Required | Revokes the current session. |
-| POST | `/api/chill-auth/change-password` | Required | Changes the current user's password. |
-| POST | `/api/chill-auth/request-password-reset` | Anonymous | Requests or generates a password reset token. |
-| POST | `/api/chill-auth/reset-password` | Anonymous | Resets a password with a reset token. |
-
-### Current User And Metadata
-
-| Method | Path | Auth | Description |
-| --- | --- | --- | --- |
-| GET | `/api/chill-auth/get-permissions` | Optional | Returns direct, role, and role-derived permissions for the current user. |
-| GET | `/api/chill-auth/get-user-list` | Management | Returns a simplified user list for management UIs. |
-| GET | `/api/chill-auth/get-role-list` | Management | Returns a simplified role list for management UIs. |
-| GET | `/api/chill-auth/get-module-list` | Management | Returns available logical modules. |
-| GET | `/api/chill-auth/get-entity-list?module={module}` | Management | Returns entities for a module. |
-| GET | `/api/chill-auth/get-query-list?module={module}` | Management | Returns queries for a module. |
-| GET | `/api/chill-auth/get-property-list?chillType={type}` | Management | Returns properties for a Chill type. |
-
-### Users
-
-| Method | Path | Auth | Description |
-| --- | --- | --- | --- |
-| GET | `/api/chill-auth/users` | Management | Lists authorization users. |
-| GET | `/api/chill-auth/users/{userGuid}` | Management | Gets one authorization user. |
-| POST | `/api/chill-auth/users` | Management | Creates an authorization user. |
-| PUT | `/api/chill-auth/users/{userGuid}` | Management | Updates an authorization user. |
-| DELETE | `/api/chill-auth/users/{userGuid}` | Management | Deletes an authorization user. |
-| GET | `/api/chill-auth/users/{userGuid}/roles` | Management | Lists roles assigned to a user. |
-| PUT | `/api/chill-auth/users/{userGuid}/roles/{roleGuid}` | Management | Assigns a role to a user. |
-| DELETE | `/api/chill-auth/users/{userGuid}/roles/{roleGuid}` | Management | Removes a role from a user. |
-
-### Roles
-
-| Method | Path | Auth | Description |
-| --- | --- | --- | --- |
-| GET | `/api/chill-auth/roles` | Management | Lists roles. |
-| GET | `/api/chill-auth/roles/{roleGuid}` | Management | Gets one role. |
-| POST | `/api/chill-auth/roles` | Management | Creates a role. |
-| PUT | `/api/chill-auth/roles/{roleGuid}` | Management | Updates a role. |
-| DELETE | `/api/chill-auth/roles/{roleGuid}` | Management | Deletes a role. |
-
-### Permission Rules
-
-| Method | Path | Auth | Description |
-| --- | --- | --- | --- |
-| GET | `/api/chill-auth/permissions` | Management | Lists permission rules, optionally filtered by `userGuid` or `roleGuid`. |
-| GET | `/api/chill-auth/permissions/{ruleGuid}` | Management | Gets one permission rule. |
-| POST | `/api/chill-auth/permissions` | Management | Creates a permission rule. |
-| PUT | `/api/chill-auth/permissions/{ruleGuid}` | Management | Updates a permission rule. |
-| DELETE | `/api/chill-auth/permissions/{ruleGuid}` | Management | Deletes a permission rule. |
-
-`Management` means the endpoint is protected by `ChillAuthManagementAccessFilter`.
-
-## Schema API
-
-Enabled when `ChillApiOptions.EnableSchemaApi` is `true` and the context implements `IChillSchemaDbContext`.
-
-Base route:
-
-```text
-/api/chill-schema
-```
-
-| Method | Path | Auth | Description |
-| --- | --- | --- | --- |
-| GET | `/api/chill-schema/get-schema?ChillType={type}&ChillViewCode={view}&CultureName={culture}` | Depends on global API protection | Gets one schema. |
-| GET | `/api/chill-schema/get-schema-list?CultureName={culture}` | Depends on global API protection | Lists entity and query schema summaries. |
-| POST | `/api/chill-schema/set-schema` | Schema management | Creates or updates a schema. |
-| GET | `/api/chill-schema/get-entity-options?ChillType={type}` | Schema management | Gets schema options for one entity type. |
-| POST | `/api/chill-schema/set-entity-options` | Schema management | Creates or updates entity options. |
-| GET | `/api/chill-schema/get-menu?ParentGuid={guid}` | Depends on global API protection | Returns menu entries, filtered by auth metadata when available. |
-| POST | `/api/chill-schema/set-menu` | Schema management | Creates or updates one menu item. |
-| DELETE | `/api/chill-schema/delete-menu?MenuItemGuid={guid}` | Schema management | Deletes one menu item. |
-
-`Schema management` means the endpoint is protected by `ChillSchemaManagementAccessFilter`.
-
-## I18n API
-
-Enabled when `ChillApiOptions.EnableI18nApi` is `true` and the context implements `IChillI18nDbContext`.
-
-Base route:
-
-```text
-/api/chill-i18n
-```
-
-| Method | Path | Auth | Description |
-| --- | --- | --- | --- |
-| POST | `/api/chill-i18n/get-text` | Anonymous | Gets one localized text. |
-| POST | `/api/chill-i18n/get-multiple-text` | Anonymous | Gets multiple localized texts. |
-| PUT | `/api/chill-i18n/set-text` | Depends on global API protection | Creates or updates localized text. |
-
-## Attachment API
-
-Enabled when `ChillApiOptions.EnableAttachmentApi` is `true` and the context implements `IChillAttachmentDbContext`.
-
-Base route:
-
-```text
-/api/chill-attachment
-```
-
-| Method | Path | Auth | Description |
-| --- | --- | --- | --- |
-| GET | `/api/chill-attachment/attachment/download?guid={guid}` | Anonymous for public files; authenticated for private files | Downloads an archived attachment. |
-| POST | `/api/chill-attachment/attachment/upload` | Depends on global API protection | Uploads one or more files as multipart form data. |
-
-Upload form fields:
-
-| Field | Required | Description |
-| --- | --- | --- |
-| `attachToChillType` | Yes | Chill type of the entity the attachment belongs to. |
-| `attachToGuid` | Yes | GUID of the entity the attachment belongs to. |
-| `file` | Yes | One or more uploaded files. |
-| `title` | No | Display title. Defaults to the filename without extension. |
-| `description` | No | Optional attachment description. |
-| `public` | No | Whether anonymous callers can download the file. |
-
-## MCP API
-
-Enabled when `ChillApiOptions.EnableMcpApi` is `true`, `ChillMcpOptions.Enabled` is `true`, and the context implements `IChillSchemaDbContext`.
-
-Default route:
-
-```text
-/api/chill-mcp
-```
-
-The MCP endpoint is registered through `MapMcp(...)` from the Model Context Protocol ASP.NET Core SDK. Its HTTP behavior follows the MCP SDK transport contract.
-
-You can override the MCP route directly:
-
-```csharp
-builder.Services.AddChillMcpApi<MyDbContext>(options =>
-{
-    options.RoutePattern = "/api/chill-mcp";
-});
-```
-
-If `RoutePattern` is relative, for example `chill-mcp`, ChillSharp places it under the configured API base path.
-
-## Protection Rules
-
-`ChillApiOptions.ProtectedApi` applies authorization to the mapped controller endpoints and SignalR hub. Some endpoints explicitly allow anonymous access, such as auth login/register, i18n read endpoints, and public attachment downloads.
-
-Module-specific management endpoints add stricter filters:
-
-| Filter | Used By |
-| --- | --- |
-| `ChillAuthManagementAccessFilter` | Auth users, roles, permissions, and management metadata. |
-| `ChillSchemaManagementAccessFilter` | Schema and menu write operations. |
-
-Entity ACL checks can also apply to core DTO and attachment operations when an `IChillEntityAclService` is registered.