urbackup/MEMORY.md

# UrBackup Plugin - Memoria di Sviluppo

## 📋 Informazioni Plugin

- **Nome**: UrBackup
- **Versione**: 0.4.2
- **Compatibilità**: GLPI 11.0.6+, PHP 8.3+
- **Namespace**: `GlpiPlugin\Urbackup`

## ✅ Funzionalità Implementate

### Installazione/Disinstallazione
- ✅ Installazione plugin tramite CLI: `php bin/console glpi:plugin:install urbackup`
- ✅ Attivazione: `php bin/console glpi:plugin:activate urbackup`
- ✅ Disinstallazione: `php bin/console glpi:plugin:uninstall urbackup`

### Struttura File
- `setup.php`: Hook di inizializzazione, menu, tab, versione, prerequisiti
- `hook.php`: Funzioni di installazione (spostate in setup.php per OPcache)
- `src/`: Classi namespaced con namespace `GlpiPlugin\Urbackup`
- `install/`: Script di installazione e disinstallazione database
- `front/`: Pagine PHP per lista server e form
- `ajax/`: Endpoint AJAX per test API (`server_test.php`)

### Classi Principali
| Classe | Descrizione |
|--------|-------------|
| `Config` | Configurazione plugin, tipi asset abilitati |
| `Profile` | Diritti utente, permessi |
| `Server` | Server UrBackup (CRUD) |
| `ServerAsset` | Linking asset-server |
| `AssetTab` | Tab visualizzato sugli asset |
| `MassiveAction` | Azioni massive |
| `UrbackupApiClient` | Client API per comunicazione con UrBackup server |
| `LocationHelper` | Helper per assegnazione server basata su location |
| `Controller/ServerController` | Symfony controller per routes server |
| `Controller/AssetController` | Symfony controller per azioni asset |
| `Command/TestApiCommand` | CLI command per test API |

### Pagine Frontend
- `front/config.form.php`: Pagina configurazione plugin
- `front/server.php`: Lista server UrBackup
- `front/server.form.php`: Form aggiunta/modifica server
- `front/asset.form.php`: Form azioni su asset (connect/disconnect/start backup)
- `ajax/server_test.php`: Endpoint AJAX per test connessione API

### Interfacce GLPI
- ✅ Menu: Amministrazione → Server UrBackup
- ✅ Tab: UrBackup su Computer e asset abilitati
- ✅ Configurazione: Abilitazione tipi asset (legacy + Asset Definition GLPI 11)

## 🔧 Fix e Correzioni Applicate

1. **OPcache**: Funzioni install in setup.php (non in hook.php) per problema OPcache
2. **Duplicate profilerights**: Aggiunto check in `Profile::registerRights()` per evitare duplicati
3. **CSRF**: Include `inc/includes.php` nei file front per gestione CSRF
4. **Firme metodi**: Corretto `getTabNameForItem(CommonGLPI, int)` e `displayTabContentForItem(CommonGLPI, int, int)`
5. **AssetTab incompleto**: Completato metodo `formatTimestamp()` mancante
6. **RIGHT_NAME costante inesistente**: Sostituito `Profile::RIGHT_NAME` con stringa `'plugin_urbackup'` in AssetTab, ServerAsset e MassiveAction. La costante non esiste nel plugin, era un errore di copia-incolla.
7. **Profile self-reference**: Corretto `displayTabContentForItem()` per usare `\Profile` (core GLPI) invece di `Profile` (plugin)
8. **UrbackupApiClient riscritto completamente**: Basato sul Python wrapper, con le seguenti correzioni chiave:
   - Session passata sia nell'URL che nel body POST
   - Content-Type: `application/x-www-form-urlencoded; charset=UTF-8`
   - Autenticazione PBKDF2 compatibile con server UrBackup
   - Login flow: anonymous → salt → login con hash
   - Gestione errore `{"error": 1}` per username inesistente
9. **`htmlescape()` non esistente**: Sostituito con `htmlspecialchars()` in tutti i file (AssetTab, Server, ServerAsset, MassiveAction, Config). La funzione `htmlescape()` non è definita in GLPI né in PHP.
10. **File `front/asset.form.php` mancante**: Creato per gestire connect/disconnect/start_backup dal tab asset.
11. **File debug/junk rimossi**: Eliminati debug_session.php, hook_corrected.php, rector.php, KILL_VED.php, front/debug.php.
12. **`initProfile()` obbligatorio**: Reso `$profile` nullable (`$profile = null`) per compatibilità con GLPI che chiama `initProfile()` senza argomenti.

