prep-step/docs/guida-utente.md

# Guida utente

Questa guida descrive, in ordine, tutti i passi da fare in **PrepStep - Cevolani** per
arrivare dalla distinta base esportata dal gestionale ai file STEP pronti, passando per
**Creo Distributed Batch**. Per il dettaglio tecnico di come funziona internamente ogni
fase vedi [`architettura.md`](architettura.md); questa guida si ferma a cosa clicca e
cosa vede l'utente. La stessa sintesi è disponibile anche dentro l'app da **Aiuto → Guida**
(F1).

## Dove finiscono i file

Tutto sta nella **cartella di lavoro**, che di default è la cartella di installazione
`%LOCALAPPDATA%\Programs\PrepStep`:

| Cosa | Dove |
|---|---|
| database `cad_index.db` | sempre nella cartella di installazione |
| CSV di ogni distinta importata | cartella di lavoro |
| `raw/` — file CAD copiati nelle fasi 3-4 | cartella di lavoro |
| `step/` — file STEP esportati da Creo | cartella di lavoro (la indichi tu a Creo) |

Il file `.xls` del gestionale resta dove l'hai preso: l'app lo legge soltanto.

- **Cambiare la cartella di lavoro**: **File → Scegli cartella di lavoro...** (viene ricordata
  agli avvii successivi). Il database resta comunque nella cartella di installazione.
- **Aprire la cartella**: `AppData` è nascosta in Esplora file; scrivi
  `%LOCALAPPDATA%\Programs\PrepStep` nella barra degli indirizzi (vale anche per scegliere
  `step/` in Creo). Dalla fase 4 si apre `raw/` con **Apri cartella raw**.
- **Fare pulizia** (menu **File**): **Pulisci raw e step...** svuota `raw/` e `step/`;
  **Elimina CSV delle distinte...** elimina i CSV, che altrimenti si accumulano uno per
  distinta. Nessuno dei due tocca il database. Entrambi chiedono conferma.
- **Disinstallando** il programma questi file restano: cancellali a mano se non servono più.

## Prima di iniziare

