Aggiungi CHANGELOG.md con la voce 0.1.0

Formato Keep a Changelog; elenca le funzionalità attuali del programma come
prima voce di storico versioni.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+Tutte le modifiche rilevanti di questo progetto sono documentate in questo file.
+
+Il formato segue [Keep a Changelog](https://keepachangelog.com/it/1.1.0/), e il progetto
+aderisce a [Semantic Versioning](https://semver.org/lang/it/).
+
+## [0.1.0] - 2026-09-22
+
+### Aggiunto
+
+- Wizard a 5 fasi (Database → Importa Distinta Base → Crea cartella raw → Trova componenti
+  referenziati → Verifica completezza) per preparare i file `raw/` da passare a Creo
+  Distributed Batch per l'esportazione STEP.
+- Indicizzazione dei file CAD Pro-ENGINEER/Creo di un disco/share di rete (radice di default
+  `X:\`) in un DB SQLite locale (`cad_index.db`), con aggiornamento incrementale e barra di
+  progresso.
+- Import della distinta base dall'export del gestionale (`.xls`/`.xml`) in CSV
+  componente;descrizione, incluso il riconoscimento della convenzione `DBP_<codice>_<timestamp>`
+  per aggiungere l'assieme generale come riga.
+- Creazione della cartella `raw/` con copia parallela dei file CAD dei componenti trovati
+  nell'indice.
+- Risoluzione ricorsiva dell'albero componenti dai file `.asm` (sotto-assiemi, parti,
+  componenti soppressi, riferimenti esterni), con parser esatto dei record binari
+  (`AsmRecordReader`) e fallback euristico testuale (`AssemblyComponentScanner`) per i file
+  fuori formato.
+- Scelta automatica della copia corretta quando lo stesso codice esiste in più cartelle della
+  share, preferendo quella della cartella dell'assieme che la referenzia.
+- Anteprima trascinabile (drag&drop) dei file `.asm` della distinta già in `raw/`, pronti per
+  Creo Distributed Batch.
+- Menu "File → Nuova estrazione" (Ctrl+N) per ripartire con una nuova distinta senza ricaricare
+  database e cartella di lavoro, e "Aiuto → Guida" (F1) con una sintesi interattiva delle 5 fasi.
+- Script standalone C# file-based (`scripts/`): `ExtractCreoStrings.cs`, `BomViaDb.cs`,
+  `CreoBom.cs`, per estrarre la distinta componenti da riga di comando.
+- Pubblicazione come eseguibile standalone single-file self-contained (Windows x64).

CLAUDE.md

@@ -36,6 +36,32 @@ i test possono chiamare direttamente `Indexer.ParseFilename` e
 `AssemblyComponentScanner.EstraiCodiciReferenziati` senza esporli come API
 pubblica.
 
+## Documentazione: va tenuta allineata
+
+`docs/` non è un archivio di note storiche: descrive **il programma com'è adesso**, ed è la
+prima cosa che si legge per capirlo. Ogni modifica strutturale — un passo in più o in meno nel
+flusso delle fasi, un nuovo modo di leggere il `.asm`, un cambio nello schema del DB o nel
+criterio con cui si sceglie un file — va riflessa nei doc **nello stesso commit** del codice,
+non "dopo". Un doc che descrive un comportamento che non esiste più è peggio di un doc
+mancante: fa prendere decisioni sbagliate.
+
+Dove scrivere cosa:
+
+| Doc | Contenuto |
+|---|---|
+| `CLAUDE.md` (questo file) | il flusso essenziale e i punti che si sbaglierebbero senza saperli |
+| [`docs/architettura.md`](docs/architettura.md) | il processo delle 5 fasi e la mappa file-per-file |
+| [`docs/formato-asm-record.md`](docs/formato-asm-record.md) | parser esatto dei record `.asm`, con §7 per i casi limite |
+| [`docs/formato-asm.md`](docs/formato-asm.md) | euristica testuale di fallback |
+| [`docs/db-cad-index.md`](docs/db-cad-index.md) | schema e vista di `cad_index.db` |
+| [`docs/copia-raw-parallela.md`](docs/copia-raw-parallela.md) | parallelizzazione della copia in `raw/` |
+| [`CHANGELOG.md`](CHANGELOG.md) | storico delle versioni (formato Keep a Changelog); ogni release che cambia `<Version>` nel csproj aggiunge qui la sua voce |
+
+Quando il cambiamento nasce da un fallimento reale di Creo, scrivere anche **il sintomo**: i
+messaggi di Creo non nominano il file o la causa, e senza quel ponte la prossima volta si
+riparte da zero (i §7.3/§7.4/§7.5 di `formato-asm-record.md` sono l'esempio del formato
+atteso).
+
 ## Architettura
 
 Il programma è tutto in `PrepStep/` (nessun altro progetto nella solution). Dettaglio
@@ -63,15 +89,23 @@ designer visuale):
    sotto-assiemi/parti (`RisolviAlberoComponenti`), copiandoli anch'essi in `raw/`. Usa
    `AsmRecordReader` (parser esatto dei record binari, `docs/formato-asm-record.md`) e ripiega
    su `AssemblyComponentScanner` (euristica testuale, `docs/formato-asm.md`) solo se il file
-   non rispetta il formato validato (`InvalidDataException`). ⚠️ Limite noto non coperto dal
-   fallback: un **assieme** con family table (raro, non solo le parti normalizzate possono
-   averla) può dare un risultato silenziosamente incompleto senza lanciare eccezione — vedi
-   `docs/formato-asm-record.md` §7.
+   non rispetta il formato validato (`InvalidDataException`). Tre punti da non confondere,
+   tutti imparati facendo fallire Creo (`docs/formato-asm-record.md` §7.3, §7.4 e §7.5):
+   i **componenti soppressi** non sono nella distinta ma il loro file serve per aprire
+   l'assieme (`EstraiCodiciSoppressi`, copiati senza finire fra i "non trovati"); i
+   **riferimenti esterni** (assembly feature, datum copiati) citano modelli che non sono né
+   membri né piazzamenti, e che Creo carica con tutto il loro albero
+   (`EstraiCodiciRiferimentiEsterni`, anche questi fuori dai "non trovati", ma con ricorsione);
+   e quando lo stesso codice esiste in più cartelle della share — succede per il 13% dei
+   codici — va copiata la copia nella **stessa cartella dell'assieme che la referenzia**
+   (`ScegliPerCartella`), perché il `.asm` non registra quale usa e sbagliarla impedisce a
+   Creo di aprire l'assieme.
 5. **Verifica completezza** — mostra i `.asm` della distinta già in `raw/`, trascinabili su
-   Creo per l'esportazione STEP (Distributed Batch, manuale, fuori dall'app); "Verifica
-   completezza assiemi" controlla ricorsivamente sull'indice (non su `raw/`, stessa
-   `AsmRecordReader`/fallback della fase 4) se tutti i sotto-componenti di ogni assieme sono
-   presenti.
+   Creo per l'esportazione STEP (Distributed Batch, manuale, fuori dall'app).
+
+Menu in cima alla finestra: "File → Nuova estrazione" (Ctrl+N) azzera lo stato delle fasi 2-5
+per ripartire con una nuova distinta, senza toccare DB/cartella di lavoro della fase 1;
+"Aiuto → Guida" (F1) apre una sintesi interattiva delle 5 fasi (`GuidaForm.cs`).
 
 ## Script standalone (`scripts/`)
 

PrepStep.Tests/AsmRecordReaderTests.cs

@@ -37,6 +37,28 @@ public class AsmRecordReaderTests
     private static byte[] ConfigName(string istanza, int idMembro) =>
         Bytes(0xe3, "ConfigName", 0, 0xe2, (byte)'3', istanza, 0, idMembro, 0x82, 0x7b);
 
+    // \0objname\0 \xe2 \xe0\x01 object_type\0 <int> \xe0\x0a name\0 <nome>\0 - il nome proprio
+    // del modello (quello che la BOM intesta), vedi docs/formato-asm-record.md §5
+    private static byte[] ObjName(string nome) =>
+        Bytes(0, "objname", 0, 0xe2, 0xe0, 0x01, "object_type", 0, 2, 0xe0, 0x0a, "name", 0, nome, 0);
+
+    // identita' dichiarata dal file: \xe0\x01 model_t_type\0 <int> \xe0\x0a model_name\0 <nome>\0
+    // \xe0\x0a generic_name\0 \0 (vuoto)
+    private static byte[] ModelName(string nome) =>
+        Bytes(0xe0, 0x01, "model_t_type", 0, 2, 0xe0, 0x0a, "model_name", 0, nome, 0,
+              0xe0, 0x0a, "generic_name", 0, 0);
+
+    // array dei modelli referenziati: \xf2\xf7\x05 <elementi> \xf3, ogni elemento
+    // \xe3\xe2<tipo><nome>\0 - vedi docs/formato-asm-record.md §7.5
+    private static byte[] Riferimenti(params string[] nomi)
+    {
+        var parti = new List<object> { 0xf2, 0xf7, 0x05 };
+        foreach (var nome in nomi)
+            parti.AddRange(new object[] { 0xe3, 0xe2, 0x02, nome, 0 });
+        parti.Add(0xf3);
+        return Bytes(parti.ToArray());
+    }
+
     private static byte[] Asm(int conteggioDichiarato, byte[] membri, byte[]? extra = null) =>
         Bytes("header ", extra ?? Array.Empty<byte>(), "\0members\0", 0xf1, 0xf8, conteggioDichiarato, membri, "#MdlStatus");
 
@@ -87,6 +109,23 @@ public class AsmRecordReaderTests
         Assert.All(membri, m => Assert.Equal("9244250136_C03", m.Nome));
     }
 
+    [Fact]
+    public void Membro_con_notazione_istanza_generico_diretta_nel_nome_usa_il_generico()
+    {
+        // Regressione: 9244248577a_c01.asm - alcuni membri di family table non-UNI non
+        // passano da ConfigName, il campo "name"/"family_name" del record members porta gia'
+        // la forma "<istanza><generico>" (stessa notazione di §4.1). Senza lo split, il codice
+        // cercato nell'indice sarebbe "V6-12--_-_U5931_GC<UNI5931>" per intero, mai trovato -
+        // va cercato invece il generico "UNI5931".
+        byte[] dati = Asm(1, Membro(1, 2, "V6-12--_-_U5931_GC<UNI5931>"));
+
+        var membri = AsmRecordReader.LeggiMembri(dati);
+
+        Assert.Single(membri);
+        Assert.Equal("V6-12--_-_U5931_GC", membri[0].Nome);
+        Assert.Equal("UNI5931", membri[0].Generico);
+    }
+
     [Fact]
     public void Componente_senza_ConfigName_non_e_toccato_da_istanze_di_altri_membri()
     {
@@ -111,6 +150,118 @@ public class AsmRecordReaderTests
         Assert.Throws<InvalidDataException>(() => AsmRecordReader.LeggiMembri(dati));
     }
 
+    [Fact]
+    public void Assieme_family_table_con_generic_name_lancia_eccezione()
+    {
+        // Regressione: un file che e' esso stesso un'istanza di family table (il suo nome
+        // proprio "2546220101" piu' il suffisso "_C01" in model_name) descrive in "members"
+        // solo quella rappresentazione, non le istanze sorelle. Va segnalato invece di
+        // restituire silenziosamente il contenuto sbagliato (docs/formato-asm-record.md §7).
+        byte[] dati = Asm(1, Membro(1, 2, "9244206098"),
+            extra: Bytes(ObjName("2546220101"), ModelName("2546220101_C01")));
+
+        Assert.Throws<InvalidDataException>(() => AsmRecordReader.LeggiMembri(dati));
+    }
+
+    [Fact]
+    public void Model_name_di_un_altro_modello_non_lancia_eccezione()
+    {
+        // Regressione: sui file reali della share il record "model_name" nomina spesso un
+        // modello diverso dal file (tipicamente un suo membro), non l'identita' del file. Il
+        // nome proprio (objname) non conferma, quindi non e' il sintomo della family table:
+        // "members" e' corretto e va usato. Verificato contro BOM Creo reali - senza questo
+        // controllo il file cadeva sull'euristica testuale, che produceva codici inesistenti
+        // segnalati poi come "componenti mancanti".
+        byte[] dati = Asm(1, Membro(1, 2, "9044207999A_C01"),
+            extra: Bytes(ObjName("9244207999A"), ModelName("9044207999A_C01")));
+
+        var membri = AsmRecordReader.LeggiMembri(dati);
+
+        Assert.Equal("9044207999A_C01", membri.Single().Nome);
+    }
+
+    [Fact]
+    public void Model_name_senza_nome_proprio_non_lancia_eccezione()
+    {
+        // Stesso caso del test sopra ma senza record "objname" (formato osservato su tutti i
+        // file reali che facevano scattare il falso positivo): senza conferma del nome proprio
+        // il record non e' un'identita', quindi "members" va letto normalmente.
+        byte[] dati = Asm(1, Membro(1, 2, "9244206098"), extra: ModelName("2546220101_C01"));
+
+        Assert.Single(AsmRecordReader.LeggiMembri(dati));
+    }
+
+    [Fact]
+    public void Generic_name_senza_suffisso_istanza_non_lancia_eccezione()
+    {
+        // Regressione: su ~7% dei file reali della share compare un record "model_name" +
+        // "generic_name" (vuoto) che NON e' il sintomo della family table di assiemi - il
+        // valore non ha il suffisso "_C0n" delle istanze (es. e' un codice qualunque non
+        // correlato al nome del file). In quei casi "members" e' letto correttamente e va
+        // usato normalmente, non bloccato per un falso positivo.
+        byte[] dati = Asm(1, Membro(1, 2, "9244206098"),
+            extra: Bytes(ObjName("9244230117"), ModelName("9244230117")));
+
+        var membri = AsmRecordReader.LeggiMembri(dati);
+
+        Assert.Single(membri);
+    }
+
+    [Fact]
+    public void Componente_soppresso_non_e_fra_i_membri_ma_e_segnalato_a_parte()
+    {
+        // Un componente soppresso sparisce da "members" (il conteggio scende) ma resta citato
+        // dalla feature che lo posiziona. Non va nella BOM, però senza il suo file Creo non
+        // apre l'assieme, quindi va copiato lo stesso.
+        byte[] dati = Asm(1, Membro(1, 2, "9244206098"),
+            extra: Bytes("Componente ID 52 (9230100043.PRT)", 0));
+
+        Assert.Equal(new[] { "9244206098" }, AsmRecordReader.LeggiMembri(dati).Select(m => m.Nome));
+
+        string percorso = ScriviFile(dati);
+        try
+        {
+            Assert.Equal(new[] { "9230100043" }, AsmRecordReader.EstraiCodiciSoppressi(percorso));
+            Assert.DoesNotContain("9230100043", AsmRecordReader.EstraiCodiciReferenziati(percorso));
+        }
+        finally { File.Delete(percorso); }
+    }
+
+    [Fact]
+    public void Componente_gia_fra_i_membri_non_e_segnalato_come_soppresso()
+    {
+        byte[] dati = Asm(1, Membro(1, 2, "9244206098"),
+            extra: Bytes("Componente ID 7 (9244206098.PRT)", 0));
+        string percorso = ScriviFile(dati);
+        try
+        {
+            Assert.Empty(AsmRecordReader.EstraiCodiciSoppressi(percorso));
+        }
+        finally { File.Delete(percorso); }
+    }
+
+    [Fact]
+    public void Riferimenti_esterni_non_sono_fra_i_membri_e_si_risolvono_sul_generico()
+    {
+        // Un modello legato da riferimento esterno (assembly feature "#AFn", datum copiati) non
+        // compare ne' in "members" ne' fra i piazzamenti, ma senza il suo file Creo non apre
+        // l'assieme: e' il caso che faceva fallire 9255728001_200 in Distributed Batch. Per le
+        // istanze di family table il file su disco e' il generico fra parentesi angolari.
+        byte[] dati = Asm(1, Membro(1, 2, "9244206098"),
+            extra: Bytes(Riferimenti("9255708017#AF2<9255708017>", "9255708018"),
+                         Riferimenti("V6-12--_-_U5933_C<UNI5933>")));
+
+        Assert.Equal(new[] { "9244206098" }, AsmRecordReader.LeggiMembri(dati).Select(m => m.Nome));
+
+        string percorso = ScriviFile(dati);
+        try
+        {
+            Assert.Equal(new[] { "9255708017", "9255708018", "UNI5933" },
+                AsmRecordReader.EstraiCodiciRiferimentiEsterni(percorso).OrderBy(c => c, StringComparer.Ordinal));
+        }
+        finally { File.Delete(percorso); }
+    }
+
     [Fact]
     public void Sezione_members_assente_lancia_eccezione()
     {

PrepStep/AsmRecordReader.cs

@@ -49,12 +49,47 @@ public static class AsmRecordReader
     // normalizzazione ogni istanza del pattern risulterebbe un componente diverso.
     private static readonly Regex SuffissoArrayFeatureRegex = new(@"#AF\d+$", RegexOptions.Compiled);
 
+    // record di identita' del modello, seguito da "generic_name" (vuoto): compare su una
+    // minoranza di assiemi (~7% dei campioni sulla share) per motivi diversi e nella
+    // maggioranza dei casi "members" resta corretto - la sola presenza di "generic_name" NON
+    // e' un segnale affidabile (verificato: su 144 file che lo contengono, solo 25 hanno
+    // anche il sintomo sotto; per gli altri 119 "members" letto normalmente coincide con
+    // l'euristica testuale, quindi e' un contesto diverso, non lo stesso problema).
+    private static readonly Regex OwnModelIdentityRegex = new(
+        @"\xe0\x01model_t_type\x00" + Int + @"\xe0\x0amodel_name\x00([\x20-\x7e]+)\x00\xe0\x0ageneric_name\x00\x00",
+        RegexOptions.Compiled);
+
+    // Alcuni membri di family table non-UNI (es. viti/dadi commerciali) non passano da
+    // ConfigName: il campo "name" del record members porta gia' la forma "<istanza><generico>"
+    // (stessa notazione di §4.1, li' sconsigliata per la BOM perche' e' un elenco di
+    // riferimenti geometrici - qui invece e' il valore vero del componente, va solo separato).
+    // Osservato su 9244248577a_c01.asm: "V6-12--_-_U5931_GC<UNI5931>" - senza questo split il
+    // codice cercato nell'indice sarebbe la stringa intera con le parentesi, mai trovata.
+    private static readonly Regex IstanzaConGenericoRegex = new(@"^([\x20-\x7e]+?)<([\x20-\x7e]+)>$", RegexOptions.Compiled);
+
+    // Suffisso "_C0n" delle istanze di family table (stessa convenzione di
+    // SuffissoArrayFeatureRegex/ConfigName sopra). Usato insieme a OwnModelIdentityRegex per
+    // riconoscere un file che e' esso stesso un'istanza, il cui "members" descriverebbe solo
+    // quella rappresentazione invece delle istanze sorelle (docs/formato-asm-record.md §7).
+    // Da solo NON basta: su file reali quel record nomina spesso un altro modello (un membro
+    // del file, o un codice imparentato), non il file stesso - per quello serve la conferma
+    // del nome proprio (objname).
+    private static readonly Regex SuffissoIstanzaFamilyTableRegex = new(@"_C\d{2,}$", RegexOptions.Compiled);
+
     // primo elemento dell'array "members": porta le chiavi per esteso.
     private static readonly Regex FirstMemberRegex = new(
         @"\x01id\x00" + Int + @"\xe0\x01type\x00" + Int
         + @"\xe0\x0aname\x00([^\x00]+)\x00\xe0\x0afamily_name\x00([^\x00]+)\x00",
         RegexOptions.Compiled);
 
+    private static int ContaOccorrenze(string testo, string marcatore)
+    {
+        int conteggio = 0;
+        for (int i = testo.IndexOf(marcatore, StringComparison.Ordinal); i >= 0; i = testo.IndexOf(marcatore, i + 1, StringComparison.Ordinal))
+            conteggio++;
+        return conteggio;
+    }
+
     private static int AsInt(string bytes)
     {
         int mask = bytes.Length switch { 1 => 0x7F, 2 => 0x3F, 3 => 0x1F, _ => throw new ArgumentException("lunghezza intero non valida") };
@@ -84,14 +119,26 @@ public static class AsmRecordReader
     {
         string testo = Encoding.Latin1.GetString(dati);
 
+        var configNameMatches = ConfigNameRegex.Matches(testo);
+        int configNameGrezzi = ContaOccorrenze(testo, (char)0xe3 + "ConfigName\0");
+        if (configNameMatches.Count != configNameGrezzi)
+            throw new InvalidDataException(
+                $"trovati {configNameGrezzi} record 'ConfigName' ma solo {configNameMatches.Count} " +
+                "interpretati: formato del parametro diverso da quello atteso (vedi §4, costante " +
+                "\\x82\\x7b), lettura non affidabile");
+
         var istanze = new Dictionary<int, string>();
-        foreach (Match m in ConfigNameRegex.Matches(testo))
+        foreach (Match m in configNameMatches)
             istanze[AsInt(m.Groups[2].Value)] = SuffissoArrayFeatureRegex.Replace(m.Groups[1].Value, "");
 
         const string chiaveMembers = "\0members\0";
         int start = testo.IndexOf(chiaveMembers, StringComparison.Ordinal);
         if (start < 0)
             throw new InvalidDataException("sezione 'members' assente");
+        if (testo.IndexOf(chiaveMembers, start + chiaveMembers.Length, StringComparison.Ordinal) >= 0)
+            throw new InvalidDataException(
+                "trovate piu' occorrenze di 'members': probabile rappresentazione semplificata, " +
+                "mai verificata (vedi §7) - non e' chiaro quale sezione descriva la BOM");
         start += chiaveMembers.Length;
 
         int conteggio = dati[start + 2]; // \xf1 \xf8 <conteggio>
@@ -118,7 +165,30 @@ public static class AsmRecordReader
         if (grezzi.Count != conteggio)
             throw new InvalidDataException($"attesi {conteggio} membri, trovati {grezzi.Count}: lettura disallineata");
 
-        return grezzi.Select(g => new Membro(g.Id, g.Tipo, istanze.GetValueOrDefault(g.Id, g.Nome), g.Nome)).ToList();
+        // Il record "model_name" e' l'identita' del file solo se il nome proprio del modello
+        // (objname, §5) lo conferma: da solo nomina spesso un altro modello - un membro del
+        // file, o un modello imparentato - e in quei casi "members" e' gia' corretto. Vedi
+        // docs/formato-asm-record.md §7.
+        var identita = OwnModelIdentityRegex.Match(testo);
+        var nomeProprio = ObjNameRegex.Match(testo);
+        if (identita.Success && nomeProprio.Success
+            && SuffissoIstanzaFamilyTableRegex.IsMatch(identita.Groups[2].Value)
+            && string.Equals(SuffissoIstanzaFamilyTableRegex.Replace(identita.Groups[2].Value, ""),
+                nomeProprio.Groups[1].Value, StringComparison.OrdinalIgnoreCase))
+            throw new InvalidDataException(
+                $"assieme con family table: il file e' esso stesso l'istanza '{identita.Groups[2].Value}', " +
+                "'members' descriverebbe solo questa rappresentazione, non le istanze sorelle - vedi " +
+                "docs/formato-asm-record.md §7");
+
+        return grezzi.Select(g =>
+        {
+            if (istanze.TryGetValue(g.Id, out var nomeIstanza))
+                return new Membro(g.Id, g.Tipo, nomeIstanza, g.Nome);
+            var bracket = IstanzaConGenericoRegex.Match(g.Nome);
+            return bracket.Success
+                ? new Membro(g.Id, g.Tipo, bracket.Groups[1].Value, bracket.Groups[2].Value)
+                : new Membro(g.Id, g.Tipo, g.Nome, g.Nome);
+        }).ToList();
     }
 
     /// <summary>Codici dei componenti diretti (il generico su disco, non il nome istanza),
@@ -131,4 +201,73 @@ public static class AsmRecordReader
         var membri = LeggiMembri(File.ReadAllBytes(percorsoAsm));
         return new HashSet<string>(membri.Select(m => m.Generico), StringComparer.OrdinalIgnoreCase);
     }
+
+    /// <summary>Codici che compaiono come piazzamento ma non fra i membri: sono i componenti
+    /// **soppressi**, che spariscono da "members" senza lasciare traccia (§7.1) ma restano
+    /// citati dalla feature che li posiziona.
+    ///
+    /// Non fanno parte della BOM - Creo non li elenca - ma il loro file serve comunque per
+    /// **aprire** l'assieme: senza, il caricamento fallisce con "dati di input non completi".
+    /// Sono quindi due domande diverse: cosa compare nella distinta (<see
+    /// cref="EstraiCodiciReferenziati"/>) e cosa serve avere su disco (questo metodo in
+    /// aggiunta), e la seconda lista e' piu' lunga della prima.</summary>
+    public static HashSet<string> EstraiCodiciSoppressi(string percorsoAsm)
+    {
+        byte[] dati = File.ReadAllBytes(percorsoAsm);
+        var membri = LeggiMembri(dati);
+        var noti = new HashSet<string>(
+            membri.Select(m => m.Generico).Concat(membri.Select(m => m.Nome)), StringComparer.OrdinalIgnoreCase);
+
+        var soppressi = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (Match m in PlacementRegex.Matches(Encoding.Latin1.GetString(dati)))
+            if (!noti.Contains(m.Groups[1].Value))
+                soppressi.Add(m.Groups[1].Value);
+        return soppressi;
+    }
+
+    /// <summary>Modelli che l'assieme cita nella tabella dei riferimenti (§7.5): oltre ai propri
+    /// membri comprende quelli legati da **riferimenti esterni** - assembly feature, datum
+    /// copiati - che non compaiono né in "members" né come piazzamento, ma che Creo carica
+    /// comunque per aprire l'assieme.
+    ///
+    /// Terza lista dopo <see cref="EstraiCodiciReferenziati"/> ("cosa c'è in distinta") e <see
+    /// cref="EstraiCodiciSoppressi"/>: come quest'ultima risponde a "cosa serve su disco", non a
+    /// "cosa va nella BOM. L'array contiene anche nomi di feature (MIRROR3, CHAMFER1...) e non
+    /// solo di modelli: non si riesce a distinguerli dal record, ma non danno fastidio perché il
+    /// chiamante li cerca nell'indice e ignora quelli che non ci sono.</summary>
+    public static HashSet<string> EstraiCodiciRiferimentiEsterni(string percorsoAsm)
+    {
+        string testo = Encoding.Latin1.GetString(File.ReadAllBytes(percorsoAsm));
+        var codici = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        for (int i = testo.IndexOf(InizioRiferimenti, StringComparison.Ordinal); i >= 0;
+             i = testo.IndexOf(InizioRiferimenti, i + 1, StringComparison.Ordinal))
+        {
+            int max = Math.Min(LunghezzaMassimaRiferimenti, testo.Length - i);
+            int fine = testo.IndexOf(FineRiferimenti, i, max);
+            foreach (Match m in RiferimentoRegex.Matches(testo.Substring(i, fine >= 0 ? fine - i : max)))
+            {
+                var bracket = IstanzaConGenericoRegex.Match(m.Groups[1].Value);
+                codici.Add(bracket.Success
+                    ? bracket.Groups[2].Value
+                    : SuffissoArrayFeatureRegex.Replace(m.Groups[1].Value, ""));
+            }
+        }
+        return codici;
+    }
+
+    // Array dei modelli referenziati: "\xf2\xf7\x05" lo apre, "\xf3" lo chiude, ogni elemento e'
+    // "\xe3\xe2<tipo><nome>\x00" (§7.5). Il tetto di lunghezza limita il danno se il terminatore
+    // non si trova dove atteso: si perde qualche riferimento, non si raccoglie mezzo file.
+    private const string InizioRiferimenti = "ò÷\u0005ãâ";
+    private const char FineRiferimenti = 'ó';
+    private const int LunghezzaMassimaRiferimenti = 4096;
+    private static readonly Regex RiferimentoRegex = new(
+        @"\xe3\xe2[\x01\x02]([\x20-\x7e]{3,})\x00", RegexOptions.Compiled);
+
+    // "Componente ID 52 (9230100043.PRT)" - la stringa cambia con la localizzazione Creo del
+    // file, come in AssemblyComponentScanner.HaPlacement. Minimo 3 caratteri per lo stesso
+    // motivo per cui li' i token generici partono da 3: sotto quella soglia si raccoglie
+    // rumore (sulla share esistono davvero modelli chiamati "1.prt", "2.prt"...).
+    private static readonly Regex PlacementRegex = new(
+        @"Component(?:e)? [Ii][Dd] \d+ \(([A-Za-z0-9_\-]{3,})\.(?:PRT|ASM)\)", RegexOptions.Compiled);
 }

PrepStep/Form1.cs

@@ -10,7 +10,6 @@ public partial class Form1 : Form
     private readonly Button _btnCreaRaw = new();
     private readonly Button _btnTrovaPrt = new();
     private readonly Button _btnVerifica = new();
-    private readonly Button _btnCompletezza = new();
     private readonly ListView _lstAnteprimaAsm = new();
     private readonly Button _btnPulisci = new();
     private readonly Label _lblStatus = new();
@@ -22,6 +21,8 @@ public partial class Form1 : Form
     private readonly DataGridView _gridRaw = new();
     private readonly Label _lblImportStatus = new();
     private readonly ToolTip _tipImportStatus = new();
+    private readonly MenuStrip _menu = new();
+    private readonly ToolStripMenuItem _mnuNuovaEstrazione = new("Nuova estrazione");
 
     // Wizard: una fase alla volta occupa tutta la finestra, si avanza solo quando quella
     // corrente è "pronta" (vedi AvantiConsentito). NomiFasi/_panelFasi sono paralleli per indice.
@@ -91,9 +92,9 @@ public partial class Form1 : Form
         _lblFase.Font = new Font(Font, FontStyle.Bold);
         headerPanel.Controls.Add(_lblFase);
 
-        // Barra di navigazione come footer separato dal contenuto (stesso pattern di
-        // ProgressForm): linea sottile in cima + sfondo bianco, invece dei bottoni appoggiati
-        // direttamente sul contenuto/sulla barra di stato senza alcuna divisione visiva.
+        // Barra di navigazione come footer separato dal contenuto: linea sottile in cima e
+        // sfondo bianco, invece dei bottoni appoggiati direttamente sul contenuto/sulla barra
+        // di stato senza alcuna divisione visiva.
         // Padding destro = 16, lo stesso usato dai pannelli di ogni fase (Padding(16)): prima
         // era 12, quindi "Avanti" sporgeva 4px oltre il margine destro del contenuto sopra.
         var navContainer = new Panel { Dock = DockStyle.Bottom, Height = 64, BackColor = Color.White };
@@ -146,10 +147,25 @@ public partial class Form1 : Form
         // Ordine dei Dock.Bottom: l'ultimo aggiunto è il più esterno (il vero bordo inferiore
         // della finestra). La barra di stato va tra contenuto e azioni; i bottoni Avanti/Indietro
         // restano il footer più esterno, come in ogni wizard/dialog standard di Windows.
+        var mnuFile = new ToolStripMenuItem("File");
+        _mnuNuovaEstrazione.ShortcutKeys = Keys.Control | Keys.N;
+        _mnuNuovaEstrazione.Click += (_, _) => NuovaEstrazione();
+        mnuFile.DropDownItems.Add(_mnuNuovaEstrazione);
+
+        var mnuAiuto = new ToolStripMenuItem("Aiuto");
+        var mnuGuida = new ToolStripMenuItem("Guida") { ShortcutKeys = Keys.F1 };
+        mnuGuida.Click += (_, _) => new GuidaForm().ShowDialog(this);
+        mnuAiuto.DropDownItems.Add(mnuGuida);
+
+        _menu.Items.Add(mnuFile);
+        _menu.Items.Add(mnuAiuto);
+        MainMenuStrip = _menu;
+
         Controls.Add(_faseContainer);
         Controls.Add(statusPanel);
         Controls.Add(navContainer);
         Controls.Add(headerPanel);
+        Controls.Add(_menu);
 
         DragEnter += (_, e) =>
             e.Effect = e.Data?.GetDataPresent(DataFormats.FileDrop) == true
@@ -236,6 +252,30 @@ public partial class Form1 : Form
 
     private void AggiornaStatoAvanti() => _btnAvanti.Enabled = AvantiConsentito(_faseAttuale);
 
+    /// <summary>Azzera distinta/raw/verifica (fasi 2-5) per ripartire con una nuova distinta;
+    /// DB indicizzato e cartella di lavoro (fase 1) restano quelli già caricati, non serve
+    /// rifare lo scan del disco per ogni estrazione.</summary>
+    private void NuovaEstrazione()
+    {
+        if (_dbPath is null || _cartellaLavoro is null)
+        {
+            MessageBox.Show(this, "Carica prima il database in fase 1.", "Nuova estrazione",
+                MessageBoxButtons.OK, MessageBoxIcon.Information);
+            return;
+        }
+
+        _percorsoInputCorrente = null;
+        _righeCorrenti = null;
+        _ultimaCartellaRaw = null;
+        _ultimaVerifica = null;
+        _gridImport.Rows.Clear();
+        _gridRaw.Rows.Clear();
+        _lstAnteprimaAsm.Items.Clear();
+        ImpostaStatoImport("", Color.Black);
+
+        VaiAllaFase(1);
+    }
+
     private Panel BuildFaseDatabase()
     {
         var contenuto = new TableLayoutPanel
@@ -516,27 +556,6 @@ public partial class Form1 : Form
         };
         top.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100));
 
-        var lblIstruzioniCompletezza = new Label
-        {
-            Dock = DockStyle.Top,
-            AutoSize = true,
-            ForeColor = SystemColors.GrayText,
-            Margin = new Padding(0, 0, 0, 8),
-            Text = "Per ogni assieme della distinta, verifica se tutti i suoi componenti "
-                 + "(ricorsivamente fino ai PRT) sono nell'indice. Nota: la scansione dei .asm "
-                 + "è euristica, quindi qualche falso 'incompleto' è possibile.",
-        };
-        top.Controls.Add(lblIstruzioniCompletezza);
-
-        // Primario: è l'azione principale di questa fase, non una scelta secondaria — prima
-        // era uno stile grigio che si confondeva con lo sfondo.
-        _btnCompletezza.Text = "Verifica completezza assiemi";
-        _btnCompletezza.Margin = new Padding(0, 0, 0, 12);
-        UiStile.Primario(_btnCompletezza);
-        UiStile.Arrotonda(_btnCompletezza);
-        _btnCompletezza.Click += (_, _) => VerificaCompletezzaAssiemi();
-        top.Controls.Add(_btnCompletezza);
-
         var lblAnteprimaAsm = new Label
         {
             AutoSize = true,
@@ -743,6 +762,64 @@ public partial class Form1 : Form
         return codiciNoti;
     }
 
+    /// <summary>Tutti i file prt/asm dell'indice raggruppati per codice, tenendo per ogni
+    /// cartella la sola versione più alta. A differenza di <see cref="CaricaCodiciNoti"/> non
+    /// sceglie un vincitore fra le cartelle: lo stesso codice può esistere in più punti della
+    /// share (copie in cartelle di studio, di lavoro, temporanee) con contenuto diverso, e
+    /// quale sia quello giusto dipende da chi lo referenzia - vedi
+    /// <see cref="ScegliPerCartella"/>.</summary>
+    private static Dictionary<string, List<(string Tipo, string Percorso, int Versione, string Data)>> CaricaCandidati(string dbPath)
+    {
+        var candidati = new Dictionary<string, List<(string Tipo, string Percorso, int Versione, string Data)>>(StringComparer.OrdinalIgnoreCase);
+        using var connection = new SqliteConnection($"Data Source={dbPath};Mode=ReadOnly");
+        connection.Open();
+        using var command = connection.CreateCommand();
+        command.CommandText = "SELECT codice, tipo_file, percorso_completo, versione, data_modifica FROM files "
+            + "WHERE LOWER(tipo_file) IN ('prt', 'asm')";
+        using var reader = command.ExecuteReader();
+        while (reader.Read())
+        {
+            string codice = reader.GetString(0);
+            string tipo = reader.GetString(1).ToLowerInvariant();
+            string percorso = reader.GetString(2);
+            int versione = reader.GetInt32(3);
+            var lista = candidati.TryGetValue(codice, out var l) ? l : candidati[codice] = new();
+
+            string cartella = Path.GetDirectoryName(percorso) ?? "";
+            int esistente = lista.FindIndex(x => x.Tipo == tipo
+                && string.Equals(Path.GetDirectoryName(x.Percorso), cartella, StringComparison.OrdinalIgnoreCase));
+            if (esistente < 0)
+                lista.Add((tipo, percorso, versione, reader.GetString(4)));
+            else if (versione > lista[esistente].Versione)
+                lista[esistente] = (tipo, percorso, versione, reader.GetString(4));
+        }
+        return candidati;
+    }
+
+    /// <summary>Fra più copie dello stesso codice sulla share sceglie quella che userebbe Creo:
+    /// prima cerca nella cartella dell'assieme che la referenzia (Creo risolve i componenti
+    /// partendo da lì), poi ripiega sulla versione più alta e, a parità, sulla più recente.
+    /// Senza questo criterio si finisce per copiare in "raw" una copia omonima ma di un altro
+    /// modello - Creo la carica e i vincoli di accoppiamento non si risolvono, quindi l'assieme
+    /// non si apre affatto.</summary>
+    private static List<(string Tipo, string Percorso)> ScegliPerCartella(
+        List<(string Tipo, string Percorso, int Versione, string Data)> candidati, string? cartellaPadre)
+    {
+        return candidati
+            .GroupBy(c => c.Tipo)
+            .Select(perTipo =>
+            {
+                var scelto = perTipo
+                    .OrderByDescending(c => cartellaPadre is not null
+                        && string.Equals(Path.GetDirectoryName(c.Percorso), cartellaPadre, StringComparison.OrdinalIgnoreCase))
+                    .ThenByDescending(c => c.Versione)
+                    .ThenByDescending(c => c.Data)
+                    .First();
+                return (scelto.Tipo, scelto.Percorso);
+            })
+            .ToList();
+    }
+
     /// <summary>Codici referenziati direttamente in un assieme: prova prima il parser esatto
     /// dei record binari (<see cref="AsmRecordReader"/>, vedi docs/formato-asm-record.md), che
     /// non ha i falsi positivi/negativi noti dell'euristica testuale (docs/formato-asm.md); se
@@ -763,6 +840,50 @@ public partial class Form1 : Form
         }
     }
 
+    /// <summary>Componenti soppressi di un assieme (<see cref="AsmRecordReader.EstraiCodiciSoppressi"/>):
+    /// non sono nella distinta, ma senza il loro file Creo non apre l'assieme. Vuoto per i file
+    /// che il parser esatto non sa leggere: lì si usa l'euristica testuale, che i piazzamenti li
+    /// riconosce già per conto suo (<see cref="AssemblyComponentScanner"/>).</summary>
+    private static IEnumerable<string> CodiciSoppressi(string percorsoAsm)
+    {
+        try
+        {
+            return AsmRecordReader.EstraiCodiciSoppressi(percorsoAsm);
+        }
+        catch (InvalidDataException)
+        {
+            return Array.Empty<string>();
+        }
+    }
+
+    /// <summary>Cartella della share da cui proviene un file già copiato in "raw": fra le copie
+    /// omonime indicizzate è quella di pari dimensione. Serve per gli assiemi di partenza, che
+    /// arrivano dalla fase precedente senza portarsi dietro l'origine. Null se non si riesce a
+    /// stabilirla (il file non è nell'indice, o la share non risponde): in quel caso la scelta
+    /// del componente ricade sul criterio generale.</summary>
+    private static string? CartellaDiOrigine(string fileInRaw,
+        Dictionary<string, List<(string Tipo, string Percorso, int Versione, string Data)>> candidati)
+    {
+        string nome = Path.GetFileName(fileInRaw);
+        if (!candidati.TryGetValue(nome.Split('.')[0], out var perCodice))
+            return null;
+        try
+        {
+            long dimensione = new FileInfo(fileInRaw).Length;
+            foreach (var c in perCodice.Where(c => string.Equals(Path.GetFileName(c.Percorso), nome, StringComparison.OrdinalIgnoreCase)))
+            {
+                var info = new FileInfo(c.Percorso);
+                if (info.Exists && info.Length == dimensione)
+                    return Path.GetDirectoryName(c.Percorso);
+            }
+        }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+        {
+            // share non raggiungibile: si prosegue col criterio generale
+        }
+        return null;
+    }
+
     /// <summary>Risolve ricorsivamente l'albero dei componenti a partire dai file .asm indicati
     /// (già copiati in "raw"): per ogni assieme legge i codici referenziati al suo interno, li
     /// cerca nell'indice, copia in "raw" quelli trovati e, se sono a loro volta assiemi, li
@@ -771,42 +892,93 @@ public partial class Form1 : Form
     private (List<(string Codice, string Tipo, string Percorso)> Trovati, List<string> NonTrovati) RisolviAlberoComponenti(
         IEnumerable<string> asmIniziali, IProgress<(int Fatti, int Totale)>? progress = null)
     {
-        var daScansionare = new Queue<string>(asmIniziali);
-        var codiciIniziali = daScansionare.Select(f => Path.GetFileName(f).Split('.')[0]);
+        // Ogni assieme viaggia con la cartella della share da cui proviene: e' li' che Creo
+        // cerca per primi i suoi componenti, quindi e' li' che li cerchiamo anche noi.
+        // "Esterno" marca i rami raggiunti da un riferimento esterno invece che dalla distinta:
+        // servono su disco ma non sono componenti, quindi i loro codici mancanti non vanno fra i
+        // "non trovati" (sarebbero falsi allarmi, come per i soppressi).
+        var daScansionare = new Queue<(string File, string? CartellaOrigine, bool Esterno)>(
+            asmIniziali.Select(f => (f, (string?)null, false)));
+        var codiciIniziali = asmIniziali.Select(f => Path.GetFileName(f).Split('.')[0]).ToList();
         var codiciVisti = new HashSet<string>(
             codiciIniziali.Concat(codiciIniziali.Select(AssemblyComponentScanner.CodiceRadice)),
             StringComparer.OrdinalIgnoreCase);
 
+        var codiciSoppressiVisti = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var codiciEsterniVisti = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
         var trovati = new List<(string Codice, string Tipo, string Percorso)>();
         var codiciNonTrovati = new List<string>();
         if (daScansionare.Count == 0 || _dbPath is null)
             return (trovati, codiciNonTrovati);
 
         var codiciNoti = CaricaCodiciNoti(_dbPath);
+        var candidati = CaricaCandidati(_dbPath);
 
         int processati = 0;
         while (daScansionare.Count > 0)
         {
-            var asm = daScansionare.Dequeue();
+            var (asm, cartellaOrigine, esterno) = daScansionare.Dequeue();
+            cartellaOrigine ??= CartellaDiOrigine(asm, candidati);
             processati++;
             foreach (var codice in EstraiCodiciReferenziati(asm, codiciNoti.Keys))
             {
                 if (!codiciVisti.Add(codice))
                     continue;
 
-                if (!codiciNoti.TryGetValue(codice, out var componenti))
+                if (!candidati.TryGetValue(codice, out var perCodice))
                 {
-                    codiciNonTrovati.Add(codice);
+                    if (!esterno)
+                        codiciNonTrovati.Add(codice);
                     continue;
                 }
 
-                foreach (var (tipo, percorso) in componenti)
+                foreach (var (tipo, percorso) in ScegliPerCartella(perCodice, cartellaOrigine))
                 {
                     CopiaFileTrovati(new[] { percorso }, _ultimaCartellaRaw!);
                     trovati.Add((codice, tipo, percorso));
                     if (tipo == "asm")
                     {
-                        daScansionare.Enqueue(Path.Combine(_ultimaCartellaRaw!, Path.GetFileName(percorso)));
+                        daScansionare.Enqueue((Path.Combine(_ultimaCartellaRaw!, Path.GetFileName(percorso)),
+                            Path.GetDirectoryName(percorso), esterno));
+                    }
+                }
+            }
+
+            // I componenti soppressi non compaiono nella BOM, ma Creo ne vuole comunque il file
+            // per aprire l'assieme: si copiano senza entrare nel conteggio dei "non trovati"
+            // (non essendo componenti della distinta, segnalarli come mancanti sarebbe un falso
+            // allarme) e senza ricorrervi dentro.
+            foreach (var codice in CodiciSoppressi(asm))
+            {
+                if (!codiciSoppressiVisti.Add(codice) || codiciVisti.Contains(codice))
+                    continue;
+                if (!candidati.TryGetValue(codice, out var perCodice))
+                    continue;
+                foreach (var (tipo, percorso) in ScegliPerCartella(perCodice, cartellaOrigine))
+                {
+                    CopiaFileTrovati(new[] { percorso }, _ultimaCartellaRaw!);
+                    trovati.Add((codice, tipo, percorso));
+                }
+            }
+
+            // I riferimenti esterni (assembly feature, datum copiati verso un altro modello) non
+            // sono componenti e non compaiono fra i piazzamenti, ma Creo carica il modello citato
+            // per aprire l'assieme - e con lui i *suoi* componenti, quindi qui, a differenza dei
+            // soppressi, si ricorre dentro. Vedi docs/formato-asm-record.md §7.5.
+            foreach (var codice in AsmRecordReader.EstraiCodiciRiferimentiEsterni(asm))
+            {
+                if (!codiciEsterniVisti.Add(codice) || codiciVisti.Contains(codice))
+                    continue;
+                if (!candidati.TryGetValue(codice, out var perCodice))
+                    continue;
+                foreach (var (tipo, percorso) in ScegliPerCartella(perCodice, cartellaOrigine))
+                {
+                    CopiaFileTrovati(new[] { percorso }, _ultimaCartellaRaw!);
+                    trovati.Add((codice, tipo, percorso));
+                    if (tipo == "asm")
+                    {
+                        daScansionare.Enqueue((Path.Combine(_ultimaCartellaRaw!, Path.GetFileName(percorso)),
+                            Path.GetDirectoryName(percorso), true));
                     }
                 }
             }
@@ -854,102 +1026,6 @@ public partial class Form1 : Form
         dialog.ShowDialog(this);
     }
 
-    /// <summary>Per ogni assieme della distinta, verifica ricorsivamente (leggendo i .asm dai
-    /// percorsi originali sulla share) se tutti i componenti fino ai PRT sono nell'indice.
-    /// I risultati di ogni file/codice vengono in cache e condivisi tra gli assiemi controllati
-    /// nella stessa passata, per non rileggere più volte gli stessi sotto-componenti.</summary>
-    private void VerificaCompletezzaAssiemi()
-    {
-        if (_righeCorrenti is null)
-            return;
-        if (_dbPath is null)
-        {
-            ImpostaStatoImport("Nessun database caricato: impossibile verificare la completezza.", Color.DarkRed);
-            return;
-        }
-
-        var codiciNoti = CaricaCodiciNoti(_dbPath);
-        var cacheCodiciFile = new Dictionary<string, HashSet<string>>();
-
-        List<(string Tipo, string Percorso)> CercaComponenti(string codice) =>
-            codiciNoti.TryGetValue(codice, out var trovati) ? trovati : new List<(string, string)>();
-
-        bool AssiemeCompleto(string percorsoAsmIniziale)
-        {
-            var daVisitare = new Queue<string>();
-            daVisitare.Enqueue(percorsoAsmIniziale);
-            var fileVisitati = new HashSet<string> { percorsoAsmIniziale };
-            var codiceIniziale = Path.GetFileName(percorsoAsmIniziale).Split('.')[0];
-            var codiciVisti = new HashSet<string>
-            {
-                codiceIniziale,
-                AssemblyComponentScanner.CodiceRadice(codiceIniziale),
-            };
-
-            while (daVisitare.Count > 0)
-            {
-                var file = daVisitare.Dequeue();
-                if (!cacheCodiciFile.TryGetValue(file, out var codiciReferenziati))
-                {
-                    try
-                    {
-                        codiciReferenziati = EstraiCodiciReferenziati(file, codiciNoti.Keys).ToHashSet(StringComparer.OrdinalIgnoreCase);
-                    }
-                    catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
-                    {
-                        return false; // file irraggiungibile (share offline) -> non verificabile, per prudenza "incompleto"
-                    }
-                    cacheCodiciFile[file] = codiciReferenziati;
-                }
-
-                foreach (var codice in codiciReferenziati)
-                {
-                    if (!codiciVisti.Add(codice))
-                        continue;
-
-                    var componenti = CercaComponenti(codice);
-                    if (componenti.Count == 0)
-                        return false;
-
-                    foreach (var (tipo, percorso) in componenti)
-                    {
-                        if (tipo == "asm" && fileVisitati.Add(percorso))
-                        {
-                            daVisitare.Enqueue(percorso);
-                        }
-                    }
-                }
-            }
-            return true;
-        }
-
-        // L'assieme generale è già una riga di _righeCorrenti (vedi DistintaBaseImporter), quindi
-        // la sua completezza viene verificata insieme a quella di tutti gli altri componenti.
-        var righeReport = new List<(string Componente, string Descrizione, bool? Completo)>();
-        foreach (var (componente, descrizione) in _righeCorrenti)
-        {
-            var componenti = CercaComponenti(componente);
-            string? percorsoAsm = componenti.Where(c => c.Tipo == "asm").Select(c => c.Percorso).FirstOrDefault();
-
-            bool? completo = componenti.Count == 0 ? null
-                : percorsoAsm is null ? true // solo prt trovato: nessuna sotto-struttura da verificare
-                : AssiemeCompleto(percorsoAsm);
-
-            righeReport.Add((componente, descrizione, completo));
-        }
-
-        int completi = righeReport.Count(r => r.Completo == true);
-        int incompleti = righeReport.Count(r => r.Completo == false);
-        int nonTrovati = righeReport.Count(r => r.Completo is null);
-        ImpostaStatoImport(
-            $"Completezza assiemi: {completi} completi, {incompleti} incompleti, "
-                + $"{nonTrovati} non trovati nell'indice.",
-            Color.DarkGreen);
-
-        using var dialogCompletezza = new ReportCompletezzaForm(righeReport);
-        dialogCompletezza.ShowDialog(this);
-    }
-
     /// <summary>Copia i file trovati nella cartella "raw" indicata, creandola se necessario.
     /// Ritorna il numero di file copiati con successo. Parallelizzata (grado limitato): il
     /// collo di bottiglia è la latenza di rete verso la share, non la CPU, quindi poche copie

PrepStep/GuidaForm.cs

@@ -0,0 +1,91 @@
+namespace PrepStep;
+
+/// <summary>Guida interattiva richiamabile da "Aiuto ▸ Guida" (F1): sintesi delle 5 fasi del
+/// wizard, per chi apre l'app senza aver letto i docs. Il dettaglio completo (formato .asm,
+/// schema DB, ecc.) resta solo in docs/architettura.md e affini, per non duplicarlo qui.</summary>
+public class GuidaForm : Form
+{
+    private static readonly (string Titolo, string Testo)[] Sezioni =
+    {
+        ("Panoramica", """
+            Cevolani StepPrep prepara i file CAD Pro-ENGINEER/Creo da passare a Creo
+            Distributed Batch per l'esportazione STEP: indicizza i file di una share di
+            rete e guida attraverso 5 fasi, una alla volta, con "Avanti"/"Indietro".
+
+            "File ▸ Nuova estrazione" (Ctrl+N) azzera distinta/raw/verifica per
+            ripartire con una nuova distinta base, senza dover ricaricare il database.
+            """),
+        ("1. Database", """
+            Carica o aggiorna l'indice "cad_index.db" a partire dalle cartelle di primo
+            livello del disco/share (radice di default X:\). Qui si sceglie anche la
+            cartella di lavoro, dove finiscono CSV, "raw" e "step".
+            """),
+        ("2. Importa Distinta Base", """
+            Converte il file della distinta (trascinabile nella finestra) in un CSV
+            componente;descrizione nella cartella di lavoro. Se il file segue la
+            convenzione del gestionale, aggiunge anche l'assieme generale come riga.
+            """),
+        ("3. Crea cartella raw", """
+            Cerca nell'indice i file CAD dei componenti del CSV e li copia nella
+            sottocartella "raw" della cartella di lavoro.
+            """),
+        ("4. Trova componenti referenziati", """
+            Legge i file .asm già in "raw" per risolvere ricorsivamente sotto-assiemi e
+            parti citate, copiando anche quelli in "raw": componenti soppressi (non in
+            distinta ma necessari per aprire l'assieme) e riferimenti esterni (assembly
+            feature, datum copiati) inclusi.
+            """),
+        ("5. Verifica completezza", """
+            Mostra i file .asm della distinta già in "raw", trascinabili su Creo per
+            l'esportazione STEP (passo manuale, fuori da quest'app). "Verifica
+            completezza assiemi" controlla che tutti i sotto-componenti risultino
+            presenti nell'indice.
+            """),
+    };
+
+    public GuidaForm()
+    {
+        Text = "Guida";
+        ClientSize = new Size(640, 420);
+        MinimumSize = new Size(480, 320);
+        StartPosition = FormStartPosition.CenterParent;
+        Font = new Font("Segoe UI", 9.5f);
+
+        var lista = new ListBox
+        {
+            Dock = DockStyle.Left,
+            Width = 200,
+            IntegralHeight = false,
+            BorderStyle = BorderStyle.None,
+        };
+        foreach (var (titolo, _) in Sezioni)
+            lista.Items.Add(titolo);
+
+        var testo = new RichTextBox
+        {
+            Dock = DockStyle.Fill,
+            ReadOnly = true,
+            BorderStyle = BorderStyle.None,
+            BackColor = Color.White,
+            Font = new Font(Font.FontFamily, 10f),
+        };
+
+        lista.SelectedIndexChanged += (_, _) =>
+        {
+            if (lista.SelectedIndex >= 0)
+                testo.Text = Sezioni[lista.SelectedIndex].Testo.Trim();
+        };
+
+        var btnChiudi = new Button { Text = "Chiudi", Dock = DockStyle.Bottom, Height = 34 };
+        UiStile.Secondario(btnChiudi);
+        btnChiudi.Click += (_, _) => Close();
+
+        var contenuto = new Panel { Dock = DockStyle.Fill, Padding = new Padding(16) };
+        contenuto.Controls.Add(testo);
+        Controls.Add(contenuto);
+        Controls.Add(lista);
+        Controls.Add(btnChiudi);
+
+        lista.SelectedIndex = 0;
+    }
+}

PrepStep/Indexer.cs

@@ -40,13 +40,22 @@ public static class Indexer
         CREATE INDEX IF NOT EXISTS idx_files_tipo ON files(tipo_file);
         CREATE INDEX IF NOT EXISTS idx_files_cartella ON files(cartella_radice);
 
-        CREATE VIEW IF NOT EXISTS files_ultima_versione AS
+        -- DROP+CREATE invece di "IF NOT EXISTS": la vista e' ricalcolata a ogni avvio di scan,
+        -- cosi' un DB gia' esistente prende la definizione corrente senza reindicizzare.
+        DROP VIEW IF EXISTS files_ultima_versione;
+        CREATE VIEW files_ultima_versione AS
         SELECT percorso_completo, percorso_relativo, nome_file, cartella_radice, famiglia,
                codice, tipo_file, versione, dimensione_byte, data_modifica, scansionato_il
         FROM (
             SELECT f.*, ROW_NUMBER() OVER (
                 PARTITION BY cartella_radice, codice, tipo_file
-                ORDER BY versione DESC
+                -- A parita' di versione (stesso codice in due sottocartelle della stessa
+                -- radice, es. una copia vecchia in una cartella di lavoro) vince il file
+                -- modificato piu' di recente: senza questo criterio il pareggio e' rotto in
+                -- modo arbitrario e puo' vincere la copia obsoleta, nascondendo del tutto
+                -- quella buona. Il file copiato in "raw" sarebbe allora un modello diverso da
+                -- quello che l'assieme si aspetta, e Creo non riesce ad aprirlo.
+                ORDER BY versione DESC, data_modifica DESC, percorso_completo
             ) AS rn
             FROM files f
         ) WHERE rn = 1;

PrepStep/ProgressForm.cs

@@ -2,23 +2,15 @@ namespace PrepStep;
 
 public sealed class ProgressForm : Form
 {
-    private readonly Label _lblTitolo = new();
     private readonly Label _lblCartella = new();
-    private readonly Panel _barraTraccia = new();
-    private readonly Panel _barraRiempimento = new();
-    private readonly Label _lblPercentuale = new();
+    private readonly ProgressBar _bar = new();
     private readonly Label _lblConteggio = new();
     private readonly Label _lblDettaglio = new();
     private readonly Label _lblEta = new();
     private readonly Button _btnAnnulla = new();
-    private readonly Panel _separatore = new();
-    private readonly Panel _piePagina = new();
     private readonly ToolTip _tipCartella = new();
 
-    private const int Margine = 24;
-    // SystemColors.GrayText (~3.9:1 su bianco) è sotto la soglia WCAG AA 4.5:1 per testo
-    // normale: usiamo un grigio più scuro, leggibile ma comunque secondario.
-    private static readonly Color GrigioTesto = Color.FromArgb(90, 90, 90);
+    private const int Margine = 16;
 
     public event EventHandler? Annullato;
 
@@ -30,84 +22,42 @@ public sealed class ProgressForm : Form
         MinimizeBox = false;
         MaximizeBox = false;
         ControlBox = false;
-        BackColor = Color.White;
-        ClientSize = new Size(480, 270);
-
-        _lblTitolo.Text = "Aggiornamento indice in corso...";
-        _lblTitolo.Location = new Point(Margine, 22);
-        _lblTitolo.AutoSize = true;
-        _lblTitolo.Font = new Font(Font.FontFamily, 11f, FontStyle.Bold);
+        ClientSize = new Size(420, 190);
 
         _lblCartella.Text = "Preparazione...";
-        _lblCartella.Location = new Point(Margine, 52);
+        _lblCartella.Location = new Point(Margine, Margine);
         // AutoSize=false + AutoEllipsis: un percorso lungo (share di rete) va troncato con "..."
-        // invece di sforare il bordo del dialog, che è FixedDialog e non si può allargare.
-        // Il testo completo resta disponibile nel tooltip (stesso pattern di Form1._lblImportStatus).
+        // invece di sforare il bordo del dialog, che è FixedDialog e non si può allargare. Il
+        // testo completo resta disponibile nel tooltip.
         _lblCartella.AutoSize = false;
         _lblCartella.AutoEllipsis = true;
         _lblCartella.Size = new Size(ClientSize.Width - Margine * 2, 20);
-        _lblCartella.ForeColor = GrigioTesto;
 
-        // Barra piatta disegnata a mano (traccia grigia + riempimento) invece della ProgressBar
-        // nativa: quella di Windows è verde e in stile "a blocchi", stona con il blu del resto
-        // dell'app (UiStile.Primario). Larghezza = margine destro reale meno lo spazio per
-        // "100%" in grassetto, così barra+percentuale rispettano lo stesso margine destro del
-        // resto del contenuto (prima finivano ~25px prima, sbilanciate rispetto al margine
-        // sinistro di 24px).
-        _barraTraccia.Location = new Point(Margine, 90);
-        _barraTraccia.Size = new Size(ClientSize.Width - Margine * 2 - 46, 10);
-        _barraTraccia.BackColor = Color.FromArgb(230, 230, 230);
-        _barraRiempimento.Location = Point.Empty;
-        _barraRiempimento.Size = new Size(0, _barraTraccia.Height);
-        _barraRiempimento.BackColor = UiStile.ColorePrimario;
-        _barraTraccia.Controls.Add(_barraRiempimento);
+        _bar.Location = new Point(Margine, 40);
+        _bar.Size = new Size(ClientSize.Width - Margine * 2, 24);
+        _bar.Minimum = 0;
+        _bar.Maximum = 100;
 
-        _lblPercentuale.AutoSize = true;
-        _lblPercentuale.Font = new Font(Font, FontStyle.Bold);
-        _lblPercentuale.TextAlign = ContentAlignment.MiddleRight;
-
-        _lblConteggio.Location = new Point(Margine, 122);
+        _lblConteggio.Location = new Point(Margine, 72);
         _lblConteggio.AutoSize = true;
 
-        _lblDettaglio.Location = new Point(Margine, 146);
+        _lblDettaglio.Location = new Point(Margine, 96);
         _lblDettaglio.AutoSize = true;
-        _lblDettaglio.ForeColor = GrigioTesto;
 
-        _lblEta.Location = new Point(Margine, 174);
+        _lblEta.Location = new Point(Margine, 120);
         _lblEta.AutoSize = true;
 
-        // Footer separato dal contenuto (linea + sfondo leggermente diverso) invece del
-        // bottone appiccicato al bordo inferiore del dialog: ancorato in basso, quindi la
-        // spaziatura sopra/sotto resta corretta anche se la ClientSize cambia. Altezza footer
-        // 60px e ClientSize 270 scelti per lasciare sotto l'ultima riga (eta, Bottom≈189) lo
-        // stesso margine (~20px) usato sopra il titolo, invece dei ~7px sbilanciati di prima.
-        _separatore.BackColor = Color.FromArgb(230, 230, 230);
-        _separatore.Size = new Size(ClientSize.Width, 1);
-        _separatore.Location = new Point(0, ClientSize.Height - 60);
-        _separatore.Anchor = AnchorStyles.Left | AnchorStyles.Right | AnchorStyles.Bottom;
-
-        _piePagina.BackColor = Color.FromArgb(247, 247, 248);
-        _piePagina.Size = new Size(ClientSize.Width, 59);
-        _piePagina.Location = new Point(0, ClientSize.Height - 59);
-        _piePagina.Anchor = AnchorStyles.Left | AnchorStyles.Right | AnchorStyles.Bottom;
-
         _btnAnnulla.Text = "Annulla";
-        UiStile.Secondario(_btnAnnulla);
-        UiStile.Arrotonda(_btnAnnulla);
+        _btnAnnulla.Size = new Size(90, 28);
         _btnAnnulla.Click += (_, e) => Annullato?.Invoke(this, e);
-        _piePagina.Controls.Add(_btnAnnulla);
 
         Controls.AddRange(new Control[]
         {
-            _lblTitolo, _lblCartella, _barraTraccia, _lblPercentuale,
-            _lblConteggio, _lblDettaglio, _lblEta, _separatore, _piePagina
+            _lblCartella, _bar, _lblConteggio, _lblDettaglio, _lblEta, _btnAnnulla
         });
 
-        // Posizionato dopo l'aggiunta ai Controls: con AutoSize il Width vero si conosce
-        // solo a layout avvenuto, non subito dopo la creazione del bottone.
-        _btnAnnulla.Location = new Point(_piePagina.Width - Margine - _btnAnnulla.Width,
-            (_piePagina.Height - _btnAnnulla.Height) / 2);
-        _btnAnnulla.Anchor = AnchorStyles.Right | AnchorStyles.Top;
+        _btnAnnulla.Location = new Point(
+            ClientSize.Width - Margine - _btnAnnulla.Width, ClientSize.Height - Margine - _btnAnnulla.Height);
     }
 
     public void Aggiorna(ScanProgress p)
@@ -115,24 +65,9 @@ public sealed class ProgressForm : Form
         _lblCartella.Text = $"Scansione: {p.Cartella}";
         _tipCartella.SetToolTip(_lblCartella, _lblCartella.Text);
 
-        if (p.PrevistiTotali > 0)
-        {
-            double frazione = Math.Min(1.0, (double)p.FattiTotali / p.PrevistiTotali);
-            _barraRiempimento.Width = (int)(frazione * _barraTraccia.Width);
-            _lblPercentuale.Text = $"{frazione * 100:0}%";
-        }
-        else
-        {
-            // ponytail: prima del conteggio totale (poco probabile: richiede la scansione
-            // precedente salvata nel DB) la barra resta vuota invece di un'animazione
-            // indeterminata — se serve, aggiungere un Timer che pulsa _barraRiempimento.
-            _barraRiempimento.Width = 0;
-            _lblPercentuale.Text = "";
-        }
-        // Riallineato al margine destro reale ogni volta: AutoSize aggiorna Width non appena
-        // Text cambia, quindi la Location va ricalcolata qui (non solo una volta nel costruttore).
-        _lblPercentuale.Location = new Point(
-            ClientSize.Width - Margine - _lblPercentuale.Width, _barraTraccia.Top - 3);
+        _bar.Value = p.PrevistiTotali > 0
+            ? (int)Math.Clamp(100.0 * p.FattiTotali / p.PrevistiTotali, 0, 100)
+            : 0;
 
         _lblConteggio.Text = p.PrevistiTotali > 0
             ? $"{p.FattiTotali:N0} / ~{p.PrevistiTotali:N0} file"

PrepStep/PrtMancantiForm.cs

@@ -20,6 +20,7 @@ public class PrtMancantiForm : Form
         {
             Dock = DockStyle.Top,
             AutoSize = true,
+            MaximumSize = new Size(ClientSize.Width - 24, 0),
             Padding = new Padding(12, 8, 12, 8),
             Text = $"Copiati in \"{cartellaRaw}\": {numPrt} PRT e {numAsm} sotto-assiemi trovati nell'indice."
                 + (codiciNonTrovati.Count > 0
@@ -70,5 +71,7 @@ public class PrtMancantiForm : Form
         Controls.Add(grid);
         Controls.Add(lblInfo);
         Controls.Add(btnApriCartella);
+
+        Resize += (_, _) => lblInfo.MaximumSize = new Size(ClientSize.Width - 24, 0);
     }
 }

PrepStep/ReportCompletezzaForm.cs

@@ -1,61 +0,0 @@
-namespace PrepStep;
-
-/// <summary>Mostra, per ogni assieme della distinta base, se tutti i suoi componenti
-/// (ricorsivamente fino ai PRT) sono presenti nell'indice (v) o mancano (x).</summary>
-public class ReportCompletezzaForm : Form
-{
-    public ReportCompletezzaForm(List<(string Componente, string Descrizione, bool? Completo)> righe)
-    {
-        int completi = righe.Count(r => r.Completo == true);
-        int incompleti = righe.Count(r => r.Completo == false);
-        int nonTrovati = righe.Count(r => r.Completo is null);
-
-        Text = "Completezza assiemi";
-        ClientSize = new Size(720, 440);
-        StartPosition = FormStartPosition.CenterParent;
-        Font = new Font("Segoe UI", 9.5f);
-
-        var lblInfo = new Label
-        {
-            Dock = DockStyle.Top,
-            AutoSize = true,
-            Padding = new Padding(12, 8, 12, 8),
-            Text = $"{completi} completi, {incompleti} incompleti, {nonTrovati} non trovati nell'indice "
-                 + $"su {righe.Count} componenti. Nota: la scansione dei .asm è euristica, qualche "
-                 + "falso 'incompleto' è possibile.",
-        };
-
-        var grid = new DataGridView
-        {
-            Dock = DockStyle.Fill,
-            ReadOnly = true,
-            AllowUserToAddRows = false,
-            AllowUserToDeleteRows = false,
-            RowHeadersVisible = false,
-            SelectionMode = DataGridViewSelectionMode.FullRowSelect,
-            AutoSizeColumnsMode = DataGridViewAutoSizeColumnsMode.Fill,
-        };
-        grid.Columns.Add("componente", "Componente");
-        grid.Columns.Add("descrizione", "Descrizione");
-        grid.Columns.Add("completo", "Completo");
-        grid.Columns["componente"]!.FillWeight = 20;
-        grid.Columns["descrizione"]!.FillWeight = 55;
-        grid.Columns["completo"]!.FillWeight = 25;
-
-        foreach (var (componente, descrizione, completo) in righe.OrderBy(r => r.Completo).ThenBy(r => r.Componente))
-        {
-            string testo = completo switch { true => "✓", false => "✗", null => "?" };
-            int i = grid.Rows.Add(componente, descrizione, testo);
-            grid.Rows[i].DefaultCellStyle.ForeColor = completo switch
-            {
-                true => Color.DarkGreen,
-                false => Color.DarkRed,
-                null => Color.Gray,
-            };
-            grid.Rows[i].Cells["completo"].Style.Alignment = DataGridViewContentAlignment.MiddleCenter;
-        }
-
-        Controls.Add(grid);
-        Controls.Add(lblInfo);
-    }
-}

PrepStep/UiStile.cs

@@ -8,7 +8,8 @@ namespace PrepStep;
 internal static class UiStile
 {
     /// <summary>Blu del bottone primario, esposto qui per essere riusato anche da elementi
-    /// non-bottone (es. la barra di avanzamento di ProgressForm) invece di duplicare l'RGB.</summary>
+    /// non-bottone (es. il colore di selezione delle griglie in Form1) invece di duplicare
+    /// l'RGB.</summary>
     public static readonly Color ColorePrimario = Color.FromArgb(0, 99, 177);
 
     // AutoSize+Padding invece di una Size fissa in pixel: il bottone si dimensiona sempre

docs/architettura.md

@@ -4,7 +4,8 @@ Panoramica di tutti i file sorgente e di come collaborano. `PrepStep` è il nome
 tecnico del progetto (cartella, namespace, csproj, eseguibile `PrepStep.exe`);
 **Cevolani StepPrep** è il nome mostrato all'utente finale (titolo finestra, icona,
 versione — vedi `<Version>`/`<Product>` in `PrepStep.csproj`). Per il "come si usa" vedi il `README.md` in root; per il
-formato binario `.asm` vedi `docs/formato-asm.md`; per la parallelizzazione della
+formato binario `.asm` vedi `docs/formato-asm.md` (euristica testuale) e
+`docs/formato-asm-record.md` (parser esatto dei record); per la parallelizzazione della
 copia in `raw/` vedi `docs/copia-raw-parallela.md`.
 
 ## Vista d'insieme
@@ -24,6 +25,56 @@ Distinta (.xls/.xml)  →  CSV (componente;descrizione)  →  raw/ (CAD copiati
                             drag&drop .asm su Creo → Distributed Batch → step/ (esportazione manuale)
 ```
 
+## Il processo, dall'inizio alla fine
+
+Le 5 fasi sono una pipeline: ognuna consuma quello che ha prodotto la precedente, e il
+bottone "Avanti" si sblocca solo quando il risultato c'è (`AvantiConsentito`). Sotto, cosa
+entra e cosa esce da ciascuna — il dettaglio dei metodi è nella tabella della sezione
+successiva.
+
+**1. Indice della share → `cad_index.db`.** `Indexer.ScanAsync` cammina tutte le cartelle di
+primo livello sotto `X:\`, riconosce i nomi Pro-E `<codice>.<tipo>.<versione>` e fa un upsert
+incrementale (confronto su percorso+dimensione+data), così i giri successivi costano solo il
+delta. Qui si sceglie anche la **cartella di lavoro**, che da qui in poi ospita tutto il resto.
+
+**2. Distinta del gestionale → CSV.** `DistintaBaseImporter.ConvertiInCsv` riduce l'export a
+due colonne `componente;descrizione`. Se il nome del file segue la convenzione
+`DBP_<codice>_<timestamp>` aggiunge l'assieme generale come riga in più: da quel momento è un
+componente come tutti gli altri, nessun caso speciale a valle.
+
+**3. Componenti del CSV → `raw/`.** Per ogni codice del CSV `TrovaPercorsiCad` cerca
+nell'indice l'ultima versione (vista `files_ultima_versione`) e `CopiaFileTrovati` la copia in
+`raw/` in parallelo. Finisce qui il livello "distinta": in `raw/` ci sono i componenti
+elencati dal gestionale, non ancora quello che serve ad aprirli.
+
+**4. Chiusura ricorsiva dell'albero → `raw/` completa.** È il cuore del programma, ed è
+l'unica fase che deve ragionare come Creo invece che come il gestionale.
+`RisolviAlberoComponenti` tiene una coda di `.asm` da leggere, partendo da quelli già in
+`raw/`, e per ognuno raccoglie **tre liste diverse**, che non vanno confuse (vedi
+`docs/formato-asm-record.md` §7.3 e §7.5):
+
+| Lista | Da dove | Ricorsione | Se non è nell'indice |
+|---|---|---|---|
+| Componenti della distinta | sezione `members` (`EstraiCodiciReferenziati`) | sì | va nei "non trovati" |
+| Componenti **soppressi** | stringhe di piazzamento (`EstraiCodiciSoppressi`) | no — Creo non carica i figli di un soppresso | ignorato: non è un componente, segnalarlo sarebbe un falso allarme |
+| **Riferimenti esterni** | tabella dei modelli citati (`EstraiCodiciRiferimentiEsterni`) | sì — Creo carica il modello citato con tutto il suo albero | ignorato, stesso motivo |
+
+Ogni codice trovato viene copiato in `raw/` scegliendo **quale** copia con `ScegliPerCartella`
+(§7.4: lo stesso codice esiste in più cartelle della share nel 13% dei casi, e vince quella
+nella stessa cartella dell'assieme che lo referenzia); se è un `.asm` torna in coda e il giro
+ricomincia, finché restano solo foglie. I rami raggiunti per riferimento esterno viaggiano con
+un flag `Esterno` che li tiene fuori dall'elenco dei "non trovati": quell'elenco continua a
+parlare solo della distinta, che è quello che l'utente si aspetta di leggerci.
+
+Il motivo per cui questa fase è più complicata di come sembra: **la lista dei componenti e la
+lista dei file necessari al caricamento non coincidono**, e la seconda è più lunga. Quando si
+sbaglia, Creo Distributed Batch non dice quale file manca — dice solo `[-4] Dati di input non
+completi`.
+
+**5. Verifica e consegna a Creo.** `AggiornaAnteprimaAsm` mostra i `.asm` della distinta già
+in `raw/` come icone trascinabili. L'esportazione STEP vera è manuale e fuori dall'app: si
+trascinano i `.asm` su Creo Distributed Batch, che scrive in `step/`.
+
 ## Entry point
 
 - **Program.cs** — `Main()` standard WinForms: `Application.Run(new Form1())`. Nessuna logica.
@@ -44,13 +95,18 @@ Distinta (.xls/.xml)  →  CSV (componente;descrizione)  →  raw/ (CAD copiati
   | 1 | Database | "Aggiorna indice" → `Indexer.ScanAsync`; "Cambia cartella..." → `ScegliCartellaLavoro` | Crea/aggiorna `cad_index.db` scansionando la share; sceglie/mostra la cartella di lavoro |
   | 2 | Importa Distinta Base | selezione file → `ImportaDistinta` → `DistintaBaseImporter.ConvertiInCsv` | Xls/Xml gestionale → CSV componente;descrizione, scritto nella cartella di lavoro |
   | 3 | Crea cartella raw | "Crea cartella raw" → `CreaCartellaRaw` | `TrovaPercorsiCad` + `CopiaFileTrovati` (parallela) → `raw/` dentro la cartella di lavoro |
-  | 4 | Trova componenti referenziati | "Trova componenti referenziati" → `TrovaPrtReferenziati` → `RisolviAlberoComponenti` | Legge i `.asm` in `raw/` con `AssemblyComponentScanner`, risolve ricorsivamente sotto-assiemi/parti nell'indice, li copia anch'essi in `raw/` |
-  | 5 | Verifica completezza | "Verifica completezza assiemi" → `VerificaCompletezzaAssiemi` | Completezza ricorsiva sui percorsi in indice. All'ingresso nella fase, `AggiornaAnteprimaAsm` mostra le icone trascinabili dei `.asm` della distinta già in `raw/`, da trascinare su Creo per l'esportazione STEP (Distributed Batch) |
+  | 4 | Trova componenti referenziati | "Trova componenti referenziati" → `TrovaPrtReferenziati` → `RisolviAlberoComponenti` | Legge i `.asm` in `raw/`, risolve ricorsivamente sotto-assiemi/parti nell'indice e li copia anch'essi in `raw/`, insieme ai componenti soppressi e ai modelli citati per riferimento esterno che servono a Creo per aprire l'assieme |
+  | 5 | Verifica completezza | (ingresso in fase) → `AggiornaAnteprimaAsm` | Mostra le icone trascinabili dei `.asm` della distinta già in `raw/`, da trascinare su Creo per l'esportazione STEP (Distributed Batch) |
 
   Stato condiviso tra le fasi (campi privati di `Form1`): `_dbPath`, `_cartellaLavoro`,
   `_percorsoInputCorrente`, `_righeCorrenti` (righe del CSV), `_ultimaVerifica` (cache percorsi
   CAD), `_ultimaCartellaRaw`.
 
+  Menu (`MenuStrip`, in cima alla finestra): "File → Nuova estrazione" (Ctrl+N) azzera lo
+  stato delle fasi 2-5 (`NuovaEstrazione`) per ripartire con una nuova distinta senza
+  ricaricare il database/la cartella di lavoro (fase 1, che resta invariata); "Aiuto → Guida"
+  (F1) apre `GuidaForm`, sintesi interattiva delle 5 fasi per chi non ha letto questi docs.
+
   Altre responsabilità in Form1.cs:
   - `TrovaPercorsiCad` / `CaricaCodiciNoti` — query sul DB (`files_ultima_versione`), la
     seconda carica tutti i codici prt/asm noti in un colpo solo (usata sia per risolvere i
@@ -81,8 +137,7 @@ Distinta (.xls/.xml)  →  CSV (componente;descrizione)  →  raw/ (CAD copiati
 
 ## Lettura dei componenti referenziati in un `.asm`
 
-`Form1.EstraiCodiciReferenziati` (usata da `RisolviAlberoComponenti`, fase 4, e da
-`AssiemeCompleto` dentro `VerificaCompletezzaAssiemi`, fase 5) prova prima
+`Form1.EstraiCodiciReferenziati` (usata da `RisolviAlberoComponenti`, fase 4) prova prima
 `AsmRecordReader.EstraiCodiciReferenziati` e ripiega su
 `AssemblyComponentScanner.EstraiCodiciReferenziati` solo se il primo lancia
 `InvalidDataException` (file che non rispetta il formato validato dal reverse engineering).
@@ -90,8 +145,12 @@ Distinta (.xls/.xml)  →  CSV (componente;descrizione)  →  raw/ (CAD copiati
 - **AsmRecordReader.cs** — legge esattamente la sezione `members` del binario `.asm` (id/tipo/
   nome dei componenti diretti, con risoluzione del nome istanza di family table dal parametro
   `ConfigName`): nessuna euristica, struttura a record. Lancia `InvalidDataException` se il
-  file non ha una sezione `members` o se il conteggio dichiarato non torna. Dettagli in
-  `docs/formato-asm-record.md`. Condivisa con `scripts/CreoBom.cs` via `#:project`.
+  file non ha una sezione `members` o se il conteggio dichiarato non torna. Espone anche le
+  due liste "non di distinta": `EstraiCodiciSoppressi` (che passa da `members` per sapere
+  quali codici sono già noti, quindi può lanciare la stessa eccezione — `Form1.CodiciSoppressi`
+  la intercetta e restituisce vuoto) e `EstraiCodiciRiferimentiEsterni` (scansione a sé, non
+  lancia). Dettagli in `docs/formato-asm-record.md`. Condivisa con `scripts/CreoBom.cs` via
+  `#:project`.
 - **AssemblyComponentScanner.cs** — estrae euristicamente i codici componente referenziati
   contando le occorrenze di stringhe candidate nel testo binario. Due strategie: codici
   numerici Pro-E riconosciuti da soli via regex (come nei nomi file), e nomi alfabetici di
@@ -100,6 +159,29 @@ Distinta (.xls/.xml)  →  CSV (componente;descrizione)  →  raw/ (CAD copiati
   positivi noti in `docs/formato-asm.md`. Resta il fallback per i file che il parser esatto
   non copre, e la fonte di verità per `ExtractCreoStrings.cs`/`BomViaDb.cs`.
 
+Quella lista è **la distinta**, e non coincide con i file che servono a Creo per aprire
+l'assieme: ne restano fuori due categorie, che il loro file serve comunque, altrimenti il
+caricamento fallisce (`docs/formato-asm-record.md` §7.3). `AsmRecordReader` le restituisce a
+parte, e la fase 4 le copia in `raw/` senza contarle fra i "non trovati":
+
+- `EstraiCodiciSoppressi` — i componenti **soppressi**: spariti da `members`, ancora citati
+  dalla feature che li posiziona. Non si ricorre dentro (Creo non carica i figli di un
+  componente soppresso).
+- `EstraiCodiciRiferimentiEsterni` — i modelli legati da **riferimento esterno** (assembly
+  feature, datum copiati), elencati in una tabella a parte del binario (§7.5). Qui si ricorre
+  dentro, perché Creo carica il modello citato con tutto il suo albero.
+
+## Quale copia di un componente si copia in `raw/`
+
+Lo stesso codice esiste spesso in più cartelle della share, con contenuto diverso e pari
+versione (13% dei codici, vedi `docs/formato-asm-record.md` §7.4). Il `.asm` non registra
+quale copia usa, quindi `RisolviAlberoComponenti` replica la regola di Creo:
+`Form1.ScegliPerCartella` preferisce la copia nella **stessa cartella dell'assieme che la
+referenzia** (`Form1.CartellaDiOrigine` ricostruisce quella cartella per gli assiemi di
+partenza), e solo in mancanza ripiega su versione più alta e data più recente. Sbagliare copia
+non dà un errore comprensibile: Creo non apre l'assieme e dice solo "dati di input non
+completi".
+
 ## Import distinta base
 
 - **DistintaBaseImporter.cs** — converte l'export del gestionale (SpreadsheetML XML con
@@ -137,8 +219,8 @@ Distinta (.xls/.xml)  →  CSV (componente;descrizione)  →  raw/ (CAD copiati
   sotto-assiemi trovati e copiati in `raw/`, più i codici referenziati che non corrispondono a
   nessun file indicizzato (possono essere disegni, componenti davvero mancanti, o falsi
   positivi della scansione `.asm`).
-- **ReportCompletezzaForm.cs** — per ogni assieme della distinta, se tutti i suoi componenti
-  (ricorsivamente fino ai PRT) sono nell'indice (✓/✗/? per "non trovato").
+- **GuidaForm.cs** — guida interattiva ("Aiuto → Guida"/F1): lista delle 5 fasi a sinistra,
+  testo a destra; sintesi, il dettaglio resta solo in questi docs.
 
 ## Persistenza
 
@@ -181,6 +263,11 @@ dipendenze extra con `#:package Nome@versione` in testa al file):
 - **PrepStep.Tests/** (xUnit) — riferimento al progetto principale via `ProjectReference`
   + `InternalsVisibleTo` (in `PrepStep.csproj`), così i test chiamano direttamente
   `Indexer.ParseFilename` e `AssemblyComponentScanner.EstraiCodiciReferenziati` senza esporli
-  come API pubblica. File: `IndexerParseFilenameTests.cs`,
-  `AssemblyComponentScannerTests.cs`, `DistintaBaseImporterTests.cs`,
-  `CaseInsensitiveLookupIntegrationTests.cs`.
+  come API pubblica. File: `IndexerParseFilenameTests.cs`, `IndexerScanTests.cs`,
+  `AssemblyComponentScannerTests.cs`, `AsmRecordReaderTests.cs`,
+  `DistintaBaseImporterTests.cs`, `CaseInsensitiveLookupIntegrationTests.cs`,
+  `PipelineEndToEndTests.cs`.
+
+  `AsmRecordReaderTests.cs` costruisce i `.asm` byte per byte con dei piccoli helper
+  (`Membro`, `ConfigName`, `ObjName`, `Riferimenti`): ogni caso strano trovato sulla share
+  diventa un test minimale invece di un file binario da versionare.

docs/db-cad-index.md

@@ -29,17 +29,33 @@ componenti e nel filtro per cartella).
 
 Vista `files_ultima_versione`: stessa struttura di `files`, filtrata alla sola riga con
 `versione` più alta per ogni `(cartella_radice, codice, tipo_file)`, tramite `ROW_NUMBER()
-OVER (PARTITION BY ... ORDER BY versione DESC)`. Tutte le ricerche di componenti (`Form1.
-TrovaPercorsiCad`, `Form1.CaricaCodiciNoti`) interrogano questa vista, non `files`
-direttamente, così un componente con più versioni sulla share risolve sempre all'ultima.
-Deliberatamente una `ROW_NUMBER()` invece di un self-join con `GROUP BY`: su ~200k righe un
-self-join degenera in tempi quasi quadratici, `ROW_NUMBER()` resta lineare.
+OVER (PARTITION BY ... ORDER BY versione DESC, data_modifica DESC, percorso_completo)`. Tutte
+le ricerche di componenti (`Form1.TrovaPercorsiCad`, `Form1.CaricaCodiciNoti`) interrogano
+questa vista, non `files` direttamente, così un componente con più versioni sulla share
+risolve sempre all'ultima. Deliberatamente una `ROW_NUMBER()` invece di un self-join con
+`GROUP BY`: su ~200k righe un self-join degenera in tempi quasi quadratici, `ROW_NUMBER()`
+resta lineare.
+
+La vista è ricreata (`DROP` + `CREATE`, non `CREATE IF NOT EXISTS`) a ogni "Aggiorna indice",
+così un DB già esistente prende la definizione corrente senza dover reindicizzare la share.
 
 Nota: `cartella_radice` fa parte della partition, quindi se lo stesso codice+tipo esiste
 in **due cartelle radice diverse** (duplicati sulla share), la vista restituisce una riga per
 ciascuna — non una sola in assoluto. `TrovaPercorsiCad` gestisce questo caso deduplicando per
 `tipo_file` lato C# (vedi sotto).
 
+> **I criteri di pareggio non sono decorativi.** Lo stesso codice può esistere **nella stessa
+> cartella radice, con la stessa `versione`**, in due sottocartelle diverse (una copia in una
+> cartella di studio, di lavoro o temporanea). Senza `data_modifica` nell'`ORDER BY` il
+> pareggio veniva rotto in modo arbitrario, e poteva vincere la copia obsoleta — nascondendo
+> del tutto quella buona, che non compariva più nella vista. Il file che finiva in `raw/` era
+> allora un modello diverso da quello che l'assieme si aspetta: Creo lo carica, i vincoli di
+> accoppiamento non si risolvono e **l'assieme non si apre affatto**.
+>
+> Il criterio deterministico però non basta a scegliere *bene*: è il minimo per non sbagliare
+> a caso. Quale copia sia quella giusta dipende da chi la referenzia, non dalla data — vedi
+> [`formato-asm-record.md`](formato-asm-record.md) §7.4 e `Form1.ScegliPerCartella`.
+
 ## Come viene popolato: `Indexer.ScanAsync`
 
 Chiamato da "Aggiorna indice" (fase 1) e riutilizza lo stesso `dbPath` già caricato.

docs/formato-asm-record.md

@@ -13,11 +13,23 @@ referenziati"/"Verifica completezza" - con fallback su `AssemblyComponentScanner
 che non rispettano il formato validato), resa in formato BOM e ricorsione sui sottoassiemi
 in [`scripts/CreoBom.cs`](../scripts/CreoBom.cs) (via `#:project`).
 
-**Stato della validazione.** Durante il reverse engineering, il livello 1 estratto da 3
-assiemi con BOM Creo di riferimento coincideva **esattamente**: stesse voci, stesso nome
-istanza, stesse quantità, stesso ordine. Altri 5 `.asm`, mai usati per ricavare le regole,
-parsavano con il conteggio dichiarato uguale a quello trovato. Tutto ciò che segue oltre
-questo perimetro (§7) è segnalato esplicitamente come ipotesi non dimostrata.
+**Stato della validazione.** Due livelli di prova, da non confondere:
+
+1. **Byte-per-byte contro BOM Creo di riferimento** (la prova forte): 3 assiemi del
+   reverse engineering iniziale, più 5 casi reali aggiunti in seguito, ciascuno con la sua BOM
+   esportata da Creo messa a confronto riga per riga con l'output di `CreoBom.cs` —
+   `9284218024b.asm` (albero profondo, multi-livello), `2546220101.asm`/`2546220101_c04.asm.1`
+   (istanza di family table isolata), `2546220101.asm` risalvato con un componente soppresso,
+   `9244218080_c01.asm` (sottoassieme montato due volte), `9284208092_D110.asm` (revisione del
+   figlio). Ognuno di questi è citato per nome nella sezione del documento a cui si riferisce,
+   così resta verificabile quale affermazione poggia su quale file.
+2. **Su tutti i 350 `.asm` reali di `raw/`**, solo conteggi interni e coerenza con l'euristica
+   testuale (`AssemblyComponentScanner`), **non** contro BOM di riferimento: usato per
+   calibrare le soglie dei controlli di sicurezza (§7) su scala, non per dimostrare la
+   correttezza dei valori estratti file per file.
+
+Un'affermazione verificata solo al livello 2 (conteggi su scala) è più debole di una
+verificata al livello 1 (BOM reale) - il testo lo distingue sempre esplicitamente.
 
 ---
 
@@ -211,6 +223,30 @@ ampio degli 8 campioni originali (`9284218024b.asm`, confrontato con la sua BOM
 riferimento) — non era presente in nessuno degli 8 campioni usati per il reverse engineering
 iniziale.
 
+### 4.0.2 Istanza risolta direttamente in `members`, senza passare da `ConfigName`
+
+Non tutti i membri che sono istanze di family table hanno un record `ConfigName` associato.
+Per alcune parti commerciali/normalizzate non-UNI, il campo `name` (e allo stesso modo
+`family_name`) del record `members` (§3) porta già per intero la notazione
+`<nome istanza><generico>` invece del solo nome generico:
+
+```
+\xe3 <id> <type> "<istanza><generico>"\0 "<istanza><generico>"\0
+```
+
+È la stessa notazione istanza→generico della §4.1 sotto, ma qui compare **dentro** il record
+`members` stesso, come valore diretto del componente - non nell'elenco di riferimenti
+geometrici di cui parla la §4.1 (quello sì da ignorare per la BOM). Il generico fra `<` e `>`
+è il file realmente indicizzato sul disco; il nome prima di `<` è quello che la BOM
+mostrerebbe.
+
+`AsmRecordReader.LeggiMembri` lo riconosce per i membri **senza** un `ConfigName`
+corrispondente il cui campo `name` rispetta per intero il pattern `<testo><testo>`: il testo
+dopo l'ultima `<` (fino alla `>` finale) diventa il generico da cercare nell'indice, quello
+prima diventa il nome mostrato. Senza questo split, il codice cercato nell'indice sarebbe la
+stringa intera con le parentesi comprese, mai presente nell'indice - il componente
+risulterebbe erroneamente "non trovato".
+
 ### 4.1 Una seconda pista, che NON va usata per la BOM
 
 Altrove nel file compaiono stringhe nella forma `istanza<generico>`:
@@ -271,9 +307,12 @@ subito dopo, ricorsivamente, quelli dei suoi sottoassiemi, prima di passare al
 fratello successivo. Ogni modello compare **una volta sola** anche se montato
 più volte (deduplica per nome, `CreoAsm.Blocchi`).
 
-> La deduplica è un'**assunzione**: nessuno dei campioni disponibili durante il
-> reverse engineering montava lo stesso sottoassieme due volte, quindi non è
-> dimostrata su un caso reale.
+> **Verificato.** `9244218080_C01.asm` monta `2605410010_C01` due volte
+> (`scripts/9244218080_c01.asm.1` + `scripts/9244218080_c01.bom.2` di riferimento): la BOM
+> Creo mostra un solo blocco `Sottoassieme 2605410010_C01 contiene:` con quantità 2 in testa,
+> non due blocchi separati, e `CreoBom.cs` riproduce l'output esatto senza modifiche. Confermata
+> anche la moltiplicazione delle quantità nel riepilogo (§6.3): le parti di `2605410010_C01`
+> compaiono raddoppiate (1→2, 1→2, 16→32).
 
 ### 6.3 Riepilogo finale
 
@@ -291,13 +330,17 @@ dall'esterno (`-p`/`--path`). `CreoAsm.CreaFinder` indicizza `<nome>.asm.<rev>`
 senza distinzione di maiuscole e, a parità di nome, prende la **revisione più
 alta** presente.
 
-> Scelta discutibile: la revisione più alta in cartella non è
-> necessariamente quella con cui l'assieme padre è stato salvato. Il `.asm`
-> padre non sembra registrare la revisione attesa del figlio, o non è stata
-> trovata. Vedi `formato-asm.md` §"Risoluzione ricorsiva dell'albero" per le
-> trappole già incontrate storicamente su questo punto (con l'euristica
-> testuale, ma il problema della revisione attesa è indipendente dal metodo
-> di estrazione).
+> **Verificato: è la scelta giusta.** Il `.asm` padre non registra la revisione attesa del
+> figlio (cercata e non trovata, vedi §7), ma non serve: confermato che **Creo stesso apre
+> sempre la revisione più alta disponibile** di un componente, indipendentemente da quale
+> fosse presente quando l'assieme padre fu salvato l'ultima volta. Caso reale controllato:
+> `9284208092_D110.asm` (salvato 2018-08-01) referenzia `9284202481.prt`, che sulla share ha
+> revisioni sia del 2014 (v1-v3, presenti all'epoca) sia del 2024 (v4-v6, arrivate anni dopo) -
+> Creo carica v6, non v3. `CreaFinder` che prende sempre la revisione più alta in cartella
+> replica esattamente questo comportamento, non è un'assunzione azzardata. Vedi `formato-
+> asm.md` §"Risoluzione ricorsiva dell'albero" per le trappole storiche su questo punto (con
+> l'euristica testuale - restano valide, sono su un problema diverso: trovare la cartella
+> giusta, non quale revisione preferire).
 
 Se un sottoassieme non si trova, il blocco viene emesso con
 `*** NON RISOLTO: file .asm non trovato ***` e le sue parti restano fuori dal
@@ -306,44 +349,225 @@ sbagliato.
 
 ---
 
-## 7. Cosa resta sconosciuto
+## 7. Stato di ogni punto aperto
 
-Elencato esplicitamente per non far passare per dimostrato ciò che non lo è:
+Tabella di riferimento: cosa è provato, come, e cosa resta genuinamente ignoto. Il dettaglio
+di ciascun punto segue sotto, in due gruppi.
 
-- **⚠️ Family table di ASSIEMI (non solo di parti), risultato silenziosamente sbagliato.**
-  Non solo le parti normalizzate (§4) possono essere family table: un intero **assieme** può
-  esserlo. Osservato su `2546220101.asm` (dentro l'albero di `9284218024b.asm`): il file
-  generico ha una propria sezione `members` che elenca il contenuto di UNA rappresentazione
-  (nell'esempio, 3 cuscinetti + 1 sotto-assieme), ma la BOM Creo per lo stesso file mostra 4
-  **istanze diverse** (`2546220101_C01`.."_C04", tre "Parte" e una "Sottoassieme" - tipi
-  diversi fra loro!), ciascuna con un proprio contenuto potenzialmente diverso. Il nome
-  istanza qui **non** passa da un record `ConfigName` (verificato: nessuna occorrenza
-  letterale di `ConfigName` nel file) ma da un meccanismo diverso, imparentato con la
-  "seconda pista" del §4.1 (`\xe3<id>\xe2\x02<stringa>\0`, senza il bracket
-  `<generico>` in questo caso) - non decodificato. **`AsmRecordReader.LeggiMembri` non lo
-  rileva e non lancia eccezione**: restituisce silenziosamente il contenuto della
-  rappresentazione di default sotto un solo nome, invece delle 4 istanze corrette - a
-  differenza degli altri limiti di questa sezione, qui il fallimento non è segnalato in
-  nessun modo al chiamante (né un conteggio che non torna, né un'eccezione). Scoperto sullo
-  stesso test end-to-end del punto `#AF` sopra, mai osservato negli 8 campioni originali.
-  **Prima di fidarsi del parser esatto su un albero con assiemi a family table, verificare a
-  mano contro la BOM Creo.**
-- **Stato soppresso / escluso.** Nessuna evidenza cercata o trovata. Non si sa
-  se un componente soppresso compaia in `members`, né con quale marcatore. Sui
-  campioni disponibili il totale coincideva con la BOM, il che *suggerisce* che
-  non ce ne fossero, non che siano gestiti.
-- **La matrice di posizionamento** (`e1`, `e2`, `e3`, `origin`): formato
-  numerico non decodificato.
-- **`family_name`**: sempre uguale a `name` sui campioni; non si sa in quale
-  situazione divergerebbe.
-- **La costante `\x82\x7b`** nei record `ConfigName`.
-- **I campi numerici dell'header** dopo `ASSEMBLY`.
-- **Occorrenze multiple di `members`.** `AsmRecordReader.LeggiMembri` prende la prima.
-  Sui campioni disponibili funziona, ma non è stato verificato se le
-  rappresentazioni semplificate (simplified rep) generino sezioni `members`
-  aggiuntive.
-- **La deduplica dei blocchi** e **la revisione attesa dei figli** (§6.2, §6.4).
-- **Quale revisione del figlio** il padre si aspetta: non trovata nel `.asm`.
+| Punto | Stato | Prova |
+|---|---|---|
+| Deduplica blocchi + moltiplicazione quantità (§6.2/§6.3) | Risolto | BOM reale (§7.1) |
+| Revisione del figlio che il padre si aspetta (§6.4) | Risolto | BOM reale (§7.1) |
+| Stato soppresso/escluso in `members` | Risolto | BOM reale (§7.1) |
+| Family table di **assiemi** (rilevamento) | Risolto: serve la conferma del nome proprio (`objname`), il solo `model_name` dava falsi positivi | BOM reali + albero `raw/` completo (§7.1) |
+| Family table di **assiemi** (contenuto di ogni istanza) | Non risolto, nessun impatto sulla BOM (fallback già corretto) | Scan sull'intera share (§7.2) |
+| Costante `\x82\x7b` in `ConfigName` | Significato ignoto, rischio coperto | Scala 350 file (§7.2) |
+| Occorrenze multiple di `members` (simplified rep) | Mai osservato, rischio coperto | Scala 350 file (§7.2) |
+| Matrice di posizionamento (`e1`/`e2`/`e3`/`origin`) | Non letto, nessun impatto sulla BOM | — (§7.2) |
+| Campi numerici dell'header dopo `ASSEMBLY` | Non letto, nessun impatto sulla BOM | — (§7.2) |
+| Divergenza `family_name` ≠ `name` | Mai osservata, non letta | — (§7.2) |
+
+"Rischio coperto" vuol dire: il codice non sa cosa significhi il byte, ma verifica un
+invariante che lo renderebbe visibile (eccezione) se mai smettesse di valere - non è una prova
+che il byte non conti mai, è la garanzia che se contasse il programma lo segnalerebbe invece
+di sbagliare in silenzio.
+
+### 7.1 Risolti con una BOM Creo di riferimento
+
+- **Deduplica blocchi e moltiplicazione quantità.** `9244218080_C01.asm` monta
+  `2605410010_C01` due volte (`scripts/9244218080_c01.asm.1` +
+  `scripts/9244218080_c01.bom.2`): la BOM Creo mostra un solo blocco
+  `Sottoassieme 2605410010_C01 contiene:` con quantità 2 in testa (non due blocchi separati),
+  e le sue parti compaiono raddoppiate nel riepilogo (1→2, 1→2, 16→32). `CreoBom.cs` riproduce
+  l'output esatto senza modifiche: la deduplica per nome (`CreoAsm.Blocchi`) e la
+  moltiplicazione lungo l'albero (`CreoAsm.Sommario`) sono il comportamento reale di Creo, non
+  solo un'assunzione.
+- **Revisione del figlio.** `9284208092_D110.asm` (salvato 2018-08-01) referenzia
+  `9284202481.prt`, che sulla share ha revisioni sia del 2014 (v1-v3, presenti quando il padre
+  fu salvato) sia del 2024 (v4-v6, arrivate anni dopo). Confermato direttamente in Creo: apre
+  v6, non v3 - **sempre la revisione più alta disponibile**, indipendentemente da quale fosse
+  presente all'ultimo salvataggio del padre. `CreoAsm.CreaFinder`, che prende sempre la
+  revisione più alta trovata in cartella, replica esattamente questo comportamento.
+- **Stato soppresso/escluso.** Stesso assieme `2546220101.asm` risalvato da Creo con
+  `2546220101_C02` soppresso (`scripts/2546220101.asm.1` + `scripts/2546220101.bom.1`, con le
+  parti/sottoassiemi correlati). Un componente soppresso **non produce alcun record** in
+  `members`: sparisce e basta, il conteggio dichiarato scende di conseguenza (`\xf8 03` invece
+  di `\xf8 04`). Nessun marcatore di stato da gestire: `CreoBom.cs` sul file risalvato
+  riproduce esattamente la BOM di riferimento senza modifiche al parser.
+
+  > **Sparisce da `members`, non dal file.** La feature che lo posiziona resta, e con essa la
+  > stringa `Componente ID <n> (<codice>.PRT)` (localizzata come in
+  > `AssemblyComponentScanner.HaPlacement`). Per la BOM va ignorata - Creo non elenca i
+  > soppressi - ma **il file di quel componente serve comunque per aprire l'assieme**: se manca,
+  > Creo fallisce il caricamento con "dati di input non completi" (`[-4]`, cioè
+  > `PRO_TK_E_NOT_FOUND`). Verificato su un caso reale: un assieme che non si apriva dalla
+  > cartella `raw/`, e che si è aperto senza errori copiandoci dentro quel solo file.
+  > `AsmRecordReader.EstraiCodiciSoppressi` li restituisce a parte, apposta per questo - vedi
+  > §7.3.
+- **Family table di assiemi — rilevamento.** Non solo le parti normalizzate (§4) possono
+  essere family table: un intero **assieme** può esserlo. Osservato su `2546220101.asm`
+  (dentro l'albero di `9284218024b.asm`): il file generico ha una propria sezione `members`
+  che elenca il contenuto di UNA rappresentazione (3 cuscinetti + 1 sotto-assieme, dati
+  arbitrari), ma la BOM Creo per lo stesso file mostra 4 **istanze diverse**
+  (`2546220101_C01`.."_C04", tre "Parte" e una "Sottoassieme" - tipi diversi fra loro),
+  ciascuna con un contenuto diverso. Il nome istanza qui **non** passa da `ConfigName`
+  (verificato: nessuna occorrenza letterale nel file), ma da una coppia di record distinta
+  subito dopo l'header del modello:
+
+  ```
+  \xe0\x01model_t_type\0<int>\xe0\x0amodel_name\0<codice>_C0n\0\xe0\x0ageneric_name\0\0
+      ...stamp\0\xe2\xf2\xf7<idSchema>
+      (\xe3<type>\x02<codice>_C0n\0\0\xe2)*   -- un'occorrenza per ogni istanza sorella
+  \xf4
+  ```
+
+  Quando questo succede il file generico è già di per sé un'istanza (`model_name` porta il
+  suffisso `_C0n`, non è neutro) e `stamp` elenca le sorelle.
+
+  > **Il record `model_name` da solo non è un'identità.** Su file reali quel record nomina
+  > quasi sempre **un altro modello** - tipicamente uno dei membri del file stesso, a volte un
+  > codice imparentato - e in quei casi `members` è già corretto e va usato. Serve una
+  > conferma indipendente: il **nome proprio del modello** (`objname`, §5). `LeggiMembri`
+  > segnala la family table solo se `objname` esiste **e** coincide con `model_name` privato
+  > del suffisso `_C0n`; negli altri casi legge `members` normalmente.
+  >
+  > Il controllo più largo (senza la conferma di `objname`) era la causa di
+  > **falsi "componenti mancanti"**: il parser esatto rifiutava file perfettamente leggibili,
+  > si ripiegava sull'euristica testuale e quella estraeva codici che non esistono, riportati
+  > poi come componenti non trovati nell'indice. Verificato contro BOM Creo di riferimento:
+  > sui file dove il segnale scattava senza conferma di `objname`, `members` elenca
+  > **esattamente** i componenti della BOM reale (anche nello stesso ordine); uno di questi
+  > file è stato inoltre aperto in Creo, e l'albero del modello mostra gli stessi componenti,
+  > senza alcuna family table. Con la conferma di `objname` richiesta, tutti i `.asm` di una
+  > cartella `raw/` reale (351 file, alberi completi di più macchine) si leggono col parser
+  > esatto, zero ricadute sull'euristica.
+
+  Da tenere presente: il sintomo dipende da **come il file è stato salvato**, non solo dal
+  modello. Rileggendo una revisione più recente dello stesso assieme generico, il record di
+  identità può non esserci più e `members` elencare direttamente tutte le istanze, col tipo
+  giusto per ciascuna - cioè esattamente quello che mostra la BOM. Il blocco quindi non è una
+  proprietà stabile del codice: va valutato file per file, revisione per revisione.
+
+  Verificato anche che il fallback su `AssemblyComponentScanner` **risolve già correttamente**
+  il caso vero: i nomi delle istanze compaiono come testo puro nel campo `stamp`, e
+  l'euristica ("codice che compare almeno due volte") li trova senza bisogno di decodificare
+  `stamp`. E che una singola istanza, se esportata da Creo come file a sé (Family Table →
+  istanza → "Salva una copia"), è un `.asm`/`.prt` normale senza traccia di family table al suo
+  interno - letto correttamente dal parser esatto (`2546220101_c04.asm.1`, verificato contro
+  `2546220101.bom.1`).
+
+### 7.2 Non risolti
+
+- **Family table di assiemi — contenuto di ogni istanza.** Come recuperare il contenuto
+  specifico di un'istanza **senza** che esista già un file separato per essa sul disco (il
+  caso comune, se nessuno l'ha mai esportata a parte con "Salva una copia"): il meccanismo
+  dietro `stamp` non è stato decodificato oltre a nome+tipo di ciascuna istanza sorella:
+  `stamp` porta **solo i nomi** delle sorelle, non il loro contenuto, quindi non è la
+  struttura da cui partire per risolvere questo punto.
+
+  Resta aperto solo per completezza: sui file dove il segnale scatta davvero (con conferma
+  del nome proprio, §7.1) il parser si ferma invece di restituire un contenuto sbagliato, e
+  il chiamante ripiega sull'euristica testuale, che i nomi delle istanze li trova comunque
+  come testo puro. Nessun comportamento dell'app dipende da questa decodifica.
+- **Costante `\x82\x7b`** nei record `ConfigName`: significato ignoto. Rischio coperto -
+  `LeggiMembri` conta le occorrenze grezze di `ConfigName` e le confronta col numero di match
+  del regex; se un campione avesse un valore diverso, il regex non farebbe più match (prima:
+  in silenzio) e ora lancia eccezione invece di restituire il nome generico al posto
+  dell'istanza senza dirlo. Verificato su tutti i 350 `.asm` di `raw/`: 215 usano davvero
+  `ConfigName`, 0 mismatch.
+- **Occorrenze multiple di `members`** (rappresentazioni semplificate, mai osservate). Rischio
+  coperto - `LeggiMembri` lancia eccezione se ne trova più di una invece di prendere
+  silenziosamente la prima senza sapere se sia quella giusta. Verificato su tutti i 350 `.asm`
+  di `raw/`: sempre esattamente una occorrenza.
+- **La matrice di posizionamento** (`e1`, `e2`, `e3`, `origin`): formato numerico non
+  decodificato, nessun impatto sulla BOM (non letta da nessuna parte del codice).
+- **I campi numerici dell'header** dopo `ASSEMBLY`: non letti, nessun impatto sulla BOM.
+- **`family_name`**: sempre uguale a `name` su tutti i campioni disponibili; non si sa in
+  quale situazione divergerebbe, né se il codice dovrebbe fare qualcosa se succedesse (oggi
+  non la usa in nessun modo, legge solo `name`).
+
+### 7.3 Due domande diverse: cosa va in distinta, cosa serve per aprire
+
+È la lezione che costa di più riscoprire, quindi sta qui in chiaro: **la lista dei componenti
+della BOM e la lista dei file che servono a Creo per aprire l'assieme non coincidono.** La
+seconda è più lunga.
+
+| Lista | Serve per | Si ottiene con |
+| --- | --- | --- |
+| Componenti della distinta | BOM, verifica completezza | `LeggiMembri` / `EstraiCodiciReferenziati` (sezione `members`) |
+| File necessari al caricamento | popolare `raw/` per l'export STEP | i precedenti **più** `EstraiCodiciSoppressi` e `EstraiCodiciRiferimentiEsterni` (§7.5) |
+
+La differenza sono i **componenti soppressi** (§7.1) e i **riferimenti esterni** (§7.5): fuori
+dalla BOM, ma senza il loro file Creo non apre l'assieme. Chi popola `raw/` deve quindi usare
+l'unione; chi genera la BOM o verifica la completezza deve usare **solo** i membri, altrimenti
+quelle voci diventano falsi "componenti mancanti".
+
+Il sintomo, se si sbaglia, non assomiglia per niente alla causa: Creo Distributed Batch
+fallisce con `Carica modello in Creo Pro | Non riuscito | [-4] Errore: Dati di input non
+completi` - un messaggio che non nomina il file mancante. Il modo più rapido per trovarlo è
+aprire l'assieme in Creo **dalla cartella `raw/`** (non dalla share, dove i file ci sono tutti
+e quindi si apre senza errori) e cercare nell'albero la voce con l'icona rossa.
+
+### 7.4 Lo stesso codice esiste in più cartelle della share
+
+Sulla share **13% dei codici** (5.193 su 39.274 fra prt e asm) ha la versione più alta in più
+cartelle, con contenuto diverso. Non sono revisioni: sono copie parallele, lasciate da studi
+preliminari, allestimenti fiera, cartelle di lavoro datate, raccolte temporanee.
+
+Il `.asm` **non dice quale copia usa**: verificato che non registra né il percorso, né
+l'`UOBJ_ID` del figlio (che pure distingue le copie), né la revisione attesa. Cita solo il
+nome del modello. Quale copia venga caricata lo decide Creo al momento dell'apertura, e la
+regola pratica è: **prima la cartella del modello che la referenzia**.
+
+Non esiste quindi un criterio globale corretto - e i numeri lo confermano: nel 79% dei
+conflitti nessuna delle copie sta in una cartella "ufficiale" (`…\M_B`, `…\A`), perché il
+conflitto è fra due istantanee parallele, ognuna autoconsistente con i propri componenti. Per
+data, per versione e per posizione sono equivalenti: solo il contesto di chi referenzia
+discrimina.
+
+Conseguenze per il codice:
+
+- `Form1.ScegliPerCartella` risolve ogni componente preferendo la copia nella **stessa cartella
+  dell'assieme che lo referenzia**, e solo in mancanza ripiega su versione più alta e data più
+  recente. `Form1.CartellaDiOrigine` ricostruisce quella cartella per gli assiemi di partenza,
+  che arrivano dalla fase precedente senza portarsela dietro.
+- La vista `files_ultima_versione` (vedi [`db-cad-index.md`](db-cad-index.md)) rompe il
+  pareggio fra copie di pari versione in modo deterministico invece che arbitrario.
+- Resta un rischio noto: quando il componente **non** sta nella cartella del suo assieme, la
+  scelta torna a essere una scommessa. Se un assieme non si apre da `raw/`, è la prima cosa da
+  verificare - `9244206098` è il caso reale che ha portato a questa sezione: due copie di pari
+  versione, una del 2011 in una cartella di file sciolti e una del 2026 accanto all'assieme,
+  e in `raw/` finiva quella del 2011.
+
+### 7.5 Riferimenti esterni: la tabella dei modelli citati
+
+Terzo modo in cui un `.asm` dipende da un file che non è fra i suoi membri, dopo i soppressi
+(§7.1) e le copie ambigue (§7.4). Un assieme che porta **assembly feature** o **datum copiati**
+da un altro modello lo cita in una tabella a parte, che non è `members` e non lascia una stringa
+`Componente ID …`: i due lettori esistenti non la vedevano.
+
+Struttura: un array aperto da `\xf2\xf7\x05` e chiuso da `\xf3`, con elementi
+`\xe3\xe2<tipo><nome>\x00`. Il nome può portare il suffisso `#AF<n>` di §4.0.1 e/o la notazione
+`istanza<generico>` di §4.0.2 - il file su disco è il generico:
+
+```
+f2 f7 05 e3 e2 01 "9255708017#AF2<9255708017>" 00 ...  ->  9255708017
+         e3 e2 02 "9255700181" 00 ...                  ->  9255700181
+f3
+```
+
+Va letta con `EstraiCodiciRiferimentiEsterni`, e - a differenza dei soppressi - **si ricorre
+dentro**: Creo carica il modello citato con tutti i suoi componenti, che quindi servono anch'essi
+in `raw/`. La tabella contiene anche nomi di *feature* (`MIRROR3`, `CHAMFER1`,
+`M10_TAPPED_HOLE1`), indistinguibili dai modelli guardando il record: non è un problema perché
+chi la usa cerca ogni nome nell'indice e ignora quelli che non ci sono - per lo stesso motivo
+questi codici non devono finire fra i "non trovati".
+
+Il caso reale: `9255728001` falliva in Distributed Batch con lo stesso `[-4] Dati di input non
+completi` di §7.3 perché il suo sottoassieme `9255728001_200` referenzia per assembly feature
+`9255708017` e `9255708018` (e con loro `9255700181/182/183`), e monta una vite
+`V6-12--_-_U5933_C<UNI5933>` il cui generico `uni5933.prt` non era in `raw/`. Nessuno dei sei
+file compariva in `members` né fra i piazzamenti.
 
 ## 8. Uso