> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Accesso studente e contratti: cosa si carica nell'Admin Panel

> Quando crei l'accesso di un nuovo studente carichi contratto (e fatture) nell'Admin Panel della piattaforma. L'attivazione/onboarding è gated sul caricamento del CONTRATTO; le fatture sono opzionali.

Questo è il primo gesto amministrativo dell'onboarding, **prima** di collegare qualsiasi integrazione. Quando **crei l'accesso di un nuovo studente**, nell'**Admin Panel** carichi anche i suoi **documenti**: il **contratto** e (facoltativamente) le **fatture**. È un passaggio che oggi genera confusione nel team, quindi la regola è una sola e netta.

<Warning>
  **Regola unica.** Il **contratto firmato si carica nell'Admin Panel al momento della creazione dell'accesso studente**. L'attivazione/onboarding è **gated sul caricamento del contratto**: niente contratto caricato → niente attivazione. Le **fatture** si caricano **"magari"** (quando ci sono): sono utili ma **non** sono un gate.
</Warning>

## Dove e quando

| | |
| - | - |
| **Dove** | **Admin Panel** della piattaforma (area amministrativa Mattone, non l'area studente). |
| **Quando** | Nello **stesso momento in cui crei l'accesso** dello studente. Non è un passaggio da rimandare "a dopo". |
| **Cosa** | **Contratto** (obbligatorio, è il gate) + **fatture** (opzionali, "magari"). |

<Steps>
  <Step title="Crea l'accesso studente nell'Admin Panel">
    Dall'Admin Panel crei l'utenza dello studente sulla piattaforma (`app.mattone.co`). È qui che nasce lo studente come tenant.
  </Step>

  <Step title="Carica il contratto (gate di attivazione)">
    Nello stesso flusso, **carica il contratto firmato** dello studente. Questo caricamento è ciò che **sblocca l'attivazione**: finché il contratto non è caricato, l'onboarding **non parte**.
  </Step>

  <Step title="Carica le fatture (facoltativo)">
    Se hai già le fatture, caricale pure — tengono i documenti dello studente in ordine e a portata. Ma la loro assenza **non blocca** nulla: sono un "magari", non un gate.
  </Step>
</Steps>

## Perché il contratto è il gate

Il contratto in questione è l'**Addendum "Servizio AI Ospiti"** (Mattone.co LLC ↔ studente): è lui a regolare le condizioni economiche del servizio. Senza contratto caricato non c'è nulla che regoli il servizio, quindi **non si attiva**. Insieme alla **carta a file** (aggiunta dallo studente nella sua area billing), il contratto forma la coppia di gate che abilita il workspace Conduit.

<Note>
  Riepilogo dei **due gate** che abilitano Conduit (vedi [Onboarding · Panoramica](/onboarding/panoramica) e [Step 3 · Conduit](/onboarding/3-conduit)):

  1. **Contratto** firmato **caricato nell'Admin Panel** (questo passo).
  2. **Carta a file** nella piattaforma (la aggiunge lo studente).

  Le **fatture** non rientrano nei gate: sono documentazione opzionale.
</Note>

<Tip>
  Fatto questo passo, prosegui con il resto della **Fase 0** (account piattaforma, allineamento) e poi con il ramo operativo → [Step 1 · Anagrafica & Notion](/onboarding/1-anagrafica-notion).
</Tip>

## Il percorso esatto nell'Admin Panel

Il riquadro non è in cima: sta **in fondo alla riga dello studente**, ed è il motivo per cui non si trova.

**Admin Panel → tab "Utenti" → clicca sulla riga dello studente per aprirla → scorri fino a "Contratto Programma" → *Carica PDF contratto*.**

L'ordine dei blocchi dall'alto è: Accesso Tool → Codice Membro → PMS API Keys → Mattoni sbloccati → **Contratto Programma** → Credenziali. Chi si ferma a "Mattoni sbloccati" non lo vede.

<Warning>
  **"Amministrazione" (`/documenti`) NON è il posto giusto.** Quella è la vista **dello studente**, in **sola lettura**: lì i contratti si guardano, non si caricano. Serve `is_admin = true`: il ruolo `special_role: 'boss'` **non basta**.
</Warning>

## Caricare il contratto NON sblocca da solo

Questo è il punto che fa perdere più tempo. I meccanismi sono **due e distinti**, e vanno capiti separati.

| | Cosa fa | Quando conta |
| - | - | - |
| **"Invia credenziali"** | crea l'accesso e lo manda allo studente | **solo alla PRIMA attivazione** |
| **Program Contract Gate** | tiene la piattaforma in **sola lettura** con banner "Firma il contratto" | per lo studente **già dentro** |

Quindi:

* **Studente nuovo** → carichi il contratto (il pulsante "Invia credenziali" si sblocca) → **premi "Invia credenziali"**. Finché non lo premi, lo studente non entra. Il caricamento da solo non attiva nessuno.
* **Studente già dentro** → il contratto caricato lo riporta in scrittura da solo, senza premere niente.

<Note>
  I due meccanismi coprono momenti diversi: **"Invia credenziali"** è il gate della **prima** attivazione, il **Program Contract Gate** è quello che tiene in sola lettura chi è già dentro. Per uno studente già attivato, il controllo che conta è il secondo.
</Note>

## Se hai caricato il contratto e lo studente è ancora bloccato

Nel 99% dei casi è **`gate_override = 'force_locked'`** sul profilo: un blocco messo a mano.

<Warning>
  **`force_locked` vince su tutto.** Viene letto **prima** del contratto e **prima** dell'interruttore generale del gate: quindi né caricare il PDF né avere il gate automatico spento lo tolgono. Finché c'è quel valore, lo studente resta in sola lettura.
</Warning>

I tre stati possibili di `gate_override`:

| Valore | Effetto |
| - | - |
| *(vuoto)* | decide l'automatico — è lo stato normale |
| `force_open` | apertura forzata: si mette solo su decisione esplicita e **si toglie subito dopo** |
| `force_locked` | **bloccato a mano, a prescindere dal contratto** |

**Procedura quando uno resta bloccato:**

<Steps>
  <Step title="Verifica che il contratto sia davvero caricato">
    Riquadro verde "Contratto caricato" nella riga dello studente.
  </Step>

  <Step title="Controlla il gate_override sul profilo">
    Se vale `force_locked`, è quello che blocca — non il contratto.
  </Step>

  <Step title="Togli il force_locked (svuota il campo)">
    Da lì in poi decide l'automatico: contratto presente → aperto.
  </Step>

  <Step title="Solo se non è mai stato attivato: premi 'Invia credenziali'">
    Se `credentials_sent_at` è vuoto, lo studente non ha mai ricevuto l'accesso: sbloccarlo non basta, va anche attivato.
  </Step>
</Steps>

<Tip>
  Il caso reale del **24/08/2026**: due contratti caricati correttamente alle 14:06 e 14:07, e i due studenti **ancora bloccati** — perché avevano entrambi `force_locked`. Uno è tornato operativo togliendo l'override; l'altro ha avuto bisogno anche dell'invio credenziali, perché non era mai stato attivato.
</Tip>

<CardGroup cols={2}>
  <Card title="Onboarding · Panoramica" icon="arrow-up-right-from-square" href="/onboarding/panoramica">Fase 0 e i due gate di attivazione</Card>
  <Card title="Step 3 · Conduit" icon="arrow-up-right-from-square" href="/onboarding/3-conduit">Dove si verificano contratto + carta prima di attivare</Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.