netgescon-day0/docs/90-UI-interfaccia-unica/PIANO-CONTI-TIPOLOGIE.md

🎯 PIANO DEI CONTI - SISTEMA TIPOLOGIE

Prevenzione collisioni codici in contabilità unificata

📅 Versione: 1.0 - 4 Agosto 2025

🎯 Obiettivo: Differenziare voci spese/entrate/unità

---

🚨 PROBLEMA IDENTIFICATO

❌ Rischio Collisioni Codici:

CASO PROBLEMATICO:
- Voce Spesa: Stabile 1, Tabella A, Voce 1 → Codice: 1.A.01
- Unità Immobiliare: Stabile 1, Scala A, Interno 1 → Codice: 1.A.01

RISULTATO: CODICI IDENTICI PER ENTITÀ DIVERSE!

---

✅ SOLUZIONE: CAMPO TIPOLOGIA

🎯 Tipologie Disponibili:

Codice	Denominazione	Utilizzo	Esempio
SPE	Spese	Voci di spesa generali	SPE.1.A.01 - Pulizie
ENT	Entrate	Ricavi e incassi	ENT.1.B.02 - Quote condominiali
CRE	Crediti	Somme da incassare	CRE.1.C.03 - Crediti vs condomini
DEB	Debiti	Somme da pagare	DEB.1.D.04 - Debiti vs fornitori
USC	Uscite	Pagamenti effettuati	USC.1.E.05 - Pagamento fatture
UNI	Unità	Unità immobiliari	UNI.1.A.01 - Appartamento Scala A

📊 Struttura Piano Conti Unificata:

-- Tabella: piano_conti
CREATE TABLE piano_conti (
    id INT PRIMARY KEY,
    stabile_id INT,
    tipologia VARCHAR(3) DEFAULT 'SPE',  -- NUOVO CAMPO
    mastro VARCHAR(10),
    conto VARCHAR(10), 
    sottoconto VARCHAR(10),
    denominazione VARCHAR(255),
    -- Indice unico composto
    UNIQUE KEY idx_piano_conti_unique (stabile_id, tipologia, mastro, conto, sottoconto)
);

🔗 Codici Risultanti:

PRIMA (Problematico):
- 1.A.01 (Pulizie)
- 1.A.01 (Appartamento) ❌ COLLISIONE!

DOPO (Risolto):
- SPE.1.A.01 (Pulizie)
- UNI.1.A.01 (Appartamento) ✅ DISTINTI!

---

🎯 IMPLEMENTAZIONE

📝 Migration Campo Tipologia:

// 2025_08_04_170024_add_tipologia_to_piano_conti_table.php
public function up(): void
{
    Schema::table('piano_conti', function (Blueprint $table) {
        $table->string('tipologia', 3)->after('sottoconto')->default('SPE');
        $table->index(['stabile_id', 'tipologia', 'mastro', 'conto', 'sottoconto'], 'idx_piano_conti_unique');
    });
}

🔄 Migration Aggiornamento Dati:

