louispaulb 41d9b5f316 feat: flow editor, Gemini QR scanner with offline queue, dispatch planning v2

Major additions accumulated over 9 days — single commit per request.

Flow editor (new):
- Generic visual editor for step trees, usable by project wizard + agent flows
- PROJECT_KINDS / AGENT_KINDS catalogs decouple UI from domain
- Drag-and-drop reorder via vuedraggable with scope isolation per peer group
- Chain-aware depends_on rewrite on reorder (sequential only — DAGs preserved)
- Variable picker with per-applies_to catalog (Customer / Quotation /
  Service Contract / Issue / Subscription), insert + copy-clipboard modes
- trigger_condition helper with domain-specific JSONLogic examples
- Global FlowEditorDialog mounted once in MainLayout, Odoo inline pattern
- Server: targo-hub flow-runtime.js, flow-api.js, flow-templates.js
- ERPNext: Flow Template/Run doctypes, scheduler, 5 seeded system templates
- depends_on chips resolve to step labels instead of opaque "s4" ids

QR/OCR scanner (field app):
- Camera capture → Gemini Vision via targo-hub with 8s timeout
- IndexedDB offline queue retries photos when signal returns
- Watcher merges late-arriving scan results into the live UI

Dispatch:
- Planning mode (draft → publish) with offer pool for unassigned jobs
- Shared presets, recurrence selector, suggested-slots dialog
- PublishScheduleModal, unassign confirmation

Ops app:
- ClientDetailPage composables extraction (useClientData, useDeviceStatus,
  useWifiDiagnostic, useModemDiagnostic)
- Project wizard: shared detail sections, wizard catalog/publish composables
- Address pricing composable + pricing-mock data
- Settings redesign hosting flow templates

Targo-hub:
- Contract acceptance (JWT residential + DocuSeal commercial tracks)
- Referral system
- Modem-bridge diagnostic normalizer
- Device extractors consolidated

Migration scripts:
- Invoice/quote print format setup, Jinja rendering
- Additional import + fix scripts (reversals, dates, customers, payments)

Docs:
- Consolidated: old scattered MDs → HANDOFF, ARCHITECTURE, DATA_AND_FLOWS,
  FLOW_EDITOR_ARCHITECTURE, BILLING_AND_PAYMENTS, CPE_MANAGEMENT,
  APP_DESIGN_GUIDELINES
- Archived legacy wizard PHP for reference
- STATUS snapshots for 2026-04-18/19

Cleanup:
- Removed ~40 generated PDFs/HTMLs (invoice_preview*, rendered_jinja*)
- .gitignore now covers invoice preview output + nested .DS_Store

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-22 10:44:17 -04:00

3.5 KiB

Raw Blame History

Gigafibre FSM — App Design & UX Guidelines

This document defines the engineering patterns and UI/UX standards for developing frontend applications within the Gigafibre ecosystem (Ops App, Mobile Tech App, Client Portal).

Adhering to these guidelines ensures scalability, maintainability, and highly efficient AI-assisted development by keeping architectural context constrained.

1. Modular Architecture (Feature-Sliced Design)

To avoid a monolithic src/ folder that overwhelms developers and LLMs, organize code by feature rather than strictly by technical type.

Do Not Do This (Technical Grouping):

src/
  components/ (contains dispatch, inventory, and customer mixed together)
  store/ (one massive pinia store for everything)
  api/ (one 2000-line api.js file)

Do This (Feature Grouping):

src/
  features/
    dispatch/
      components/
      store.ts
      api.ts
      types.ts
    equipment/
      components/

Why? When executing a task inside a specific domain, only the pertinent features/{feature}/ directory needs to be referenced, drastically reducing cross-pollution and token usage.

2. Component & API Standardization (Vue / Quasar)

Architecture

Composition API: Use Vue 3 <script setup> syntax universally. Avoid Options API.
Component Size Limit: Keep .vue files small. If a component exceeds 250 lines, it must be split down.
Smart vs Dumb:
- Smart Components (Pages): Connect to Pinia, fetch data from API, hold domain state.
- Dumb Components (UI): Accept props, emit events. Do not independently fetch data.

API Abstraction

Never make raw axios.get or authFetch calls directly inside a .vue component. All interactions with the targo-hub or ERPNext backend must go through a dedicated service file (e.g., features/dispatch/api.ts).

State Management (Pinia)

One Pinia store per domain.
Do not store UI state in Pinia (e.g., isSidebarOpen). Use local ref() inside the component. Pinia is solely for caching fetched ERPNext data.

3. Tech Mobile App — Wizard UX

Technicians in the field are wearing gloves, dealing with glare, and often lack cellular signal. Complex, scrolling forms are forbidden.

Core Mobile Principles

Minimal inputs per screen: Max 2-3 fields per step.
Carousel/swipe navigation: Horizontal navigation instead of vertical scrolling.
Big touch targets: Buttons minimum 48px height, inputs 56px+.
Auto-advance: When a user taps a selection card, immediately slide to the next step.
Offline-first: All completed Wizards must queue locally via IndexedDB if the device lacks internet access, syncing silently once connectivity is restored.

The Component: `WizardCarousel.vue`

All tech jobs (Installation, Diagnostic Swap, Closure) utilize a dynamic carousel driven by a JSON schema representing steps.

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

Flow Example: Diagnostic Wizard

Problème signalé [Info Card] → Shows linked Ticket context.
Signal ONT [Toggle + Text Input] → Signal present? Input dBm level.
Action Prise [Select Cards] → "Redémarrage" / "Swap Hardware".
Nouvel équipement [Barcode Scan] → Triggers device camera to read ONT MAC address.
Signature [Touch Pad] → Client signs to confirm completion.
Résumé [Info Card] → Syncs automatically if connection is active.

3.5 KiB Raw Blame History