# Guida al sistema — Gestione recruiting nel pannello admin

## Panoramica

Il pannello admin di Supernova integra un modulo recruiting completo accessibile dalla sezione **Recruiting → Candidature**. Consente di gestire l'intero ciclo di vita di un candidato: dall'acquisizione alla firma del contratto, con tracciabilità completa, valutazioni strutturate e raccolta digitale dell'anagrafica.

---

## 1. Accesso all'area recruiting

Dal menu laterale aprire il gruppo **Recruiting** e selezionare **Candidature**. La sezione mostra la tabella di tutti i candidati ricevuti (massimo 500, ordinati per data di candidatura decrescente).

---

## 2. La tabella candidature

### Colonne principali

| Colonna | Descrizione |
|---|---|
| Nome / Cognome | Nome del candidato. Se presente il badge **✓ Anagrafica** (verde), il candidato ha completato il form di onboarding. |
| Ruolo | Posizione per cui si è candidato. |
| Esperienza | Livello di esperienza dichiarato. |
| Stato pipeline | Fase corrente nel processo di selezione (vedi §4). |
| Recruiter | Responsabile assegnato alla candidatura. |
| Esito prequal. | Esito della fase di screening (Pending / Idoneo / Riserva / Non idoneo). |
| Data prequal. | Data del primo contatto. |
| Esito finale | Esito conclusivo della selezione. |
| Data esito | Data della decisione finale. |
| Score | Punteggio ponderato dalla scorecard di valutazione. |

### Filtri disponibili

In testa alla tabella sono disponibili i filtri: **testo libero** (nome, cognome, email), **ruolo**, **esperienza**, **stato pipeline**, **recruiter**, **esito screening**, **esito finale**, **campagna di provenienza**. Il pulsante **Reset filtri** ripristina tutti i valori predefiniti.

### Nuova candidatura manuale

Premere il bottone **+ Nuova candidatura** in alto a destra per inserire un candidato non arrivato dal sito. Compilare i campi obbligatori (nome, cognome, email, ruolo) e opzionalmente caricare il CV.

---

## 3. Il menu azioni (⋮)

Ogni riga della tabella ha un bottone **⋮** (tre puntini verticali) che apre un menu contestuale con le azioni disponibili per quel candidato.

| Voce | Disponibilità | Azione |
|---|---|---|
| **Modifica anagrafica** | Sempre | Apre il pannello di modifica dati personali, residenza, documento, IBAN e CV. |
| **Valutazione / pipeline** | Sempre | Apre il modale di gestione pipeline, colloqui, scorecard ed esito finale. |
| **Invia link anagrafica** | Solo se stato = *Proposta accettata* | Genera e invia via email al candidato il link per compilare il form di onboarding. |
| **Visualizza CV** | Sempre visibile | Se il CV è presente, apre l'anteprima (PDF inline o download per altri formati). Se non è stato caricato alcun CV, la voce appare in grigio con la dicitura **CV non presente** e non è cliccabile. |
| **Documenti anagrafica** | Solo se anagrafica completata | Mostra i documenti caricati dal candidato (fronte/retro documento identità, codice fiscale). |
| **Elimina** | Sempre | Elimina definitivamente la candidatura (azione irreversibile). |

---

## 4. Pipeline di selezione

### Gli stati della pipeline

```
Nuovo → Prequalifica → Colloquio 1 → [Colloquio 2] → Proposta → Proposta accettata → Assunto
                                                                                        ↕
                                                               Non idoneo / Riserva (terminali)
```

| Stato | Significato |
|---|---|
| **Nuovo** | Candidatura appena ricevuta, non ancora gestita. |
| **Prequalifica** | In corso o completato lo screening telefonico. |
| **Colloquio 1** | Primo colloquio strutturato completato. |
| **Colloquio 2** | Secondo colloquio decisionale (facoltativo). |
| **Proposta** | Proposta contrattuale inviata al candidato. |
| **Proposta accettata** | Il candidato ha accettato. Si sblocca l'invio del link di onboarding. |
| **Assunto** | Inserimento formalizzato. |
| **Non idoneo** | Processo concluso negativamente (terminale). |
| **Riserva** | Candidato interessante ma non selezionato ora (terminale). |

