# Nav-Fi³ Web – Guida Operativa (Referee & Player Manual)

> **Ultimo Aggiornamento**: 2026-03-22 (v3.8.8 — OAuth Expansion & GCP Ops)
> **Obiettivo**: Definire i flussi di lavoro standard per la gestione di campagne, navi ed economia.

## 1. Mappa delle Relazioni
Il sistema è gerarchico: l'**Utente** possiede una **Campagna** (ruolo **Master**), la Campagna gestisce il tempo e ospita gli **Asset** (Navi). Ogni Asset ha il proprio libro mastro (**Ledger**) dove vengono registrati **Income** (Entrate) e **Cost** (Uscite).

A partire dalla versione 3.4, un utente può anche essere **Player** (giocatore invitato) in campagne di altri utenti. In questo caso, il Player ha accesso in **sola lettura** ai dati della campagna (Asset, Mutui, The Cube), ma **non può modificare, creare o eliminare** risorse.

## 2. Setup: Commissioning & Onboarding
1.  **Context Setup**: Assicurarsi che le tabelle di contesto (Leggi, Ruoli, Categorie) siano popolate tramite `app:context:import`.
2.  **Asset Registration**: Creare la nave definendo classe e specifiche tecniche (JSON).
3.  **Financial Setup**: Se la nave non è pagata interamente, attivare un **Mutuo** (`Mortgage`). La firma del mutuo genera ufficialmente il piano di ammortamento.

## 3. Ciclo Operativo di Missione

### Fase 1: Pianificazione & Context (Smart Forms)
Nav-Fi³ utilizza **Smart Forms** che si adattano al contesto. Quando si registra un'operazione:
1.  **Asset Selection**: Selezionare prima l'Asset (Nave). I dettagli finanziari e i limiti temporali verranno caricati dinamicamente.
2.  **Ledger Linking**: Se l'Asset ha già un conto collegato, il sistema lo blocca automaticamente per prevenire errori. Se è necessario un nuovo conto, appariranno i campi per la creazione rapida.
3.  **Navigation Intelligence**: I campi di posizione (Signing Location, Target Destination, Origin) utilizzano ora un selettore a due livelli (Settore -> Mondo). Selezionando un settore, la lista dei mondi viene filtrata in tempo reale basandosi sui dati ufficiali OTU. Il sistema supporta l'auto-completamento dei dati tecnici (Hex/UWP) anche per inserimenti parziali.

### Fase 2: Esecuzione e Spese (Cost & Logistics)
1.  **Vendor Management**: Durante la registrazione di un `Cost`, è possibile selezionare un Vendor (Compagnia) esistente o inserirne uno nuovo testualmente. In caso di nuovo inserimento, il sistema lo registrerà come entità permanente.
2.  **Trade & Inventory**: Gli acquisti di merci (`TRADE`) richiedono un link a un `FinancialAccount` attivo. La merce rimane in inventario finché non viene liquidata con un `Income` corrispondente.

*   **Receiver**: È il conto dell'Asset che riceve i fondi.

### Fase 3: Gestione Stiva & Logistica (Cargo Hold)
Accessibile direttamente dalla **Tactical Card** dell'Asset tramite il pulsante "Cargo":
1.  **Inventory Tracking**: Visualizzazione densa di tutte le merci in stiva (Trade, Loot, Quest Items).
2.  **Loot & JIT Capacity**: Aggiungendo bottino (`Loot`), se la nave non ha una capacità di stiva definita (0 tons), il sistema richiederà l'inserimento del tonnellaggio del cargo. Questo valore verrà persistito permanentemente nelle specifiche tecniche dell'Asset.
3.  **Liquidation (Liberazione Spazio)**: Vendendo la merce, il sistema marca gli articoli come venduti e **libera istantaneamente lo spazio** in stiva. Questo permette di ricaricare immediatamente nuova merce a bordo.
4.  **Mail Tonnage**: Il peso dei container postali imperiali (`totalMass`) viene ora conteggiato correttamente nel calcolo del carico attuale.

