SXXXXXXX_ProjectUtility/doc/Italian-manual.md

Italiano

1. Introduzione

Benvenuto al Project Utility Dashboard! Questa applicazione è progettata per fornire un'interfaccia centralizzata e intuitiva per la gestione e l'esecuzione di una varietà di strumenti a riga di comando, script e applicazioni esterne, sia che siano memorizzati localmente sia che siano gestiti tramite repository Git.

Obiettivi Chiave:

• Semplificare l'Esecuzione: Avviare strumenti complessi con parametri multipli attraverso una GUI intuitiva.
• Organizzare gli Strumenti: Mantenere tutte le utility usate di frequente in un unico posto facilmente accessibile.
• Gestire Strumenti Basati su Git: Clonare, aggiornare ed eseguire facilmente strumenti direttamente da Git.
• Migliorare il Flusso di Lavoro: Risparmiare tempo ricordando i parametri e fornendo un'esperienza di avvio coerente.

2. Installazione e Configurazione

(Questa sezione potrebbe richiedere personalizzazioni in base al tuo metodo di distribuzione)

• Prerequisiti:
  • Python 3.8+
  • (Opzionale ma Raccomandato) Git installato e disponibile nel PATH di sistema per le funzionalità degli strumenti Git.
  • (Opzionale) Libreria Python GitPython (pip install GitPython) per le funzionalità complete di integrazione Git nel dashboard. Se non presente, gli elementi UI relativi a Git saranno disabilitati o mostreranno "GitPython Mancante".
• Esecuzione da Sorgente:
  1. Clona il repository ProjectUtility.
  2. Installa le dipendenze: pip install -r requirements.txt (Dovrai creare questo file elencando GitPython se lo usi).
  3. Avvia l'applicazione: python -m projectutility dalla radice del repository.
