gigafibre-fsm/docs/FIELD-APP-WIZARD-UX.md

Field Tech App — Wizard UX & Form Customizer

Design Principles

1. Minimal inputs per screen — Techs are manual workers, not desk jockeys. Max 2-3 fields per step.
2. Carousel/swipe navigation — Next/Back with swipe gestures, not scrolling a long form.
3. Big touch targets — Fat fingers in work gloves. Buttons 48px+ height, inputs 56px+.
4. Auto-advance — When a field is selected (like equipment_type), auto-advance to next step.
5. Offline-first — Everything queued if no signal. Sync indicator always visible.
6. Customizable — Admin can add/remove/reorder steps via an Odoo Studio-like builder.

---

Wizard Component Architecture

Core: WizardCarousel.vue

A reusable carousel-based wizard that renders steps from a JSON definition:

<WizardCarousel
  :steps="wizardSteps"
  :context="{ job, customer, location }"
  @complete="onComplete"
  @cancel="onCancel"
/>

Each step is a self-contained screen rendered in a q-carousel-slide:

• Swipe left/right to navigate
• Bottom progress dots
• "Suivant" / "Précédent" buttons (large, thumb-friendly)
• Step counter: "Étape 2/5"

Step Definition Schema

{
  "id": "equipment_type",
  "title": "Type d'équipement",
  "icon": "router",
  "fields": [
    {
      "name": "equipment_type",
      "type": "select-cards",
      "label": "Quel équipement?",
      "options": [
        { "value": "ONT", "label": "ONT", "icon": "settings_input_hdmi", "color": "blue" },
        { "value": "Routeur", "label": "Routeur WiFi", "icon": "wifi", "color": "green" },
        { "value": "Décodeur TV", "label": "Décodeur TV", "icon": "tv", "color": "purple" },
        { "value": "Téléphone IP", "label": "Téléphone", "icon": "phone", "color": "orange" }
      ],
      "auto_advance": true
    }
  ],
  "visible_if": null,
  "required": true
}

Field Types

Type	Render	Use Case
select-cards	Big tappable cards with icons	Equipment type, status, connection type
text	Single large input	Serial number, name
scan	Camera button → barcode scanner	Serial, MAC address
photo	Camera button → photo capture	Equipment photo, site photo
signature	Touch signature pad	Customer sign-off
toggle	Large yes/no toggle	Signal OK?, WiFi working?
notes	Textarea (expandable)	Completion notes
date	Date picker	Schedule date
search	Autocomplete search	Customer lookup
checklist	List of checkable items	Installation checklist
info	Read-only display card	Summary, confirmation

---

Example Wizards

1. Installation Completion Wizard

When tech taps "Compléter" on a Dispatch Job:

Step 1: "Équipements installés" [checklist]
  ☐ ONT branché et signal OK
  ☐ Routeur WiFi configuré
  ☐ Décodeur TV branché (if TV service)
  ☐ Téléphone IP testé (if phone service)

Step 2: "Numéros de série" [scan]
  → Camera opens, scan ONT barcode
  → Auto-detected: RCMG19E0AB57
  → "Suivant" button

Step 3: "Signal ONT" [toggle + text]
  Signal OK? [OUI / NON]
  Niveau signal: [-20 dBm] (optional)

Step 4: "WiFi" [toggle]
  Client connecté au WiFi? [OUI / NON]
  SSID affiché: "Gigafibre-Tremblay"

Step 5: "Photo du boîtier" [photo]
  📸 Prendre une photo

Step 6: "Signature client" [signature]
  Le client confirme que le service fonctionne