### Regole di progressione

- Il **Colloquio 2 è facoltativo**: è possibile passare direttamente da Colloquio 1 a Proposta.
- Gli stati **Assunto** e **In formazione** come esito finale sono disponibili solo se la pipeline è in *Proposta accettata* o *Assunto*. Il sistema blocca combinazioni incoerenti.
- Lo stato pipeline si modifica nel modale **Valutazione / pipeline**. Quando si seleziona uno stato terminale (*Non idoneo*, *Riserva*, *Assunto*) l'esito finale viene sincronizzato automaticamente con un avviso toast.

### Step tracker visivo

In cima al modale di valutazione è visibile un **tracker grafico** della pipeline che mostra:
- **Grigio** — step non ancora raggiunto.
- **Crimson pieno** — step completato.
- **Crimson pulsante** — step corrente.
- **Viola** — step *Proposta accettata* (milestone chiave).
- **Verde** — step *Assunto*.

---

## 5. Modale valutazione e pipeline

Il modale si apre tramite il menu ⋮ → **Valutazione / pipeline**. È strutturato in tre aree principali.

### Action panel — bottoni contestuali

In cima al modale (sotto il tracker visivo della pipeline) compare l'**action panel**: una barra con i bottoni disponibili per il passaggio successivo, calcolati automaticamente in base allo stage corrente.

| Stage corrente | Bottoni disponibili |
|---|---|
| Nuovo | Avvia prequalifica |
| Prequalifica | Promuovi a colloquio · Metti in riserva · Scarta |
| Colloquio 1 | Colloquio 2 · Vai a Proposta · Scarta · Rinuncia candidato |
| Colloquio 2 | Vai a Proposta · Scarta · Rinuncia candidato |
| Proposta | Proposta accettata · Candidato rinuncia · Proposta non accettata |
| Proposta accettata | Assumi · In formazione |
| Stato terminale | Badge di stato + link "Riapri candidatura" |

Cliccare un bottone aggiorna in un'unica operazione `pipeline_status`, `screening_outcome` e `final_outcome` in modo coerente — non è necessario aggiornare i tre campi manualmente.

**Azioni che richiedono nota obbligatoria** (evidenziate in rosso/ambra/grigio): quando si clicca su *Scarta*, *Metti in riserva*, *Rinuncia candidato*, *Proposta non accettata*, *Assumi* o *In formazione*, gli altri bottoni si opacizzano e appare un campo di testo inline. Il bottone **Conferma** resta disabilitato finché la nota non è compilata. La nota viene automaticamente salvata in `Note finali`.

**Riapri candidatura**: se lo stato è terminale, il link *Riapri candidatura* riporta il candidato allo stato *Nuovo* resettando tutti e tre i campi di stato. Usare con cautela.

### Colonna sinistra — dati operativi

- **Recruiter** — responsabile assegnato alla candidatura.
- **Date contatto/colloqui** — data primo contatto (compilata automaticamente al clic su *Avvia prequalifica*), data Colloquio 1, data Colloquio 2.
- **Note prequal.** — annotazioni della fase di screening telefonico.
- **Campagna** — associa la candidatura a una campagna di acquisizione.

### Colonna destra — scorecard e motivazione

Selezionare il tipo di scorecard (**Agenti**, **Operatori** o **Custom**) e compilare i punteggi per ogni dimensione. Il sistema calcola automaticamente lo **score ponderato** mostrato nella tabella.

Il campo **Motivazione / Note finali** raccoglie le note di chiusura inserite tramite l'action panel.

### Impostazioni avanzate (override manuale)

In fondo al modale è disponibile la sezione **Impostazioni avanzate** (collassabile, visibile cliccando il chevron). Contiene i tre dropdown originali per impostare manualmente `Stato pipeline`, `Esito prequal.` e `Esito finale`. Da usare solo per correzioni o migrazione di dati storici — in uso normale preferire sempre i bottoni contestuali.

### Errori e validazioni
Se il form presenta incongruenze (es. data colloquio 2 mancante mentre lo stato è *Colloquio 2*, o esito finale incompatibile con la pipeline) apparirà un pannello di errori sopra il footer. Il salvataggio è bloccato fino alla risoluzione.