- Serve accesso alla share di rete con i file CAD (di default `X:\`).
- Serve l'estrazione "Distinta Base" dal gestionale (Fata): il file `.xls` così come
  Fata lo salva, con le colonne Componente/Descrizione (foglio `"Distinta Base"`) — va
  lasciato nel formato/estensione in cui viene esportato, senza risalvarlo o convertirlo
  in altri formati prima di usarlo nell'app. Sotto l'estensione `.xls` il contenuto può
  essere XML (SpreadsheetML) o Excel binario vero: l'app riconosce da sola quale dei due
  è, non serve fare nulla di diverso a seconda del caso.
- Se il file segue la convenzione di nome del gestionale (`DBP_<codice>_<timestamp>`),
  l'app aggiunge da sola l'assieme generale come componente in più — non serve fare
  nulla di diverso.
- Se non vuoi usare la cartella di installazione, scegli la **cartella di lavoro**
  ("File → Scegli cartella di lavoro...") prima di importare la distinta: è lì che
  finiscono CSV, `raw/` e, dopo l'esportazione con Creo, `step/`.
- Se la cartella di lavoro è già stata usata per un'altra distinta, conviene **pulire
  `raw/` e `step/`** prima di ripartire ("File → Pulisci raw e step..."): evita di
  confondere i file CAD/STEP della copia precedente con quelli della nuova distinta (il
  "File → Nuovo" descritto più sotto azzera solo lo stato di CSV/griglie dell'app, non
  tocca i file già copiati su disco).

## 1. Database

Se nella cartella di installazione c'è già un database (`cad_index.db`), l'app lo carica
da sola all'avvio: si vede il pallino verde accanto a "Database", il percorso del
file e la data dell'ultimo aggiornamento.

- **Se il pallino è rosso** (nessun database trovato): premi **Aggiorna indice** per
  scansionare la share (`X:\`) e crearne uno nuovo — l'operazione può richiedere qualche
  minuto la prima volta, i giri successivi sono più veloci perché aggiornano solo quello
  che è cambiato.
- **Se hai già un database da un'altra postazione o cartella**: premi **Apri DB...** e
  selezionalo a mano. Vale solo finché non chiudi il programma: al prossimo avvio si riparte
  dal database nella cartella di installazione. Per usarlo sempre, copialo in
  `%LOCALAPPDATA%\Programs\PrepStep` come `cad_index.db`.
- La **cartella di lavoro** non si imposta qui: vedi [Dove finiscono i file](#dove-finiscono-i-file).

Premi **Avanti** quando il database è caricato.

## 2. Importa Distinta Base

- **1. Carica la distinta**: trascina il file `.xls` esportato da Fata nella finestra,
  oppure premi **Scegli file distinta...** e selezionalo da Esplora risorse. Le righe importate
  compaiono nella griglia (Componente/Descrizione) e viene scritto un CSV nella cartella
  di lavoro.
  In alternativa scegli **Lista personalizzata**: digita un codice e premi **Invio** (o
  **Aggiungi**) per inserirlo, ripeti per ogni codice; **Canc** sulla riga selezionata lo
  toglie. La lista non scrive nessun CSV e, passando da una modalità all'altra, viene azzerata
  (con conferma). Inserisci anche l'assieme generale, se serve: qui non viene aggiunto da solo.
- **2. Verifica la presenza dei file sul server**: compare solo dopo un import riuscito
  (o dopo il primo codice aggiunto alla lista personalizzata; ogni modifica della lista
  richiede di rifare la verifica).
  Premila per cercare ogni componente nel database — le righe della griglia si colorano
  di verde (trovato) o rosso (non trovato nell'indice).

**Avanti** si sblocca solo dopo aver premuto **Verifica presenza**, non basta il solo
import: è il modo per accorgersi subito se il database è disallineato
rispetto alla share (es. indice non aggiornato) prima di andare avanti.

## 3. Crea cartella raw

Premi **Crea cartella raw**: per ogni componente della distinta trovato nell'indice,
l'app ne copia il file CAD dalla share nella cartella `raw/` (dentro la cartella di
lavoro). La griglia mostra il percorso CAD copiato per ogni componente.

## 4. Trova componenti referenziati

Gli assiemi (`.asm`) referenziano altri file (sotto-assiemi, parti, componenti soppressi,
riferimenti esterni) che Creo deve poter caricare insieme all'assieme principale, anche
se non compaiono nella distinta del gestionale. Premi **Trova componenti referenziati**:
l'app legge i file `.asm` già in `raw/`, risolve ricorsivamente tutto l'albero e copia
anche quei file in `raw/`.

Si apre una finestra con l'elenco di quanto trovato e copiato (PRT e sotto-assiemi), con
in fondo eventuali codici referenziati che non corrispondono a nessun file indicizzato
(possono essere disegni, componenti davvero mancanti, o falsi positivi della scansione —
non bloccano il lavoro, ma vale la pena controllarli). Da qui puoi anche aprire
direttamente la cartella `raw/` con **Apri cartella raw**.

Questo passo è opzionale se la distinta contiene solo parti singole senza sotto-assiemi:
in quel caso si può passare direttamente alla fase successiva.

## 5. Verifica completezza e Creo Distributed Batch

L'ultima fase mostra l'elenco dei file `.asm` della distinta già presenti in `raw/`,
trascinabili. Da qui il passaggio a Creo è manuale, fuori dall'app:

1. Apri **Creo Distributed Batch** (dal menu Start di Windows, o dal file
   `ptcdbatch.bat` nella cartella `bin` dell'installazione Creo).
2. Crea un nuovo gruppo di attività per l'esportazione STEP (menu **Actions → New Task
   Group**), scegliendo il tipo di attività per l'export STEP — se in azienda è già
   presente un profilo/gruppo predefinito per l'export STEP, riusa quello invece di
   crearne uno nuovo.
3. Aggiungi i file: trascina i `.asm` dalla finestra dell'app (o direttamente da Esplora
   risorse, dalla cartella `raw/`) sul gruppo di attività, oppure sfoglia e selezionali a
   mano da Distributed Batch.
4. Verifica che il gruppo di attività punti al `config.pro`/profilo di export STEP giusto
   (sezione **Configuration Files** del gruppo) — di norma è già impostato una volta sola
   per tutti, non richiede modifiche a ogni giro.
5. Avvia l'elaborazione (**Start**/**Run**): Distributed Batch legge ogni `.asm`, con
   tutto l'albero di sotto-componenti già raccolto in `raw/` nelle fasi 3-4, ed esporta i
   file STEP nella cartella `step/` (dentro la cartella di lavoro, accanto a `raw/`).

I nomi esatti dei menu possono variare leggermente a seconda della versione di Creo e di
come Distributed Batch è già configurato in azienda — questi passi descrivono il flusso
generale (fonte: [documentazione e community PTC](https://www.ptc.com/en/support/article/CS28241));
in caso di dubbio su profili/config già pronti, chiedi a chi ha impostato Distributed
Batch la prima volta.

**Se Distributed Batch fallisce con `[-4] Dati di input non completi`**, quasi sempre
manca un file nell'albero dei componenti — Creo non dice quale. Torna alla fase 4 e
controlla l'elenco dei "non trovati": è il punto di partenza per capire cosa recuperare
prima di riprovare.

## Ripartire con una nuova distinta

Quando devi processare un'altra distinta, usa **File → Nuovo** (Ctrl+N): svuota le griglie e
la verifica delle fasi 2-5 e riporta al passo 2, senza dover ricaricare il database né
cambiare la cartella di lavoro. Non cancella nessun file su disco: CSV, `raw/` e `step/`
restano (vedi sotto per ripulirli).

Per ripulire le cartelle `raw/` e `step/` della cartella di lavoro prima di un nuovo giro
(senza toccare l'indice), usa **File → Pulisci raw e step...**.

Ogni distinta importata lascia un CSV nella cartella di lavoro: per eliminarli tutti usa
**File → Elimina CSV delle distinte...** (i file `.xls` del gestionale non vengono toccati).