• Utilizzo di un Eseguibile PyInstaller:
  1. Scarica o compila ProjectUtility.exe (o l'eseguibile specifico per la piattaforma).
  2. Posiziona l'eseguibile in una directory desiderata.
  3. Al primo avvio, potrebbe creare sottodirectory config/, logs/ e managed_tools/ accanto all'eseguibile se non esistono.

3. Panoramica dell'Applicazione

La finestra principale è suddivisa in diverse aree chiave:

• Barra dei Menu:
  • Tools (Strumenti):
    • Update All Git Tools: Tenta di clonare o scaricare aggiornamenti per tutti gli strumenti Git abilitati.
    • Configure Selected Tool...: Apre una finestra di dialogo per configurare lo strumento attualmente selezionato.
    • Reload Tool List: Rianalizza manualmente il registro degli strumenti e aggiorna l'elenco.
• Pannello "Available Tools" (Sinistra): Elenca tutti gli strumenti scoperti e abilitati. Cliccando su uno strumento lo si seleziona per la configurazione e l'esecuzione.
• Pannello "Tool Options" (In Alto a Destra, Scorrevole):
  • Mostra Display Name e Description dello strumento selezionato.
  • Mostra informazioni sullo stato Git se è uno strumento gestito tramite Git.
  • Genera dinamicamente widget di input per i Parameters definiti per lo strumento.
• Pannello "Output Log" (Al Centro a Destra): Mostra stdout e stderr degli strumenti in esecuzione, così come messaggi di stato dal dashboard stesso.
• Area Pulsante "Run" (In Basso a Destra): Contiene il pulsante "Run Tool".
• Pannello "Running Tools" (In Basso): Una vista ad albero che elenca tutti gli strumenti attualmente in esecuzione da parte del dashboard, mostrando il loro Run ID, Nome, Stato e PID. Permette la terminazione dei processi selezionati.

4. Configurazione degli Strumenti (tools_registry.json)

La flessibilità del dashboard risiede nel file projectutility/config/tools_registry.json (o [AppExecutableDir]/config/tools_registry.json per le app "frozen"). Questo file JSON contiene un array di oggetti di definizione degli strumenti.

Anatomia di una Voce di Strumento:

{
  "id": "id_univoco_strumento", // Obbligatorio, stringa univoca
  "display_name": "Il Mio Fantastico Strumento", // Obbligatorio, stringa mostrata nella GUI
  "description": "Questo strumento fa cose fantastiche.", // Opzionale, stringa
  "type": "local", // Obbligatorio: "local" o "git"
  "enabled": true, // Opzionale, booleano (default: true)
  "run_command": ["python", "scripts/mio_script.py"], // Obbligatorio, lista di stringhe
  "has_gui": false, // Obbligatorio, booleano (lo strumento ha una sua GUI?)
  "version": "1.0.1", // Opzionale, stringa
  // --- Per type: "local" ---
  "parameters": [ // Opzionale, lista di oggetti parametro
    {
      "name": "file_input",
      "label": "File di Input:",
      "type": "file", // es. string, integer, float, boolean, file, folder
      "required": true,
      "default": "default.txt", // Valore di default opzionale
      "description": "Percorso al file di dati di input.", // Tooltip opzionale
      "options": {"filter": [["File di Testo", "*.txt"], ["Tutti i File", "*.*"]]} // Opzionale, specifico per tipo
    }
  ],
  // --- Per type: "git" ---
  "git_url": "https://gitea.example.com/utente/mio_strumento_git.git", // Richiesto per "git"
  "git_ref": "main", // Opzionale, default "main" (branch, tag, o commit)
  "local_dir_name": "mio_clone_strumento_git", // Opzionale, nome directory in managed_tools/
  "parameters_definition_file": "tool_params.json" // Opzionale, percorso a file JSON nella root del repo
}

Spiegazione dei Campi Chiave:

• id: Deve essere univoco per tutti gli strumenti.
• type:
  • local: Per eseguibili nel PATH o script nella directory tools/ dell'applicazione.
    • Directory tools/ (per script):
      • Se eseguito da sorgente: [RepoRoot]/tools/
      • Se eseguito come eseguibile: [AppExecutableDir]/_internal/tools/ (impacchettato da PyInstaller)
  • git: Per strumenti clonati e gestiti da un repository Git. Saranno clonati in managed_tools/.
• run_command:
  • Il primo elemento è solitamente l'eseguibile (es. python, powershell.exe, mia_app.exe).
  • Gli elementi successivi sono argomenti.
  • Per script locali in tools/, usare percorsi relativi a tools/, es. ["python", "mia_sottodir_strumento/main.py"]. Il dashboard risolve questo in un percorso assoluto.
• parameters: Un array di oggetti, ognuno dei quali definisce un parametro di input per la GUI.
  • name: Chiave interna per il parametro.
  • label: Testo mostrato accanto al campo di input.
  • type: Determina il widget: string, integer, float, boolean, file (seleziona file), folder (seleziona directory).
  • required: true o false.
  • default: Un valore di default.
  • description: Testo del tooltip.
  • options: Configurazioni specifiche per tipo. Per file: {"filter": [["Descrizione", "*.ext"]], "save_as": false}.
• parameters_definition_file (per strumenti git): Se specificato, è un percorso relativo alla radice del repository Git clonato a un file JSON. Questo file JSON deve avere un oggetto radice con una chiave "parameters" che è un array di oggetti parametro (stesso formato dei parameters inline).
• local_dir_name (per strumenti git): Se omesso, viene usato l'id come nome della directory all'interno di managed_tools/.

Esempio: Script Python Locale

{
  "id": "mio_script_locale",
  "display_name": "Mio Elaboratore Dati",
  "description": "Elabora dati CSV usando uno script Python locale.",
  "type": "local",
  "run_command": ["python", "elaborazione_dati/processor.py"],
  "has_gui": false,
  "parameters": [
    {"name": "csv_input", "label": "CSV di Input:", "type": "file", "required": true, "options": {"filter": [["File CSV", "*.csv"]]}},
    {"name": "cartella_output", "label": "Dir Output:", "type": "folder", "required": true},
    {"name": "soglia", "label": "Soglia:", "type": "float", "required": false, "default": 0.5}
  ]
}

(Questo presume che elaborazione_dati/processor.py esista nella tua directory tools/).

Esempio: Strumento Gestito da Git

{
  "id": "fantastica_cli_git",
  "display_name": "Fantastica CLI (da Git)",
  "description": "Un'utility a riga di comando recuperata da Git.",
  "type": "git",
  "git_url": "https://gitea.example.com/utente/fantastica-cli.git",
  "git_ref": "v1.2.0", // Traccia un tag specifico
  "run_command": ["python", "fantastica_cli/main.py"], // Comando relativo alla root del repo clonato
  "has_gui": false,
  "parameters_definition_file": "params_config.json" // File nella root del repo fantastica-cli
}

5. Utilizzo del Dashboard

1. Avvia l'Applicazione.
2. Seleziona uno Strumento: Clicca sul nome di uno strumento nell'elenco "Available Tools" a sinistra.
3. Rivedi e Inserisci i Parametri:
   • La descrizione dello strumento ed eventuali informazioni sullo stato Git appariranno nell'area "Tool Options".
   • Verranno mostrati i campi di input per i parametri dello strumento. Compilali come richiesto.
   • I parametri obbligatori sono tipicamente indicati dalla GUI (es. un asterisco o uno stile distinto, anche se l'implementazione attuale si basa su label*).
   • Per tipi file o folder, usa il pulsante "Browse...".
   • Gli ultimi parametri utilizzati sono spesso precompilati.
4. Avvia lo Strumento: Clicca il pulsante "Run Tool".
5. Monitora l'Output: Osserva stdout e stderr nell'"Output Log". I messaggi possono essere colorati o formattati specialmente se lo strumento emette JSON strutturato.
6. Gestisci gli Strumenti in Esecuzione:
   • Il pannello "Running Tools" in basso mostra i processi attivi.
   • Per terminare uno strumento, selezionalo in questo pannello e clicca "Terminate Selected".

6. Gestione degli Strumenti Git

• Clonazione Iniziale: Se uno strumento Git non è ancora stato clonato, selezionandolo nell'elenco potrebbe mostrare "Not Cloned". Tentare di "Aggiornare Tutti gli Strumenti Git" o aggiornarlo tramite la sua finestra "Configura Strumento Selezionato..." attiverà il processo di clonazione nella directory managed_tools/.
• Controllo dello Stato:
  • Quando si seleziona uno strumento Git, il suo stato Git attuale (relativo al git_ref configurato su origin) viene recuperato e visualizzato.
  • Questo può essere aggiornato manualmente dalla finestra di configurazione dello strumento.
• Aggiornamento degli Strumenti:
  • Singolo Strumento: Apri la finestra di dialogo "Configura Strumento Selezionato...", opzionalmente cambia il campo Git Ref, e clicca "Update This Tool".
  • Tutti gli Strumenti: Usa la voce di menu "Tools" > "Update All Git Tools". Questo itererà su tutti gli strumenti Git abilitati, recupererà le ultime modifiche da origin e tenterà di portarli al loro git_ref configurato.
• Output durante l'Aggiornamento: I messaggi di avanzamento (clonazione, fetch, checkout) appariranno nell'"Output Log".

7. Finestra di Configurazione Strumento

Accessibile tramite "Tools" > "Configure Selected Tool..." (quando uno strumento è selezionato).

• Campi Modificabili:
  • Display Name: Cambia come lo strumento appare nell'elenco.
  • Description: Modifica il testo descrittivo dello strumento.
  • Enabled: Attiva/disattiva se lo strumento è attivo e scopribile.
  • Git Ref (solo per strumenti Git): Cambia il branch, tag o hash di commit che lo strumento deve tracciare. Nota: Il processo di aggiornamento tenterà di fare il checkout di questo nuovo riferimento.
• Info di Sola Lettura: Mostra altri dettagli configurati come Tool ID, Run Command, Git URL.
• Stato Git (per strumenti Git):
  • Mostra lo stato dettagliato (riferimento locale corrente, hash, ecc.).
  • Pulsante Refresh Status: Ri-effettua il fetch dal remoto e aggiorna la visualizzazione dello stato.
  • Pulsante Update This Tool: Avvia un aggiornamento per questo strumento al suo Git Ref attualmente configurato (o appena inserito).
• Salvataggio: Clicca "Save Changes" per rendere persistenti le modifiche a tools_registry.json. L'elenco principale degli strumenti si aggiornerà.

8. Risoluzione dei Problemi

• ModuleNotFoundError: No module named 'projectutility' (App "Frozen"):
  • Assicurati che tutti i file __init__.py necessari siano presenti nelle directory del pacchetto sorgente (projectutility/, projectutility/core/, projectutility/gui/).
  • Controlla il tuo file .spec di PyInstaller:
    • pathex dovrebbe puntare alla directory radice del tuo progetto.
    • hiddenimports dovrebbe elencare projectutility e i suoi sottomoduli se non rilevati automaticamente.
    • datas deve includere correttamente i file non Python come gli script degli strumenti locali (directory tools) ed eventuale tools_registry.json di default che vuoi impacchettare.
• Strumento Non Trovato / "Non Disponibile":
  • Strumenti Locali:
    • Verifica run_command in tools_registry.json.
    • Se è un eseguibile (es. notepad.exe), assicurati che sia nel PATH di sistema.
    • Se è uno script, assicurati che il percorso dello script in run_command (es. mia_dir_script/script.py) sia corretto relativamente alla directory tools/ e che la directory tools/ (con lo script) sia correttamente impacchettata se si esegue l'app "frozen".
  • Strumenti Git:
    • Assicurati che git_url sia corretto e accessibile.
    • Controlla se lo strumento è stato clonato in managed_tools/. In caso contrario, prova ad aggiornarlo.
    • Verifica che il percorso run_command sia corretto relativamente alla radice del repository Git clonato.
    • Se viene utilizzato un parameters_definition_file, assicurati che il suo percorso sia corretto relativamente alla radice del repo clonato.
• Operazioni Git Fallite:
  • Assicurati che Git sia installato e nel PATH.
  • Assicurati che GitPython sia installato nell'ambiente Python che il dashboard sta usando.
  • Controlla la connettività di rete al remote Git.
  • Esamina i messaggi nell'"Output Log" per errori Git specifici.
• Permesso Negato: L'applicazione (o l'utente che la esegue) potrebbe non avere il permesso di eseguire uno script o accedere a una directory.