prep-step/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Cos'è questo progetto

PrepStep è il nome tecnico del progetto (cartella, namespace, csproj, eseguibile PrepStep.exe); il nome mostrato all'utente finale è Cevolani StepPrep (<Product>/ <AssemblyTitle> in PrepStep/PrepStep.csproj, usato nel titolo della finestra insieme alla versione, <Version>, attualmente 0.1.0). È un'app Windows Forms (.NET 10, WinForms) che indicizza e permette di cercare i file CAD Pro-ENGINEER/Creo contenuti in tutte le cartelle di primo livello di un disco/share di rete (radice di default X:\), salvando i metadati in un DB SQLite locale (cad_index.db). Il flusso a valle (fasi 2-5, vedi sotto) prepara i file raw/ da passare a Creo Distributed Batch per l'esportazione STEP: la app è quindi un pre-processo per quel passaggio, non lo sostituisce.

Comandi

Tutti da eseguire dentro PrepStep/.

dotnet build -c Release
dotnet run -c Release

Pubblicazione come eseguibile standalone (single-file, self-contained, Windows x64):

dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -o publish

PrepStep.Tests/ (xUnit) contiene unit e integration test — vedi dotnet test da dentro quella cartella. Riferimento al progetto principale via ProjectReference + InternalsVisibleTo (in PrepStep.csproj), così i test possono chiamare direttamente Indexer.ParseFilename e AssemblyComponentScanner.EstraiCodiciReferenziati senza esporli come API pubblica.

Architettura