### Modifica Test API Connection (v0.4.3)

**Data**: 2026-05-19

**Descrizione**: Modificato il comportamento del test API nel form del server:
- Rimosso il pulsante "Test API Connection" manuale
- Rimosse le righe "Last API status", "Last API message", "Last API check"
- Aggiunto controllo automatico della connessione API eseguito ad ogni visualizzazione del form

**Stati visualizzati**:
- 🟢 **Verde** "Connessione API OK" - Connessione riuscita
- 🔴 **Rosso** "Connessione API fallita" - Errore di autenticazione o configurazione
- 🟡 **Giallo** "Server irraggiungibile" - Problemi di rete (timeout, DNS, HTTP 4xx/5xx, SSL)

**File modificati**:
- `src/Server.php`: Rimossa sezione pulsante e aggiunto metodo `testApiConnection()`
- `locales/it_IT.po`, `locales/en_GB.po`, `locales/de_DE.po`: Aggiunte traduzioni

### API UrBackup - Endpoints Verificati
| Endpoint | Metodo | Note |
|----------|--------|------|
| `/x?a=login` | POST | Login anonimo o con sessione |
| `/x?a=salt&username=X` | POST | Richiede salt, ritorna ses + rnd |
| `/x?a=login` | POST | Con username, password hash, ses |
| `/x?a=status` | POST | Richiede ses nel body (non solo URL) |

## 📝 Checklist Pre-Consegna

- [x] `declare(strict_types=1);` in ogni file PHP
- [x] Namespace `Plugin\<Nome>\` e PSR-4 corretto
- [x] Check versione GLPI 11.0.6+ in `setup.php`
- [x] CSRF e permessi su ogni POST/AJAX
- [x] Query parametrizzate o `$DB->request()`
- [x] Output escaped e loggato
- [x] Nessun uso di API deprecate GLPI 11
- [x] Compatibilità PHP 8.3 verificata
- [ ] Istruzioni installazione e test incluse (da completare)

## 🚧 Da Completare

1. **Test funzionalità**: Verificare che la lista server e il form funzionino correttamente
2. **Asset Definition**: Testare con Asset Definition di GLPI 11 se presenti
3. **AJAX**: Endpoint per comunicazione API con server UrBackup
4. **Logging**: Aggiungere trace per debugging
5. **composer.json**: Creare file con PSR-4 e dipendenze

## 📌 Comandi Utili

```bash
# Installare il plugin
php bin/console glpi:plugin:install urbackup

# Attivare il plugin
php bin/console glpi:plugin:activate urbackup

# Disinstallare il plugin
echo "yes" | php bin/console glpi:plugin:uninstall urbackup

