# 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** (``/ `` in `PrepStep/PrepStep.csproj`, usato nel titolo della finestra insieme alla versione, ``, 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/`. ```powershell dotnet build -c Release dotnet run -c Release ``` Pubblicazione come eseguibile standalone (single-file, self-contained, Windows x64): ```powershell 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`: ```powershell & "$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`](docs/architettura.md) | il processo delle 5 fasi e la mappa file-per-file | | [`docs/guida-utente.md`](docs/guida-utente.md) | cosa clicca l'utente, passo per passo, fino a Creo Distributed Batch | | [`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/` | | [`docs/README.md`](docs/README.md) | indice Diátaxis di tutti i doc (tutorial, how-to, reference, decisioni) e regola di fonte unica | | [`CHANGELOG.md`](CHANGELOG.md) | storico delle versioni (formato Keep a Changelog); ogni release che cambia `` 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`](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`](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__`), 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`.