# Manuale Operativo e Architettonico - MyICR Suite

**Data:** 03 Settembre 2025
**Versione Architettura:** 4.0 (Stabile)
**Autori:** Mauro Gagliardi & Assistente AI

## 1. Scopo del Documento

Questo documento serve come riferimento completo e guida pratica per lo sviluppo, la manutenzione e il deployment dell'applicazione **MyICR Suite**. Descrive l'architettura finale, i componenti dell'ecosistema e le procedure operative standard per il rilascio di aggiornamenti.

## 2. Filosofia e Principi Chiave (La Nostra Rotta)

L'architettura di MyICR Suite si basa su principi fondamentali progettati per garantire robustezza, scalabilità e una manutenzione semplificata. La metafora guida è quella della **"Nave Portacontainer"**.

*   **La Nave (Core Applicativo):** L'applicazione è un'entità autonoma.
*   **I Container (Componenti):** Le sue dipendenze (ambiente Python, dati) sono "container sigillati" che vengono caricati a bordo, garantendo l'isolamento.
*   **Zero Installazioni Client:** L'utente finale non deve installare manualmente alcun prerequisito (Python, librerie, ecc.).
*   **Esperienza Utente Curata:** L'avvio e l'aggiornamento sono gestiti da un installer/launcher grafico (`.exe`), che astrae tutta la complessità.
*   **Performance Locale:** L'esecuzione e l'accesso ai dati pesanti avvengono localmente sul PC client per la massima velocità.
*   **Centralizzazione:** La gestione delle versioni e la distribuzione sono centralizzate su un file server, che agisce da "porto principale".

## 3. Architettura Generale

Il sistema è suddiviso in tre ambienti distinti con strutture specifiche.

### 3.1. Ambiente di Sviluppo (L'Officina)

È il workspace sul PC dello sviluppatore (`C:\PYTHON\MyICR_Suite`).

```
C:\PYTHON\MyICR_Suite\
│
├── app/                          # Il pacchetto sorgente dell'applicazione (codice + dati)
│   ├── main.py
│   ├── start.py                  # Bootloader per l'ambiente client
│   ├── database/
│   │   ├── db_dati_master.db
│   │   └── db_dati_daily.db
│   └── ...
│
├── launcher_src/                 # Il codice sorgente del launcher/installer
│   └── __main__.py
│
├── templates/                    # Gli "stampi" per i pacchetti di distribuzione
│   ├── python_embeddable/        # L'ambiente Python "nudo"
│   └── python_embeddable.zip     # Il container sigillato con le librerie
│
├── venv/                         # L'ambiente virtuale per lo sviluppo
├── MyICR_Suite_builder.py        # Lo script ETL per "distillare" i dati
├── MyICR_Suite_deployer.py       # Lo script per pubblicare sul server
└── build_launcher.py             # Lo script di avvio per PyInstaller
```

### 3.2. Ambiente Server (Il Deposito Centrale)

È la struttura finale sulla share di rete, che funge da fonte per tutti i client.

```
\\...\MyICR_Suite\
│
├── client_distribution/          # La "matrice" 1:1 di ciò che va al client
│   ├── app/                      
│   ├── database/                 
│   └── python_embeddable.zip
│
├── shared_db/                    # Database condivisi di produzione (live, R/W)
│   └── db_live.db
│
├── launcher_cache/               # Metadati per il sistema di aggiornamento
│   └── metadata.json
│
└── MyICR_Suite_installer.exe     # L'UNICO file che l'utente esegue
```

### 3.3. Ambiente Client (Il Porto di Destinazione)

È la struttura che viene creata e mantenuta automaticamente dal launcher in `%localappdata%\MyICR_Suite`.

```
C:\Users\<utente>\AppData\Local\MyICR_Suite\
│
├── app/                          # Codice e configurazione dell'applicazione
├── database/                     # Dati di sola lettura locali
├── python_embeddable/            # Ambiente Python decompresso
└── launcher_cache/               # Copia locale dei metadati
    └── metadata.json
```