// 2025_08_04_170158_update_piano_conti_tipologie_data.php
public function up(): void
{
    DB::update("
        UPDATE piano_conti 
        SET tipologia = CASE 
            WHEN denominazione LIKE '%spesa%' OR denominazione LIKE '%costo%' THEN 'SPE'
            WHEN denominazione LIKE '%entrata%' OR denominazione LIKE '%ricavo%' THEN 'ENT'
            WHEN denominazione LIKE '%credito%' OR denominazione LIKE '%anticipo%' THEN 'CRE'
            WHEN denominazione LIKE '%debito%' OR denominazione LIKE '%dovuto%' THEN 'DEB'
            WHEN denominazione LIKE '%uscita%' OR denominazione LIKE '%pagamento%' THEN 'USC'
            WHEN denominazione LIKE '%unità%' OR denominazione LIKE '%appartamento%' THEN 'UNI'
            ELSE 'SPE'
        END
    ");
}

---

🎯 UTILIZZO PRATICO

💡 Esempi Codici Finali:

🏢 Spese Condominiali:

SPE.1.A.01 - Pulizie scale
SPE.1.A.02 - Illuminazione
SPE.1.B.01 - Manutenzione ascensore
SPE.1.B.02 - Gestione amministrativa
SPE.1.C.01 - Assicurazione fabbricato

💰 Entrate:

ENT.1.A.01 - Quote ordinarie
ENT.1.A.02 - Quote straordinarie  
ENT.1.B.01 - Rimborsi assicurazione
ENT.1.C.01 - Interessi attivi

🏠 Unità Immobiliari:

UNI.1.A.01 - Appartamento Scala A Int. 1
UNI.1.A.02 - Appartamento Scala A Int. 2
UNI.1.B.01 - Appartamento Scala B Int. 1
UNI.1.C.01 - Box auto n. 1

💳 Crediti/Debiti:

CRE.1.A.01 - Credito vs condomino Rossi
CRE.1.A.02 - Anticipo da amministratore
DEB.1.B.01 - Debito vs Enel
DEB.1.B.02 - Debito vs ditta pulizie

---

🔧 AGGIORNAMENTO MODELLI

📝 Model PianoDeiConti:

// app/Models/PianoDeiConti.php
class PianoDeiConti extends Model
{
    protected $table = 'piano_conti';
    
    protected $fillable = [
        'stabile_id', 'tipologia', 'mastro', 'conto', 'sottoconto', 'denominazione'
    ];
    
    // Costanti tipologie
    const TIPOLOGIE = [
        'SPE' => 'Spese',
        'ENT' => 'Entrate', 
        'CRE' => 'Crediti',
        'DEB' => 'Debiti',
        'USC' => 'Uscite',
        'UNI' => 'Unità'
    ];
    
    // Accessor per codice completo
    public function getCodiceCompletoAttribute()
    {
        return "{$this->tipologia}.{$this->mastro}.{$this->conto}.{$this->sottoconto}";
    }
    
    // Scope per tipologia
    public function scopeSpese($query)
    {
        return $query->where('tipologia', 'SPE');
    }
    
    public function scopeEntrate($query)
    {
        return $query->where('tipologia', 'ENT');
    }
    
    public function scopeUnita($query)
    {
        return $query->where('tipologia', 'UNI');
    }
}

---

🎯 INTERFACCIA UTENTE

📊 Select Tipologia nei Form:

<!-- resources/views/admin/piano-conti/form.blade.php -->
<div class="form-group">
    <label for="tipologia">Tipologia *</label>
    <select name="tipologia" id="tipologia" class="form-control" required>
        <option value="">Seleziona tipologia</option>
        @foreach(\App\Models\PianoDeiConti::TIPOLOGIE as $codice => $nome)
            <option value="{{ $codice }}" {{ old('tipologia', $pianoConto->tipologia ?? '') == $codice ? 'selected' : '' }}>
                {{ $codice }} - {{ $nome }}
            </option>
        @endforeach
    </select>
</div>

🎨 Badge Colorati per Tipologie:

<!-- Visualizzazione con colori -->
@switch($pianoConto->tipologia)
    @case('SPE')
        <span class="badge bg-danger">{{ $pianoConto->tipologia }} - Spese</span>
        @break
    @case('ENT')
        <span class="badge bg-success">{{ $pianoConto->tipologia }} - Entrate</span>
        @break
    @case('CRE')
        <span class="badge bg-info">{{ $pianoConto->tipologia }} - Crediti</span>
        @break
    @case('DEB')
        <span class="badge bg-warning">{{ $pianoConto->tipologia }} - Debiti</span>
        @break
    @case('USC')
        <span class="badge bg-dark">{{ $pianoConto->tipologia }} - Uscite</span>
        @break
    @case('UNI')
        <span class="badge bg-primary">{{ $pianoConto->tipologia }} - Unità</span>
        @break
@endswitch

---

📊 VANTAGGI SISTEMA

✅ Benefici Immediati:

1. Zero Collisioni - Codici sempre univoci
2. Chiarezza Immediata - Tipologia visibile nel codice
3. Filtraggio Facile - Raggruppamento per tipologia
4. Bilanci Separati - Spese/Entrate/Crediti distinti
5. Scalabilità - Facile aggiungere nuove tipologie

📈 Reportistica Migliorata:

-- Bilancio per tipologia
SELECT 
    tipologia,
    COUNT(*) as voci_count,
    SUM(importo) as totale_importo
FROM piano_conti pc
JOIN movimenti m ON pc.id = m.piano_conti_id
WHERE pc.stabile_id = 1
GROUP BY tipologia
ORDER BY tipologia;

-- Risultato:
-- CRE | 15 | 12.500,00
-- DEB | 8  | -8.300,00  
-- ENT | 25 | 45.000,00
-- SPE | 42 | -38.200,00
-- UNI | 50 | 0,00
-- USC | 18 | -15.600,00

---

🚀 PROSSIMI PASSI

1. Eseguire Migration:

cd /var/www/netgescon
php artisan migrate

2. Aggiornare Controller:

• Aggiungere validation per tipologia
• Implementare filtri per tipologia
• Aggiornare form di inserimento

3. Aggiornare Interfacce:

• Form piano dei conti con select tipologia
• Liste con badge colorati
• Filtri per tipologia

4. Testing:

• Verificare unicità codici
• Test inserimento/modifica
• Validazione reportistica

---

🎯 SISTEMA TIPOLOGIE ATTIVO
Previene collisioni e migliora organizzazione contabile