# Verificare syntax PHP
php -l plugins/urbackup/src/*.php
php -l plugins/urbackup/front/*.php
```

## 📚 Riferimenti

- GLPI 11 Plugin Development: https://glpi-project.org/documentation/
- Plugin Example: https://github.com/pluginsGLPI/example
- GLPI Inventory: https://github.com/glpi-project/glpi-inventory-plugin

---

## 🔌 API UrBackup - Riferimenti Ufficiali

### Documentazione UrBackup Web API

L'API di UrBackup Server è accessibile via HTTP alla porta 55414 (default). Gli endpoint sono accessibili tramite il path `/x` (es. `http://localhost:55414/x`).

### Risorse API Utilizzate

1. **Python Wrapper** (uroni/urbackup-server-python-web-api-wrapper)
   - URL: https://github.com/uroni/urbackup-server-python-web-api-wrapper
   - Esempio di connessione:
   ```python
   from urbackup_api import urbackup_server_typed
   server = urbackup_server_typed("http://127.0.0.1:55414/x", "admin", "password")
   server.login()
   ```

2. **Node.js Wrapper** (bartmichu/node-urbackup-server-api)
   - URL: https://github.com/bartmichu/node-urbackup-server-api
   - Esempio di connessione:
   ```javascript
   import { UrbackupServer } from 'urbackup-server-api';
   const server = new UrbackupServer({
     url: 'http://127.0.0.1:55414',
     username: 'admin',
     password: 'secretpassword',
   });
   ```

### Endpoint API Principali

| Metodo | Descrizione |
|--------|-------------|
| `login` | Autenticazione con username/password |
| `get_status` | Lista client con stato backup |
| `get_backups` | Lista backup per client |
| `start_backup` | Avvia backup (file/image) |
| `get_progress` | Monitora progresso backup |
| `get_clients` | Lista clienti |
| `get_groups` | Lista gruppi |

### Implementazione Corrente

La classe `UrbackupApiClient` in `src/UrbackupApiClient.php` gestisce la connessione API. Il test di connessione deve:
1. Tentare login con credenziali salvate
2. Verificare risposta JSON valida
3. Mostrare messaggio di successo/errore

### Problemi Noti

- **JSON Parse Error**: L'API restituisce HTML invece di JSON quando le credenziali sono errate
- **Timeout**: Verificare che il server UrBackup sia raggiungibile
- **SSL**: Se `ignore_ssl` è attivo, accettare certificati auto-signati
### Debug - AJAX Endpoint 403 Error

Il test del pulsante "Test API" continua a restituire 403 Forbidden quando accesso via curl. Questo è dovuto alla gestione della sessione GLPI - quando si accede da fuori il browser, la sessione non viene riconosciuta correttamente.

**Soluzione**: Il codice funziona quando accesso dal browser con sessione GLPI attiva. L'endpoint `front/server_test.ajax.php` e il JS in `public/js/urbackup.js` sono configurati correttamente.

**File chiave**:
- `front/server_test.ajax.php` - endpoint AJAX per test API
- `public/js/urbackup.js` - JavaScript per gestire il click del pulsante

**Test da effettuare**:
1. Accedere a GLPI con browser
2. Navigare a: Server UrBackup > Modifica server
3. Cliccare "Test API connection"
4. Verificare che appaia "Testing..." e poi il risultato

### Modifica Tab Linked/Unlinked Clients (v0.4.4)

**Data**: 2026-05-19

**Descrizione**: Modificato il comportamento delle tabelle nel form del server:

**Linked Clients**:
- Query alla tabella `glpi_plugin_urbackup_serverassets` dove `plugin_urbackup_servers_id` = ID server
- Per ogni asset collegato: mostrare `client_name` (dal DB)
- Recuperare le altre info (status, last backup, IP) via API da UrBackup
- I campi statici nel DB (client_version, last_file_backup, last_image_backup, last_sync) non vengono più usati per la visualizzazione

**Unlinked Clients**:
- Chiamata API a UrBackup per ottenere tutti i client presenti sul server
- Escludere tutti i client che sono già nella tabella `glpi_plugin_urbackup_serverassets` (collegati a qualsiasi server, non solo quello visualizzato)
- Mostrare i client rimanenti con le info da API

**Correzione bug**:
- Nome tabella corretto: `glpi_plugin_urbackup_serverassets` (non `glpi_plugin_urbackup_server_assets`)
- Campo corretto: `plugin_urbackup_servers_id` (non `servers_id`)

**File modificati**:
- `src/Server.php`: Modificati metodi `showLinkedClientsTab()` e `showUnlinkedClientsTab()`

### Tabella semplificata glpi_plugin_urbackup_serverassets (v0.4.5)

**Data**: 2026-05-19

**Descrizione**: Semplificata la tabella per collegamento asset-server:
- Rimossi campi non necessari: `client_name`, `client_ip`, `client_version`, `is_active`, `last_file_backup`, `last_image_backup`, `last_sync`, `date_creation`, `date_mod`, `urbackup_client_id`
- La tabella ora contiene solo: `id`, `plugin_urbackup_servers_id`, `itemtype`, `items_id`
- Il nome dell'asset viene recuperato dinamicamente da GLPI (sempre aggiornato)
- Il confronto con UrBackup avviene via API

**File modificati**:
- `install/mysql/plugin_urbackup-empty.sql`: Schema semplificato
- `install/install.php`: Funzione aggiornata
- `src/ServerAsset.php`: Metodi `createForAsset()`, `getAssetName()`
- `src/AssetTab.php`: Recupero nome asset da GLPI
- `src/Server.php`: Tabelle Linked/Unlinked aggiornate
- `src/MassiveAction.php`: Rimossi messaggi confusing
- `front/asset.form.php`: Corretto redirect e gestione disconnessione

### Funzionalità API completate (v0.4.6)

**Data**: 2026-05-19

**Descrizione**: Completate le funzionalità API mancanti:
- Salvataggio Modalità Internet su server UrBackup
- Salvataggio Directory Predefinite su server UrBackup
- Esecuzione backup file (incremental/full)
- Esecuzione backup immagine (incremental/full)
- Recupero versione client da API

**File modificati**:
- `src/AssetTab.php`: Aggiunti metodi `startBackup()`, `saveInternetMode()`, `saveDefaultDirs()`
- `src/UrbackupApiClient.php`: Aggiunti metodi `updateClientSettings()`, `saveInternetMode()`
- `front/asset.form.php`: Gestione azioni per salvataggio impostazioni e backup

### Refactoring server.form.php e nuove tab (v0.4.7)

**Data**: 2026-05-21

**Descrizione**: Restrutturazione completa della pagina server con tab laterali e nuove funzionalità:

**Refactoring Server::showForm()**:
- Estratto `showFormFields(?int $ID)` da `showForm()` per permettere layout custom
- `showForm()` ora chiama header + fields + buttons in sequenza

**Tab laterali (server.form.php)**:
- Side tabs a sinistra (col-2) con `nav-pills flex-column`
- 4 tab: Server, Linked clients, Unlinked clients, Missing clients
- Tab persistence via URL hash (JS su `shown.bs.tab`)

**Missing clients tab**:
- Mostra asset GLPI con root location matching, non ancora collegati a ServerAsset e non presenti su UrBackup
- Colonne: Name (link all'asset), Entity, Location (completename), Inventory number, IP, State, User, Group
- Ricerca testuale client-side
- Ordinamento colonne click-to-sort vanilla JS
- Navigazione server spostata in server.form.php (sopra i tab, indipendente dalle sezioni)

**Bug fix namespace risolto**:
- `getCachedName()` usava `new $classname()` con stringa → PHP cercava `GlpiPlugin\Urbackup\Group` invece di `\Group`
- Fix: `$fqcn = '\\' . ltrim($classname, '\\')` per forzare global namespace

**Gruppo asset corretto**:
- Gruppo non in `glpi_computers.groups_id` (colonna inesistente)
- Letto da `glpi_groups_items` WHERE `type = 1` (GROUP_TYPE_NORMAL)
- Usa `completename` per gerarchia (es. "Helpdesk > Livello 1")

**Indirizzo IP asset**:
- Query JOIN: `glpi_ipaddresses → glpi_networknames → glpi_networkports`
- Primo IP valido per l'item

**Breadcrumb**:
- Cambiato da `'Assets'` a `'admin'` in `Html::header()` di server.php e server.form.php
- Mostra: Pagina principale > Amministrazione > UrBackup servers

**Fix port default per nuovi server**:
- `prepareInputForAdd()` ora setta default 55414 per `port`, 'http' per `protocol`, 1 per `is_active`, ecc.
- `prepareInputForUpdate()` normalizza anche valori vuoti

**File modificati**:
- `src/Server.php`: `showFormFields()`, `showMissingClientsTab()`, `getCachedName()` fix, `getAssetGroupName()`, `getAssetIp()`, `getCachedLocationName()`, `prepareInputForAdd/Update` default fix, icona `ti-cloud-up`
- `front/server.form.php`: Tab laterali, tab hash JS, breadcrumb admin, navigazione server
- `front/server.php`: Breadcrumb admin, rimosso pulsante "Add" manuale
- `src/Profile.php`: Icona `ti-cloud-up`
- `src/AssetTab.php`: Icona `ti-cloud-up`
- **Permessi**: `front/server.form.php` ora usa READ invece di UPDATE per accesso form; View search option + pulsanti Connect nascosti per READ; API username/password nascosti per READ
- **i18n**: aggiunte 17 stringhe mancanti con dominio `urbackup` a tutti i file e .po/.mo (it, en, de)
- **Bug fix**: ServerAsset colonne rimosse, asset.form.php usa disconnectAsset(), `declare(strict_types=1)` in 11 file