# Gigafibre FSM — Data Structures & Customer Flows

> A unified document defining the ERPNext data structure and the "Lead to Live" customer flow architecture.

## 1. ERPNext Data Schema

All operational data revolves around the Customer, connected closely to their physical service location and the equipment provided. 

```text
┌───────────────────────────────────────────────────────────┐
│                        Customer                           │
│  customer_group (Résidentiel/Comm.), legacy_customer_id   │
└──────────┬─────────────────────────┬──────────────────────┘
           │                         │
           ▼                         ▼
┌─────────────────────┐   ┌─────────────────────────┐
│  Service Location   │   │    Sales Invoice         │
│  (delivery address) │   │    Payment Entry         │
│  connection/olt_port│   └─────────────────────────┘
└──────┬──────────────┘
       │
       ├──────────────────────────────────┐
       ▼                                  ▼
┌──────────────────┐            ┌──────────────────────┐
│ Service          │            │ Service Equipment    │
│ Subscription     │            │  (ONT/Routeur/TV)    │
│  (Internet/TV)   │            │  mac/serial/wifi/sip │
└──────────────────┘            └──────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────────────┐
│                Dispatch Job                      │
│  (Tech installs equipment at Service Location)   │
│  Status: Scheduled → In Progress → Completed     │
└──────────────────────────────────────────────────┘
```

---

## 2. The Customer Journey (Lead to Live)

This flow replaces the legacy PHP quote builder. It operates atomically to ensure equipment and ports are correctly reserved.

### Step 1: Address Qualification
- Website hits `/api/address`.
- Queries the `fiber_availability` table (coupled with pg_trgm fuzzy matching against RQA databases).
- Identifies the specific `fibre_id` and checks port availability in real time.

### Step 2: Plan & Price Selection
- Prices dynamically populate based on the `zone_tarifaire` tied to the OLT Port.

### Step 3: Payment Intent (Stripe)
- Stripe Elements capture CC info for a SetupIntent.
- We **do not** charge the card until the Dispatch Job is confirmed by the technician.

### Step 4: Atomic Order Creation
Through `targo-hub` or `n8n`, a successful sign-up generates exactly:
1. `Customer` (Jane Doe)
2. `Service Location` (Address, linked to OLT Port)
3. `Service Subscription` (Internet Plan, TV Package)
4. `Service Equipment` (Empty templates waiting for tech to scan serials)
5. `Dispatch Job` (Triggered for Installation, waiting for tech assignment)

### Step 5: Hardware Auto-Provisioning
1. When the order is generated, custom fields on `Service Equipment` (like `custom_wifi_ssid` and `custom_sip_username`) are prefilled in ERPNext.
2. The technician arrives, installs the TP-Link ONT, and scans its serial/MAC.
3. The ONT boots up and hits the TR-369 server (Oktopus).
4. `targo-hub` acts as the TR-069 proxy, matching the MAC to ERPNext, reading the custom provisioning profile, and automatically injecting the WiFi and SIP credentials onto the modem.

---

## 3. Ops App "Client 360" View

The `ClientDetailPage` in the Ops App acts as a unified console pulling from these relationships.

**It displays:**
- Standard Frappe Customer metadata + Custom Flags (PPA Enabled).
- A map and grid of the `Service Location`.
- Live diagnostic queries to `targo-hub` providing real-time data on the linked `Service Equipment`.
- The historical thread of `Issue` and `Dispatch Job` events.
- Inline Odoo-style editing for rapid support.