# Guida utente — @eqproject/eqp-dynamic-module

> Documento complementare al [README.md](./README.md). Contiene guide pratiche d'uso e prompt AI di esempio.  
> Companion document to [README.md](./README.md). Contains practical usage guides and example AI prompts.

---

## Indice / Table of Contents

- [Guida utente (Italiano)](#guida-utente-italiano)
  - [Scenario 1 — Form in sola lettura (VIEW)](#scenario-1--form-in-sola-lettura-view)
  - [Scenario 2 — Compilazione form (COMPILE)](#scenario-2--compilazione-form-compile)
  - [Scenario 3 — Lista risposte con filtri (LIST)](#scenario-3--lista-risposte-con-filtri-list)
  - [Scenario 4 — Configuratore no-code](#scenario-4--configuratore-no-code)
  - [Scenario 5 — Endpoint personalizzati](#scenario-5--endpoint-personalizzati)
  - [Troubleshooting](#troubleshooting)
- [User Guide (English)](#user-guide-english)
  - [Scenario 1 — Read-only form (VIEW)](#scenario-1--read-only-form-view)
  - [Scenario 2 — Form fill (COMPILE)](#scenario-2--form-fill-compile)
  - [Scenario 3 — Answer list with filters (LIST)](#scenario-3--answer-list-with-filters-list)
  - [Scenario 4 — No-code configurator](#scenario-4--no-code-configurator)
  - [Scenario 5 — Custom endpoints](#scenario-5--custom-endpoints)
  - [Troubleshooting (EN)](#troubleshooting-en)
- [Utilizzo con AI / AI-assisted Usage](#utilizzo-con-ai--ai-assisted-usage)
  - [Prompt per Claude Code](#prompt-per-claude-code)

---

## Guida utente (Italiano)

### Prerequisiti

1. Angular 15
2. `npm install @eqproject/eqp-dynamic-module --legacy-peer-deps`
3. `EqpDynamicModuleModule` importato nel modulo Angular consumer (vedi README)
4. Un server che espone le API DynamicModule (oppure endpoint custom configurati via `EndPointConfiguration`)

---

### Scenario 1 — Form in sola lettura (VIEW)

Mostrare una form compilata senza possibilità di modifica. Tipico caso d'uso: pagina di dettaglio di un record.

**Template:**
```html
<eqp-dynamic-module
  [dynamicModuleConfig]="configView"
  [starterViewMode]="'VIEW'"
  [formId]="selectedFormId"
  [recordId]="selectedRecordId">
</eqp-dynamic-module>
```

**Componente:**
```typescript
import { DynamicModuleConfig, DynamicModuleGeneralConfig, DynamicModuleViewModeEnum } from '@eqproject/eqp-dynamic-module';

configView: DynamicModuleConfig = {
  GeneralConfig: {
    baseServerUrl: 'https://your-api-host',
    userToken: this.authService.getToken(),
    context: 'MY_APP'
  } as DynamicModuleGeneralConfig
} as DynamicModuleConfig;

starterViewMode = DynamicModuleViewModeEnum.VIEW;
```

---

### Scenario 2 — Compilazione form (COMPILE)

Permettere all'utente di inserire o modificare una risposta.

```html
<eqp-dynamic-module
  [dynamicModuleConfig]="configCompile"
  [starterViewMode]="'COMPILE'"
  [formId]="formId"
  [recordId]="null"
  (onRecordSaved)="handleSaved($event)">
</eqp-dynamic-module>
```

- Passa `recordId = null` per una nuova risposta, oppure un ID esistente per modificarla.
- Ascolta `(onRecordSaved)` per reagire al salvataggio.

---

### Scenario 3 — Lista risposte con filtri (LIST)

Visualizzare la lista delle risposte a una form con filtri e paginazione integrati.

```html
<eqp-dynamic-module
  [dynamicModuleConfig]="configList"
  [starterViewMode]="'LIST'"
  [formId]="formId">
</eqp-dynamic-module>
```

Per abilitare i filtri dalla lista imposta `ListConfig.showFilters = true` dentro `DynamicModuleConfig`.

---

### Scenario 4 — Configuratore no-code

Permettere a un amministratore di creare o modificare la definizione di una form.

```html
<eqp-dynamic-module-configurator
  [dynamicModuleConfiguratorConfig]="configConfigurator"
  [configuratorMode]="'EDIT'"
  [formId]="formId"
  (onFormSaved)="handleFormSaved($event)">
</eqp-dynamic-module-configurator>
```

**Modalità disponibili:**

| Valore | Comportamento |
|--------|---------------|
| `NEW` | Crea una nuova form da zero |
| `EDIT` | Modifica una form esistente per `formId` |
| `EXPORT` | Esporta la form come JSON scaricabile |
| `IMPORT` | Importa una form da JSON |

---

### Scenario 5 — Endpoint personalizzati

Quando il server non espone le API al percorso default, configura `EndPointConfiguration`:

```typescript
import { EndPointConfiguration, EndPointData, ParamTypeEnum } from '@eqproject/eqp-dynamic-module';

const customEndpoints: EndPointConfiguration = new EndPointConfiguration();
customEndpoints.Records.GetAll = {
  Url: 'https://custom-host/api/records',
  Token: 'Bearer my-token',
  RequestMethod: 'GET',
  Params: []
} as EndPointData;

// Poi passa customEndpoints in GeneralConfig.EndPointConfiguration
```

Ogni campo di `EndPointConfiguration` è opzionale: puoi sovrascrivere solo gli endpoint che differiscono dai default.

---

### Troubleshooting

**Campi non visibili nel configuratore**
- Verifica che il `formId` sia corretto e che il server risponda su `GET /api/conf/form/{id}`.

**Errore CORS**
- Il server deve restituire `Access-Control-Allow-Origin: *` (o il dominio specifico). In sviluppo puoi usare il proxy Angular.

**Form vuota in modalità COMPILE**
- Controlla che `baseServerUrl` non abbia una barra finale (`/`).
- Verifica che `userToken` sia valido e non scaduto.

**Lista non si aggiorna dopo salvataggio**
- Chiama `dynamicModuleRef.refreshList()` nell'handler di `(onRecordSaved)` oppure passa `ListConfig.autoRefresh = true`.

**Errore di tipo sui campi data**
- Da v2.10.62 il formato data usa token Luxon (`dd/MM/yyyy`). Se aggiorni da versioni precedenti, verifica i valori salvati in DB.

---

## User Guide (English)

### Prerequisites

1. Angular 15
2. `npm install @eqproject/eqp-dynamic-module --legacy-peer-deps`
3. `EqpDynamicModuleModule` imported in the consumer Angular module (see README)
4. A server exposing the DynamicModule API (or custom endpoints configured via `EndPointConfiguration`)

---

### Scenario 1 — Read-only form (VIEW)

Display a completed form without allowing edits. Typical use case: detail page of a record.

**Template:**
```html
<eqp-dynamic-module
  [dynamicModuleConfig]="configView"
  [starterViewMode]="'VIEW'"
  [formId]="selectedFormId"
  [recordId]="selectedRecordId">
</eqp-dynamic-module>
```

**Component:**
```typescript
import { DynamicModuleConfig, DynamicModuleGeneralConfig, DynamicModuleViewModeEnum } from '@eqproject/eqp-dynamic-module';

configView: DynamicModuleConfig = {
  GeneralConfig: {
    baseServerUrl: 'https://your-api-host',
    userToken: this.authService.getToken(),
    context: 'MY_APP'
  } as DynamicModuleGeneralConfig
} as DynamicModuleConfig;

starterViewMode = DynamicModuleViewModeEnum.VIEW;
```

---

### Scenario 2 — Form fill (COMPILE)

Allow the user to create or edit an answer.

```html
<eqp-dynamic-module
  [dynamicModuleConfig]="configCompile"
  [starterViewMode]="'COMPILE'"
  [formId]="formId"
  [recordId]="null"
  (onRecordSaved)="handleSaved($event)">
</eqp-dynamic-module>
```

- Pass `recordId = null` for a new answer, or an existing ID to edit it.
- Listen to `(onRecordSaved)` to react to the save event.

---

### Scenario 3 — Answer list with filters (LIST)

Display the list of answers for a form with built-in filters and pagination.

```html
<eqp-dynamic-module
  [dynamicModuleConfig]="configList"
  [starterViewMode]="'LIST'"
  [formId]="formId">
</eqp-dynamic-module>
```

To enable list filters set `ListConfig.showFilters = true` inside `DynamicModuleConfig`.

---

### Scenario 4 — No-code configurator

Let an administrator create or modify a form definition.

```html
<eqp-dynamic-module-configurator
  [dynamicModuleConfiguratorConfig]="configConfigurator"
  [configuratorMode]="'EDIT'"
  [formId]="formId"
  (onFormSaved)="handleFormSaved($event)">
</eqp-dynamic-module-configurator>
```

**Available modes:**

| Value | Behaviour |
|-------|-----------|
| `NEW` | Create a new form from scratch |
| `EDIT` | Edit an existing form by `formId` |
| `EXPORT` | Export the form as a downloadable JSON |
| `IMPORT` | Import a form from a JSON file |

---

### Scenario 5 — Custom endpoints

When the server does not expose APIs at the default paths, configure `EndPointConfiguration`:

```typescript
import { EndPointConfiguration, EndPointData, ParamTypeEnum } from '@eqproject/eqp-dynamic-module';

const customEndpoints: EndPointConfiguration = new EndPointConfiguration();
customEndpoints.Records.GetAll = {
  Url: 'https://custom-host/api/records',
  Token: 'Bearer my-token',
  RequestMethod: 'GET',
  Params: []
} as EndPointData;

// Then pass customEndpoints in GeneralConfig.EndPointConfiguration
```

Each field in `EndPointConfiguration` is optional — only override the endpoints that differ from the defaults.

---

### Troubleshooting (EN)

**Fields not visible in the configurator**
- Verify that `formId` is correct and that the server responds on `GET /api/conf/form/{id}`.

**CORS error**
- The server must return `Access-Control-Allow-Origin: *` (or the specific domain). In development you can use the Angular proxy.

**Empty form in COMPILE mode**
- Check that `baseServerUrl` does not have a trailing slash (`/`).
- Verify that `userToken` is valid and not expired.

**List does not refresh after save**
- Call `dynamicModuleRef.refreshList()` in the `(onRecordSaved)` handler, or pass `ListConfig.autoRefresh = true`.

**Date field type error**
- From v2.10.62 dates use Luxon tokens (`dd/MM/yyyy`). If upgrading from older versions, verify DB-saved values.

---

## Utilizzo con AI / AI-assisted Usage

Questa sezione mostra come usare Claude Code (o un altro assistente AI) per lavorare con `@eqproject/eqp-dynamic-module` in modo efficiente, sia come consumatore della libreria che come manutentore.

*This section shows how to use Claude Code (or another AI assistant) to work efficiently with `@eqproject/eqp-dynamic-module`, both as a consumer and as a maintainer.*

---

### Prompt per Claude Code

I prompt seguenti funzionano bene con Claude Code (CLI `claude`) all'interno del repo `DynamicModuleClient`.

*The following prompts work well with Claude Code (CLI `claude`) inside the `DynamicModuleClient` repo.*

---

#### Pubblicazione NPM

```
Pubblica una nuova versione patch del modulo su npm.
```
```
Fai una release minor del modulo dinamico.
```
```
Fai una release major — stiamo rilasciando la versione 3.
```
```
Release patch — ma prima controlla che non ci siano errori TypeScript.
```

Claude eseguirà: analisi diff → aggiornamento README e USERGUIDE → bump versione → build → publish → commit → aggiornamento TMED.

---

#### Aggiungere un tipo di campo

```
Aggiungi un nuovo tipo di campo chiamato "SignatureField" per la firma digitale.
Deve comparire nel configuratore come "Firma" e salvare una stringa base64.
```
```
Voglio un campo "RatingField" (stelle 1-5). Mostralo in sola lettura come stelle SVG
e in compilazione come radio button.
```

Claude creerà: modello in `models/fields/`, template di rendering, template filtro, template trigger, enum, registrazione nel modulo, export da `public-api.ts`.

---

#### Correzione bug

```
Nella modalità LIST il componente non mostra i risultati quando la lista è vuota.
Cerca la causa e correggila.
```
```
Gli ActionButton nei form in modalità VIEW sono cliccabili ma non dovrebbero esserlo.
```
```
Il configuratore non salva i trigger quando ci sono più di 5 condizioni.
Analizza il problema e proponi la correzione.
```

---

#### Analisi e spiegazione

```
Spiega come funziona il sistema di trigger nel configuratore.
```
```
Come viene gestita la modalità FILTER? Quali componenti sono coinvolti?
```
```
Quali endpoint chiama il componente in modalità COMPILE? Mostrami il flusso completo.
```

---

#### Aggiornamento documentazione

```
Il README è obsoleto rispetto al codice. Aggiornalo analizzando i cambiamenti
dall'ultimo tag git.
```
```
Aggiorna la sezione Changelog del README con le modifiche fatte dall'ultima versione.
```
```
Aggiungi a USERGUIDE.md un esempio per il campo ImageWithMarkers.
```

---

#### Task e tracciamento ADO

```
Crea un task ADO per l'implementazione del SignatureField nel modulo dinamico.
```
```
Apri un task per il bug degli ActionButton in VIEW mode — è un fix critico.
```
```
Questo fix tocca sia DynamicModuleClient che DynamicModule. Crea un task per entrambi i progetti e linkali come Related.
```

---

#### Workflow multi-step

```
Analizza i cambiamenti dall'ultima release, aggiorna README e USERGUIDE,
poi fai una release patch.
```
```
C'è un bug in produzione sugli allegati in modalità COMPILE. Analizza la causa,
crea un task ADO, correggilo e fai una release patch urgente.
```
```
Voglio aggiungere il supporto a un nuovo endpoint per l'esportazione CSV.
Crea il task ADO, implementa la modifica e poi fai una release minor.
```