41d9b5f316
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>
84 lines
3.5 KiB
Markdown
84 lines
3.5 KiB
Markdown
# 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):**
|
|
```text
|
|
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):**
|
|
```text
|
|
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
|
|
1. **Minimal inputs per screen:** Max 2-3 fields per step.
|
|
2. **Carousel/swipe navigation:** Horizontal navigation instead of vertical scrolling.
|
|
3. **Big touch targets:** Buttons minimum 48px height, inputs 56px+.
|
|
4. **Auto-advance:** When a user taps a selection card, immediately slide to the next step.
|
|
5. **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.
|
|
|
|
```vue
|
|
<WizardCarousel
|
|
:steps="wizardSteps"
|
|
:context="{ job, customer, location }"
|
|
@complete="onComplete" />
|
|
```
|
|
|
|
### Flow Example: Diagnostic Wizard
|
|
1. **Problème signalé** [Info Card] → Shows linked Ticket context.
|
|
2. **Signal ONT** [Toggle + Text Input] → Signal present? Input dBm level.
|
|
3. **Action Prise** [Select Cards] → "Redémarrage" / "Swap Hardware".
|
|
4. **Nouvel équipement** [Barcode Scan] → Triggers device camera to read ONT MAC address.
|
|
5. **Signature** [Touch Pad] → Client signs to confirm completion.
|
|
6. **Résumé** [Info Card] → Syncs automatically if connection is active.
|