netgescon-master/docs/02-architettura-laravel/specifiche/DATABASE_SCHEMA.md

DATABASE_SCHEMA.md - NetGesCon Laravel

Creato: 8 Luglio 2025
Ultimo aggiornamento: 8 Luglio 2025
Versione: 2.0

🎯 SCOPO DEL DOCUMENTO

Documentazione completa dello schema database NetGesCon, struttura dati ad albero, relazioni e convenzioni per evitare errori di sviluppo e facilitare la comprensione del sistema.

---

📊 TABELLE DATABASE - SCHEMA COMPLETO

<EFBFBD> SISTEMA AMMINISTRATORI E GESTIONE

amministratori - Gestori condomini

id                    BIGINT PRIMARY KEY AUTO_INCREMENT
codice_amministratore VARCHAR(8) UNIQUE NOT NULL           # Generato auto (es: "ADM8K3L9")
nome_amministratore   VARCHAR(255) NOT NULL
cognome_amministratore VARCHAR(255) NOT NULL
codice_fiscale        VARCHAR(16) UNIQUE
partita_iva          VARCHAR(11)
email                VARCHAR(255)
telefono             VARCHAR(20)
indirizzo            TEXT
database_attivo      VARCHAR(255) DEFAULT 'netgescon'      # Per multi-database
cartella_dati        VARCHAR(255)                          # Percorso dati specifici
server_database      VARCHAR(255)                          # Server distribuzione
server_port          INT DEFAULT 3306
url_accesso          VARCHAR(255)                          # URL accesso diretto
stato_sincronizzazione ENUM('locale','distribuito','migrazione')
created_at           TIMESTAMP
updated_at           TIMESTAMP
deleted_at           TIMESTAMP NULL

users - Utenti sistema (Admin, Super-admin, altri)

id              BIGINT PRIMARY KEY AUTO_INCREMENT
name            VARCHAR(255) NOT NULL
email           VARCHAR(255) UNIQUE NOT NULL
email_verified_at TIMESTAMP NULL
password        VARCHAR(255) NOT NULL
role            VARCHAR(50) DEFAULT 'user'                # admin, super-admin, amministratore
amministratore_id BIGINT NULL                             # FK a amministratori
codice_utente   VARCHAR(8) UNIQUE                         # Generato auto (es: "USR9X2M4")
remember_token  VARCHAR(100) NULL
created_at      TIMESTAMP
updated_at      TIMESTAMP
deleted_at      TIMESTAMP NULL

# RELAZIONI:
# belongsTo: amministratore (amministratore_id)

---

🏠 GESTIONE STABILI E UNITÀ

stabili - Edifici/Condomini gestiti

id                     BIGINT PRIMARY KEY AUTO_INCREMENT
denominazione          VARCHAR(255) NOT NULL
indirizzo             VARCHAR(255)
cap                   VARCHAR(10)
citta                 VARCHAR(100)
provincia             VARCHAR(5)
codice_fiscale_stabile VARCHAR(16)
partita_iva_stabile   VARCHAR(11)
amministratore_id     BIGINT NOT NULL                      # FK a amministratori
codice_stabile        VARCHAR(8) UNIQUE                    # Generato auto (es: "STB5H7K1")

# NUOVI CAMPI CATASTALI E CONFIGURAZIONE:
foglio_catastale      VARCHAR(20)                         # Dati catastali
particella_catastale  VARCHAR(20)
subalterno_catastale  VARCHAR(20)
codice_destinatario_sdi VARCHAR(7)                        # Sistema Di Interscambio
pec_stabile          VARCHAR(255)                         # PEC per fatturazione elettronica
numero_rate_anno     INT DEFAULT 4                        # Rate annuali (bimestrali=6, trimestrali=4)
mese_inizio_esercizio INT DEFAULT 1                       # Mese inizio anno amministrativo
piano_terra_denominazione VARCHAR(50) DEFAULT 'PT'        # Denominazione piano terra
piano_primo_denominazione VARCHAR(50) DEFAULT '1°'        # Denominazione primo piano
ascensore            BOOLEAN DEFAULT FALSE               # Presenza ascensore
balconi_totali       INT DEFAULT 0                       # Numero totale balconi
terrazze_totali      INT DEFAULT 0                       # Numero totale terrazze
posti_auto_coperti   INT DEFAULT 0                       # Posti auto in garage
posti_auto_scoperti  INT DEFAULT 0                       # Posti auto esterni
note_caratteristiche TEXT                                # Note libere caratteristiche

