# Product Requirements Document (PRD): Mobile Back-Camera QR Scanner for WMS

**Status:** Ready for Build  
**Classification:** `T2 · S2 — Cross-Platform Mobile QR/Barcode Scanner (iOS Safari & Android Chrome) for WMS Master ID & Asset Inventory`  
**Target Delivery:** Mobile Web / Progressive Web App (PWA) on Laravel 11 Blade  

---

## 1. Falsifiable Problem Statement

**Problem:** Warehouse floor auditors cannot use their smartphones (iPhone or Android) to quickly scan Master ID packages and component items on shelves because:
1. Web browsers block the camera over plain HTTP Wi-Fi connections (`window.isSecureContext === false`).
2. iOS Safari frequently defaults to the front selfie camera or blurry ultra-wide lens.
3. The UI lacks mobile-first ergonomics (torch control, haptic feedback, single-handed portrait layout).

**Falsification Criteria:** This problem statement is proven solved if an auditor using any standard iPhone (iOS 15+) or Android smartphone can open the `/scan` URL over HTTPS, tap "Start Camera", and successfully decode a Master ID QR code using the **rear back camera in under 1.5 seconds** with simultaneous audio chime and haptic vibration feedback, without installing an app from the App Store.

---

## 2. Named Personas

| Persona | Role & Device | Goals | Frustrations |
| :--- | :--- | :--- | :--- |
| **Somnang** | Floor Auditor (iPhone 14 / 15 Pro) | Walk warehouse aisles scanning boxed POS rental kits with back camera. | Hates when camera opens facing his face; needs clear focus in dark rack aisles. |
| **Sokha** | Receiving Clerk (Samsung Galaxy A54 Android) | Inspect incoming customer return pallets directly at the truck loading bay. | Heavy laptops cannot be brought out to the truck; needs quick 1-hand mobile phone scanning. |
| **Visal** | Warehouse Supervisor (Desktop / iPad) | Monitor real-time audit counts, review missing items, and approve inventory movements. | Wants zero software installation headaches across different worker phone brands. |

---

## 3. Ranked Jobs to Be Done (JTBD)

1. **P0 (Critical):** As a mobile auditor, I need the `/scan` screen to reliably activate my phone's **rear back camera** (not the front camera) on both iOS Safari and Android Chrome so I can scan barcodes and QR codes immediately.
2. **P0 (Critical):** As a mobile auditor, when I scan a **Master ID QR code**, I need the screen to instantly display the Master package details (customer, warehouse location, total components) and list all attached units.
3. **P0 (Critical):** As a mobile auditor, when I scan an **Individual Component QR/barcode** (e.g. Slip Printer serial), I need the system to display that item, show which Master ID container it belongs to, and indicate its status.
4. **P1 (High):** As a mobile auditor working in dim aisles, I need a 1-tap **Torch (Flashlight)** button and 1x/2x zoom controls directly on the camera viewfinder.
5. **P1 (High):** As an operator scanning without constantly staring at the phone screen, I need an audible high-pitch beep and physical phone vibration upon each successful scan.
6. **P2 (Nice-to-Have):** PWA Standalone Manifest: Provide an "Add to Home Screen" shortcut icon and full-screen app display mode without browser search bars.

---

## 4. Functional Specifications

### 4.1 Camera & Viewfinder Engine
- **Engine:** `Html5Qrcode` with native hardware-accelerated `BarcodeDetector` support enabled.
- **Camera Target:** Default constraint `{ facingMode: { ideal: "environment" } }`.
- **Mobile Camera Device Selection:**
  - Avoid pre-selecting Camera `0` on iOS before permissions are granted.
  - Automatically filter and label back/rear cameras when multiple lenses are reported.
  - Provide a quick "Flip Camera" toggle between front and rear cameras.
- **Viewfinder HUD:**
  - Dynamic QR targeting frame with high-visibility cyan corners.
  - Animated red laser scanline.
  - Green border flash and HUD toast badge on successful decode.

### 4.2 Scanner Feedback System
- **Audio:** Web Audio API synthesized sine sweep (880Hz $\rightarrow$ 1320Hz, 180ms duration) requiring zero external MP3/WAV assets.
- **Haptics:** `navigator.vibrate([70, 30, 70])` dual-pulse vibration on supported Android and iOS WebKit browsers.

### 4.3 Mobile Viewport & Ergonomics
- **Responsive Layout:**
  - Viewfinder maintains a minimum 280px–360px height in mobile portrait orientation.
  - Sticky scan results below the viewfinder with automatic smooth scroll on mobile screens.
  - Touch-friendly buttons ($44\times44$px minimum touch targets) for one-handed thumb operation.

---

## 5. Non-Goals (Out of Scope)

- **No Native App Store Submissions:** We will NOT build an Objective-C / Swift / Kotlin native app or submit to the Apple App Store or Google Play Store. The solution is 100% Mobile Web / PWA.
- **No Bluetooth Scanner Firmware Flashing:** The system supports USB/Bluetooth barcode guns via standard keyboard HID wedge mode; no custom Bluetooth Low Energy (BLE) proprietary drivers will be built.
- **No Offline-First Multi-Day Sync:** The scanner operates live connected to the warehouse network via HTTPS. Offline client-side IndexedDB caching is out of scope for MVP.

---

## 6. Success Metrics

### Leading Metrics
- **Camera Initialization Time:** Under **1.2 seconds** from tapping "Start Camera" to active video stream on iPhone and Android.
- **Scan Decode Speed:** QR code recognized and payload parsed within **< 250ms** of entering the camera frame.
- **Zero Front-Camera Misdirects:** 100% of initial mobile scans correctly launch on the rear back camera.

### Lagging Metrics
- **Cycle Count Audit Duration:** 60% reduction in total time spent conducting physical inventory audits.
- **Hardware Equipment Savings:** $0 spent on dedicated mobile scanner hardware across the warehouse team.