---

## 6. Modifica anagrafica

Il modale **Modifica anagrafica** consente di aggiornare i dati personali del candidato compilati in fase di candidatura o integrati successivamente.

### Dati disponibili

- **Dati personali** — codice fiscale, data e luogo di nascita.
- **Residenza** — indirizzo completo con autocompletamento comune/CAP.
- **Domicilio** — attivabile con la spunta *"Il domicilio è diverso dalla residenza"*.
- **Dati bancari** — IBAN per accredito stipendio.
- **Documento d'identità** — tipo, numero, ente emittente, date di rilascio e scadenza.
- **CV** — possibilità di sostituire il file caricato dal candidato (formati accettati: PDF, DOC, DOCX; dimensione massima **5 MB**).

### Autocompletamento indirizzi
I campi comune sono collegati a un archivio di tutti i comuni italiani con relativi CAP. Selezionare prima la **provincia** dal menu a tendina, poi digitare o scegliere il **comune** dalla lista filtrata. Il CAP si compila automaticamente.

---

## 7. Processo di onboarding digitale

### Quando si attiva

Il link di onboarding diventa disponibile (voce nel menu ⋮) quando lo stato pipeline è **Proposta accettata**.

### Invio del link

1. Aprire il menu ⋮ → **Invia link anagrafica**.
2. Verificare l'indirizzo email pre-compilato.
3. Premere **Invia link**.

Il sistema genera un token sicuro (valido **7 giorni**) e invia al candidato un'email con il link personalizzato. L'email conferma l'avvio del rapporto di lavoro e invita a completare il form.

### Cosa compila il candidato

Il candidato accede al link senza bisogno di login e trova un form suddiviso in sezioni:
- Dati anagrafici (codice fiscale, data/luogo di nascita)
- Residenza e domicilio (con autocompletamento comuni)
- Dati bancari (IBAN)
- Documento d'identità (tipo, numero, ente, date)
- Caricamento documenti (fronte/retro documento identità, codice fiscale/tessera sanitaria) — anche con foto da smartphone

Il form è pre-compilato con i dati già presenti in anagrafica. Il candidato può rientrare e modificare fino alla scadenza del link.

### Completamento

Quando il candidato invia il form, nella tabella candidature compare il badge verde **✓ Anagrafica** accanto al nome.

### Visualizzazione documenti

Aprire il menu ⋮ → **Documenti anagrafica**. Compare una griglia con un riquadro per ogni documento caricato:
- Anteprima thumbnail per le immagini (JPG, PNG, WebP)
- Icona PDF per i documenti in formato PDF
- Bottoni **Visualizza** (viewer full-screen) e **Scarica**

---

## 8. Data retention (GDPR)

La sezione **Recruiting → Data Retention** gestisce l'anonimizzazione automatica dei dati personali dei candidati, in conformità all'art. 5 par. 1 lett. e) GDPR e all'art. 111-bis D.Lgs. 196/2003.

### Tempistiche di conservazione

| Stato pipeline | Periodo massimo | Decorrenza |
|---|---|---|
| Non idoneo, Nuovo, Prequalifica | **6 mesi** | Dal più recente tra data ricezione e ultimo aggiornamento |
| Colloquio 1/2, Proposta, Proposta accettata (senza esito) | **6 mesi** | Dall'ultimo aggiornamento |
| Riserva | **12 mesi** | Dall'ultimo aggiornamento |
| **Assunto** | **Esente** | I dati passano alla gestione HR |

### Cosa viene eliminato

All'anonimizzazione il sistema:

- Sostituisce con `[ANONIMIZZATO]` i campi: nome, cognome, telefono, messaggio, note screening, note finali, codice fiscale, luogo e provincia di nascita, indirizzo/comune/provincia/CAP di residenza e domicilio, IBAN, tipo/numero/ente documento
- Imposta a `NULL` i campi: email (→ indirizzo fittizio non valido), data di nascita, date documento, payload scorecard
- **Elimina dallo storage esterno** il CV caricato e tutti i documenti caricati tramite onboarding (fronte/retro documento identità, codice fiscale)
- Elimina i token di onboarding associati
- Azzera il flag `anagrafica_completata`

### Cosa viene conservato

