# RateOS — Istruzioni operative

**Versione**: 2.0
**Studio**: Andrea Torresi — Dottore Commercialista e Revisore Legale
**Ultimo aggiornamento**: 5 maggio 2026

---

## Indice

1. [Cosa è RateOS](#1-cosa-è-rateos)
2. [Primo avvio](#2-primo-avvio)
3. [Operatività quotidiana](#3-operatività-quotidiana)
4. [Caricare un avviso bonario](#4-caricare-un-avviso-bonario)
5. [Gestione clienti Persone Fisiche](#5-gestione-clienti-persone-fisiche)
6. [Download F24 e prospetti Excel](#6-download-f24-e-prospetti-excel)
7. [Invio email al cliente](#7-invio-email-al-cliente)
8. [Personalizzazione testi email](#8-personalizzazione-testi-email)
9. [Memo automatici di scadenza](#9-memo-automatici-di-scadenza)
10. [Pulizia e manutenzione](#10-pulizia-e-manutenzione)
11. [Risoluzione problemi](#11-risoluzione-problemi)
12. [Riferimenti normativi](#12-riferimenti-normativi)

---

## 1. Cosa è RateOS

RateOS è l'applicazione interna dello Studio per automatizzare il ciclo completo della rateazione degli avvisi bonari emessi dall'Agenzia delle Entrate ai sensi degli artt. 36-bis DPR 600/1973, 54-bis DPR 633/1972 e 36-ter DPR 600/1973.

Il sistema:

- **legge** automaticamente i dati dal PDF dell'avviso bonario (parser pdfplumber);
- **calcola** il piano di rateazione interrogando il portale ufficiale `ratef24` dell'AdE;
- **scarica** i modelli F24 precompilati per ciascuna rata;
- **archivia** tutto su un database privato (TiDB Cloud cluster);
- **genera** prospetti Excel professionali e archivi ZIP degli F24;
- **invia** automaticamente email ai clienti, sia all'apertura della pratica sia 10 giorni prima di ogni scadenza.

---

## 2. Primo avvio

> Da fare **una sola volta**, alla prima installazione su un nuovo computer.

### 2.1 Avvia l'applicazione

Apri PowerShell nella cartella `RateOS` e digita:

```powershell
.\venv\Scripts\python.exe -m uvicorn web.app:app --host 127.0.0.1 --port 8000 --reload
```

Lascia il terminale aperto. Apri il browser su:

> **http://127.0.0.1:8000**

### 2.2 Configura le credenziali

Vai su **Configurazione** (icona ingranaggio in alto a destra). Compila:

**Database TiDB Cloud**
- `Host`, `Porta`, `Database`, `Username`, `Password` — ottieni questi dati creando un cluster Serverless gratuito su [tidbcloud.com](https://tidbcloud.com). Procedura passo-passo nella pagina **Setup guidato**.

**Server SMTP**
- `Server SMTP`, `Porta`, `Indirizzo mittente`, `App Password` — per Google Workspace usa `smtp.gmail.com:587` e una App Password generata su [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords).

### 2.3 Testa le connessioni

Sulla stessa pagina:
- **Testa connessione DB** — deve restituire "Connesso a TiDB v…"
- **Testa invio email** — deve restituire "Login SMTP OK su…"

Se entrambi rispondono OK, click **Salva configurazione**.

### 2.4 Riavvia il server e inizializza il database

Da terminale: `Ctrl+C` per fermare il server, poi rilancia il comando del punto 2.1.

Apri un secondo terminale nella stessa cartella e digita:

```powershell
.\venv\Scripts\python.exe main.py --init-db
```

Crea le tabelle e popola i template email di default. Il messaggio finale deve essere:

> `Database RateOS inizializzato su TiDB Cloud.`

---

## 3. Operatività quotidiana

### Lanciare l'applicazione

Ogni volta che apri il computer, riavvia il server con:

```powershell
.\venv\Scripts\python.exe -m uvicorn web.app:app --host 127.0.0.1 --port 8000 --reload
```

Apri il browser su **http://127.0.0.1:8000**.

### Spegnere l'applicazione

Nel terminale del server premi `Ctrl+C`. Per chiudere completamente, chiudi il terminale.

---

## 4. Caricare un avviso bonario

### 4.1 Persona Giuridica (S.R.L., S.p.A., S.n.c., …)

1. Click **Carica avviso** dalla home oppure dalla navbar.
2. Seleziona il PDF dell'avviso bonario originale dell'AdE.
3. Click **Estrai dati**.
4. Verifica i dati estratti nella pagina di conferma:
   - Codice atto, anno imposta, tipo comunicazione (9001/9002/9003), importo, date.
   - Ragione sociale (verrà troncata automaticamente a 25 caratteri come richiesto dal form AdE).
   - Domicilio fiscale (indirizzo, comune, provincia).
   - Email del cliente (opzionale, ma necessaria per i memo).
5. **Numero rate**: scegli un valore tra 2 e 20. Campo obbligatorio, da decidere caso per caso secondo la liquidità del cliente.
6. (Opzionale) Spunta **Invia subito al cliente** se vuoi che, al termine del calcolo, parta automaticamente l'email con prospetto Excel + ZIP F24.
7. Click **Calcola piano e scarica F24**.

Il sistema interroga l'AdE, scarica gli F24 e ti porta alla dashboard.

### 4.2 Persona Fisica

Stesso flusso del punto 4.1, ma in più devi indicare **anagrafica nascita** (data, provincia, comune, sesso) — dato richiesto dal form AdE per i soggetti `aso=F` e non presente nel PDF dell'avviso.

**Conviene pre-registrare il cliente PF** una sola volta (vedi sezione 5), così al successivo upload del suo avviso i dati nascita vengono caricati automaticamente.

---

## 5. Gestione clienti Persone Fisiche

Vai su **Clienti PF** dalla navbar.

### Pre-registrare un PF

Compila il form a destra ("Registra Persona Fisica"):
- Codice fiscale (16 caratteri, alfanumerico)
- Cognome, Nome
- Data nascita (GG/MM/AAAA), Provincia (sigla), Comune
- Sesso (M / F)
- Email (opzionale)

Click **Registra**. Da quel momento, ogni avviso bonario di quel CF importerà automaticamente l'anagrafica.

### Aggiornare l'anagrafica

Riapri il form per lo stesso CF: i nuovi valori sovrascrivono quelli vecchi.

---

## 6. Download F24 e prospetti Excel

### Per singola rata

In dashboard, espandi la card cliente, espandi la pratica e click sul bottone **F24** della rata desiderata.

### Per pratica completa (tutti gli F24 in ZIP)

In dashboard, sull'header della pratica click **ZIP F24**. Scarica un singolo archivio compresso con tutti gli F24 della pratica.

Nome del file:
> `F24_{ragionesociale_o_cognome_nome}_{codice_atto}.zip`

### Prospetto Excel del piano

Sull'header della pratica click **Excel**. Scarica un workbook con due fogli:
- **Riepilogo** — anagrafica cliente, dati pratica, importo totale, importo residuo, riferimenti normativi.
- **Piano rate** — tabella completa con #, scadenza, capitale, interessi, totale, stato (futura/imminente/scaduta/pagata) con colorazione, riga totali.

Nome del file:
> `Prospetto_{ragionesociale_o_cognome_nome}_{codice_atto}.xlsx`

---

## 7. Invio email al cliente

### Invio "prima volta"

Manda al cliente in un'unica email: prospetto Excel + ZIP con tutti gli F24 + corpo del messaggio dal template `prima_invio`.

**Modalità A — Automatica al caricamento**
Spunta la checkbox **Invia subito al cliente** nella pagina di conferma upload. L'email parte appena terminato il calcolo del piano.

**Modalità B — Manuale dalla dashboard**
Espandi la pratica e click **Invia al cliente** sull'header.

### Reinvio

Se l'email è già stata inviata, il bottone diventa **Reinvia al cliente** e c'è il badge "✓ Email cliente inviata". Cliccare reinvia l'email aggiornata (utile se hai modificato il template o cambiato i dati della pratica).

### Requisiti

- Il cliente deve avere un'email registrata (vedi pagina Clienti PF o campo email in conferma upload).
- Server SMTP correttamente configurato e testato.

---

## 8. Personalizzazione testi email

Vai su **Configurazione → Modifica testi email** oppure direttamente su `/configurazione/email-templates`.

### Template disponibili

- **`prima_invio`** — email post-creazione del piano (con allegati Excel + ZIP F24).
- **`memo_scadenza`** — promemoria automatico 10 giorni prima di ogni scadenza (con singolo F24 in allegato).

### Segnaposti dinamici

Quando salvi oggetto e corpo, puoi usare questi segnaposti tra parentesi graffe:

| Segnaposto | Descrizione | Disponibile in |
|---|---|---|
| `{nome_destinatario}` | Ragione sociale (PNF) o Nome+Cognome (PF) | Entrambi |
| `{codice_atto}` | Codice atto AdE | Entrambi |
| `{importo_totale}` | Totale dell'avviso o della rata (formato italiano) | Entrambi |
| `{numero_rate}` | Numero rate del piano | Solo `prima_invio` |
| `{importo_prima_rata}` | Capitale + interessi prima rata | Solo `prima_invio` |
| `{scadenza_prima_rata}` | Data scadenza prima rata (GG/MM/AAAA) | Solo `prima_invio` |
| `{numero_rata}` | Numero della rata in scadenza | Solo `memo_scadenza` |
| `{scadenza}` | Data di scadenza (GG/MM/AAAA) | Solo `memo_scadenza` |

I segnaposti vengono sostituiti al momento dell'invio. Se scrivi un segnaposto inesistente, viene lasciato letterale nel testo.

### Esempio di personalizzazione

```
Oggetto: Studio Torresi — Piano rate atto {codice_atto}

Corpo:
Gentile {nome_destinatario},

abbiamo elaborato per Lei il piano di rateazione su {numero_rate} rate
(prima rata: € {importo_prima_rata} entro il {scadenza_prima_rata}).

Resto a disposizione,
Andrea Torresi
```

---

## 9. Memo automatici di scadenza

Lo scheduler interno (`automazione/scheduler.py`, basato su APScheduler) viene avviato automaticamente al lancio dell'applicazione. Ogni giorno all'orario configurato in `/configurazione` esegue `invia_memo_scadenze` per tutte le soglie configurate.

### Configurazione (UI `/configurazione` → card "Memo automatici scadenze")

- **Stato scheduler**: Attivo / Disattivato
- **Orario invio giornaliero**: HH:MM (fuso `Europe/Rome`)
- **Giorni di anticipo**: CSV soglie. Esempi:
  - `10` → 1 memo a 10 giorni dalla scadenza
  - `10,3,1` → 3 memo per ogni rata (10gg, 3gg, 1gg prima)
  - `30,15,7,1` → 4 memo a cadenza decrescente
- **Esegui memo ora**: bottone per esecuzione manuale immediata (utile per test)

Le modifiche si applicano **senza riavviare il server**: lo scheduler si riconfigura automaticamente al salvataggio.

### Idempotenza e multi-PC

Ogni rata tiene traccia delle soglie già inviate nella colonna `memo_inviati_gg` (CSV). Per impedire **email duplicate quando più PC dello studio sono accesi contemporaneamente** è implementato un lock cooperativo SQL: solo il primo PC che esegue l'`UPDATE` atomico ottiene il diritto di inviare; gli altri vedono la soglia già marcata e saltano.

In caso di errore SMTP, il claim viene rilasciato (la soglia torna disponibile) così un retry successivo può ritentare.

### Esecuzione manuale (CLI)

```powershell
.\venv\Scripts\python.exe -c "from notifiche.memo_service import invia_memo_scadenze; print(invia_memo_scadenze())"
```

---

## 9-bis. Distribuzione multi-PC nello studio

Se RateOS è installato su più postazioni dello studio, **tutti i PC condividono lo stesso database TiDB Cloud** (basta usare le stesse credenziali in `/configurazione`). Per condividere anche gli **allegati F24 e i PDF degli avvisi** segui questi passi:

### Archivio condiviso su NAS / share di rete

1. Crea uno share di rete accessibile a tutti i PC, es. `\\nas-studio\studio\rateos\` oppure un disco mappato `S:\rateos\`.
2. Su ciascun PC, imposta la variabile d'ambiente di sistema:
   ```
   RATEOS_DATA_DIR = \\nas-studio\studio\rateos
   ```
   (Pannello di Controllo → Sistema → Impostazioni avanzate → Variabili d'ambiente → Variabili di sistema → Nuova).
3. Riavvia RateOS su tutti i PC. Tutti vedranno lo stesso archivio F24 + PDF input + `.env`.

**Vantaggi:**
- Un solo `.env` da configurare (sul NAS), tutti i PC ereditano credenziali.
- F24 generati da PC1 sono immediatamente accessibili da PC2.
- Backup unico sullo share.

**Senza condivisione**, ogni PC ha il proprio `%LOCALAPPDATA%\RateOS\` con allegati locali (DB però rimane condiviso → le pratiche sono visibili a tutti, ma i PDF F24 solo sul PC che li ha generati).

### Scheduler memo: lasciare attivo su tutti

Grazie al lock SQL cooperativo, puoi tranquillamente lasciare `MEMO_ATTIVO=true` su tutti i PC: solo uno invierà effettivamente l'email per ogni rata/soglia, gli altri vedranno il claim già preso. Questo garantisce continuità anche se un PC è spento.

---

## 10. Pulizia e manutenzione

### Pulire l'archivio (TUTTO)

Vai su **Configurazione**, in fondo alla pagina nel riquadro rosso **Pulizia archivio**:

1. Scrivi `PULISCI` nel campo (esattamente, in maiuscolo).
2. Click **Pulisci tutto**, conferma il dialog.

Vengono eliminati:
- Tutte le righe da `clienti`, `pratiche`, `rate`.
- Tutti i file PDF in `allegati_f24/`.
- Tutti i PDF di input in `allegati_pdf_input/`.

> ⚠️ **Operazione non reversibile**. Fai sempre prima un backup esportando i prospetti Excel di tutte le pratiche, oppure un dump del DB.

### Backup

**Backup files**
Copia regolarmente le cartelle `allegati_f24/` e `allegati_pdf_input/` su disco esterno o cloud privato dello studio.

**Backup database**
Il cluster TiDB Cloud Serverless è ridondato lato AWS. Per backup on-demand:

```powershell
.\venv\Scripts\python.exe -c "from sqlalchemy import inspect; from database.models import engine; ..."
```

Più semplicemente, esporta i prospetti Excel di tutte le pratiche aperte come backup leggibile.

### Aggiornamenti

Quando arriva un'evoluzione del software:

1. `Ctrl+C` per fermare il server.
2. Sostituisci i file aggiornati nella cartella `RateOS`.
3. Aggiorna le dipendenze: `.\venv\Scripts\python.exe -m pip install -r requirements.txt`.
4. Esegui le eventuali migrazioni: `.\venv\Scripts\python.exe main.py --init-db`.
5. Riavvia il server.

---

## 11. Risoluzione problemi

### "SMTPAuthenticationError 534" durante invio email
Stai usando la password dell'account Google. Devi usare un'**App Password** di 16 caratteri. Vedi [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords).

### "Errore di validazione AdE" durante calcolo piano
Il portale `ratef24` ha rifiutato i dati. Cause più comuni:
- **Ragione sociale > 25 caratteri** — il sistema tronca automaticamente, ma se il troncamento taglia in modo strano (es. "ADRIATICA BUSINESS SOLUTI"), il portale può rifiutare.
- **Codice atto errato o non ancora attivo** sul portale AdE.
- **Data di ricevimento futura** rispetto a quella di sistema.

### "Tabella piano rate non trovata"
Il portale AdE ha risposto con una pagina diversa dal previsto: probabile manutenzione del sito o cambiamento del template HTML. Riprova più tardi; se persiste, contattare il fornitore del software per aggiornamento del parser.

### Il PDF non viene letto correttamente
RateOS legge solo PDF testuali (avvisi originali). Se l'avviso è una scansione, serve un OCR (modulo non ancora attivo). Carica il PDF originale ricevuto dall'AdE.

### "SSL: CERTIFICATE_VERIFY_FAILED" su connessione DB
Su Windows manca il bundle CA. RateOS usa `certifi` automaticamente; se il problema persiste:

```powershell
.\venv\Scripts\python.exe -m pip install --upgrade certifi
```

### "Cliente non ha email registrata"
Aggiungi l'email del cliente nel form di conferma upload, oppure dalla pagina Clienti PF (per i PF) o direttamente sul DB (per i PNF, attualmente l'edit non è esposto in UI — rimane sul roadmap).

### Server non si avvia, errore "address already in use"
Un'altra istanza di RateOS è già in esecuzione su porta 8000.

```powershell
netstat -ano | findstr :8000
taskkill /PID <pid> /F
```

Oppure cambia porta nel comando di avvio (`--port 8001`).

---

## 12. Riferimenti normativi

| Norma | Oggetto | Codice tributo |
|---|---|---|
| Art. 36-bis DPR 600/1973 | Controllo automatizzato dichiarazioni redditi | 9001 |
| Art. 54-bis DPR 633/1972 | Controllo automatizzato IVA | 9002 |
| Art. 36-ter DPR 600/1973 | Controllo formale | 9003 |
| Art. 3-bis D.Lgs. 462/1997 | Pagamento rateale (max 20 rate trimestrali, interessi 3,5% annuo) | — |
| Art. 2 c. 2 D.Lgs. 462/1997 | Sanzione ridotta a 1/3 se prima rata entro 60 giorni | — |
| Provv. AdE prot. 17431 / 6 marzo 2017 | Definizione modello F24 precompilato | — |

---

## Contatti e supporto

- **Repository codice**: cartella `RateOS` sul filesystem dello studio.
- **Owner del software**: Andrea Torresi.
- **Manutenzione**: aggiornamenti del parser PDF possono essere necessari se l'AdE modifica il layout degli avvisi bonari o del portale `ratef24`.

---

*Documento generato il 5 maggio 2026. RateOS v2.0.*