fix(import-pipeline): align unit comproprietari matching via physical identity (scala + int) and document architecture directive (task-d095b0e23b)

app/Console/Commands/ImportGesconFullPipeline.php

@@ -8127,34 +8127,45 @@ private function loadLegacyComproprietariHistoryRows(object $row, ?string $legac
             return [];
         }
 
-        $codStabile = trim((string) ($row->cod_stabile ?? ''));
-        $codCond    = trim((string) ($row->cod_cond ?? ''));
+        $codStabile   = trim((string) ($row->cod_stabile ?? ''));
+        $scala        = trim((string) ($row->scala ?? ''));
+        $interno      = trim((string) ($row->interno ?? $row->int ?? ''));
         $stableCondId = $this->extractStableLegacyCondId($row, $legacyCondId);
 
         if ($codStabile === '') {
             return [];
         }
 
-        $startCondId = $stableCondId !== null && $stableCondId !== '' ? $stableCondId : null;
-        $linkedCondIds = [];
-        if ($startCondId !== null) {
-            $linkedCondIds = $this->resolveLinkedLegacyCondIds($codStabile, $startCondId);
+        $unitIdConds = [];
+        if ($stableCondId !== null && $stableCondId !== '') {
+            $unitIdConds[] = $stableCondId;
+        }
+
+        if ($scala !== '' || $interno !== '') {
+            $matchingConds = DB::connection('gescon_import')->table('condomin')
+                ->where('cod_stabile', $codStabile)
+                ->where('scala', $scala)
+                ->where(function ($q) use ($interno): void {
+                    $q->where('interno', $interno);
+                    if (Schema::connection('gescon_import')->hasColumn('condomin', 'int')) {
+                        $q->orWhere('int', $interno);
+                    }
+                })->pluck('id_cond')->filter()->all();
+
+            $unitIdConds = array_values(array_unique(array_merge($unitIdConds, $matchingConds)));
+        }
+
+        if (empty($unitIdConds)) {
+            return [];
         }
 
         $query = DB::connection('gescon_import')
             ->table('comproprietari')
             ->where('cod_stabile', $codStabile)
+            ->whereIn('id_cond', $unitIdConds)
             ->orderByDesc('legacy_year')
             ->orderByDesc('id');
 
-        if (! empty($linkedCondIds)) {
-            $query->whereIn('id_cond', $linkedCondIds);
-        } elseif ($startCondId !== null) {
-            $query->where('id_cond', $startCondId);
-        } else {
-            return [];
-        }
-
         $historyRows = $query->get()->all();
         if ($historyRows === []) {
             return [];

directives/ANAGRAFICHE_MAPPING_LEGACY.md

@@ -9,6 +9,11 @@ ## 1. Collegamento tra `condomin` e `comproprietari`
   - Risultato unificato: Int. B/4 -> **Barone Michele (50% Comproprietà)** e **Francioni Claudia / Cecilia Tordini (50% Comproprietà)**.
   - Divieto: È vietata qualsiasi associazione tra `comproprietari` e `condomin` basata sul campo `cod_cond`, in quanto `cod_cond` è il progressivo contabile della singola gestione e può identificare un'altra unità in quell'anno (es. `cod_cond = 47` appartiene all'interno E - Giovagnoni Marina).
 
+## 1.1 Identità Fisica dell'Unità Immobiliare (`scala` + `interno`) e Gestione Temporale dei Codici
+- **Identità Fisica Costante**: L'Unità Immobiliare è definita univocamente dalla combinazione `cod_stabile` + `scala` + `interno` (es. Stabile 0013, Scala B, Interno 8). Questa identità fisica rimane stabile nel tempo ed è collegata ai dati catastali.
+- **Dinamica dei Codici di Gestione (`id_cond`, `cod_cond`)**: Nei file delle singole gestioni annuali (`singolo_anno.mdb`), i codici `id_cond` e `cod_cond` variano nel tempo con i subentri (es. su Stabile 0013 B/8: `id_cond = 18` Maurelli Rossana -> `id_cond = 82` Ranchino Valentina -> `id_cond = 83` D'Aniello Andrea).
+- **Regola di Isolamento per Unità**: Il matching delle anagrafiche e dei comproprietari deve sempre vincolarsi tassativamente all'identità fisica dell'unità (`scala` + `interno`). È tassativamente vietato raccogliere comproprietari o legami da altre unità basandosi unicamente sul valore numerico del codice di gestione senza verificare la corrispondenza di scala ed interno.
+
 ## 2. Collegamento Contabile (`incassi`, `rate`, `emes_det`)
 - **Campo contabile per anno gestione**: `cod_cond`
 - **Distinzione ruolo contabile**: `cond_inquil`