created_at           TIMESTAMP
updated_at           TIMESTAMP
deleted_at           TIMESTAMP NULL

# RELAZIONI:
# belongsTo: amministratore (amministratore_id)
# hasMany: unita_immobiliari, movimenti_contabili, assemblee, preventivi, etc.

unita_immobiliari - Singole unità (appartamenti, garage, etc.)

id                    BIGINT PRIMARY KEY AUTO_INCREMENT
stabile_id           BIGINT NOT NULL                      # FK a stabili
denominazione        VARCHAR(255) NOT NULL               # "Interno 1", "Box 5", etc.
piano                VARCHAR(10)                         # "PT", "1°", "2°", etc.
numero_vani          DECIMAL(3,1) DEFAULT 0              # Vani catastali
superficie_catastale DECIMAL(8,2) DEFAULT 0              # Superficie in mq
categoria_catastale  VARCHAR(10)                         # A/2, C/1, etc.
classe_catastale     VARCHAR(10)                         # Classe catastale
rendita_catastale    DECIMAL(10,2) DEFAULT 0             # Rendita €

# SISTEMA MILLESIMI (MULTIPLI TABELLE):
millesimi_proprieta   DECIMAL(7,4) DEFAULT 0             # Millesimi di proprietà
millesimi_scale      DECIMAL(7,4) DEFAULT 0             # Millesimi scale
millesimi_ascensore  DECIMAL(7,4) DEFAULT 0             # Millesimi ascensore
millesimi_riscaldamento DECIMAL(7,4) DEFAULT 0          # Millesimi riscaldamento
millesimi_acqua_calda DECIMAL(7,4) DEFAULT 0            # Millesimi acqua calda
millesimi_pulizie    DECIMAL(7,4) DEFAULT 0             # Millesimi pulizie

# CONFIGURAZIONE UNITÀ:
tipo_utilizzo_id     BIGINT                              # FK a tipi_utilizzo
stato_occupazione    ENUM('occupata','libera','in_vendita','in_affitto') DEFAULT 'occupata'
note_unita          TEXT                                # Note specifiche unità

created_at          TIMESTAMP
updated_at          TIMESTAMP
deleted_at          TIMESTAMP NULL

# RELAZIONI:
# belongsTo: stabile (stabile_id), tipo_utilizzo (tipo_utilizzo_id)
# hasMany: diritti_reali, contratti_locazione (come unita_immobiliare_id)

tipi_utilizzo - Tipologie di utilizzo unità

id           BIGINT PRIMARY KEY AUTO_INCREMENT
denominazione VARCHAR(100) NOT NULL               # "Abitazione", "Garage", "Cantina", etc.
codice       VARCHAR(10) UNIQUE NOT NULL         # "ABIT", "GAR", "CANT", etc.
descrizione  TEXT                                # Descrizione dettagliata
attivo       BOOLEAN DEFAULT TRUE               # Se utilizzabile
ordinamento  INT DEFAULT 0                      # Ordine visualizzazione
created_at   TIMESTAMP
updated_at   TIMESTAMP

# DATI PREDEFINITI:
# 1. Abitazione (ABIT)
# 2. Garage/Box (GAR) 
# 3. Cantina (CANT)
# 4. Soffitta (SOFF)
# 5. Posto auto coperto (PAC)
# 6. Posto auto scoperto (PAS)
# 7. Locale commerciale (COMM)
# 8. Ufficio (UFF)

# RELAZIONI:
# hasMany: unita_immobiliari

---

<EFBFBD> SISTEMA ANAGRAFICA CONDOMINIALE

anagrafica_condominiale - Persone (proprietari, inquilini, fornitori)

id                    BIGINT PRIMARY KEY AUTO_INCREMENT
amministratore_id     BIGINT NOT NULL                     # FK a amministratori
codice_anagrafica     VARCHAR(8) UNIQUE NOT NULL          # Generato auto (es: "ANAP4UQ2")

