# SNYT Salesman Van

## Customer onboarding

Customers now include approved active accounts and the salesman's own applications. The five-step SNYT Enterprise form supports draft saving, duplicate warnings, territory selection, legal/VAT documents, conditional credit requests, submission and visible review status. Pending, rejected and suspended customers cannot be selected for invoices.

**Version:** 1.0.0+1  
**Documentation updated:** 2026-07-30

SNYT Salesman Van is a Flutter mobile application connected to the SNYT Laravel Catalog and Field Sales backend. It is designed for salesmen working from a van, with live van inventory, catalogs, customers, draft orders, printing, stock deduction, delivery, and cancellation workflows.

## Supported platforms

- Android phones and tablets
- iPhone and iPad
- Responsive layouts for phone and tablet screens

## Main navigation

- Home
- Catalogs
- Customers
- My Van
- More

## Implemented modules

### Authentication

- Login
- Auto login
- Logout
- Authenticated Laravel mobile API requests

### Dashboard

- Van product count
- Total van pieces
- Box count
- Quick actions
- Automatic refresh after stock-changing order actions

### Catalogs

- Main catalog
- Clearance catalog
- Salesman van catalog
- Responsive product grid
- Search
- Product details
- Van quantity visibility
- Add to cart
- Barcode scanning

### My Van

- Live van inventory
- Search by SKU, barcode, or product name
- Product details
- Barcode scanner
- Automatic refresh after confirming or cancelling an order

### Customers

- Customer list
- Customer search
- Customer details
- Customer selection during checkout
- Walk-in customer checkout without creating a saved customer record

### Cart

- Persistent cart using SharedPreferences
- Quantity validation against van stock
- Prevent adding unavailable products
- Prevent quantities above van stock
- Persistent client UUID to prevent duplicate draft orders
- Cart clears only after a draft is successfully saved

### Orders

- Create draft order
- My Orders list
- Search orders
- Filter by Draft, Confirmed, Delivered, and Cancelled
- Order details
- Order timeline
- Confirm sale
- Mark delivered
- Cancel order
- Cancel reason
- Automatic van-stock refresh

### Printing

- Authenticated Laravel PDF endpoint
- Native Android and iOS print dialog
- Print from Draft Saved
- Print from Order Details
- A4 preparation copy
- Small product photo
- SKU and barcode
- Product name
- Picking checkbox
- Quantity
- Price and totals
- Customer and salesman information
- Notes
- Draft stock warning

## Important stock rules

| Action | Order status | Stock effect |
|---|---|---|
| Save Draft | Draft | No deduction |
| Print Draft | Draft | No deduction |
| Confirm Sale | Confirmed | Deduct once |
| Mark Delivered | Delivered | No additional change |
| Cancel Draft | Cancelled | No stock change |
| Cancel Confirmed | Cancelled | Restore deducted stock |
| Cancel Delivered | Not allowed | No change |

The backend protects against duplicate deduction and duplicate reversal.

## Current sales workflow

```text
Browse Catalog / My Van
→ Add Products to Cart
→ Continue
→ Select Saved Customer or Walk-in Customer
→ Save Draft
→ Print Preparation Copy
→ Prepare Items
→ Confirm Sale
→ Van Stock Deducted
→ Mark Delivered
```

## Scanner notes

- Uses one-dimensional barcode formats
- Duplicate-scan protection
- Scan-window restriction
- Lifecycle-safe scanner handling
- Manual barcode entry
- Torch support where the device has a flash
- Samsung Tab A11 has no camera LED flash, so torch is unavailable on that device

## Current UI decisions

- Printing remains inside Order Details rather than inside every My Orders card
- Walk-in Customer appears only during checkout customer selection
- Delivery does not deduct stock; deduction happens on Confirm Sale

<!-- 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.
- Only outstanding rejected quantity is offered again after a partial warehouse handover; previously accepted quantity is not duplicated.
- 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 -->
## Explicit Return review states

The mobile workflow is Draft → Pending Accountant → Approved or Rejected. Salesmen save and edit drafts, then explicitly submit them. Only submitted returns expose accountant actions. Rejected RMA remains physically recorded in the salesman's RMA bucket.
## Dedicated RMA Stock

Returns now contains an RMA Stock view for defective, non-sellable goods. It shows current in-van balance, Draft-handover reservation, ready quantity, and in-transit quantity without changing catalog or sellable van stock.

## Runtime and release baseline

Android and iOS use the stable identifier `xyz.snyt.vanapp`. Android launches through the Flutter embedding v2 `xyz.snyt.vanapp.MainActivity`. Releases are produced by `tool/release.sh`, which validates Flutter first, increments the build number, archives a signed Android APK and explicitly unsigned iOS IPA, writes SHA256 checksums and release metadata, and restores the original version if a build fails.

## SNYT Enterprise UI v1

The shared UI foundation follows the approved Returns/RMA dark enterprise design. It centralizes colors, spacing, radii, typography, status tones, cards, metrics, badges, headers, buttons, search, and standard loading/empty/error states. Splash, Login, the global phone/tablet shell, Dashboards, and More/Profile use the foundation. Feature modules not named in this phase remain functionally and visually unchanged except for inheriting safe global theme defaults.

### Full visual QA baseline

The physical Android tablet baseline now includes the complete salesman navigation path and its reachable detail/forms screens. Catalog prices use the cyan high-contrast value style, shared cards provide their own Material/ink surface, and empty boxes use the standard enterprise empty state. Printable company reports intentionally retain their light document appearance inside the dark application shell.