Step 7: "Résumé" [info]
  ✓ ONT: RCMG19E0AB57
  ✓ Signal: -18.5 dBm
  ✓ WiFi: OK
  ✓ Photo: 1 prise
  ✓ Signé par: Jean Tremblay
  [Confirmer l'installation]

2. Equipment Scan & Link Wizard

When tech scans a barcode (from ScanPage or Job context):

Step 1: "Scanner" [scan]
  📸 Scanner le code-barres
  → Detected: RCMG19E0AB57

Step 2: "Type" [select-cards]
  ONT / Routeur / Décodeur / Téléphone
  → Tap "ONT" → auto-advance

Step 3: "Confirmer" [info]
  Serial: RCMG19E0AB57
  Type: ONT
  Client: Jean Tremblay (from job context)
  Adresse: 123 rue Principale
  [Lier à ce client]

3. Repair/Diagnostic Wizard

Step 1: "Problème signalé" [info]
  Ticket: "Pas d'internet depuis hier"
  Client: Jean Tremblay
  Adresse: 123 rue Principale

Step 2: "Signal ONT" [toggle + text]
  Signal présent? [OUI / NON]
  Niveau: [-XX dBm]

Step 3: "Test WiFi" [toggle]
  WiFi fonctionne? [OUI / NON]

Step 4: "Action prise" [select-cards]
  Redémarrage / Remplacement ONT / Remplacement routeur / Reconnexion fibre / Autre

Step 5: "Nouvel équipement" [scan] (if replacement)
  Scanner le nouveau serial

Step 6: "Notes" [notes]
  Détails supplémentaires...

Step 7: "Résultat" [toggle]
  Service rétabli? [OUI / NON]
  [Fermer le ticket]

---

Form Customizer (Odoo Studio-like)

Concept

An admin page in the Ops app (/ops/form-builder) that lets managers customize the tech wizard steps without code changes.

How It Works

1. Wizard Templates stored as JSON documents in ERPNext (new doctype: Wizard Template)
2. Each template = ordered list of steps with field definitions
3. Admin UI = drag-and-drop step editor:
   • Add step (from field type library)
   • Reorder steps (drag handle)
   • Edit step properties (label, options, required, visibility condition)
   • Remove step
   • Preview on mock phone screen
4. Templates linked to job types: Installation, Réparation, Maintenance, Retrait, etc.
5. Field app fetches the template for the current job type and renders it dynamically

Wizard Template Doctype

Wizard Template
  name: "Installation FTTH"
  job_type: "Installation"
  is_active: Check
  steps: (child table: Wizard Template Step)
    - step_order: 1
      step_id: "equipment_checklist"
      title: "Équipements installés"
      field_type: "checklist"
      field_config: '{"items":["ONT branché","Routeur configuré","Décodeur branché"]}'
      required: 1
      visible_condition: null
    - step_order: 2
      step_id: "ont_scan"
      title: "Scanner ONT"
      field_type: "scan"
      field_config: '{"placeholder":"Scanner le code-barres ONT"}'
      required: 1
    - ...

Admin Builder UI

┌─ Form Builder: Installation FTTH ─────────────────────────┐
│                                                             │
│  ┌─ Step 1 ─────────────────────────── [≡] [✏️] [🗑] ──┐  │
│  │ 📋 Checklist: "Équipements installés"                  │  │
│  │    Items: ONT, Routeur, Décodeur, Téléphone            │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌─ Step 2 ─────────────────────────── [≡] [✏️] [🗑] ──┐  │
│  │ 📷 Scan: "Scanner ONT"                                 │  │
│  │    Required: Oui                                        │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌─ Step 3 ─────────────────────────── [≡] [✏️] [🗑] ──┐  │
│  │ ✅ Toggle: "Signal ONT OK?"                             │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  [+ Ajouter une étape]                                      │
│                                                             │
│  ┌─ Aperçu téléphone ──┐                                   │
│  │  ┌────────────────┐  │                                   │
│  │  │  Étape 1/7     │  │                                   │
│  │  │                │  │                                   │
│  │  │  ☐ ONT branché │  │                                   │
│  │  │  ☐ Routeur     │  │                                   │
│  │  │  ☐ Décodeur    │  │                                   │
│  │  │                │  │                                   │
│  │  │  [Suivant →]   │  │                                   │
│  │  │  ● ○ ○ ○ ○ ○ ○ │  │                                   │
│  │  └────────────────┘  │                                   │
│  └──────────────────────┘                                   │
│                                                             │
│  [Sauvegarder]  [Publier]                                   │
└─────────────────────────────────────────────────────────────┘

4. Equipment Swap Wizard (Defective → Replacement)

When tech taps "Remplacer" on a device or from the "Plus" menu:

Step 1: "Équipement défectueux" [search/scan]
  Scan le code-barres de l'ancien équipement
  → OU chercher par numéro de série
  → Affiche: RCMG19E0AB57 — ONT Raisecom HT803G-WS2
    Client: Jean Tremblay
    Adresse: 123 rue Principale

Step 2: "Raison du remplacement" [select-cards]
  🔴 Défectueux (ne s'allume plus)
  🟡 Performance dégradée
  🔵 Mise à niveau (upgrade)
  ⚪ Autre

Step 3: "Nouvel équipement" [scan]
  📸 Scanner le code-barres du remplacement
  → Detected: TPLGA1E7FB90
  → Auto-detect type: XX230v (ONT)

Step 4: "Confirmer le remplacement" [info]
  ❌ Ancien: RCMG19E0AB57 → sera marqué "Défectueux"
  ✅ Nouveau: TPLGA1E7FB90 → sera activé

  Données transférées automatiquement:
  • WiFi SSID/mot de passe ✓
  • SIP (VoIP) credentials ✓
  • Port OLT: 0/3/2 ONT:12 ✓
  • VLANs: inet/mgmt/tel/tv ✓

  ⚠️ L'OLT sera reconfiguré (ancien ONT supprimé, nouveau enregistré)

  [Confirmer le remplacement]

Step 5: "Vérification" [toggle]
  Nouveau ONT en ligne? [OUI / NON]
  Signal OK? [OUI / NON]
  Services fonctionnels? [OUI / NON]

  [Terminer]

Backend flow (POST /provision/swap):

1. Marks old equipment as "Défectueux" in ERPNext
2. Creates new Service Equipment with transferred WiFi/VoIP/OLT data
3. Generates OLT swap commands (delete old ONT, register new)
4. n8n executes OLT commands via SSH
5. ACS pushes config to new device on bootstrap
6. Ops team notified via SSE

5. Quick Actions Menu (field app "Plus" page)

┌──────────────────────────────────────────┐
│          Actions rapides                  │
│                                          │
│  ┌────────┐  ┌────────┐  ┌────────┐    │
│  │ 📷     │  │ 🔄     │  │ 🔧     │    │
│  │ Scan   │  │ Swap   │  │ Diag   │    │
│  │ équip. │  │ équip. │  │ réseau │    │
│  └────────┘  └────────┘  └────────┘    │
│                                          │
│  ┌────────┐  ┌────────┐  ┌────────┐    │
│  │ 📋     │  │ 📸     │  │ ✏️     │    │
│  │ Check  │  │ Photo  │  │ Note   │    │
│  │ -list  │  │ site   │  │ rapide │    │
│  └────────┘  └────────┘  └────────┘    │
└──────────────────────────────────────────┘

Each action opens the corresponding wizard flow.

---

Implementation Plan

Phase 1: WizardCarousel Component

1. Create apps/field/src/components/WizardCarousel.vue — carousel renderer
2. Create apps/field/src/components/wizard-fields/ — one component per field type:
   • SelectCards.vue (big tappable cards)
   • ScanField.vue (camera + barcode)
   • ToggleField.vue (yes/no)
   • PhotoField.vue (camera capture)
   • SignatureField.vue (touch pad)
   • ChecklistField.vue (checkable items)
   • TextField.vue (single input)
   • NotesField.vue (textarea)
   • InfoField.vue (read-only summary)
3. Create apps/field/src/composables/useWizard.js — step state, validation, submission

Phase 2: Hardcoded Wizards

1. Build "Installation Complete" wizard (7 steps as above)
2. Build "Equipment Scan & Link" wizard (3 steps)
3. Integrate into TasksPage "Complete Job" action
4. Replace current ScanPage equipment creation dialog with wizard flow

Phase 3: Wizard Template Doctype

1. Create Wizard Template + Wizard Template Step doctypes in ERPNext
2. Seed with Installation, Repair, Maintenance templates
3. Field app fetches template by job_type on wizard open
4. WizardCarousel renders dynamically from template

Phase 4: Admin Form Builder (Ops App)

1. Build /ops/form-builder page
2. Drag-and-drop step editor (vue-draggable)
3. Step property editor (sidebar panel)
4. Phone preview panel
5. Publish → saves to ERPNext Wizard Template

---

CSS / Styling Notes

// Wizard slide — full height, centered content
.wizard-slide {
  display: flex;
  flex-direction: column;
  justify-content: center;
  padding: 24px 16px;
  min-height: calc(100vh - 160px); // account for header + progress bar
}

// Select cards — large touch targets
.select-card {
  min-height: 80px;
  border-radius: 16px;
  font-size: 18px;
  margin-bottom: 12px;
  transition: transform 0.15s, box-shadow 0.15s;
  &:active { transform: scale(0.97); }
  &.selected {
    border: 3px solid var(--q-primary);
    box-shadow: 0 0 0 4px rgba(var(--q-primary-rgb), 0.2);
  }
}

// Progress dots
.wizard-dots {
  display: flex;
  justify-content: center;
  gap: 8px;
  padding: 16px;
  .dot {
    width: 10px; height: 10px;
    border-radius: 50%;
    background: #ccc;
    &.active { background: var(--q-primary); width: 24px; border-radius: 5px; }
    &.done { background: var(--q-positive); }
  }
}

// Navigation buttons — thumb-friendly
.wizard-nav {
  display: flex;
  gap: 12px;
  padding: 16px;
  .q-btn { min-height: 56px; font-size: 16px; flex: 1; border-radius: 12px; }
}