# IDENTIFICAZIONE SOGGETTO:
tipo_soggetto         ENUM('persona_fisica','persona_giuridica') NOT NULL
nome                  VARCHAR(255)                        # Nome persona fisica
cognome               VARCHAR(255)                        # Cognome persona fisica  
ragione_sociale       VARCHAR(255)                        # Nome per persona giuridica
codice_fiscale        VARCHAR(16)                         # CF persona fisica/giuridica
partita_iva          VARCHAR(11)                         # P.IVA se presente

# DATI ANAGRAFICI:
data_nascita         DATE                                # Solo per persona fisica
luogo_nascita        VARCHAR(255)                        # Solo per persona fisica
sesso                ENUM('M','F') NULL                  # Solo per persona fisica
stato_civile         ENUM('celibe/nubile','coniugato/a','divorziato/a','vedovo/a') NULL

# RESIDENZA E DOMICILIO:
indirizzo_residenza   VARCHAR(255)                       # Via/Piazza residenza
cap_residenza        VARCHAR(10)                        # CAP residenza
citta_residenza      VARCHAR(100)                       # Città residenza
provincia_residenza   VARCHAR(5)                         # Provincia residenza
nazione_residenza    VARCHAR(100) DEFAULT 'Italia'      # Nazione residenza

# DOMICILIO (se diverso da residenza):
indirizzo_domicilio   VARCHAR(255)                       # Via/Piazza domicilio
cap_domicilio        VARCHAR(10)                        # CAP domicilio
citta_domicilio      VARCHAR(100)                       # Città domicilio
provincia_domicilio   VARCHAR(5)                         # Provincia domicilio
nazione_domicilio    VARCHAR(100)                       # Nazione domicilio

# CONFIGURAZIONE:
attivo               BOOLEAN DEFAULT TRUE               # Se utilizzabile
note_anagrafica      TEXT                              # Note libere
privacy_consenso     BOOLEAN DEFAULT FALSE             # Consenso privacy
marketing_consenso   BOOLEAN DEFAULT FALSE             # Consenso marketing

created_at           TIMESTAMP
updated_at           TIMESTAMP
deleted_at           TIMESTAMP NULL

# RELAZIONI:
# belongsTo: amministratore (amministratore_id)
# hasMany: contatti_anagrafica, diritti_reali, contratti_locazione (locatore/conduttore)

contatti_anagrafica - Contatti multipli per anagrafica

id               BIGINT PRIMARY KEY AUTO_INCREMENT
anagrafica_id    BIGINT NOT NULL                        # FK a anagrafica_condominiale
tipo_contatto    ENUM('email','telefono','cellulare','fax','pec','altro') NOT NULL
valore          VARCHAR(255) NOT NULL                  # Email, numero, etc.
etichetta       VARCHAR(100)                          # "Casa", "Ufficio", "Mobile", etc.

# FLAGS USO CONTATTO:
usa_per_convocazioni BOOLEAN DEFAULT FALSE             # Usare per convocazioni assemblee
usa_per_comunicazioni BOOLEAN DEFAULT FALSE            # Usare per comunicazioni generali
usa_per_emergenze    BOOLEAN DEFAULT FALSE             # Contatto di emergenza
principale          BOOLEAN DEFAULT FALSE             # Contatto principale del tipo

note_contatto       TEXT                              # Note specifiche contatto
created_at          TIMESTAMP
updated_at          TIMESTAMP

# RELAZIONI:
# belongsTo: anagrafica_condominiale (anagrafica_id)

---

🏘️ GESTIONE PROPRIETÀ E LOCAZIONI

diritti_reali - Quote di proprietà su unità immobiliari

id                      BIGINT PRIMARY KEY AUTO_INCREMENT
unita_immobiliare_id   BIGINT NOT NULL                  # FK a unita_immobiliari
anagrafica_id          BIGINT NOT NULL                  # FK a anagrafica_condominiale (proprietario)

# TIPOLOGIA DIRITTO:
tipo_diritto           ENUM('proprieta','nuda_proprieta','usufrutto','uso','abitazione','enfiteusi','superficie') NOT NULL DEFAULT 'proprieta'

