# Architettura: da questo prototipo a Laravel 11 e Flutter

Il prototipo non e una bozza da buttare: e gia la struttura dell interfaccia.
Qui c e come diventa un prodotto.

## 1. Impianto

| Pezzo | Scelta | Perche |
|---|---|---|
| Gestionale e sito | **Laravel 11**, PHP 8.3 | richiesto dal committente; ecosistema maturo per code, permessi, PDF, fatturazione |
| Base dati | **PostgreSQL 16** (o MySQL 8) | vincoli di integrita veri, numeri esatti con `numeric`, partizionamento per studio |
| Code e lavori lunghi | **Redis + Horizon** | invii, trascrizioni, PDF, riconciliazioni: niente deve bloccare una richiesta web |
| File | **S3 compatibile** (anche MinIO) | documenti separati per studio, con conservazione a scadenza |
| App dei condomini | **Flutter 3.2x** | una base per iOS e Android, marchio per studio senza duplicare il codice |
| Notifiche | APNs e FCM | con ricaduta automatica su e-mail per chi non ha l app |
| Interfaccia | Blade + il CSS di questo prototipo | nessun framework CSS: `app.css` e gia il sistema |

Niente Tailwind, niente Bootstrap: il foglio di stile e scritto a mano, pesa poco
e non porta dipendenze da aggiornare.

## 2. Multi-studio

Un impianto solo, molti studi. Scelta consigliata: **una base dati, `studio_id` su ogni tabella**,
con `Scope` globale applicato dal middleware che risolve lo studio dal dominio o dall utente.

```php
// app/Models/Concerns/AppartieneAlloStudio.php
protected static function booted(): void
{
    static::addGlobalScope('studio', fn (Builder $q) =>
        $q->where('studio_id', app(ContestoStudio::class)->id())
    );
    static::creating(fn ($m) => $m->studio_id ??= app(ContestoStudio::class)->id());
}
```

Regole che evitano i guai:
- nessuna query senza `studio_id`: lo scope e obbligatorio, le eccezioni sono esplicite e tracciate;
- i file stanno in `studi/{studio_id}/...`, mai in una cartella condivisa;
- i lavori in coda portano con se lo studio e lo rimettono nel contesto prima di partire;
- in prova una volta al mese: un utente di uno studio non deve vedere nemmeno un conteggio di un altro.

Se un giorno uno studio molto grande chiede dati separati, si sposta in una base dedicata
senza toccare il codice: cambia solo la connessione risolta dal contesto.

### Marchio per studio

Tutto il vestito sta in una riga di configurazione (`studi.branding`): nome, colore,
marchio in SVG, dominio, mittente e-mail e PEC, nome dell app, identificativo del pacchetto.
Nel prototipo la stessa cosa la fa `theme-boot.js`: scrive le variabili CSS prima del primo disegno.
In Laravel diventa un `ViewComposer` che inietta le stesse variabili nel layout; in Flutter,
un `ThemeData` costruito all avvio dalla configurazione scaricata.
**Una sola base di codice, un solo rilascio per tutti.**

## 3. Modello dati

Le tabelle che contano, con i vincoli che tengono in piedi il mestiere.

**Studio e persone** — `studi`, `utenti`, `ruoli`, `permessi`, `assegnazioni`
(quale amministratore tiene quale condominio, da quando a quando).

**Immobili** — `condomini`, `scale`, `unita`, `pertinenze`.
`unita` porta dati catastali, superficie, categoria, piano, scala.

**Persone del condominio** — `soggetti` (persone fisiche, societa, comunioni ereditarie) e
`titolarita`: la tabella chiave, che lega soggetto e unita con **tipo** (proprietario,
comproprietario, usufruttuario, nudo proprietario, conduttore, comodatario), **quota**,
**dal/al**. E qui che vive la distinzione fra chi possiede le mura e chi ci abita:
una unita ha piu titolarita insieme, e ciascuna riceve cose diverse.