### Fase 4: Navigazione Tattica e Viaggio (Navigation HUD)
Nav-Fi³ offre un sistema di navigazione asincrona per gestire il movimento tra sistemi:
1.  **Initiate Nav-Link**: Dalla pagina di dettaglio della rotta, attivando il link di navigazione si inizializza la sequenza di viaggio. L'interfaccia si trasforma in un HUD tattico.
2.  **Execute Transit**: Il transito tra waypoint (Engagement/Transit/Retrace) avviene senza ricaricare la pagina. 
3.  **Temporal Auto-Sync**: Ogni salto effettuato avanza automaticamente l'orologio della campagna di **7 giorni**, aggiornando istantaneamente la navbar di sistema.
4.  **Real Distance Log**: Le distanze visualizzate sono calcolate in parsec reali tra le coordinate dei sistemi, garantendo che le stime del carburante siano accurate per ogni tratta.

### 4. Procedure Operative (SOP)

#### SOP-FIN-01: Inizializzare la Finanza di una Nave
Ogni Asset registrato **deve** possedere un libro mastro (Financial Account) attivo. Il sistema impedisce l'esistenza di navi prive di copertura contabile.

##### A. Metodo Tattico (Manuale - Raccomandato per Audit)
1.  **Registrazione Asset**: Creare l'Asset (es. "Beowulf") dalla pagina Asset.
2.  **Creazione Conto**: Accedere alla pagina **Financial Accounts** (link in sidebar).
3.  **Nuovo Conto**: Cliccare su "New". 
    - Selezionare l'Asset "Beowulf".
    - Selezionare una banca esistente o scriverne una nuova in `Bank Name`.
    - Inserire il saldo iniziale (`credits`).
4.  **Confirm**: Il conto è ora blindato sull'Asset. **NOTA**: Non potrà essere rimosso singolarmente se non eliminando l'intero Asset.

##### B. Metodo Rapido (Automatico - Deep Scan)
1.  **Safety Protocol**: Il sistema rileva automaticamente se l'Asset è privo di conto durante la creazione di Mortgage, Income o Cost.
2.  **Auto-Settle**: Al salvataggio di un'operazione finanziaria (o della scheda tecnica nave), il sistema genera atomicamente un `FinancialAccount` di default se non ne trova uno esistente (assegnando un istituto di credito generato narrativamente).
3.  **Integrità**: Questo garantisce che ogni nave disponga sempre di un registro su cui annotare le spese di carburante e manutenzione.

> [!TIP]
> **Dove sono i miei soldi?**
> Se i crediti non appaiono nell'Asset, controlla il **Time Cursor**: se la data della transazione è nel futuro rispetto alla data sessione, i soldi sono `PENDING` (non ancora disponibili). Puoi verificare tutti i saldi nella pagina **Financial Account Index**.

---

## 5. Gestione HR e Salari
1.  **Setup**: Assegnare Crew all'Asset e configurare lo stipendio.
2.  **Temporal Trigger**: Il sistema calcola il pro-rata iniziale. I pagamenti successivi avvengono automaticamente ogni 28 giorni imperiali al variare della Data Sessione.

## 6. Chiusura Sessione (Temporal Advance & Sync)
Il Referee ha la responsabilità dell'integrità del log:
1.  **Avanzamento Data**: Quando la data della Campagna viene aggiornata, il sistema esegue la **Sincronizzazione Finanziaria**.
2.  **Post-Processing**: Transazioni `PENDING` diventano `POSTED`. In questa fase, i saldi di cassa degli Asset vengono aggiornati definitivamente.
3.  **Audit**: Eventuali correzioni a transazioni già postate devono essere effettuate tramite storni (`REVERSAL`), non modificando i record originali.

## 7. Glossario UI
*   **Cyan (Abyss)**: Operatività, Liste, Dati tecnici.
*   **Emerald**: Flussi di cassa positivi, Saldi attivi.
*   **Amber**: Dati in attesa (Pending), Scadenze imminenti.
*   **Red**: Debito, Spese, Annullamenti (Void).