Il programma è tutto in PrepStep/ (nessun altro progetto nella solution — in passato esisteva anche una CLI separata e uno script Python di indicizzazione, entrambi rimossi: ora l'unico programma è questo, con GUI e indicizzazione integrate).

• Program.cs — entry point WinForms standard, avvia Form1.
• Form1.cs / Form1.Designer.cs — finestra principale, costruita come wizard: una sola fase alla volta occupa tutta la finestra (_panelFasi[]/NomiFasi), si avanza con "Avanti" solo quando la fase corrente è pronta (AvantiConsentito). La UI è costruita interamente in codice in Form1.BuildUi() (nessun designer visuale usato). Form1.Designer.cs contiene solo lo scheletro minimo (InitializeComponent/Dispose) generato dal template. Le fasi, in ordine:
  1. Database — carica/aggiorna l'indice, mostra data ultimo aggiornamento; qui vive anche la cartella di lavoro (_cartellaLavoro, mostrata in _lblCartellaLavoro, cambiabile con "Cambia cartella..." → ScegliCartellaLavoro): destinazione di CSV, raw/ per tutte le fasi successive (gli STEP esportati a mano con Creo vanno in step/, dentro la stessa cartella). All'avvio InizializzaCartellaLavoro propone l'ultima usata (ricordata in %AppData%/PrepStep/ultima_cartella_lavoro.txt, stesso pattern di ultimo_db.txt per il DB) se esiste ancora, altrimenti AppContext.BaseDirectory — non dipende da un marker di repo (niente più CLAUDE.md/TrovaRadiceRepo), quindi funziona identica anche sull'exe pubblicato standalone (PrepStep.exe) copiato su un'altra macchina. Qui vive anche "Pulisci raw e step" (manutenzione, non fa parte del flusso a valle).
  2. Importa Distinta Base — DistintaBaseImporter.ConvertiInCsv genera il CSV dei componenti nella cartella di lavoro; se il nome del file segue la convenzione del gestionale (DBP_<codice>_<timestamp>), l'assieme generale viene aggiunto come riga in più nel CSV stesso (il foglio elenca solo i componenti sotto l'assieme, non l'assieme in sé). Da qui in avanti l'assieme generale è un componente come tutti gli altri, nessun caso speciale nel resto del codice.
  3. Crea cartella raw — cerca nell'indice il percorso CAD di ogni componente del CSV (TrovaPercorsiCad) e lo copia in raw/ dentro la cartella di lavoro (CopiaFileTrovati, parallela — vedi docs/copia-raw-parallela.md).
  4. Trova componenti referenziati — legge euristicamente i metadati binari dei .asm già in raw/ (AssemblyComponentScanner) per risolvere ricorsivamente i sotto-assiemi/parti che contengono (RisolviAlberoComponenti), copiandoli anch'essi in raw/.
  5. Verifica completezza — appena si entra nella fase, AggiornaAnteprimaAsm mostra in una ListView a icone i file .asm della distinta importata (esclusi i sotto-assiemi di fase 4) già presenti in raw/ — letti dal filesystem locale, non dall'indice/share — trascinabili (drag&drop, ItemDrag → DoDragDrop con DataFormats.FileDrop) direttamente su Creo o Esplora risorse, per l'esportazione STEP con Creo Distributed Batch. "Verifica completezza assiemi" controlla ricorsivamente (sui percorsi originali in indice, non su raw/) se tutti i sotto-componenti di ogni assieme della distinta sono nell'indice.
• Indexer.cs — logica di scansione del disco e scrittura/aggiornamento del DB SQLite (Indexer.ScanAsync). Cammina tutte le cartelle di primo livello trovate sotto la radice (scoperte dinamicamente con Directory.GetDirectories, non un elenco fisso) con un walk manuale a stack (Walk, più veloce di EnumerateFiles(..., AllDirectories) su share di rete con centinaia di migliaia di file), estrae da ogni nome file il pattern Pro-E <codice>.<tipo>.<versione> via regex, e fa un upsert incrementale riga per riga (confronto per percorso_completo + dimensione + data modifica). Riporta il progresso tramite IProgress<ScanProgress>, marshalato automaticamente sul thread UI. Contiene anche lo schema SQL del DB (tabella files + vista files_ultima_versione, che seleziona solo l'ultima versione per (cartella_radice, codice, tipo_file) usando ROW_NUMBER() OVER (...) — non un self-join con GROUP BY, che su ~200k righe degenera in tempi quasi quadratici).
• ProgressForm.cs — dialog modale mostrato durante l'aggiornamento indice: barra di progresso, conteggi nuovi/aggiornati/invariati/rimossi, tempo trascorso e stima del tempo rimanente (calcolata dal ritmo file/secondo rispetto al totale atteso, preso dal conteggio della scansione precedente salvato nel DB).
• UiStile.cs — stile bottoni condiviso da Form1 e dai dialog secondari (Primario/Secondario, entrambi AutoSize col padding invece di una Size fissa in pixel, per evitare che il testo vada a capo e si tagli quando non ci sta) e Arrotonda per gli angoli dei bottoni "Avanti"/"Indietro" del wizard.
• app.ico — icona dell'app (logo Cevolani + pezzo + STEP, sfondo trasparente), referenziata da <ApplicationIcon> in PrepStep.csproj e riletta a runtime in Form1.BuildUi() via Icon.ExtractAssociatedIcon(Application.ExecutablePath) per la titlebar (stessa icona dell'exe, nessun file duplicato nell'output).

Schema del DB (cad_index.db)

Tabella files: un record per ogni file trovato, con percorso_completo (chiave univoca), cartella_radice, famiglia (primo livello di sottocartella), codice/tipo_file/versione estratti dal nome file, dimensione, data modifica e timestamp dell'ultima scansione (scansionato_il, usato per rilevare ed eliminare i file non più presenti su disco a fine scansione).

Vista files_ultima_versione: stessa struttura, filtrata alla sola versione più recente per codice+tipo.

Percorso del DB

All'avvio la app cerca cad_index.db accanto all'eseguibile o nella working directory corrente; se non lo trova, l'utente può selezionarlo con "Apri DB...". Il bottone "Aggiorna indice" rilancia Indexer.ScanAsync sullo stesso path (radice disco di default X:\, hardcoded in Form1.RadiceDiscoDefault).

Script standalone (scripts/)

scripts/ contiene C# file-based apps (.NET 10, dotnet run scripts/Nome.cs -- arg1 arg2), senza csproj proprio — dipendenze NuGet extra si aggiungono con #:package Nome@versione in cima al file. ExtractCreoStrings.cs e BomViaDb.cs risolvono ricorsivamente l'albero componenti di un .asm contro cad_index.db da riga di comando (stessa logica di Form1.RisolviAlberoComponenti/AssiemeCompleto): entrambi referenziano PrepStep/PrepStep.csproj via #:project (più #:property TargetFramework=net10.0-windows, richiesto perché il progetto principale è WinForms) invece di duplicare l'euristica di estrazione/placement, che vive solo in PrepStep/AssemblyComponentScanner.cs — un'unica fonte di verità condivisa da GUI e script, vedi docs/formato-asm.md. Le due varianti restano distinte solo nel candidato passato a EstraiCodiciReferenziati: ExtractCreoStrings.cs non passa codiciNoti (riconosce solo i codici numerici Pro-E, dalla forma, senza bisogno del DB); BomViaDb.cs lo passa, per intercettare anche i nomi alfabetici delle parti commerciali validati contro l'indice. Analyze.cs dumpa il contesto testo/hex attorno a un pattern in un file binario, per investigare a mano nuovi falsi positivi prima di toccare la regex; Query.cs esegue una query SQL ad-hoc contro cad_index.db da riga di comando.

Il formato binario .asm, l'euristica di estrazione codici e i falsi positivi noti (ID vista ModelView#, self-reference, riferimenti fantasma a codici superati/rinominati — sintatticamente identici a un componente vero, non filtrabili in modo affidabile) sono documentati in docs/formato-asm.md.