**Millesimi** — `tabelle_millesimali` (una per uso: generale, scala A, scala B, ascensore,
riscaldamento) e `millesimi` (tabella × unita). Vincolo di dominio: **la somma di ogni
tabella fa 1000**, verificata in scrittura e da un controllo periodico.

**Denaro** — `esercizi`, `voci_preventivo`, `movimenti`, `fatture` (con `ritenuta`),
`riparti` e `riparto_righe` (congelate: un riparto approvato non si ricalcola mai,
si rifa e si versiona), `rate`, `rate_unita`, `incassi`, `solleciti`.

**Operativo** — `ticket`, `messaggi`, `allegati`, `fornitori`, `fornitore_condominio`,
`richieste_preventivo`, `preventivi`, `interventi`, `rapportini`.

**Istituzionale** — `assemblee`, `convocazioni`, `consegne` (per canale, con prova),
`punti_odg`, `presenze`, `deleghe`, `votazioni`, `verbali`, `registri`.

**Audio e verbale** — `registrazioni` (file, durata, stato, cancellazione programmata),
`trascrizioni` (righe con minutaggio, voce, testo, affidabilita), `estrazioni`
(quorum, presenze, votazioni riconosciute), `bozze_verbale`.

**Adempimenti** — `scadenze` (polimorfica: condominio, unita, impianto, fornitore),
`adempimenti`, `contenziosi`, `impianti`, `verifiche`.

**Tracce** — `attivita` (chi, cosa, quando, su cosa: in sola aggiunta) e
`proposte_ia` (funzione, oggetto, esito, accettata o scartata, da chi).

## 4. Dal prototipo al codice

| Qui | Diventa |
|---|---|
| `assets/js/shell.js` | `resources/views/layouts/app.blade.php` piu i componenti della navigazione |
| i gruppi di `NAV` | un file di configurazione dei menu per ruolo, filtrato dai permessi |
| `assets/js/data.js` | `database/seeders/*`: lo stesso condominio di esempio, utile per i collaudi |
| ogni file HTML | una vista Blade, con i blocchi ripetuti estratti in componenti |
| `data-mill`, `data-seg`, `data-chart` | componenti Blade (`<x-mill :valore="78" />`) con lo stesso HTML |
| `assets/css/app.css` | `resources/css/app.css`, invariato |
| le schermate telefono | schermate Flutter, stessi token di colore |

Il lavoro di interfaccia, dopo l approvazione, e trasformazione: la struttura non cambia.

## 5. API per l app

`/api/v1`, autenticazione con **Sanctum** (token per dispositivo, revocabile), tutto filtrato
dal contesto studio e dal soggetto collegato all utente.

```
POST   /auth/accesso            codice fiscale + codice usa e getta, poi impronta
GET    /mio/situazione          quota dell anno, prossima rata, avvisi non letti
GET    /mio/unita               millesimi, tabelle, pertinenze, dati catastali
GET    /mio/rate                rate ed estratto conto
POST   /pagamenti/avvia         pagoPA o carta, torna il riferimento
GET    /segnalazioni            le mie, con stato
POST   /segnalazioni            testo, foto, posizione -> classificazione IA
GET    /avvisi                  comunicazioni, con conferma di lettura
POST   /avvisi/{id}/letto
GET    /assemblee/prossima      ordine del giorno, delega, collegamento video
POST   /assemblee/{id}/delega
POST   /letture                 autolettura con foto del contatore
GET    /documenti               solo quelli che il condomino puo vedere
```

Per l amministratore in sopralluogo, la stessa app con un altro ruolo aggiunge:
`POST /interventi/{id}/foto`, `POST /rapportini/{id}/firma`,
`POST /assemblee/{id}/registrazione` (l audio che diventa bozza di verbale).

## 6. Lavori in coda

