# Piano Implementazione Multi-Pagina per Report Designer

## Obiettivo
Aggiungere la gestione di template multi-pagina al report designer, permettendo di creare documenti PDF con più pagine, ognuna con i propri elementi.

---

## Analisi dello Stato Attuale

### Frontend
- **EditorCanvas.tsx**: Renderizza un singolo canvas Fabric.js che rappresenta una pagina
- **ReportEditorPage.tsx**: Gestisce `template.elements` come array flat (tutti gli elementi)
- **AprtTemplate**: Ha già un campo `sections` ma non è usato per le pagine
- Gli elementi hanno già un campo `section` (header/body/footer) ma non `pageIndex`

### Backend
- **ReportGeneratorService.cs**: Genera PDF con una sola pagina (`container.Page(...)`)
- **AprtModels.cs**: Definisce `AprtSection` con `repeatOnPages` (pensato per header/footer ripetuti)

### Metalinguaggio APRT
- Attualmente non supporta concetto di "pagine multiple"
- Gli elementi hanno posizione assoluta relativa alla pagina

---

## Approccio Proposto

### Opzione Scelta: Array di Pagine nel Template

Modificare la struttura del template per includere un array esplicito di pagine:

```typescript
interface AprtTemplate {
  // ... existing fields
  pages: AprtPage[];  // NUOVO
  elements: AprtElement[];  // Rimane per backward compatibility
}

interface AprtPage {
  id: string;
  name: string;
  pageSize?: PageSize;      // Override opzionale (default: dal meta)
  orientation?: PageOrientation;  // Override opzionale
  margins?: AprtMargins;    // Override opzionale
  backgroundColor?: string;
  elements: string[];       // Array di ID elementi che appartengono a questa pagina
}

interface AprtElement {
  // ... existing fields
  pageId?: string;  // NUOVO - ID della pagina di appartenenza
}
```

---

## Modifiche Richieste

### 1. Frontend - Types (`report.ts`)

```typescript
// Aggiungere:
export interface AprtPage {
  id: string;
  name: string;
  pageSize?: PageSize;
  orientation?: PageOrientation;
  margins?: AprtMargins;
  backgroundColor?: string;
}

// Modificare AprtTemplate:
export interface AprtTemplate {
  // ... existing
  pages: AprtPage[];  // Aggiungere
}

// Modificare AprtElement:
export interface AprtElement {
  // ... existing
  pageId?: string;  // Aggiungere
}

// Aggiornare defaultTemplate:
export const defaultTemplate: AprtTemplate = {
  // ... existing
  pages: [{
    id: 'page-1',
    name: 'Pagina 1'
  }],
};
```

### 2. Frontend - Nuovo Componente `PageNavigator.tsx`

Barra laterale sinistra o tabs per navigare tra le pagine:

```
┌─────────────────────────────────────────────────┐
│ [+ Aggiungi Pagina]                             │
├─────────────────────────────────────────────────┤
│ ┌─────────┐  Pagina 1 (A4 Portrait)      [⋮]   │
│ │ thumb   │  5 elementi                         │
│ └─────────┘                                     │
├─────────────────────────────────────────────────┤
│ ┌─────────┐  Pagina 2 (A4 Portrait)      [⋮]   │
│ │ thumb   │  3 elementi                    ●    │ ← Selezionata
│ └─────────┘                                     │
└─────────────────────────────────────────────────┘
```

Funzionalità:
- Lista pagine con miniatura
- Aggiunta nuova pagina
- Duplicazione pagina
- Eliminazione pagina (con conferma)
- Riordinamento drag-and-drop
- Indicatore pagina attiva

### 3. Frontend - Modifiche a `ReportEditorPage.tsx`

```typescript
// Nuovo state:
const [currentPageId, setCurrentPageId] = useState<string>('page-1');

// Computed:
const currentPage = template.pages.find(p => p.id === currentPageId);
const currentPageElements = template.elements.filter(e => e.pageId === currentPageId);

// Handlers:
const handleAddPage = () => { /* ... */ };
const handleDeletePage = (pageId: string) => { /* ... */ };
const handleDuplicatePage = (pageId: string) => { /* ... */ };
const handleReorderPages = (fromIndex: number, toIndex: number) => { /* ... */ };
const handleUpdatePageSettings = (pageId: string, updates: Partial<AprtPage>) => { /* ... */ };

// Quando si aggiunge un elemento, assegnare pageId corrente:
const handleAddElement = (type: ElementType) => {
  const newElement = {
    // ... existing
    pageId: currentPageId,  // NUOVO
  };
};
```

