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 è PrepStep - Cevolani (<Product>/ <AssemblyTitle> in PrepStep/PrepStep.csproj, usato nel titolo della finestra insieme alla versione, <Version>, attualmente 1.0.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

Setup di installazione per-utente (%LOCALAPPDATA%\Programs\PrepStep, niente admin), dalla root del repo dopo il publish — dettagli in README.md e docs/architettura.md:

& "$env:LOCALAPPDATA\Programs\Inno Setup 6\ISCC.exe" installer\PrepStep.iss

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.

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	il processo delle 5 fasi e la mappa file-per-file
docs/guida-utente.md	cosa clicca l'utente, passo per passo, fino a Creo Distributed Batch
docs/formato-asm-record.md	parser esatto dei record .asm, con §7 per i casi limite
docs/formato-asm.md	euristica testuale di fallback
docs/db-cad-index.md	schema e vista di cad_index.db
docs/copia-raw-parallela.md	parallelizzazione della copia in raw/
docs/README.md	indice Diátaxis di tutti i doc (tutorial, how-to, reference, decisioni) e regola di fonte unica
CHANGELOG.md	storico delle versioni (formato Keep a Changelog); ogni release che cambia <Version> nel csproj aggiunge qui la sua voce

I doc sono trattati come codice: stanno in git e si verificano con dotnet run scripts/CheckDocs.cs (link, versione/CHANGELOG, copertura di architettura.md) e npx markdownlint-cli2 (config .markdownlint-cli2.jsonc) — da lanciare prima di ogni commit che tocca i doc. Organizzazione (Diátaxis) e regola di fonte unica: docs/README.md.

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/ (accanto ci sono solo i test PrepStep.Tests/, gli script scripts/ e il setup installer/). Dettaglio completo file-per-file in docs/architettura.md; qui solo il flusso che conta per capire il prodotto.

Form1.cs è un wizard a 5 fasi (una sola visibile alla volta, _panelFasi[], si avanza con "Avanti" solo se AvantiConsentito), UI costruita interamente in codice (BuildUi, nessun designer visuale):

1. Database — carica/aggiorna cad_index.db (Indexer.ScanAsync, radice disco di default X:\ hardcoded in RadiceDiscoDefault); un pallino verde/rosso accanto al titolo indica se un DB è caricato. La cartella di lavoro (destinazione di CSV/raw//step/) non è più mostrata qui — proposta dall'ultima usata o dalla cartella di installazione se non c'è ancora nulla di salvato, cambiabile in qualunque momento da "File → Scegli cartella di lavoro..." — vedi docs/db-cad-index.md per il dettaglio di schema e percorso del DB (sempre cad_index.db nella cartella di installazione; "Apri DB..." vale solo per la sessione).
2. Importa Distinta Base — DistintaBaseImporter.ConvertiInCsv genera il CSV componente;descrizione nella cartella di lavoro (da file scelto o trascinato); se il file segue la convenzione del gestionale (DBP_<codice>_<timestamp>), aggiunge l'assieme generale come riga in più (da quel momento è un componente come tutti gli altri, nessun caso speciale nel resto del codice). Il bottone "Verifica presenza" compare solo dopo un import riuscito e cerca i componenti nell'indice (VerificaCodiciNelDb, righe colorate in verde/rosso in griglia): è quello — non il solo import — a sbloccare "Avanti" (AvantiConsentito).
3. Crea cartella raw — TrovaPercorsiCad + CopiaFileTrovati (parallela, vedi docs/copia-raw-parallela.md) copiano in raw/ i file CAD dei componenti del CSV trovati nell'indice.
4. Trova componenti referenziati — legge i .asm in raw/ per risolvere ricorsivamente 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). 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).

Menu in cima alla finestra: "File → Nuovo" (Ctrl+N) azzera lo stato delle fasi 2-5 per ripartire con una nuova distinta, senza toccare DB/cartella di lavoro della fase 1 (va volutamente alla fase 2, non alla 1: quei dati restano quelli già caricati); "File → Scegli cartella di lavoro..." cambia la cartella di CSV/raw//step/ in qualunque momento; "File → Pulisci raw e step..." svuota le cartelle raw//step/ nella cartella di lavoro (non tocca l'indice); "File → Elimina CSV delle distinte..." elimina i *.csv generati in fase 2, che altrimenti si accumulano uno per distinta nella cartella di lavoro; "Aiuto → Guida" (F1) apre una sintesi interattiva delle 5 fasi (GuidaForm.cs).

Script standalone (scripts/)

scripts/ contiene C# file-based apps (.NET 10, dotnet run scripts/Nome.cs -- arg1 arg2, lanciati dalla root del repo — non da dentro PrepStep/, che ha un .csproj WinExe: dotnet run lì avvia la GUI vera invece dello script). Elenco e dettaglio di ciascuno in docs/architettura.md.

Il pattern da preservare: gli script referenziano PrepStep/PrepStep.csproj via #:project invece di duplicare la logica di lettura dei .asm, che vive solo nel progetto principale — un'unica fonte di verità condivisa da GUI e script. Due famiglie distinte, non intercambiabili:

• ExtractCreoStrings.cs/BomViaDb.cs usano AssemblyComponentScanner (euristica testuale, docs/formato-asm.md) e risolvono i sottoassiemi contro cad_index.db.
• CreoBom.cs usa AsmRecordReader (parser esatto dei record binari, docs/formato-asm-record.md, condiviso con la GUI in fase 4) e risolve i sottoassiemi cercandoli in cartelle locali (-p), non contro cad_index.db.