0f8d2b0565
Mass refresh — the docs were last touched 2026-04-22, two weeks behind
shipped reality. This commit updates 9 files to reflect current truth.
WHAT CHANGED IN THE PRODUCT (since 22 Apr) THAT THE DOCS NOW REFLECT:
• Oktopus CE / TR-369 stack decommissioned (containers + volumes +
images all removed; broker had filled /dev/sdb with 75 GB of debug
logs and took ERPNext down for 4 days). Hub gates the integration
behind OKTOPUS_DISABLED=1 — modules retained, no-op'd at runtime.
• dispatch.gigafibre.ca (legacy PHP SPA) replaced by an nginx 301
redirect to /ops/#/dispatch.
• Top toolbar of the dispatch module: collapsed to single-color
Lucide icons + ⋯ overflow menu + "Vue principale ▾" + "[👥 N ▾]"
resource type chip (defaults to techs, materials in the dropdown
only when relevant).
• Tech home base / departure point: editable per-tech via 📍 button,
address geocode (Nominatim) or click-on-map picker, right-click
on tech pin opens the same actions. Map defaults centered on
Gigafibre HQ (1867 chemin de la Rivière, Sainte-Clotilde) instead
of downtown Montreal.
• POST /auth/users invite flow on the hub: creates the Authentik
user, sets a temp password, mails it via Mailjet (Authentik's
own recovery flow isn't configured), creates the matching ERPNext
System User. Surfaced in ops Settings → Utilisateurs → Inviter.
• Two Authentik instances clarified as parallel-and-permanent (not
a migration): auth.targo.ca for staff, id.gigafibre.ca for clients.
FILES TOUCHED:
README.md — service table refreshed, arch diagram redrawn (no
Oktopus row), auth section explains the invite flow + two
parallel instances.
docs/architecture/overview.md — new "Decommissioned" section,
correct retirement status for dispatch-app + apps/field, two
Authentik instances explicitly distinguished, dev-gotchas list
rewritten (drops MongoDB AVX, adds log-rotation hard-learned
lesson, adds note about Authentik recovery flow).
docs/architecture/data-model.md — Step 5 hardware provisioning
now describes the GenieACS path (TR-069 Inform → preset push)
instead of the dead TR-369 path.
docs/architecture/module-interactions.md — oktopus.js and
oktopus-mqtt.js entries marked as gated, provision.js note
updated, GenieACS row in external-integrations updated, MQTT
row removed from real-time channels, interaction matrix loses
the Oktopus column and gains an Authentik admin REST cell.
docs/features/dispatch.md — Top bar section completely rewritten
to match the current chrome (left/center/right regions,
single-color Lucide, dropdowns); new Tech home base section
documenting the 📍 + map-pick + right-click flows; retirement
note now reads as a status, not a plan.
docs/features/cpe-management.md — full rewrite. Oktopus migration
plan replaced by a "decommissioned" note + the existing GenieACS
+ modem-bridge architecture as the steady state. TP-Link XX230v
deep-dive sections preserved (still accurate).
docs/README.md, docs/features/README.md, docs/roadmap.md —
intent-table descriptions and live-URLs table corrected.
The docs/archive/ snapshots (2026-04-18, 2026-04-19) are untouched —
they're historical and should remain that way.
82 lines
4.6 KiB
Markdown
82 lines
4.6 KiB
Markdown
# 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 via the tech mobile page.
|
|
3. The ONT boots up and reaches the GenieACS ACS over TR-069 / CWMP for its first Inform.
|
|
4. `targo-hub` matches the MAC to the ERPNext Service Equipment row, fetches the custom provisioning profile, and pushes a GenieACS preset that injects the WiFi and SIP credentials onto the modem on its next Inform cycle.
|
|
|
|
---
|
|
|
|
## 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.
|