### 4. Frontend - Modifiche a `EditorCanvas.tsx`

- Ricevere solo gli elementi della pagina corrente
- Opzionalmente mostrare indicatore numero pagina

```typescript
interface EditorCanvasProps {
  // ... existing
  pageIndex?: number;      // Numero pagina per visualizzazione
  totalPages?: number;     // Totale pagine
}
```

### 5. Frontend - Modifiche a `PropertiesPanel.tsx`

Quando nessun elemento è selezionato, mostrare le impostazioni della pagina corrente:
- Formato pagina (override rispetto al default)
- Orientamento (override)
- Margini (override)
- Colore sfondo

### 6. Frontend - Modifiche a `EditorToolbar.tsx`

Aggiungere pulsanti per navigazione veloce:
- `[◀ Pagina Prec]` / `[Pagina Succ ▶]`
- Indicatore `Pagina 1 di 3`

### 7. Backend - Modifiche a `AprtModels.cs`

```csharp
public class AprtTemplate
{
    // ... existing
    
    [JsonPropertyName("pages")]
    public List<AprtPage> Pages { get; set; } = new();
}

public class AprtPage
{
    [JsonPropertyName("id")]
    public string Id { get; set; } = string.Empty;
    
    [JsonPropertyName("name")]
    public string Name { get; set; } = string.Empty;
    
    [JsonPropertyName("pageSize")]
    public string? PageSize { get; set; }
    
    [JsonPropertyName("orientation")]
    public string? Orientation { get; set; }
    
    [JsonPropertyName("margins")]
    public AprtMargins? Margins { get; set; }
    
    [JsonPropertyName("backgroundColor")]
    public string? BackgroundColor { get; set; }
}

public class AprtElement
{
    // ... existing
    
    [JsonPropertyName("pageId")]
    public string? PageId { get; set; }
}
```

### 8. Backend - Modifiche a `ReportGeneratorService.cs`

```csharp
public async Task<byte[]> GeneratePdfAsync(int templateId, Dictionary<string, object> dataContext)
{
    // ... load template
    
    var document = Document.Create(container =>
    {
        // Raggruppa elementi per pagina
        var pages = aprt.Pages.Any() 
            ? aprt.Pages 
            : new List<AprtPage> { new AprtPage { Id = "default" } };
        
        foreach (var page in pages)
        {
            // Determina dimensioni pagina (override o default)
            var pageSize = page.PageSize ?? aprt.Meta.PageSize;
            var orientation = page.Orientation ?? aprt.Meta.Orientation;
            var margins = page.Margins ?? aprt.Meta.Margins;
            
            // Filtra elementi per questa pagina
            var pageElements = aprt.Elements
                .Where(e => e.Visible && (e.PageId == page.Id || 
                    (string.IsNullOrEmpty(e.PageId) && page.Id == pages[0].Id)))
                .ToList();
            
            container.Page(p =>
            {
                var dims = GetPageDimensionsMm(pageSize, orientation);
                p.Size(dims.Width, dims.Height, Unit.Millimetre);
                p.Margin(0);
                
                // Render elementi della pagina
                var pageImageBytes = RenderContentToBitmap(
                    pageElements, dims.Width, dims.Height, 
                    dataContext, resources, 300f);
                
                p.Content().Image(pageImageBytes).FitArea();
            });
        }
    });
    
    return document.GeneratePdf();
}
```

---

## Migrazione Template Esistenti

Per backward compatibility, i template senza `pages` funzionano come prima:

```csharp
// Nel backend:
if (!aprt.Pages.Any())
{
    // Crea pagina di default con tutti gli elementi
    aprt.Pages.Add(new AprtPage { Id = "page-1", Name = "Pagina 1" });
    foreach (var element in aprt.Elements.Where(e => string.IsNullOrEmpty(e.PageId)))
    {
        element.PageId = "page-1";
    }
}
```

