# Salesman Van Flutter Architecture

## Customer feature boundary

`CustomerSummary` carries approval/account eligibility, `CustomerOnboardingPage` owns the structured form and document actions, and `ApiService` transports requests only. Business decisions remain in Laravel. Customer profile uses Overview, Sales, Returns, Payments and Documents; every transactional request includes the selected customer ID.

## Goal

The Flutter app is for mobile users only:

- Salesman
- Van Inventory
- Barcode Scanner
- Inventory Check
- Orders
- Offline Sync later

Laravel Web remains the admin panel.

## Current Structure

lib/core

Shared foundation code.

- config
- theme
- storage
- api
- utils

lib/shared/widgets

Reusable UI widgets used across many screens.

Examples:

- AppCard
- ProductPhoto
- StatusDot
- QtyBadge
- AppSearchBox

lib/pages

Current app screens.

Later we may move pages into feature folders.

## Why this structure matters

The same widgets will be reused in:

- My Van
- Product Details
- Inventory Check
- Barcode Scanner
- Orders
- Picking
- Box Items

This avoids duplicated code and makes the app easier to maintain.

## Refactor Progress

### My Van Page

My Van has been refactored to use shared widgets:

- AppCard
- ProductPhoto
- QtyBadge
- StatusDot
- AppSearchBox

This reduces duplicated UI code and makes future screens easier to build.

### Inventory Check Page

Inventory Check started moving to shared widgets:

- AppCard
- InventoryStatusLabel

This prepares the screen for scanner, offline mode, and better tablet layout.

## Models

### VanStockItem

The app now has a typed VanStockItem model.

This replaces raw Map usage in My Van.

Benefits:

- Cleaner code
- Better safety
- Easier future offline database mapping
- Easier reuse in Orders and Picking

<!-- SNYT_RETURNS_RMA_FLUTTER_V1_START -->
## Returns / RMA v1

Status: **Implemented in source; device QA required**

### Navigation and UI

- `Returns` is a top-level bottom-navigation destination for salesman and manager/admin layouts.
- Team chat remains available from the More page.
- The global app theme now uses the approved SNYT dark visual system: deep navy/black backgrounds, cyan primary actions, teal success states, amber accounting states, red RMA states, subtle borders, rounded enterprise cards, and compact mobile-first spacing.
- Existing business-specific report sheets keep their required company document appearance while app chrome follows the dark SNYT system.

### Returns Screens

- Returns list with search and filters.
- Create Return with mandatory saved customer.
- Customer Return / Resellable and RMA / Defective type selection. Types cannot be mixed in one document.
- Partial SKU/name/barcode search and barcode scanner.
- Multiple items per return.
- Optional photos.
- Direct exchange from sellable van stock on RMA items.
- Return details with separate operational and financial status.
- Accounting Review for admin/supervisor accounts.
- RMA warehouse handover list/create/details.
- Dispatch to warehouse.
- Full / partial / rejected warehouse confirmation.
- Print A4 handover PDF.
- Customer profile includes Sales / Returns / Payments tabs.

### Stock Behavior

- Resellable items do not enter sellable stock until accountant approval.
- RMA/Defective items enter a separate non-sellable RMA stock bucket.
- Direct exchange shows current sellable VAN availability, adds the defective unit to RMA, and deducts the replacement from sellable van stock.
- Flutter never performs authoritative stock math locally; Laravel confirms all stock-changing operations.

### API

Returns APIs are exposed under the existing mobile API base and include returns, product search, accountant review, opening RMA reclassification, handover batches, warehouse confirmation, and handover PDF.
<!-- SNYT_RETURNS_RMA_FLUTTER_V1_END -->
## Return state authority

Flutter renders Return actions from API state but Laravel owns all transition, ownership, stock, idempotency, and handover validation. Draft editing and explicit submit use separate service calls.
## RMA Stock data flow

`RmaStockService` reads the Laravel-computed balance into dedicated immutable models. Flutter displays the result and never derives authoritative stock locally. RMA Stock remains inside the Returns feature and does not add a bottom-navigation destination.