Fleet & Staff: Screen Specifications

UI layout and interaction specs for Phase 1: Fleet & Staff CRUD. Translates the Fleet & Staff Journeys and UX Design Decisions into actionable component requirements.

1. Fleet Management (Vehicles)

1.1 Vehicle List View (/fleet)

Layout Pattern: Quasar QTable wrapped in @busflow/ui-core styling.

• Empty State: Illustration + "Let's build your fleet" + Subtext + "+ Add Vehicle" CTA.
• Columns:
  • license_plate (Bold, primary identifier)
  • status (Chip: Active=Green, Maintenance=Amber, Decommissioned=Grey)
  • model & vehicle_class (Combined into one column for readability, e.g., "Mercedes Tourismo • Coach")
  • capacity (e.g., "49 seats")
  • actions (Row-level menu ⋮)
• Row Actions: Edit, Decommission (soft delete).
• Global Actions: "+ Add Vehicle" button (top right), Search input, Status filter.

1.2 Vehicle Create/Edit Flow

Layout Pattern: Slide-over Drawer (QDrawer right-aligned).

• Validation: VeeValidate + Valibot schema.
• Fields:
  • license_plate (Text, required, uppercase transform)
  • model (Text, required)
  • vehicle_class (Select: COACH, MINIBUS, VAN, required)
  • capacity (Number, required, min: 1)
  • transmission_type (Radio/Toggle: MANUAL, AUTOMATIC, default: MANUAL)
• Footer: Cancel (closes drawer), Save (submits).
• Feedback: Global toast on success, inline text on validation error.

1.3 Vehicle Detail View

Layout Pattern: Popup/Modal Overlay (QDialog).

• Header: License Plate + Status Chip.
• Body Section 1 (Info): Model, Class, Capacity, Transmission.
• Body Section 2: (Inspections and Mileage are deferred to later phases).

---

2. Staff Management (Crew)

2.1 Crew List View (/fleet/staff)

Layout Pattern: Quasar QTable.

• Empty State: Illustration + "Add your first crew member" + Subtext + "+ Add Crew Member" CTA.
• Columns:
  • name (First + Last, bold)
  • role (Driver, Dispatcher, Guide)
  • status (Chip: Active, On Leave, Inactive)
  • phone & email
  • actions (Row-level menu ⋮)
• Row Actions: Edit, Deactivate (soft delete).

2.2 Crew Create/Edit Flow

Layout Pattern: Slide-over Drawer (QDrawer).

• Fields:
  • first_name & last_name (Text, required)
  • role (Select: DRIVER, DISPATCHER, GUIDE, required)
  • phone (Text, optional)
  • email (Text/Email, optional but recommended for app access)
  • license_number (Text, optional)
  • license_expiry (Date, optional)

2.3 Crew Detail View

Layout Pattern: Popup/Modal Overlay (QDialog).

• Header: Full Name + Role Badge.
• Section 1 (Contact Info): Phone, Email, License info.
• Section 2 (Qualifications):
  • Sub-table of crew_qualifications (e.g., Module 95, D License).
  • Columns: Type, Expiry, Status.
  • Header Action: "+ Add Qualification" (micro-modal).
• Section 3 (Absences):
  • Sub-table of crew_absences (Vacation, Sick).
  • Columns: Type, Dates, Status (defaults to Approved).

---

3. Operator Settings

3.1 Settings Layout (/settings)

Layout Pattern: Full Dedicated Page with vertical side-tabs.

3.2 Company Profile Tab

Layout Pattern: Standard Form.

• Fields: Company Name, Legal Name, Address, Country, VAT ID, Tax ID, Legal Form.
• Interaction: Inline editing, "Save Changes" button at bottom. Success indicated via toast.

3.3 Branding Tab

Layout Pattern: Image Uploader + Color Picker.

• Fields: Logo Upload (S3 bucket or base64 placeholder for now), Primary Brand Color (Hex picker).

---

4. Shared Component Requirements

To implement these screens efficiently, we need to build or configure the following shared patterns first:

1. DataTable Wrapper: A component that wraps QTable, applies @busflow/ui-core styles (Tailwind), standardizes the search input, empty state slot, and pagination.
2. DrawerForm Component: A standardized right-aligned drawer using QDrawer that handles the header (Title + Close), scrollable body (form fields), and fixed footer (Cancel/Save buttons).
3. FormFields: VeeValidate + Quasar inputs (q-input, q-select, q-date) wrapped to display inline error messages correctly when Valibot validation fails.