```typescript
// Nel frontend (ReportEditorPage.tsx):
useEffect(() => {
  if (existingTemplate) {
    const parsed = JSON.parse(existingTemplate.templateJson);
    
    // Migrazione: se manca pages, creane una di default
    if (!parsed.pages || parsed.pages.length === 0) {
      parsed.pages = [{ id: 'page-1', name: 'Pagina 1' }];
      // Assegna tutti gli elementi esistenti alla prima pagina
      parsed.elements?.forEach(el => {
        if (!el.pageId) el.pageId = 'page-1';
      });
    }
    
    // ... rest of loading
  }
}, [existingTemplate]);
```

---

## Ordine di Implementazione

### Fase 1: Struttura Dati (30 min)
1. [ ] Aggiornare `report.ts` con `AprtPage` e modifiche a `AprtTemplate`/`AprtElement`
2. [ ] Aggiornare `AprtModels.cs` con le stesse strutture
3. [ ] Aggiornare `defaultTemplate` con pagina di default

### Fase 2: Backend PDF Multi-Pagina (30 min)
4. [ ] Modificare `ReportGeneratorService.GeneratePdfAsync` per iterare sulle pagine
5. [ ] Aggiungere logica di migrazione per template esistenti
6. [ ] Testare generazione PDF con template multi-pagina manuale

### Fase 3: Frontend - PageNavigator (1 ora)
7. [ ] Creare componente `PageNavigator.tsx`
8. [ ] Integrare in `ReportEditorPage.tsx` (layout con sidebar sinistra)
9. [ ] Implementare selezione pagina corrente

### Fase 4: Frontend - Gestione Elementi per Pagina (30 min)
10. [ ] Modificare `ReportEditorPage.tsx` per filtrare elementi per pagina
11. [ ] Assegnare `pageId` agli elementi nuovi
12. [ ] Aggiornare `EditorCanvas.tsx` per ricevere solo elementi pagina corrente

### Fase 5: Frontend - CRUD Pagine (45 min)
13. [ ] Implementare aggiunta pagina
14. [ ] Implementare duplicazione pagina (con copia elementi)
15. [ ] Implementare eliminazione pagina
16. [ ] Implementare riordinamento pagine (drag-and-drop)

### Fase 6: Frontend - Settings Pagina (30 min)
17. [ ] Modificare `PropertiesPanel.tsx` per mostrare settings pagina corrente
18. [ ] Supportare override formato/orientamento/margini per pagina

### Fase 7: UI Polish (30 min)
19. [ ] Aggiungere navigazione rapida in toolbar
20. [ ] Miniature pagine nel navigator
21. [ ] Indicatore pagina corrente nel canvas

### Fase 8: Test e Documentazione (30 min)
22. [ ] Test completo flusso multi-pagina
23. [ ] Test migrazione template esistenti
24. [ ] Aggiornare CLAUDE.md con documentazione

---

## Considerazioni UX

1. **Default intuitivo**: Template nuovo ha 1 pagina, utente può aggiungerne altre
2. **Copia/Incolla tra pagine**: Gli elementi copiati mantengono posizione, si può incollare su altra pagina
3. **Keyboard shortcuts**: 
   - `Page Up` / `Page Down` per navigare
   - `Ctrl+Shift+N` per nuova pagina
4. **Undo/Redo**: Le operazioni su pagine sono incluse nella history
5. **Preview**: Mostra tutte le pagine del PDF generato

---

## File da Modificare

| File | Tipo Modifica |
|------|---------------|
| `frontend/src/types/report.ts` | Aggiungere `AprtPage`, modificare `AprtTemplate`, `AprtElement` |
| `frontend/src/pages/ReportEditorPage.tsx` | Gestione stato pagina corrente, filtro elementi |
| `frontend/src/components/reportEditor/PageNavigator.tsx` | NUOVO - Navigatore pagine |
| `frontend/src/components/reportEditor/EditorCanvas.tsx` | Ricevere elementi filtrati |
| `frontend/src/components/reportEditor/PropertiesPanel.tsx` | Settings pagina corrente |
| `frontend/src/components/reportEditor/EditorToolbar.tsx` | Navigazione rapida |
| `src/Apollinare.API/Services/Reports/AprtModels.cs` | Aggiungere `AprtPage` |
| `src/Apollinare.API/Services/Reports/ReportGeneratorService.cs` | Loop pagine per PDF |
| `CLAUDE.md` | Documentazione feature |

---

## Stima Tempo Totale
**~4 ore** per implementazione completa