Rimangono intatti i dati statistici: stato pipeline, esito finale, punteggio scorecard, date dei colloqui, ruolo, fonte di provenienza, campagna, **stage di chiusura** (`pipeline_stage_at_close`). Questi consentono di mantenere le metriche aggregate senza identificare il candidato.

### Controlli disponibili nel pannello

- **Interruttore ciclo automatico** — abilita/disabilita l'esecuzione ogni 24 ore.
- **Esegui ciclo ora** — avvia l'anonimizzazione on-demand (disponibile solo a ciclo automatico attivo).
- **Candidature in scadenza** — tabella con i candidati che raggiungeranno la soglia nei prossimi 30 giorni, con data di scadenza stimata evidenziata in rosso.

---

## 9. Coerenza pipeline / esito finale

Usando i **bottoni contestuali** (action panel) la coerenza tra i tre campi è gestita in automatico — ogni azione aggiorna tutti i campi necessari in una sola operazione.

Usando il pannello **Impostazioni avanzate** (dropdown manuali) il backend applica comunque le seguenti regole e blocca combinazioni contraddittorie:

| Esito finale | Stato pipeline richiesto |
|---|---|
| Assunto | Proposta accettata o Assunto |
| In formazione | Proposta accettata o Assunto |
| Rinuncia / Riserva / Non idoneo | Qualsiasi |
| Qualsiasi esito ≠ Pending | Richiede nota obbligatoria in *Note finali* |

Il sistema blocca il salvataggio mostrando un errore esplicativo.

### Analytics di funnel — Stage chiusura

Ogni volta che una candidatura viene chiusa tramite i bottoni contestuali, il sistema salva automaticamente in `pipeline_stage_at_close` lo stage in cui si trovava il candidato al momento della chiusura (utile per rispondere a "dove perdiamo più candidati?"). Il campo è esportabile via CSV (colonna **Stage Chiusura**).

---

## 10. Export CSV

Il bottone **Esporta CSV** nella barra degli strumenti esporta tutte le candidature visibili (max 500, rispettando i filtri attivi). Il file è in formato UTF-8 con BOM per compatibilità Excel.

| Sezione | Colonne |
|---|---|
| Anagrafica | Cognome, Nome, CF, Data nascita, Luogo nascita, Prov. nascita |
| Contatti | Email, Telefono, IBAN |
| Residenza | Indirizzo, Comune, Provincia, CAP |
| Domicilio | Diverso da residenza, Indirizzo, Comune, Provincia, CAP |
| Documento | Tipo, Numero, Rilasciato da, Data rilascio, Scadenza |
| Candidatura | Ruolo, Esperienza, Smart work, Canale, Campagna, Data |
| Recruiting | Pipeline, Recruiter, Score, Esito Prequal., Data Prequal., Esito Finale, Data Esito, **Stage Chiusura** |
| Extra | Anagrafica Compilata, Note Finali |

> Il campo Telefono viene normalizzato rimuovendo il prefisso `+39`/`0039` per evitare che Excel lo interpreti come formula.

---

## 11. Flusso operativo consigliato

```
1. Candidatura ricevuta (stato: Nuovo)
   ↓
2. Screening CV → aprire modale → clic "Avvia prequalifica"
   → first_contact_at impostata automaticamente all'ora locale
   ↓
3. Telefonata prequalifica → clic "Promuovi a colloquio" (idoneo)
   oppure "Metti in riserva" / "Scarta" con nota obbligatoria
   ↓
4. Colloquio 1 → inserire data colloquio → compilare scorecard
   → clic "Colloquio 2" oppure direttamente "Vai a Proposta"
   ↓
5. [Facoltativo] Colloquio 2 → inserire data → clic "Vai a Proposta"
   ↓
6. Proposta contrattuale → clic "Proposta accettata"
   → Inviare link onboarding al candidato (menu ⋮)
   ↓
7. Candidato compila form → badge ✓ Anagrafica compare in tabella
   → Verificare documenti caricati (menu ⋮ → Documenti anagrafica)
   ↓
8. Formalizzazione → clic "Assumi" con nota → Salva
   (richiede scorecard completa con score)
```

---

*Documento ad uso interno — Supernova S.r.l.*