# QUOTE E PERCENTUALI:
quota_numeratore       INT NOT NULL DEFAULT 1000       # Numeratore quota (es: 1000 su 1000 = 100%)
quota_denominatore     INT NOT NULL DEFAULT 1000       # Denominatore quota
percentuale_proprieta  DECIMAL(5,2) NOT NULL DEFAULT 100.00  # Percentuale (0.00-100.00)

# DATI LEGALI:
data_acquisizione      DATE                            # Data acquisizione diritto
atto_notarile         VARCHAR(255)                     # Riferimento atto notaio
notaio                VARCHAR(255)                     # Nome notaio
data_trascrizione     DATE                            # Data trascrizione
numero_trascrizione   VARCHAR(50)                     # Numero di trascrizione
ufficio_registri      VARCHAR(255)                    # Ufficio conservatoria

# VALIDITÀ TEMPORALE:
data_inizio_validita  DATE NOT NULL                   # Inizio validità diritto
data_fine_validita    DATE                           # Fine validità (NULL = illimitato)

# CONFIGURAZIONE:
attivo                BOOLEAN DEFAULT TRUE            # Se diritto attivo
note_diritto          TEXT                           # Note specifiche
created_at            TIMESTAMP
updated_at            TIMESTAMP

# RELAZIONI:
# belongsTo: unita_immobiliare (unita_immobiliare_id), anagrafica_condominiale (anagrafica_id)

contratti_locazione - Contratti di affitto/locazione

id                      BIGINT PRIMARY KEY AUTO_INCREMENT
unita_immobiliare_id   BIGINT NOT NULL                 # FK a unita_immobiliari (unità locata)
locatore_id            BIGINT NOT NULL                 # FK a anagrafica_condominiale (proprietario)
conduttore_id          BIGINT NOT NULL                 # FK a anagrafica_condominiale (inquilino)

# DATI CONTRATTO:
numero_contratto       VARCHAR(50)                     # Numero contratto
data_stipula          DATE NOT NULL                   # Data stipula contratto
data_inizio           DATE NOT NULL                   # Inizio locazione
data_fine             DATE                           # Fine locazione (NULL = indeterminato)
durata_mesi           INT                            # Durata in mesi
tipo_contratto        ENUM('libero','concordato','transitorio','uso_foresteria','commerciale') NOT NULL DEFAULT 'libero'

# CANONI E DEPOSITI:
canone_mensile        DECIMAL(10,2) NOT NULL DEFAULT 0    # Canone mensile €
deposito_cauzionale   DECIMAL(10,2) DEFAULT 0             # Deposito cauzionale €
spese_condominiali    DECIMAL(10,2) DEFAULT 0             # Spese condominiali mensili €

# CONFIGURAZIONE SPESE:
spese_a_carico_inquilino BOOLEAN DEFAULT TRUE              # Spese condominiali a carico inquilino
riscaldamento_a_carico   BOOLEAN DEFAULT TRUE              # Riscaldamento a carico inquilino
acqua_a_carico          BOOLEAN DEFAULT TRUE              # Acqua a carico inquilino

# INDICIZZAZIONE E AGGIORNAMENTI:
indice_istat_base      DECIMAL(8,4)                       # Indice ISTAT di riferimento
ultimo_aggiornamento   DATE                              # Ultima data aggiornamento canone
prossimo_aggiornamento DATE                              # Prossima data aggiornamento

# STATO E CONFIGURAZIONE:
stato_contratto       ENUM('attivo','sospeso','terminato','disdetto') DEFAULT 'attivo'
disdetta_data         DATE                              # Data eventuale disdetta
disdetta_motivo       TEXT                             # Motivo disdetta
note_contratto        TEXT                            # Note libere
created_at            TIMESTAMP
updated_at            TIMESTAMP

# RELAZIONI:
# belongsTo: unita_immobiliare, locatore (anagrafica), conduttore (anagrafica)

ripartizione_spese_inquilini - Configurazione ripartizione spese locazione

