# Pivot — installazione in una nuova app ("capsula")

Implementazione **condivisa** della feature "Pivot" (PivotTable.js + renderer custom
`multifact-pivottable.js`), usata da più app sotto `/opt/gts` (`itg`, `rda`, ...).
Tutta la logica vive qui, in `/opt/gts/shared/pivot/` — ogni app tiene solo
qualche file minuscolo ("stub") + la propria configurazione.

Per l'architettura completa (perché serve uno stub per app, schema di
`pivot_cfg.json`, gotcha noti) vedi **[/opt/gts/CLAUDE.md](../../CLAUDE.md)** —
questo file spiega solo *come installarla* in un'app che non ce l'ha ancora.

## Installazione rapida

```sh
/opt/gts/shared/pivot/install.sh /opt/gts/<nomeapp>
```

Crea, solo se non esistono già, questi file dentro `/opt/gts/<nomeapp>/`:

| File | Cosa fa |
|---|---|
| `pivot.php` | Pagina Pivot (stub → `pivot_impl.php`) |
| `pivot_data.php` | Estrazione dati per "Crea/Aggiorna Pivot" e vista Dettaglio (stub → `pivot_data_impl.php`) |
| `html2xls.php` | Export Excel della pivot (stub → `html2xls_impl.php`) |
| `pivot_toggle_campo.php` | Checkbox "aggiungi/togli campo" nella vista Dettaglio (stub → `pivot_toggle_campo_impl.php`) |
| `pivot_cfg_edit.php` | Pagina "Modifica configurazione" (stub → `pivot_cfg_edit_impl.php`) |
| `pivot_cfg_edit_save.php` | Salvataggio della pagina sopra (stub → `pivot_cfg_edit_save_impl.php`) |
| `pivot_cfg_test_select.php` | Pulsante "Testa Select" della pagina sopra (stub → `pivot_cfg_test_select_impl.php`) |
| `pivot_cfg.json` | **L'unica cosa che varia davvero per app** — Fonti, campi/valori, filtri (vedi schema in `/opt/gts/CLAUDE.md`). Lo script ne crea uno scheletro minimo se manca. |

Lo script imposta anche il permesso di scrittura su `pivot_cfg.json` (necessario
perché il webserver possa salvare da "Modifica configurazione"/checkbox
Dettaglio — vedi il gotcha "permessi" in `/opt/gts/CLAUDE.md`).

## Dopo l'installazione (manuale)

1. **Configurare almeno una Fonte** in `pivot_cfg.json` — o a mano (`vista`,
   `campoData`, `select` con almeno `TO_CHAR(<colonna_data>,'YYYYMMDD') AS DATAP`,
   obbligatorio), o dalla pagina web "Modifica configurazione"
   (`pivot_cfg_edit.php`) una volta raggiungibile (punto 2).
2. **Aggiungere una voce di menu** (`menu.xml` o card in `main.php`, a seconda
   dell'app) che punti a `pivot.php`. I pulsanti "Dettaglio"/"Modifica
   configurazione" restano comunque visibili solo a `ctx_uid()==1` — non serve
   nascondere la voce di menu agli altri utenti a meno di preferirlo.
3. **Verificare i permessi reali** di `pivot_cfg.json` sul server (non solo in
   locale/sandbox) — Apache/php-fpm deve poter scrivere il file.

## Non copiare mai questi file dentro l'app

Vivono e restano **solo** in `/opt/gts/shared/pivot/` (e
`/opt/gts/shared/components/pivotui/multifact-pivottable.js`): `pivot_impl.php`,
`pivot_data_impl.php`, `html2xls_impl.php`, `pivot_toggle_campo_impl.php`,
`pivot_cfg_edit_impl.php`, `pivot_cfg_edit_save_impl.php`,
`pivot_cfg_test_select_impl.php`, `pivot.layout`,
`pivot.js`, `pivot.css`, `pivot_cfg_edit.layout`, `pivot_cfg_edit.js`. Un bug
fixato qui vale per tutte le app che usano la Pivot — copiarli localmente
romperebbe questa garanzia.