prep-step/docs/architettura.md

# Architettura di CadSearchGui (Cevolani StepPrep)

Panoramica di tutti i file sorgente e di come collaborano. `CadSearchGui` è il nome
tecnico del progetto; **Cevolani StepPrep** è il nome del programma per l'utente
finale (titolo finestra, icona, versione — vedi `<Version>`/`<Product>` in
`CadSearchGui.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
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/raccoglie gli STEP corrispondenti
(`step_finali/`).

```
Distinta (.xls/.xml)  →  CSV (componente;descrizione)  →  raw/ (CAD copiati dall'indice)
                                                              │
                                          scansione .asm ─────┘  (sotto-assiemi/parti mancanti)
                                                              │
                              step/ (esportati a mano da Creo) → step_finali/ (solo i codici distinta)
```

## 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 |
  | 2 | Importa Distinta Base | selezione file → `ImportaDistinta` → `DistintaBaseImporter.ConvertiInCsv` | Xls/Xml gestionale → CSV componente;descrizione, scritto nella root del repo (`TrovaRadiceRepo`) |
  | 3 | Crea cartella raw | "Crea cartella raw" → `CreaCartellaRaw` | `TrovaPercorsiCad` + `CopiaFileTrovati` (parallela) → `raw/` |
  | 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 e STEP | "Verifica completezza assiemi" → `VerificaCompletezzaAssiemi`; "Crea cartella step_finali" → `GeneraReportStep` | Completezza ricorsiva sui percorsi in indice; confronto con `step/` → `step_finali/`. All'ingresso nella fase, `AggiornaAnteprimaAsm` mostra le icone trascinabili dei `.asm` della distinta già in `raw/` |

  Stato condiviso tra le fasi (campi privati di `Form1`): `_dbPath`, `_percorsoInputCorrente`,
  `_righeCorrenti` (righe del CSV), `_ultimaVerifica` (cache percorsi CAD), `_ultimaCartellaRaw`.

  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
    componenti sia da `AssemblyComponentScanner` per validare i token generici).
  - `CopiaFileTrovati` — copia (in parallelo, grado 6) i file trovati in `raw/`, saltando
    silenziosamente quelli irraggiungibili (share offline/permessi).
  - `PulisciRawEStep` — svuota `raw/`, `step/`, `step_finali/` (manutenzione, richiede conferma).
  - `InizializzaDatabase` / `ScegliDatabase` / `TrovaRadiceRepo` — localizzazione del DB e
    della root del repo (quest'ultima risalendo da `AppContext.BaseDirectory` fino alla
    cartella che contiene `CLAUDE.md`).

## 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
  `<codice>.<tipo>.<versione>` (`ParseFilename`, regex), e fa un upsert incrementale riga per
  riga confrontando `percorso_completo` + dimensione + data modifica. Progresso riportato via
  `IProgress<ScanProgress>` (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).

## Scansione binaria dei `.asm`

- **AssemblyComponentScanner.cs** — estrae euristicamente i codici componente referenziati
  dentro un `.asm` (formato per lo più binario, codici come stringhe ASCII leggibili al suo
  interno). 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
  sul formato, l'euristica e i falsi positivi noti in `docs/formato-asm.md`.

## 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_<codice>_<timestamp>`, 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` (root del repo), 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). `Arrotonda` applica angoli arrotondati via `Region` calcolata su
  `SizeChanged` (non una volta sola: con `AutoSize` la dimensione finale del bottone si
  conosce solo a layout avvenuto), usata sui bottoni "Avanti"/"Indietro" del wizard.
- **app.ico** — icona dell'app, referenziata da `<ApplicationIcon>` 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`).
- **ReportCompletezzaForm.cs** — per ogni assieme della distinta, se tutti i suoi componenti
  (ricorsivamente fino ai PRT) sono nell'indice (✓/✗/? per "non trovato").
- **ReportStepForm.cs** — per ogni componente della distinta, `EsitoStep`: `Creato` (STEP
  trovato e copiato), `StepMancante` (CAD in indice ma STEP non esportato),
  `ComponenteNonTrovato` (nemmeno il CAD è in indice).

## Persistenza

- **DB** (`cad_index.db`, SQLite) — vedi tabella `files`/vista `files_ultima_versione` sopra.
  Percorso: cercato accanto all'eseguibile o nella working directory all'avvio; altrimenti
  selezionabile con "Apri DB...". Radice disco di scansione di default `X:\`
  (`Form1.RadiceDiscoDefault`, hardcoded).
- **File su disco**, tutti nella root del repo (non nella cartella dell'eseguibile): il CSV
  della distinta, `raw/` (CAD dei componenti e sotto-componenti), `step/` (STEP esportati a
  mano da Creo, input), `step_finali/` (STEP dei soli codici della distinta, output).

## 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` (stessa logica di `AssiemeCompleto` in Form1, 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.
- **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.

> ⚠️ Nota importante di sicurezza: se `dotnet run` viene lanciato dentro `CadSearchGui/`
> (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

- **CadSearchGui.Tests/** (xUnit) — riferimento al progetto principale via `ProjectReference`
  + `InternalsVisibleTo` (in `CadSearchGui.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`.