id                     BIGINT PRIMARY KEY AUTO_INCREMENT
denominazione          VARCHAR(255) NOT NULL            # Nome categoria spesa
codice_categoria       VARCHAR(20) UNIQUE NOT NULL      # Codice categoria (RISC, ACQ, PUL, etc.)
descrizione           TEXT                             # Descrizione dettagliata
percentuale_inquilino  DECIMAL(5,2) DEFAULT 0.00        # % a carico inquilino (0-100)
percentuale_proprietario DECIMAL(5,2) DEFAULT 100.00     # % a carico proprietario
tipo_spesa            ENUM('ordinaria','straordinaria','manutenzione','consumi') DEFAULT 'ordinaria'

# CONFIGURAZIONE LEGALE (SECONDO CONFEDILIZIA):
art_1131_cc           BOOLEAN DEFAULT FALSE            # Art. 1131 Cod. Civile (amministratore)
art_1133_cc           BOOLEAN DEFAULT FALSE            # Art. 1133 Cod. Civile (manutenzione)
art_1134_cc           BOOLEAN DEFAULT FALSE            # Art. 1134 Cod. Civile (innovazioni)
riferimento_normativo  TEXT                            # Riferimenti normativi specifici

ordinamento           INT DEFAULT 0                    # Ordine visualizzazione
attivo                BOOLEAN DEFAULT TRUE             # Se utilizzabile
created_at            TIMESTAMP
updated_at            TIMESTAMP

# DATI PREDEFINITI (STANDARD CONFEDILIZIA):
# Spese 100% proprietario: manutenzione straordinaria, innovazioni, accantonamenti
# Spese 100% inquilino: consumi individuali, pulizie scale, portineria  
# Spese ripartite: riscaldamento centralizzato, acqua comune, gestione amministrativa

---

🔄 RIPARTIZIONE SPESE E GESTIONE RATE

voci_spesa - Tipologie di spesa condominiale

id                              BIGINT PRIMARY KEY AUTO_INCREMENT
codice_voce                     VARCHAR(8) UNIQUE NOT NULL           # Generato auto (es: "VCS7H2K9")
stabile_id                      BIGINT NOT NULL                      # FK a stabili
descrizione                     VARCHAR(255) NOT NULL
tipo_gestione                   ENUM('ordinaria','straordinaria','speciale') DEFAULT 'ordinaria'
categoria                       VARCHAR(100) NOT NULL
tabella_millesimale_default_id  BIGINT NULL                          # FK a tabelle_millesimali
ritenuta_acconto_default        DECIMAL(5,2) DEFAULT 0.00
attiva                          BOOLEAN DEFAULT TRUE
ordinamento                     INT DEFAULT 0
created_at                      TIMESTAMP
updated_at                      TIMESTAMP
deleted_at                      TIMESTAMP NULL

ripartizione_spese - Ripartizione importi per stabile

id                            BIGINT PRIMARY KEY AUTO_INCREMENT
codice_ripartizione           VARCHAR(8) UNIQUE NOT NULL           # Generato auto (es: "RPS4M8N2")
voce_spesa_id                 BIGINT NOT NULL                      # FK a voci_spesa
stabile_id                    BIGINT NOT NULL                      # FK a stabili
tabella_millesimale_id        BIGINT NOT NULL                      # FK a tabelle_millesimali
importo_totale                DECIMAL(10,2) NOT NULL
importo_ripartito             DECIMAL(10,2) DEFAULT 0.00
tipo_ripartizione             ENUM('millesimale','uguale','personalizzata') DEFAULT 'millesimale'
data_ripartizione             DATE NOT NULL
stato                         ENUM('bozza','approvata','contabilizzata') DEFAULT 'bozza'
note                          TEXT NULL
configurazione_ripartizione   JSON NULL
creato_da                     BIGINT NOT NULL                      # FK a users
approvato_at                  TIMESTAMP NULL
approvato_da                  BIGINT NULL                          # FK a users
contabilizzato_at             TIMESTAMP NULL
contabilizzato_da             BIGINT NULL                          # FK a users
created_at                    TIMESTAMP
updated_at                    TIMESTAMP
deleted_at                    TIMESTAMP NULL

dettaglio_ripartizione_spese - Dettaglio per singola unità

