210 lines
14 KiB
Markdown
210 lines
14 KiB
Markdown
## 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:**
|
|
|
|
```json
|
|
{
|
|
"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**
|
|
|
|
```json
|
|
{
|
|
"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**
|
|
|
|
```json
|
|
{
|
|
"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. |