Architettura, modello dati, requisiti funzionali e non funzionali, piano di lavoro ed esclusioni per una piattaforma multitenant destinata alla vendita agli studi notarili. Ogni voce è numerata e verificabile in collaudo.
Requisiti funzionali del sistema. La colonna Sprint indica in quale sprint il requisito è consegnato e collaudabile.
| ID | Requisito | Descrizione tecnica | Sprint |
|---|---|---|---|
| RF-01 | Tenant per studio | Ogni studio notarile è un tenant isolato: dati, utenti e documenti separati a livello di schema applicativo. Nessuna query può restituire record di un tenant diverso dal contesto di sessione. | S1 |
| RF-02 | Autenticazione e ruoli | Login email/password con hash Argon2id, sessioni firmate, recupero password via token a scadenza. Ruoli: owner, notaio, segreteria. | S1 |
| RF-03 | Anagrafica studio | Ragione sociale, sede, P.IVA/CF, contatti, logo. I dati compaiono su ogni pratica e su ogni documento generato. | S1 |
| RF-04 | Pratica da preventivo accettato | Creazione pratica con: tipo atto, parti coinvolte (acquirente, venditore, agenzie), importi, data prevista, note. Genera un identificativo pratica univoco leggibile. | S1 |
| RF-05 | Sezione condivisa con token | Per ogni parte viene generato un link con token opaco non indovinabile, scadenza configurabile e permessi limitati al ruolo della parte. Accesso senza registrazione. | S2 |
| RF-06 | Checklist documentale per ruolo | Set di documenti richiesti differenziato per acquirente, venditore e agenzia. Stato per singolo documento: mancante, caricato, rifiutato, accettato. | S2 |
| RF-07 | Upload documenti | Upload multiplo con limite di dimensione e tipi ammessi (PDF, JPG, PNG, DOCX). Storage su object storage con URL firmate; metadati in database. Anteprima per i formati supportati. | S2 |
| RF-08 | Controllo coerenza dati | Motore di regole che incrocia i dati estratti dai documenti e i campi della pratica: date, importi, intestatari, dati catastali. Produce una lista di anomalie con gravità (bloccante, avviso). | S2 |
| RF-09 | Solleciti automatici | Job schedulato che rileva documenti mancanti oltre soglia e invia promemoria alla parte interessata con link diretto. Frequenza e soglia configurabili per studio. | S2 |
| RF-10 | Dashboard pratica | Vista per studio con stato di ogni pratica: percentuale completamento documentale, anomalie aperte, giorni di fermo, parti in attesa. | S2 |
| RF-11 | Compilazione atto da dati | Template di atto con segnaposto risolti dai dati della pratica e dai documenti validati. Merge con anteprima delle incongruenze residue prima della generazione. | S3 |
| RF-12 | Export documento | Generazione del documento finale nel formato concordato (PDF e/o DOCX), archiviazione nella pratica, download tracciato a log. | S3 |
| RF-13 | Archivio e ricerca | Pratiche concluse consultabili e filtrabili per parti, data, tipo atto, stato. Ricerca full-text sui metadati. | S3 |
| RF-14 | Log attività | Registro immutabile delle operazioni rilevanti: accesso ai link, upload, download, modifica dati, generazione atto. Con utente o token, timestamp, IP. | S3 |
Stack e scelte strutturali. Le alternative sono indicate dove la decisione ha un impatto economico o di tempi.
Monolite modulare in TypeScript, con rendering server-side e API interne tipizzate. Un solo deployable, moduli separati per dominio (pratiche, documenti, atti, amministrazione): più semplice da consegnare e da mantenere rispetto a microservizi, che su questo perimetro aggiungerebbero solo complessità operativa.
TypeScript · SSR · API internePostgreSQL gestito, con isolamento per tenant tramite tenant_id obbligatorio e policy a livello di applicazione, più schema dedicato per la parte documentale. Scelta preferita a un database serverless con limiti di concorrenza, perché qui le transazioni contano.
Object storage compatibile S3 con bucket privato, accesso solo tramite URL firmate a scadenza breve. I file non sono mai pubblici. Naming per tenant e pratica, checksum SHA-256 per integrità e deduplica.
S3-compatible · URL firmate · checksumCoda per elaborazioni non bloccanti: parsing documenti, controllo coerenza, generazione PDF, invio solleciti. Le operazioni lunghe non stanno nella richiesta HTTP, così il caricamento resta immediato anche con file pesanti.
Queue · retry con backoff · dead letterParsing deterministico per i PDF testuali (regex e layout), OCR per le scansioni, modello linguistico solo come fallback per i campi non strutturati. Ogni dato estratto resta modificabile a mano: l'automazione propone, l'umano conferma.
PDF parse · OCR · LLM fallbackToken opachi a 256 bit, hashati a database, con permessi per ruolo della parte, scadenza e revoca immediata dal pannello dello studio. Ogni accesso è loggato. Un link non dà mai accesso a pratiche diverse da quella per cui è stato emesso.
Token opachi · revoca · scope per praticaEntità principali e relazioni. Le entità di supporto (log, token, allegati) sono omesse per leggibilità.
| Entità | Campi chiave | Relazioni |
|---|---|---|
tenant | id, ragione_sociale, sede, piva, logo, config_json | 1 → n utenti, pratiche |
user | id, tenant_id, email, password_hash, ruolo, stato | n → 1 tenant |
pratica | id, tenant_id, codice, tipo_atto, stato, data_prevista, importi_json | n → 1 tenant · 1 → n parti, documenti, atti |
parte | id, pratica_id, ruolo (acquirente/venditore/agenzia), anagrafica_json, contatti | n → 1 pratica · 1 → 1 token |
documento | id, pratica_id, parte_id, tipo, storage_key, checksum, stato, dati_estratti_json | n → 1 pratica · n → 1 parte |
checklist_item | id, pratica_id, ruolo_parte, tipo_documento, obbligatorio | n → 1 pratica |
anomalia | id, pratica_id, regola_id, gravità, campo, atteso, rilevato, stato | n → 1 pratica |
atto | id, pratica_id, template_id, versione, storage_key, generato_da, generato_il | n → 1 pratica |
token_accesso | id, parte_id, hash_token, scope, scadenza, revocato_il | n → 1 parte |
audit_log | id, tenant_id, attore, azione, entità, entità_id, ip, timestamp | append-only |
tenant_id non nullo. Il livello di accesso dati applica il filtro dal contesto di sessione: non esiste codice applicativo che possa leggere senza tenant. È una scelta strutturale, non una convenzione.Sequenza tecnica delle due operazioni centrali del sistema.
// 1. Il notaio crea la pratica e invita le parti POST /api/pratiche/{id}/parti → parte + checklist_item generati POST /api/pratiche/{id}/inviti → per ogni parte: token_accesso (256 bit) → restituisce URL firmato + testo pronto per WhatsApp // 2. La parte apre il link: nessuna registrazione GET /p/{token} → valida hash, scadenza, scope → sessione limitata alla singola pratica // 3. Upload: file diretto su storage, metadati su DB POST /api/upload/presign → URL firmata (PUT, scadenza 15 min) PUT {storage_url} → file su bucket privato POST /api/pratiche/{id}/documenti → verifica checksum, accoda parsing → job: estrazione dati + aggiornamento checklist // 4. Job pianificato: solleciti CRON /jobs/solleciti → documenti mancanti oltre soglia → notifica con link riutilizzabile
// 1. Il motore di regole gira sui dati disponibili POST /api/pratiche/{id}/coerenza → regole: date, importi, intestatari, catastali → anomalie{gravità: bloccante|avviso, campo, atteso, rilevato} // 2. Il notaio rivede e conferma i dati estratti PATCH /api/pratiche/{id}/dati → ogni campo è editabile: l'estrazione propone → le anomalie bloccanti vanno chiuse prima dell'atto // 3. Generazione documento dal template POST /api/pratiche/{id}/atto → merge segnaposto ← dati confermati → job: render PDF/DOCX → tracking giallo su campi non risolti // 4. Export e archiviazione GET /api/atti/{id}/download → URL firmata + voce in audit_log
Criteri misurabili. Sono quelli che finiscono nel collaudo, non quelli che si scoprono dopo.
| ID | Ambito | Requisito |
|---|---|---|
| RNF-01 | Sicurezza | Password con Argon2id, HTTPS obbligatorio, header di sicurezza (CSP, HSTS, X-Frame-Options), rate limit su login e sugli endpoint pubblici dei link. |
| RNF-02 | Isolamento | Nessuna query applicativa senza filtro tenant. Test automatico che tenta accesso cross-tenant su ogni endpoint e deve fallire. |
| RNF-03 | Documenti | Bucket privato, URL firmate con scadenza ≤ 15 minuti, checksum verificato in upload, tipi MIME e dimensione validati lato server. |
| RNF-04 | Prestazioni | Apertura di un link con checklist: risposta server < 800 ms al 95° percentile. Upload reso immediato con elaborazione asincrona. |
| RNF-05 | Backup | Backup giornaliero del database con retention a 30 giorni e ripristino provato in collaudo, non solo configurato. Documenti su storage versionato. |
| RNF-06 | Tracciabilità | Log append-only di accessi, upload, download, modifiche e generazioni. Conservazione minima 24 mesi. |
| RNF-07 | GDPR | Base giuridica e informativa per dati di parti e documenti di identità, tempi di conservazione configurabili per studio, cancellazione tracciata a fine retention. |
| RNF-08 | Compatibilità | Ultime due versioni di Chrome, Safari, Firefox ed Edge su desktop; link condivisi utilizzabili da mobile senza installazione. |
| RNF-09 | Accessibilità | Form pubblici delle parti conformi WCAG 2.1 livello AA su contrasto, focus e navigazione da tastiera. |
| RNF-10 | Manutenibilità | Migrazioni versionate, ambiente di test separato, test end-to-end sui flussi critici, documentazione tecnica consegnata. |
Tre sprint da due settimane. Ogni sprint chiude con una demo e un blocco di requisiti collaudabili.
Base dati, isolamento, autenticazione e creazione pratica. Al termine si può accedere, creare uno studio e inserire un preventivo accettato.
Il flusso operativo completo lato parti. Al termine un'agenzia può caricare i documenti da link e il notaio vede cosa manca e cosa non torna.
Generazione dell'atto dai dati validati, export, tracciabilità e chiusura. Al termine la piattaforma è consegnabile.
In entrambe le opzioni: consegna di codice e proprietà intellettuale, documentazione e due mesi di garanzia sui difetti. Nessun canone di manutenzione.
Sviluppo più accompagnamento al go-to-market. Seguiamo le prime vendite, adattiamo le tipologie di pagamento e interveniamo sulle modifiche nei tre mesi di lancio.
Sviluppo e consegna. Costruiamo la piattaforma secondo le specifiche, la consegniamo con documentazione e ci fermiamo. Nessuna consulenza go-to-market.
Esecuzione di tutti i requisiti RF-01 → RF-14 su un set di tre pratiche reali fornite dal cliente, con esito registrato.
Test di accesso cross-tenant (deve fallire), verifica URL firmate e scadenza, ripristino backup eseguito, controllo dei log di audit.
Verbale firmato a fine Sprint 3. I difetti bloccanti vanno chiusi prima del verbale; i non bloccanti entrano nei due mesi di garanzia.