id                          BIGINT PRIMARY KEY AUTO_INCREMENT
ripartizione_spese_id       BIGINT NOT NULL                      # FK a ripartizione_spese
unita_immobiliare_id        BIGINT NOT NULL                      # FK a unita_immobiliari
anagrafica_condominiale_id  BIGINT NOT NULL                      # FK a anagrafica_condominiale
millesimi                   DECIMAL(8,3) NOT NULL
importo_calcolato           DECIMAL(10,2) NOT NULL
importo_rettificato         DECIMAL(10,2) NULL
motivo_rettifica            VARCHAR(255) NULL
note                        TEXT NULL
created_at                  TIMESTAMP
updated_at                  TIMESTAMP
deleted_at                  TIMESTAMP NULL

piano_rateizzazione - Piani dilazione pagamenti

id                      BIGINT PRIMARY KEY AUTO_INCREMENT
codice_piano            VARCHAR(8) UNIQUE NOT NULL           # Generato auto (es: "PRT5K9L3")
ripartizione_spese_id   BIGINT NOT NULL                      # FK a ripartizione_spese
stabile_id              BIGINT NOT NULL                      # FK a stabili
descrizione             VARCHAR(255) NOT NULL
tipo_piano              ENUM('standard','personalizzato') DEFAULT 'standard'
importo_totale          DECIMAL(10,2) NOT NULL
numero_rate             INT NOT NULL
data_prima_rata         DATE NOT NULL
frequenza               ENUM('mensile','bimestrale','trimestrale','semestrale') DEFAULT 'mensile'
stato                   ENUM('attivo','sospeso','completato','annullato') DEFAULT 'attivo'
configurazione_rate     JSON NULL
note                    TEXT NULL
creato_da               BIGINT NOT NULL                      # FK a users
attivato_at             TIMESTAMP NULL
attivato_da             BIGINT NULL                          # FK a users
created_at              TIMESTAMP
updated_at              TIMESTAMP
deleted_at              TIMESTAMP NULL

rate - Singole rate di pagamento

id                      BIGINT PRIMARY KEY AUTO_INCREMENT
codice_rata             VARCHAR(8) UNIQUE NOT NULL           # Generato auto (es: "RAT2J7M5")
piano_rateizzazione_id  BIGINT NOT NULL                      # FK a piano_rateizzazione
ripartizione_spese_id   BIGINT NOT NULL                      # FK a ripartizione_spese
numero_rata             INT NOT NULL
importo_rata            DECIMAL(10,2) NOT NULL
data_scadenza           DATE NOT NULL
stato                   ENUM('attiva','pagata','scaduta','annullata') DEFAULT 'attiva'
data_pagamento          DATE NULL
importo_pagato          DECIMAL(10,2) NULL
modalita_pagamento      VARCHAR(100) NULL
riferimento_pagamento   VARCHAR(255) NULL
note                    TEXT NULL
registrato_da           BIGINT NULL                          # FK a users
registrato_at           TIMESTAMP NULL
created_at              TIMESTAMP
updated_at              TIMESTAMP
deleted_at              TIMESTAMP NULL

---

🌳 STRUTTURA DATI AD ALBERO