## 4. Procedura Operativa Standard (La Checklist)

Seguire questi passaggi per rilasciare un aggiornamento.

### 4.1. CASO A: Aggiornamento Completo (Tipico del Lunedì)

Questo scenario si applica quando sia i dati settimanali che il codice sono stati modificati.

**FASE 0: Aggiornamento dei Dati Grezzi**
1.  **Azione:** Eseguire lo script `start_DataHub.bat`.
2.  **Risultato:** Il "bidone dati" `tv_archive.db` viene aggiornato in `C:\PYTHON\DataHub\db\`.

**FASE 1: Distillazione dei Dati per la Suite**
1.  **Azione:** Aprire un terminale in `C:\PYTHON\MyICR_Suite` (con `venv` attivo).
2.  Eseguire il builder in modalità completa:
    ```bash
    python MyICR_Suite_builder.py --mode completo
    ```
3.  **Risultato:** I file `db_dati_master.db` e `db_dati_daily.db` vengono aggiornati in `app/database/`.

**FASE 2: Pubblicazione sul Server**
1.  **Azione:** Dallo stesso terminale, eseguire il deployer:
    ```bash
    python MyICR_Suite_deployer.py deploy
    ```
2.  **Risultato:** Il deployer rileva le modifiche, copia i nuovi file sul server e aggiorna il `metadata.json` con i nuovi hash e versioni. Il server è ora pronto a distribuire l'aggiornamento.

**FASE 3: Verifica (Simulazione Client)**
1.  **Azione:** Su un PC di test, cancellare la cartella `%localappdata%\MyICR_Suite`.
2.  Eseguire `MyICR_Suite_installer.exe` direttamente dalla share di rete.
3.  **Risultato Atteso:** Il launcher deve installare l'intera applicazione e avviarla con successo. Un secondo avvio deve essere quasi istantaneo.

### 4.2. CASO B: Aggiornamento Rapido (Solo Modifiche al Codice)

Questo scenario si applica quando hai corretto un bug o aggiunto una piccola feature, ma i dati non sono cambiati.

1.  **Azione:** Aprire un terminale in `C:\PYTHON\MyICR_Suite` (con `venv` attivo).
2.  Eseguire direttamente il deployer:
    ```bash
    python MyICR_Suite_deployer.py deploy
    ```
3.  **Risultato:** Il deployer rileverà che solo l'hash di `app` è cambiato. Copierà solo la cartella `app` sul server e aggiornerà il `metadata.json`. I client, al prossimo avvio, scaricheranno solo il codice aggiornato.

## 5. Manutenzione Straordinaria

### 5.1. Aggiornamento dell'Ambiente Python

Da eseguire solo se si aggiunge una nuova libreria o si cambia versione di Python.
1.  Attivare il `venv`: `.\venv\Scripts\activate`.
2.  Aggiornare `requirements.txt`: `pip freeze > requirements.txt`.
3.  "Vestire" l'ambiente embeddable:
    ```bash
    pip install -r requirements.txt --target "templates/python_embeddable/Lib/site-packages"
    ```
4.  Cancellare il vecchio `python_embeddable.zip` da `templates/`.
5.  Creare il nuovo zip dalla cartella `templates/python_embeddable`.
6.  Eseguire un deploy forzato: `python MyICR_Suite_deployer.py deploy -f`.

### 5.2. Aggiornamento del Launcher/Installer

Da eseguire solo se si modifica il codice in `launcher_src/`.
1.  Attivare il `venv`.
2.  Compilare l'eseguibile:
    ```bash
    pyinstaller --name MyICR_Suite_installer --onefile --windowed build_launcher.py
    ```
3.  Copiare manualmente il nuovo `MyICR_Suite_installer.exe` dalla cartella `dist/` alla radice della share di rete sul server, sovrascrivendo il vecchio.

---