## 8. Ruoli e Permessi nelle Campagne Multi-Utente

### 8.1 Definizioni
*   **Master (Proprietario)**: L'utente che ha creato la campagna. Ha accesso completo a tutte le funzionalità.
*   **Player (Giocatore Invitato)**: Un utente invitato dal Master nella campagna. Ha accesso in **sola lettura** con le seguenti restrizioni.

### 8.2 Matrice Permessi per Modulo (v3.5)

| Modulo | Operazione | Master | Player | Note |
|--------|-----------|--------|--------|------|
| **Asset** | Visualizzare lista e dettaglio | ✅ | ✅ | Accesso completo ai dati tecnici |
| **Asset** | Modificare (Strutturale) | ✅ | ❌ | Nome, Classe, Prezzo (Master Only) |
| **Cargo** | Visualizzare stiva e prezzi | ✅ | ✅ | Consultabile dalla Tactical Card |
| **Cargo** | Aggiungere Loot / Liquidare | ✅ | ⚠️ | Permesso **SCA Cargo** richiesto |
| **Finance** | Visualizzare saldi (Accounts) | ✅ | ✅ | "Station Protocol" (View Only per non-SCA) |
| **Finance** | Trasferire fondi / Edit Conto | ✅ | ⚠️ | Riservato a Master o **Capitani** |
| **Finance** | Aggiungere Cost / Income | ✅ | ⚠️ | Permesso **SCA Finance** richiesto |
| **Mortgage** | Visualizzare lista e dettaglio | ✅ | ✅ | - |
| **Mortgage** | Creare nuovo Mutuo | ✅ | ✅ | Form limita la selezione campagna |
| **Mortgage** | Modificare / Firmare / Pagare | ✅ | ❌ | Pulsanti disabilitati + 403 (Master Only) |
| **Mortgage** | Generare PDF | ✅ | ✅ | Documento ufficiale PDF |
| **The Cube** | Visualizzare console e contratti | ✅ | ✅ | Analisi opportunità ammessa |
| **The Cube** | Scan Network / Accettare | ✅ | ❌ | Master Clearance Required (Master Only) |
| **Routes** | Gestire Waypoint / Viaggio | ✅ | ⚠️ | Permesso **SCA Pilot** richiesto |
| **Crew** | Visualizzare lista e dettaglio | ✅ | ✅ | Include crew dei Player della campagna |
| **Crew** | Assegnare alla nave | ✅ | ⚠️ | Master può assegnare chiunque; Player solo i propri personaggi |

## 9. Protocollo d'Invito (SCA)
Il Master può invitare i Player nella propria Campagna tramite un **Invite Code** univoco.
*   **Generazione**: Il codice viene generato automaticamente alla creazione della campagna. Per le campagne legacy, il Master può generarlo manualmente cliccando su **"Generate Code"** nella pagina dei dettagli della missione.
*   **Utilizzo**: I Player inseriscono il codice nella propria Dashboard (`Mission Control`) per unirsi alla campagna e ottenere l'accesso SCA agli Asset autorizzati.
*   **Personnel Invite Protocol**: Unirsi a una campagna è solo il primo passo. Il Master deve poi procedere all'assegnazione dei personaggi all'Asset appropriato e alla configurazione dei **Ruoli Tattici** per sbloccare le funzionalità SCA (`Pilot`, `Cargo`, `Finance`).

### 8.3 Strategia di Protezione UI
La protezione lato client avviene **esclusivamente a livello di pulsante**: i campi del form rimangono interagibili per il Player (può esplorare i dati), ma il pulsante di salvataggio/azione è `disabled` o nascosto. 

La protezione lato server è garantita dai **Voter** Symfony e dalle query filtrate nei **Repository**, che restituiscono HTTP 403 per qualsiasi tentativo di modifica non autorizzato, indipendentemente dallo stato dell'interfaccia.