NETGESCON SYSTEM
├── 🏢 AMMINISTRATORI (amministratori)
│   ├── 👤 Profile: nome, cognome, CF, P.IVA, contatti
│   ├── 🔧 Configurazione: database_attivo, cartella_dati, server
│   ├── 👥 UTENTI SISTEMA (users)
│   │   ├── Admin/Super-admin (gestione sistema)
│   │   └── Altri ruoli collegati
│   │
│   └── 🏠 STABILI (stabili)
│       ├── 📋 Dati anagrafici: denominazione, indirizzo, CF stabile
│       ├── 🏛️ Dati catastali: foglio, particella, subalterno
│       ├── ⚙️ Configurazione: SDI, PEC, rate/anno, caratteristiche
│       │
│       ├── 🏘️ UNITÀ IMMOBILIARI (unita_immobiliari)
│       │   ├── 📍 Identificazione: denominazione, piano, vani
│       │   ├── 🏛️ Catasto: categoria, classe, rendita, superficie
│       │   ├── 📊 Millesimi: proprietà, scale, ascensore, riscaldamento
│       │   ├── 🔧 Configurazione: tipo_utilizzo, stato_occupazione
│       │   │
│       │   ├── 👥 ANAGRAFICA CONDOMINIALE (anagrafica_condominiale)
│       │   │   ├── 🆔 Identificazione: tipo_soggetto, nome/ragione_sociale, CF
│       │   │   ├── 📍 Residenza/Domicilio: indirizzi completi
│       │   │   ├── ⚙️ Configurazione: privacy, marketing, note
│       │   │   │
│       │   │   ├── 📞 CONTATTI (contatti_anagrafica)
│       │   │   │   ├── Tipologie: email, telefono, cellulare, PEC, fax
│       │   │   │   ├── Configurazione uso: convocazioni, comunicazioni, emergenze
│       │   │   │   └── Etichette: casa, ufficio, mobile, etc.
│       │   │   │
│       │   │   ├── 🏠 DIRITTI REALI (diritti_reali)
│       │   │   │   ├── Tipologie: proprietà, nuda proprietà, usufrutto, uso
│       │   │   │   ├── Quote: numeratore/denominatore, percentuale
│       │   │   │   ├── Dati legali: atto notarile, trascrizione
│       │   │   │   └── Validità temporale: data_inizio, data_fine
│       │   │   │
│       │   │   └── 📄 CONTRATTI LOCAZIONE (contratti_locazione)
│       │   │       ├── Parti: locatore_id, conduttore_id
│       │   │       ├── Durata: data_stipula, data_inizio, data_fine
│       │   │       ├── Economici: canone, deposito, spese
│       │   │       ├── Configurazione spese: ripartizione inquilino/proprietario
│       │   │       └── Indicizzazione: ISTAT, aggiornamenti automatici
│       │   │
│       │   └── 🏷️ TIPI UTILIZZO (tipi_utilizzo)
│       │       └── Categorie: abitazione, garage, cantina, posto auto, etc.
│       │
│       ├── 💰 GESTIONE CONTABILE (movimenti_contabili)
│       │   ├── 📊 Movimenti: entrate/uscite, causali, importi
│       │   ├── 📋 Categorizzazione: categoria_id, fornitore_cliente_id
│       │   ├── 🔄 Stati: bozza → confermato → registrato
│       │   ├── 💳 Pagamenti: metodo, conto, numero_documento
│       │   ├── ⚙️ Workflow: prima_nota vs definitivo
│       │   │
│       │   └── 📎 ALLEGATI (allegati)
│       │       ├── File: nome_originale, path_completo, dimensione
│       │       ├── Tipologie: fattura, ricevuta, contratto, preventivo
│       │       └── Sicurezza: pubblico/privato, user_id
│       │
│       └── 💸 RIPARTIZIONE SPESE (ripartizione_spese_inquilini)
│           ├── Categorie standard: riscaldamento, acqua, pulizie, amministrazione
│           ├── Percentuali: inquilino vs proprietario
│           ├── Riferimenti normativi: Codice Civile, Confedilizia
│           └── Configurazione: ordinaria/straordinaria/manutenzione
│
├── 📊 RIPARTIZIONE SPESE E GESTIONE RATE
│   ├── 🏷️ VOCI SPESA (voci_spesa)
│   │   ├── Tipologie: ordinaria, straordinaria, speciale
│   │   ├── Categorie: descrittori spesa
│   │   ├── Configurazione: tabelle millesimali, ritenuta d'acconto
│   │   └── Attivazione: flag attivo, ordinamento
│   │
│   ├── 📊 RIPARTIZIONE SPESE (ripartizione_spese)
│   │   ├── Dettaglio ripartizione per stabile
│   │   ├── Collegamenti: voci_spesa, stabili, tabelle millesimali
│   │   ├── Configurazione: tipo ripartizione, stato, note
│   │   └── Audit: creato/approvato/contabilizzato da utenti
│   │
│   ├── 📋 DETTAGLIO RIPARTIZIONE SPESE (dettaglio_ripartizione_spese)
│   │   ├── Dettaglio per singola unità: millesimi, importo calcolato
│   │   ├── Rettifiche: importo rettificato, motivo rettifica
│   │   └── Note: annotazioni libere
│   │
│   └── 📅 PIANI RATEIZZAZIONE (piano_rateizzazione)
│       ├── Piani di dilazione pagamenti
│       ├── Collegamenti: ripartizione_spese, stabili
│       ├── Configurazione: tipo piano, stato, note
│       └── Audit: creato/attivato da utenti
│
└── 💰 GESTIONE RATE (rate)
    ├── Rate di pagamento per piani
    ├── Collegamenti: piano_rateizzazione, ripartizione_spese
    ├── Configurazione: stato rata, modalità pagamento, note
    └── Audit: registrato da utenti