Tutto quello che dura piu di due secondi va in coda, con stato visibile all utente:
invio di comunicazioni multicanale (e-mail, PEC, SMS, push, stampa e postalizzazione),
generazione dei PDF (rendiconto, riparto, convocazione, verbale), trascrizione dell audio
e bozza del verbale, riconciliazione degli incassi, calcolo notturno delle scadenze e
dei solleciti, esportazione per il passaggio di consegne.

## 7. Integrazioni

| Cosa | Con chi | Note |
|---|---|---|
| Fatturazione elettronica | SDI tramite intermediario | lo studio emette parcelle; il condominio riceve fatture passive in XML |
| PEC | provider certificato | convocazioni e diffide, con ricevute conservate |
| Incassi | pagoPA, carta, MAV, SDD (CBI) | riconciliazione automatica sulla rata |
| Banca | estratto conto in CBI o import OFX | movimenti del conto condominiale |
| Firma | firma elettronica avanzata | verbali, rapportini, deleghe |
| Agenzia delle Entrate | comunicazione delle spese sulle parti comuni | tracciato annuale entro il 16 marzo |
| Catasto | visure | aggiornamento dell anagrafe |
| Trascrizione | modello in cloud europeo | audio delle assemblee, con cancellazione programmata |

## 8. Intelligenza artificiale, dal lato tecnico

Un servizio dedicato dietro una coda, mai dentro la richiesta web.
Per ogni funzione: un modello di prompt versionato, le fonti citate, e la risposta
salvata in `proposte_ia` con l esito. Le risposte sulle domande dei condomini
usano la ricerca sui documenti di **quel** condominio (regolamento, verbali, rendiconto),
non su una memoria generica.

Per il verbale: trascrizione con separazione delle voci, allineamento ai punti
dell ordine del giorno, estrazione di presenze, quorum e votazioni, poi composizione
nel modello dello studio. Le parti incerte restano marcate e l amministratore deve
confermarle prima di poter firmare. L audio si cancella quando il verbale e approvato.

## 9. Sicurezza e dati personali

Ruoli e permessi con `spatie/laravel-permission`, controllo anche a livello di modello.
Registro delle attivita in sola aggiunta. Cifratura a riposo per i documenti.
Conservazione: contabilita dieci anni, audio delle assemblee fino all approvazione del
verbale, dati dei condomini finche dura il rapporto piu i termini di legge.
Lo studio e titolare del trattamento, la piattaforma e responsabile (art. 28):
il contratto fa parte dell attivazione. L accesso di assistenza va chiesto, e lascia traccia.

## 10. Fasi

| Fase | Contenuto | Stima |
|---|---|---|
| 1. Fondamenta | multi-studio, utenti e permessi, condomini, unita, anagrafe, millesimi, documenti | 5-6 settimane |
| 2. Denaro | esercizi, preventivo, movimenti, fatture con ritenuta, riparti, rate, incassi, solleciti | 6-7 settimane |
| 3. Operativo | segnalazioni, fornitori, preventivi, interventi, portale artigiano | 4 settimane |
| 4. Istituzionale | assemblee, convocazioni, quorum, votazioni, verbali, registri, comunicazioni multicanale | 5 settimane |
| 5. App Flutter | accesso, rate e pagamenti, segnalazioni, avvisi, assemblea, documenti, letture | 6 settimane |
| 6. Intelligenza artificiale | smistamento, lettura fatture, confronto preventivi, verbale dall audio, previsione morosita | 4 settimane |
| 7. Marchio e pubblicazione | pannello del marchio, sito per studio, pubblicazione negli store | 3 settimane |
| 8. Adempimenti e rifiniture | scadenzario, fiscale, sicurezza, contenzioso, passaggio di consegne, importazioni | 4 settimane |

Le fasi 1 e 2 insieme sono gia un prodotto vendibile a uno studio piccolo.
La 5 va avviata in parallelo appena la 2 e stabile: l app e quello che si vede.
