# Nav-Fi³ Web – Operational Guide (Referee & Player Manual)

> **Last Updated**: 2026-03-08 (v1.2 — Campaign Access Control)
> **Objective**: Define standard workflows for managing campaigns, assets, and economy.

## 1. Relationship Map
The system is hierarchical: a **User** owns a **Campaign** (role: **Master**), the Campaign manages time and hosts **Assets** (Ships). Each Asset has its own ledger (**Financial Account**) where **Income** and **Costs** are recorded.

Starting from version 3.4, a user can also be a **Player** (invited member) in other users' campaigns. In this case, the Player has **read-only** access to campaign data (Assets, Mortgages, The Cube), but **cannot create, modify, or delete** resources.

## 2. Setup: Commissioning & Onboarding
1.  **Context Setup**: Ensure context tables (Laws, Roles, Categories) are populated via `app:context:import`.
2.  **Asset Registration**: Create the ship by defining its class and technical specifications (JSON).
3.  **Financial Setup**: If the ship is not fully paid, activate a **Mortgage** (`Mortgage`). Signing the mortgage officially generates the amortization schedule.

## 3. Operational Mission Cycle

### Phase 1: Planning & Context (Smart Forms)
Nav-Fi³ uses **Smart Forms** that adapt to the context. When logging an operation:
1.  **Asset Selection**: Select the Asset (Ship) first. Financial details and time constraints will load dynamically.
2.  **Ledger Linking**: If the Asset already has a linked account, the system locks it automatically to prevent errors. If a new account is needed, quick-creation fields will appear.
3.  **Navigation Intelligence**: Position fields (Signing Location, Target Destination, Origin) now use a two-level selector (Sector -> World). Selecting a sector filters the world list in real-time based on official OTU data. The system supports auto-completion of technical data (Hex/UWP) even for partial entries.

### Phase 2: Execution and Expenses (Cost & Logistics)
1.  **Vendor Management**: When logging a `Cost`, you can select an existing Vendor (Company) or enter a new one manually. If entered manually, the system will register it as a permanent entity.
2.  **Trade & Inventory**: Purchasing goods (`TRADE`) requires a link to an active `FinancialAccount`. The goods remain in inventory until liquidated with a corresponding `Income`.

### Phase 3: Cargo Hold & Logistics
Accessible directly from the Asset's **Tactical Card** via the "Cargo" button:
1.  **Inventory Tracking**: Dense visualization of all cargo in the hold (Trade, Loot, Quest Items).
2.  **Loot Registration**: Ability to add recovered loot by defining quantity, estimated value, and origin (via Location Picker).
3.  **Liquidation**: Sales procedure for cargo. Requires selecting the sale location (Sector/World) and applicable local law for transaction legal calculations. Liquidation automatically removes the asset from the hold and generates the related `Income`.

### Phase 4: Tactical Navigation and Travel (Navigation HUD)
Nav-Fi³ offers an asynchronous navigation system to manage movement between systems:
1.  **Initiate Nav-Link**: From the route detail page, activating the navigation link initializes the travel sequence. The interface transforms into a tactical HUD.
2.  **Execute Transit**: Transit between waypoints (Engagement/Transit/Retrace) occurs without reloading the page. 
3.  **Temporal Auto-Sync**: Each jump performed automatically advances the campaign clock by **7 days**, instantly updating the system navbar.
4.  **Real Distance Log**: Displayed distances are calculated in real parsecs between system coordinates, ensuring fuel estimates are accurate for every leg.

### 4. Operating Procedures (SOP)

#### SOP-FIN-01: Initializing Ship Finance
Every registered Asset **must** have an active ledger (Financial Account). The system prevents the existence of ships without accounting coverage.

##### A. Tactical Method (Manual - Recommended for Audits)
1.  **Asset Registration**: Create the Asset (e.g., "Beowulf") from the Asset page.
2.  **Account Creation**: Access the **Financial Accounts** page (sidebar link).
3.  **New Account**: Click "New". 
    - Select Asset "Beowulf".
    - Select an existing bank or enter a new one in `Bank Name`.
    - Enter the initial balance (`credits`).
4.  **Confirm**: The account is now anchored to the Asset. **NOTE**: It cannot be removed individually except by deleting the entire Asset.

##### B. Rapid Method (Automatic - Deep Scan)
1.  **Safety Protocol**: The system automatically detects if the Asset lacks an account during Mortgage, Income, or Cost creation.
2.  **Auto-Settle**: Upon saving a financial operation (or ship Technical Specs), the system atomically generates a default `FinancialAccount` (using a procedurally generated bank name from the narrative system) if no existing account is found.
3.  **Integrity**: This ensures every ship always has a register to record fuel and maintenance costs.

> [!TIP]
> **Where is my money?**
> If credits do not appear in the Asset, check the **Time Cursor**: if the transaction date is in the future relative to the session date, the money is `PENDING` (not yet available). You can verify all balances on the **Financial Account Index** page.

---

## 5. HR & Salary Management
1.  **Setup**: Assign Crew to the Asset and configure their salary.
2.  **Temporal Trigger**: The system calculates the initial pro-rata. Subsequent payments occur automatically every 28 imperial days as the Session Date changes.

## 6. Session Closing (Temporal Advance & Sync)
The Referee is responsible for log integrity:
1.  **Date Advancement**: When the Campaign date is updated, the system performs **Financial Synchronization**.
2.  **Post-Processing**: `PENDING` transactions become `POSTED`. In this phase, Asset cash balances are permanently updated.
3.  **Audit**: Any corrections to posted transactions must be made via reversals (`REVERSAL`), not by modifying original records.

## 7. UI Glossary
*   **Cyan (Abyss)**: Operations, Lists, Technical data.
*   **Emerald**: Positive cash flows, Active balances.
*   **Amber**: Waiting data (Pending), Imminent deadlines.
*   **Red**: Debt, Expenses, Cancellations (Void).

## 8. Roles & Permissions in Multi-User Campaigns

### 8.1 Definitions
*   **Master (Owner)**: The user who created the campaign. Has full access to all features.
*   **Player (Invited Member)**: A user invited by the Master into the campaign. Has **read-only** access with the following restrictions.

### 8.2 Permission Matrix by Module

| Module | Operation | Master | Player |
|--------|-----------|--------|--------|
| **Asset** | View list and detail | ✅ | ✅ |
| **Asset** | Create new Asset | ✅ | ❌ |
| **Asset** | Edit existing Asset | ✅ | ❌ (403 on submit) |
| **Mortgage** | View list and detail | ✅ | ✅ |
| **Mortgage** | Create new Mortgage | ✅ | ✅ (form restricts campaign selection) |
| **Mortgage** | Edit Mortgage (save) | ✅ | ❌ (button disabled + 403) |
| **Mortgage** | Sign / Pay / Set start date | ✅ | ❌ (403) |
| **Mortgage** | Generate PDF | ✅ | ✅ |
| **The Cube** | View console and contracts | ✅ | ✅ |
| **The Cube** | Generate opportunities (Scan Network) | ✅ | ❌ (button disabled) |
| **The Cube** | Accept contracts | ✅ | ❌ (button disabled) |

### 8.3 UI Protection Strategy
Client-side protection is applied **exclusively at the button level**: form fields remain interactive for the Player (they can explore data), but the save/action button is `disabled`. This avoids the complexity of managing `fieldset disabled`, which causes issues with Symfony form widgets (disabled fields do not send their values in POST requests and would require server-side recovery logic).

Server-side protection is guaranteed by Symfony **Voters**, which return HTTP 403 for any unauthorized modification attempt, regardless of the interface state.