# Execution Plan: Mobile Back-Camera QR Scanner for WMS

**Status:** Approved & Build-Ready  
**Classification:** `T2 · S2 — Cross-Platform Mobile QR/Barcode Scanner (iOS Safari & Android Chrome) for WMS Master ID & Asset Inventory`  

---

## 1. User Journey Flowchart

```mermaid
flowchart TD
    A["Operator Opens /scan on iPhone or Android"] --> B{"Is Connection HTTPS?"}
    B -- No --> C["Display Clear Warning: 'Requires HTTPS for Camera Access'"]
    B -- Yes --> D["Tap 'Start Camera' Button"]
    
    D --> E["Browser Prompts Camera Permission"]
    E --> F["Hardware Constraints Applied:<br/>facingMode: { ideal: 'environment' }"]
    F --> G["Rear Back Camera Viewfinder Active<br/>(Laser line + Focus box)"]
    
    G --> H["Point Camera at QR Code / Barcode"]
    H --> I["Decoded Payload Extracted"]
    I --> J["Web Audio Beep (880→1320Hz) +<br/>Haptic Vibration Pulse"]
    
    J --> K{"Payload Classification"}
    K -- Master ID Code --> L["Display Master ID Overview Card:<br/>• Customer & Location<br/>• Attached Items Checklist (18 units)"]
    K -- Component Serial --> M["Display Component Card:<br/>• Identified Serial & Type<br/>• Belongs to Master ID Set<br/>• Current Status Badge"]
    K -- Not Found in DB --> N["Display 'Not Found' Card with Quick Actions:<br/>• Create Master ID<br/>• Attach to Existing Master ID"]
    
    L --> O["1-Tap 'Scan Another' to Continue"]
    M --> O
    N --> O
```

---

## 2. Platform & Stack Recommendation

| Tier | Technology Choice | Rationale & Fit |
| :--- | :--- | :--- |
| **Standard Mobile Web (Selected)** | Responsive Mobile Web Blade + `html5-qrcode` + Cloudflare Tunnel | **Zero installation, zero home screen setup.** Workers simply open the URL in Safari or Chrome, tap "Start Camera", and scan directly inside the browser. |
| **Ergonomics Add-ons** | HTML5 BarcodeDetector API + Web Audio + Haptics | Hardware GPU barcode decode, audio sweep chime, and physical vibration feedback on decode. |
| **Cutting-Edge (Future)** | Capacitor Native Wrapper + `@capacitor-community/barcode-scanner` | Native camera pipeline for high-speed offline continuous frame scanning if the team ever needs 100% offline warehouse support. |

---

## 3. Phased Build Plan

```mermaid
flowchart LR
    P1["Phase 1: MVP<br/>Back-Camera Browser Scanner"] --> P2["Phase 2: v1<br/>Quick Hardware Controls (Torch/Zoom)"] --> P3["Phase 3: Target<br/>Continuous Rapid Audit Mode"]
```

### Phase 1: MVP (Completed & Live)
- **Deliverables:**
  - Fixed mobile back camera selection in [scan/index.blade.php](file:///C:/xampp/htdocs/Management-warehouse/resources/views/scan/index.blade.php): defaults to `{ facingMode: { ideal: "environment" } }`.
  - Prevented iPhone iOS front selfie camera lock when labels are initially empty.
  - Active Cloudflare HTTPS Tunnel configured and running for instant mobile browser access.
  - Real-time scannable QR code generator for 1-step mobile testing.
  - Zero-install: No app installation or "Add to Home Screen" required.
- **Kill Criteria:** If iOS Safari fails to open the back camera stream within 3 seconds after granting permission, fallback to manual USB/Bluetooth barcode input mode.
- **Metrics:** 100% back-camera activation rate on iOS and Android test devices.

---

### Phase 2: v1 Enhancements (Ergonomics & Hardware Controls)
- **Deliverables:**
  - Dedicated **Torch / Flashlight** toggle button on the viewfinder for low-light warehouse aisles.
  - 1x and 2x digital zoom quick-switch buttons for high-shelf barcodes.
  - Touch-friendly layout optimized for single-handed thumb operation.
- **Kill Criteria:** If torch constraint (`applyConstraints({ torch: true })`) causes camera freeze on specific budget Android models, wrap in graceful `try/catch` and silently disable torch button.
- **Metrics:** Average scan-to-result time $< 1.2$ seconds per item on mobile Wi-Fi.

---

### Phase 3: Target State (Continuous Rapid Audit & Stock Verification)
- **Deliverables:**
  - Integrate back-camera mobile scanner directly into `/verify-stock/{id}` for live cycle counts.
  - Continuous rapid scan mode: camera remains open, beeping and checking off items in the Master ID checklist in real-time without pausing.
  - Offline sync buffer: if Wi-Fi drops between metal aisles, store up to 50 scanned serials in `localStorage` and flush upon reconnect.
- **Kill Criteria:** If continuous video streaming overheats smartphones during $>45$-minute audit sessions, introduce an auto-sleep timer that pauses the camera after 60 seconds of inactivity.
- **Metrics:** Audit throughput $>120$ components verified per operator hour.

---

## 4. Immediate Next Actions (Today's Build Queue)

1. **Open directly in Mobile Browser:**
   - Scan the on-screen QR code or open `https://permitted-foam-firefox-guam.trycloudflare.com/Management-warehouse/public/scan` in Safari (iPhone) or Chrome (Android).
2. **Scan Master ID or Component:**
   - Tap "Start Camera" $\rightarrow$ Tap "Allow" $\rightarrow$ Point back camera at QR code.
3. **Verify Torch & Zoom:**
   - Test flashlight toggle in a dim room or shelf to ensure hardware lighting triggers on your device.
