# Architettura di PrepStep Panoramica di tutti i file sorgente e di come collaborano. `PrepStep` è il nome tecnico del progetto (cartella, namespace, csproj, eseguibile `PrepStep.exe`); **PrepStep - Cevolani** è il nome mostrato all'utente finale (titolo finestra, icona, versione — vedi ``/`` in `PrepStep.csproj`). Per il "come si usa" vedi il `README.md` in root e la [`guida-utente.md`](guida-utente.md); per il 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 Un solo eseguibile WinForms (nessuna CLI, nessun processo esterno): indicizza i file CAD di una share di rete in un DB SQLite locale, poi guida l'utente in un wizard a 5 fasi che, a partire da una distinta base esportata dal gestionale, raccoglie in locale (`raw/`) tutti i file CAD dei componenti e dei loro sotto-assiemi e verifica che l'indice li copra, come pre-process prima dell'esportazione STEP con Creo Distributed Batch (manuale, fuori dall'app: i file esportati finiscono in `step/`, dentro la cartella di lavoro). ``` Distinta (.xls/.xml) → CSV (componente;descrizione) → raw/ (CAD copiati dall'indice) │ scansione .asm ─────┘ (sotto-assiemi/parti mancanti) │ 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 `..` e fa un upsert incrementale (confronto su percorso+dimensione+data), così i giri successivi costano solo il delta. La **cartella di lavoro**, che da qui in poi ospita tutto il resto, non si sceglie qui ma da "File → Scegli cartella di lavoro..." (default: cartella di installazione). **2. Distinta del gestionale → CSV.** `DistintaBaseImporter.ConvertiInCsv` riduce l'export a due colonne `componente;descrizione`. Se il nome del file segue la convenzione `DBP__` 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. ## Finestra principale (wizard) - **Form1.cs** — tutta la UI è costruita in codice (`BuildUi`/`BuildFase*`), non con il designer visuale. È un wizard: `_panelFasi[]` contiene un `Panel` per fase, uno solo visibile alla volta (`VaiAllaFase`); si avanza con "Avanti" solo se `AvantiConsentito` ritorna vero per la fase corrente. `Form1.Designer.cs` contiene solo lo scheletro minimo generato dal template (`InitializeComponent`/`Dispose`), non è usato per costruire i controlli. Le 5 fasi e i metodi principali dietro ciascuna: | # | Fase | Bottone → metodo | Cosa fa | |---|---|---|---| | 1 | Database | "Aggiorna indice" → `Indexer.ScanAsync` | Crea/aggiorna `cad_index.db` scansionando la share; un pallino verde/rosso accanto al titolo indica se un DB è caricato. La cartella di lavoro non è mostrata qui (cambiabile in qualunque momento da "File → Scegli cartella di lavoro...") | | 2 | Importa Distinta Base | selezione file/drag&drop → `ImportaDistinta` → `DistintaBaseImporter.ConvertiInCsv`, poi "Verifica presenza" → `VerificaCodiciNelDb` | Xls/Xml gestionale → CSV componente;descrizione, scritto nella cartella di lavoro (oppure "Lista personalizzata": codici digitati uno alla volta con `AggiungiCodice`, solo in memoria, senza CSV; tutto a valle legge solo `_righeCorrenti`); "Verifica presenza" (visibile solo dopo un import riuscito) cerca i componenti nell'indice e colora le righe della griglia — è quella che sblocca "Avanti", non il solo import | | 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/`, 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 → Nuovo" (Ctrl+N) azzera lo stato delle fasi 2-5 (`NuovaEstrazione`) e va direttamente alla fase 2, senza passare dalla fase 1: database e cartella di lavoro restano quelli già caricati, non serve rifare lo scan; "File → Scegli cartella di lavoro..." → `ScegliCartellaLavoro`, cambia in qualunque momento la destinazione di CSV/`raw/`/`step/`; "File → Pulisci raw e step..." svuota le cartelle `raw/`/`step/` nella cartella di lavoro (`PulisciRawEStep`, non tocca l'indice); "File → Elimina CSV delle distinte..." elimina i `*.csv` direttamente nella cartella di lavoro (`EliminaCsv`); "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 prima risolve i componenti del CSV (fase 3), la seconda carica tutti i codici prt/asm noti in un colpo solo, usata in fase 4 solo per validare i token generici di `AssemblyComponentScanner`. - `CaricaCandidati` — in fase 4, tutte le copie di ogni codice dalla tabella `files` (non dalla vista), da cui `ScegliPerCartella` sceglie quella da copiare in `raw/`. - `CopiaFileTrovati` — copia (in parallelo, grado 6) i file trovati in `raw/`, saltando silenziosamente quelli irraggiungibili (share offline/permessi). - `PulisciRawEStep` — svuota `raw/` e `step/` nella cartella di lavoro (manutenzione, richiede conferma). - `EliminaCsv` — elimina i `*.csv` generati dall'import (uno per distinta) nella cartella di lavoro, solo al primo livello; gli `.xls` del gestionale restano (richiede conferma, con l'elenco dei file). - `InizializzaDatabase` / `ScegliDatabase` — localizzazione del DB (sempre `cad_index.db` accanto all'eseguibile; "Apri DB..." ne carica un altro solo per la sessione). - `InizializzaCartellaLavoro` / `ScegliCartellaLavoro` — stesso pattern per la cartella di lavoro (`ultima_cartella_lavoro.txt`), fallback `AppContext.BaseDirectory` se non c'è ancora nulla di salvato: nessuna dipendenza da un marker di repo, funziona identica sull'exe pubblicato standalone spostato su un'altra macchina. ## Indicizzazione - **Indexer.cs** — `ScanAsync` cammina tutte le cartelle di primo livello sotto la radice (scoperte dinamicamente, non un elenco fisso) con un walk manuale a stack (`Walk`, più veloce di `EnumerateFiles(..., AllDirectories)` su share con centinaia di migliaia di file), esclude le cartelle `temp_*`, estrae da ogni nome file il pattern Pro-E `..` (`ParseFilename`, regex), e fa un upsert incrementale riga per riga confrontando `percorso_completo` + dimensione + data modifica. Progresso riportato via `IProgress` (marshalato sul thread UI). Contiene anche lo schema SQL: tabella `files` e vista `files_ultima_versione` (ultima versione per `codice`+`tipo_file` via `ROW_NUMBER() OVER (...)`, non self-join+`GROUP BY` per evitare tempi quasi quadratici su ~200k righe). ## Lettura dei componenti referenziati in un `.asm` `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). - **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. 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 parti commerciali tokenizzati genericamente e validati contro l'elenco di codici noti del DB (altrimenti il rumore binario sarebbe ingestibile). Dettagli sull'euristica e i falsi 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 estensione `.xls`/`.xml`, oppure `.xls`/`.xlsx` binario vero, distinti dai primi byte del file) nelle sole colonne Componente/Descrizione, foglio `"Distinta Base"`. Se il nome del file segue la convenzione `DBP__`, aggiunge l'assieme generale come riga in più (il foglio elenca solo i componenti sotto l'assieme). Scrive il CSV nella cartella passata da `Form1` (la cartella di lavoro, impostabile da "File → Scegli cartella di lavoro..."), non necessariamente accanto al file di input. ## Finestre di dialogo (modali, mostrate a fine step) - **ProgressForm.cs** — durante l'aggiornamento indice: barra di progresso, conteggi nuovi/aggiornati/invariati/rimossi, tempo trascorso e stima del tempo rimanente (dal ritmo file/secondo rispetto al totale atteso, preso dal conteggio della scansione precedente salvato nel DB). - **ProgressoComponentiForm.cs** — dialog minimale (etichetta + barra) durante `RisolviAlberoComponenti` in fase 4. ## Stile UI condiviso - **UiStile.cs** — `Primario`/`Secondario`: stile piatto per i bottoni (bordo sottile per i secondari, blu pieno per l'azione principale di ogni fase), entrambi con `AutoSize`+`Padding`+`MinimumSize` invece di una `Size` fissa in pixel indovinata a mano (altrimenti il testo va a capo e si taglia in verticale se non ci sta nella larghezza scelta). `SecondarioPieno` è la variante senza bordo (sfondo grigio chiaro pieno) per i bottoni secondari sopra le card bianche di `Card`/`FloatBar`, dove il bordo sottile di `Secondario` è troppo poco visibile su sfondo bianco. `Arrotonda` applica angoli arrotondati a un `Control` qualsiasi (bottone o card) via `Region` calcolata su `SizeChanged`, non una volta sola: con `AutoSize` la dimensione finale si conosce solo a layout avvenuto — va chiamata dopo aver fissato le dimensioni finali del controllo (es. dopo `LarghezzaUguale`), altrimenti la `Region` vecchia resta visibile come bordo residuo finché non arriva un repaint completo. `Card` costruisce una card di stato (sfondo/bordo distinti, angoli arrotondati), usata in fase 1 per il riepilogo Database. `FloatBar` costruisce la barra di navigazione "flottante" in fondo alle finestre (card bianca staccata su tutti e 4 i lati, non un footer a tutta larghezza): usata per Avanti/Indietro nel wizard e per Chiudi/Apri cartella raw in `PrtMancantiForm`. `LarghezzaUguale` forza la stessa larghezza e altezza tra due bottoni della stessa barra (es. Avanti/Indietro, che altrimenti avrebbero dimensioni diverse: testi di lunghezza diversa, e il font in grassetto di `Primario` richiede più altezza di quello normale di `Secondario`/`SecondarioPieno`). - **app.ico** — icona dell'app, referenziata da `` nel csproj (icona dell'exe in Esplora risorse/taskbar) e riletta esplicitamente in `Form1.BuildUi()` con `Icon.ExtractAssociatedIcon(Application.ExecutablePath)` per la titlebar, senza copiare il file `.ico` nell'output. Sfondo trasparente (nessuna card bianca), 7 risoluzioni da 16 a 256px. - **PrtMancantiForm.cs** — esito della risoluzione ricorsiva dell'albero componenti: PRT e 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`). - **GuidaForm.cs** — guida interattiva ("Aiuto → Guida"/F1): elenco delle sezioni a sinistra (Panoramica, Dove finiscono i file, Prima di iniziare, le 5 fasi, Ripartire da capo), testo a destra; stessa guida di `docs/guida-utente.md`, il dettaglio tecnico resta solo in questi docs. ## Persistenza - **DB** (`cad_index.db`, SQLite) — vedi tabella `files`/vista `files_ultima_versione` sopra. Sempre `cad_index.db` accanto all'eseguibile (`AppContext.BaseDirectory`, cioè la cartella di installazione): `InizializzaDatabase` carica solo quello, e "Aggiorna indice" lo crea lì se manca. "Apri DB..." carica un altro file solo per la sessione corrente, senza ricordarlo. Radice disco di scansione di default `X:\` (`Form1.RadiceDiscoDefault`, hardcoded). - **Cartella di lavoro** — ricordata tra un avvio e l'altro in `%AppData%/PrepStep/ultima_cartella_lavoro.txt`; se non c'è una preferenza salvata (o punta a una cartella cancellata) si propone la cartella di installazione (`AppContext.BaseDirectory`); cambiabile in qualunque momento da "File → Scegli cartella di lavoro...". Tutti i file generati a valle ci finiscono dentro: il CSV della distinta, `raw/` (CAD dei componenti e sotto-componenti); `step/` non è scritta dall'app ma è dove l'utente esporta gli STEP a mano con Creo Distributed Batch, a partire dai file trascinati da `raw/` in fase 5. ## Installazione `installer/PrepStep.iss` (Inno Setup 6) impacchetta `PrepStep/publish/PrepStep.exe` in un setup **per-utente** (`PrivilegesRequired=lowest`, quindi `{autopf}` = `%LOCALAPPDATA%\Programs`, cartella `PrepStep`): niente admin, e la cartella resta scrivibile — cosa che serve, perché `cad_index.db` e (di default) la cartella di lavoro con `raw/` stanno accanto all'eseguibile (`AppContext.BaseDirectory`, vedi Persistenza). In `C:\Program Files` fallirebbe per un utente normale. Versione del setup letta dall'`exe` (ProductVersion, tolto il `+`), quindi basta cambiare `` nel csproj. L'`AppId` fisso fa riconoscere a Windows le versioni nuove come aggiornamento della stessa app: non va cambiato (`AppGuid` nello script). Se l'app risulta già installata (chiave `…\Uninstall\{AppGuid}_is1` in HKCU), `InitializeSetup` nella sezione `[Code]` chiede se aggiornare o disinstallare (lancia l'`UninstallString`), perché Inno da solo aggiornerebbe sempre; con `/VERYSILENT` non chiede. La disinstallazione rimuove solo i file installati: `cad_index.db`, `raw/`/`step/`/CSV creati accanto all'exe e `%AppData%/PrepStep/` restano. Comandi di build del setup in [`rilascio.md`](rilascio.md). ## Script standalone (`scripts/`) C# file-based apps (.NET 10, `dotnet run scripts/Nome.cs -- arg1 arg2`, nessun `.csproj`, dipendenze extra con `#:package Nome@versione` in testa al file): - **ExtractCreoStrings.cs** — BOM di un `.asm` risolvendo ricorsivamente i sotto-assiemi contro `cad_index.db` con `AssemblyComponentScanner` (via `#:project`, solo codici numerici Pro-E). - **BomViaDb.cs** — come sopra ma con la tokenizzazione generica validata contro il DB, per intercettare anche i nomi alfabetici delle parti commerciali. - **CreoBom.cs** — usa `AsmRecordReader` (stesso lettore esatto della GUI, fase 4, via `#:project`) invece dell'euristica testuale. Risolve i sottoassiemi cercandoli in cartelle locali (`-p`), non contro `cad_index.db` come `ExtractCreoStrings.cs`/`BomViaDb.cs`. - **Analyze.cs** — dump del contesto testo/hex attorno a un pattern in un file binario, per investigare a mano nuovi falsi positivi prima di toccare la regex di `AssemblyComponentScanner`. - **Query.cs** — query SQL ad-hoc contro `cad_index.db` da riga di comando. - **CheckDocs.cs** — controllo dei doc (docs-as-code): link relativi e ancore, `` del csproj uguale all'ultima voce del `CHANGELOG.md`, ogni `.cs` di `PrepStep/` e `scripts/` descritto qui. Exit 1 se qualcosa non torna. > ⚠️ Nota importante di sicurezza: se `dotnet run` viene lanciato dentro `PrepStep/` > (che contiene un `.csproj` di tipo `WinExe`), esegue l'app GUI vera invece dello script > standalone e resta bloccato in attesa che una finestra si chiuda. Lanciare gli script da > una cartella senza `.csproj` (es. la root del repo o `scripts/` stessa). ## Test - **PrepStep.Tests/** (xUnit) — riferimento al progetto principale via `ProjectReference` e `InternalsVisibleTo` (in `PrepStep.csproj`), così i test chiamano direttamente `Indexer.ParseFilename` e `AssemblyComponentScanner.EstraiCodiciReferenziati` senza esporli 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.