---

🔗 RELAZIONI PRINCIPALI

Gerarchia Master:

1. Amministratore (1) → (N) Stabili
2. Stabile (1) → (N) Unità Immobiliari
3. Unità (1) → (N) Diritti Reali → (1) Anagrafica
4. Anagrafica (1) → (N) Contatti
5. Unità (1) → (N) Contratti Locazione → (2) Anagrafica (locatore + conduttore)

Gestione Contabile:

• Stabile (1) → (N) Movimenti Contabili
• Movimento (1) → (N) Allegati
• Movimento (N) → (1) Anagrafica (fornitore/cliente)

Configurazione:

• Unità (N) → (1) Tipo Utilizzo
• Sistema → Ripartizione Spese (configurazione globale)

---

📝 CONVENZIONI E STANDARD

Codici Univoci 8 Caratteri:

• ADM: Amministratori (es: "ADM8K3L9")
• USR: Utenti sistema (es: "USR9X2M4")
• STB: Stabili (es: "STB5H7K1")
• ANA: Anagrafica condominiale (es: "ANAP4UQ2")
• MOV: Movimenti contabili (es: "MOV7K3L9")
• ALL: Allegati (es: "ALL9X2M4")
• VCS: Voci spesa (es: "VCS7H2K9")
• RPS: Ripartizione spese (es: "RPS4M8N2")
• PRT: Piani rateizzazione (es: "PRT5K9L3")
• RAT: Rate (es: "RAT2J7M5")

Chiavi Database:

• Primary Key: Sempre id BIGINT AUTO_INCREMENT
• Foreign Key: {tabella_singolare}_id (es: stabile_id, anagrafica_id)
• Codici: codice_{tabella_singolare} VARCHAR(8) UNIQUE

Timestamps Standard:

• created_at, updated_at su tutte le tabelle
• deleted_at per Soft Deletes dove appropriato

Enum Values:

• Stati: attivo/inattivo, confermato/bozza
• Tipologie: definite secondo standard settore immobiliare
• Configurazioni: boolean per flags, enum per scelte multiple

---

🔧 NOTE TECNICHE E OTTIMIZZAZIONI

Indici Database:

# Indici performance critici:
INDEX idx_amministratore_id ON stabili (amministratore_id)
INDEX idx_stabile_id ON unita_immobiliari (stabile_id)
INDEX idx_anagrafica_id ON contatti_anagrafica (anagrafica_id)
INDEX idx_movimento_data ON movimenti_contabili (data_movimento, stabile_id)
INDEX idx_codici_univoci ON * (codice_*)

# Indici compositi per query frequenti:
INDEX idx_diritti_attivi ON diritti_reali (unita_immobiliare_id, attivo, data_fine_validita)
INDEX idx_contratti_attivi ON contratti_locazione (unita_immobiliare_id, stato_contratto)

Validazioni Applicative:

• Codici fiscali: Validazione algoritmo CF italiana
• Partite IVA: Validazione checksum P.IVA
• Quote proprietà: Somma quote per unità = 100%
• Date validità: data_inizio ≤ data_fine
• Percentuali: Range 0.00-100.00

Compatibilità Legacy:

• Mantenuto supporto per campi esistenti dove necessario
• Migration graduali per evitare rotture
• Mapping automatico vecchi → nuovi campi dove possibile

---

🎯 RIFERIMENTI ALTRI DOCUMENTI

• PROGRESS_LOG.md: Storico sviluppo, errori risolti, stato implementazione
• DATA_ARCHITECTURE.md: (DA CREARE) Architettura applicativa e flussi
• API_ENDPOINTS.md: (DA CREARE) Documentazione API REST e GraphQL
• UI_COMPONENTS.md: (DA CREARE) Componenti interfaccia e responsive design
• DEVELOPMENT_IDEAS.md: (DA CREARE) Roadmap, feature, idee creative

---

Documento aggiornato: 8 Luglio 2025 - Base per comprensione completa database NetGesCon