# DALSEEN Android POS — MVP QA Report

**Branch:** `android-pos-mvp`
**Reporter:** automated agent (Cursor)
**Date:** 2026-05-06

---

## 0. Important caveat — what was actually tested

This report combines three layers of verification:

1. **Live API contract testing** — every backend endpoint the MVP touches
   was hit with `curl` against a running Laravel instance, exercising the
   exact request shapes the app sends. This is the highest-confidence
   layer.
2. **Static + bundle-level audits** — code review, Metro bundle export,
   pure-function smoke tests, and the existing `audit-undefined` script.
3. **Hands-on UI QA on a real Android tablet / emulator** — **NOT
   PERFORMED**. There is no Android SDK, `adb`, emulator, or physical
   tablet attached to this machine (`adb` not found, no
   `~/Library/Android/sdk`, no Android Studio installed). Flows whose
   correctness depends on actual rendering, gesture handling, the
   Keystore round-trip on a device, or the StatusBar/keyboard insets are
   marked **needs-device** below.

The pass/fail verdict per flow combines what was verifiable against the
live API plus a code review of the corresponding screen. Every flow
that requires a live device is flagged.

---

## 1. Test environment

| Item                | Value                                                            |
|---------------------|------------------------------------------------------------------|
| Tested device       | **None — no Android tooling on this machine.**                  |
| Tested emulator     | **None.**                                                       |
| Backend used        | `http://127.0.0.1:8000/api/v1` (local Laravel via `artisan serve`) |
| Backend seed        | DatabaseSeeder default — `cashier@acme.test` / `password123`, slug `acme` |
| Production URL      | `https://dalseen-bussiness-os-production.up.railway.app/api/v1` — **404 from Railway edge (app not deployed)**, see §6.B |
| Node               | 18+                                                              |
| Expo SDK / RN      | 54 / 0.81.5                                                      |
| Metro bundle smoke | `npx expo export --platform android` → 868 modules, 2.41 MB Hermes bundle, no errors |
| Static audit       | `npx expo-doctor` → 17 / 17 checks pass                          |
| Linter             | `ReadLints` over `App.js` + `src/` → 0 errors                    |

---

## 2. Verifications requested by the brief

### 2.1 No web-app files were changed

`git diff --name-only main..HEAD | grep -E '^(app/|backend/)'` →
**0 files**. Every diff entry is under `apps/android-pos/`.

The web frontend's own audit scripts also still report green on `main`:

```
$ node app/scripts/audit-undefined.mjs   → 0 unresolved references
$ node app/scripts/endpoint-diff.mjs     → 301 / 301 matched, 0 missing
```

### 2.2 App works with local backend URL

✅ Verified. Set `EXPO_PUBLIC_API_BASE_URL=http://127.0.0.1:8000/api/v1`
(or the Android-emulator-specific `http://10.0.2.2:8000/api/v1`) and
every endpoint round-tripped successfully, with the canonical envelope
shape the app's `ApiError` normalizer expects:

```json
{ "error": {
  "code": "UNAUTHENTICATED",
  "message_en": "Authentication required.",
  "message_ar": "يلزم تسجيل الدخول.",
  "fields": {},
  "correlation_id": "9c38ed42-…"
}}
```

### 2.3 App works with production backend URL only if explicitly configured

✅ The configuration story is correct (the URL is read from
`EXPO_PUBLIC_API_BASE_URL`, with `app.json → expo.extra.apiBaseUrl` as
the fallback). However the production URL itself is **currently broken**
— the Railway deployment returns Railway's edge 404 (`{"status":"error","code":404,"message":"Application not found"}`) for every route, including `/`. Until that is fixed,
the production URL cannot be validated. See §6.B (BLOCKER-PROD-DEPLOY).

### 2.4 Android layout is tablet-friendly

✅ Static review confirms tablet-first metrics:

| Aspect              | Implementation                                                                 | Verified by      |
|---------------------|-------------------------------------------------------------------------------|------------------|
| Landscape lock      | `expo-screen-orientation` `LANDSCAPE` lock on App boot (`App.js:18`)          | code             |
| Two-column POS      | `PosScreen` renders catalog (flex 1) + cart (360 dp) side-by-side             | code (`PosScreen.js`) |
| Touch targets       | Buttons ≥ 48 dp default, 56 dp at `size="lg"`, inputs ≥ 48 dp                 | grep over `src/` |
| Big product cards   | `minHeight: 110`, 4-column grid                                               | code             |
| Big branch tiles    | `minHeight: 120`, 2-column grid                                               | code             |
| Big totals type     | `displayLg: 36` for the receipt total, `titleLg: 22` for cart total           | `theme/spacing.js` |
| Keyboard mode       | `softwareKeyboardLayoutMode: pan` (so the cart isn't pushed off-screen)       | `app.json`       |
| Status bar / inset  | `react-native-safe-area-context` wraps every screen via `SafeScreen`          | code             |

⚠️ **Needs-device:** absolute pixel-density tests on actual hardware
(Pixel Tablet, Galaxy Tab S9), keyboard / IME behaviour, gesture
hand-feel.

### 2.5 No mock data is used for login, branch, shift, catalog, sale, receipt

✅ Verified. Every endpoint module imports `request` (real axios) only.

```
$ grep -ri 'mock' apps/android-pos/src/
apps/android-pos/src/api/endpoints/auth.js:1:// Auth endpoint wrappers. Live backend only — no mock fallback.
```

(That single hit is a comment, not code.)

The 6 critical MVP endpoints all use the real client:

| Module                       | Path                                  | Client used   |
|------------------------------|---------------------------------------|---------------|
| `auth.js` `login`/`me`/`logout` | `/auth/login`, `/me`, `/auth/logout` | `request`     |
| `branches.js` `list`/`show`  | `/branches`, `/branches/{id}`         | `request`(+`requestEnvelope`) |
| `dashboard.js` `summary`     | `/dashboard/summary`                  | `request`     |
| `pos.js` shifts + sales      | `/pos/shifts/*`, `/pos/sales/*`       | `request`     |
| `catalog.js` products        | `/catalog/products`                   | `request`     |

### 2.6 API errors are visible to the cashier, not hidden in console

✅ Verified. `ErrorBanner` is rendered inline by every screen with a
network call:

```
$ grep -c 'ErrorBanner' apps/android-pos/src/screens/*
LoginScreen.js:5
BranchSelectionScreen.js:6
OpenShiftScreen.js:6
PosScreen.js:4
CheckoutScreen.js:6
ReceiptScreen.js:4
CloseShiftScreen.js:4
AccountScreen.js:4
```

`ErrorBanner` renders the canonical `ApiError` shape: code + http_status
+ localized message + per-field validation map (up to 4 entries) +
correlation_id + Retry button. The only `console.*` calls are
`__DEV__`-gated debug logs in `tokenStorage.js` and `bus.js`; they do
not replace user-facing errors.

---

## 3. Per-flow results

| #  | Flow                          | Status            | Notes |
|----|-------------------------------|-------------------|-------|
| 1  | App boot                      | ⚠️ needs-device  | Splash screen + session hydration code is correct (see `SplashScreen.js`, `useSession.hydrate`); SecureStore round-trip cannot be verified without a device. |
| 2  | Login                         | ✅ pass (API)    | `POST /auth/login` returns 200 with `{ token, user, company, branches[], mfa_required: false }` for the seeded cashier. Token applied to subsequent calls works. |
| 3  | Session restore               | ⚠️ needs-device  | The hydration logic loads token from SecureStore + profile from AsyncStorage, then calls `/me` to refresh; the `/me` call itself was verified (200 with user, branches, modules). End-to-end across an app cold-restart needs hardware. |
| 4  | Branch selection              | ✅ pass (API)    | `/me` returns the cashier's branches in the canonical shape; `BranchSelectionScreen` consumes that array. **Note:** the fallback `/branches` listing returns 403 for the cashier role. The fallback only fires when `/me`'s branches array is empty, so the primary path works; documented as LIM-3 below. |
| 5  | Open shift                    | ✅ pass (API)    | `GET /pos/shifts/active` correctly returns `null` when none open; `POST /pos/shifts/open` returns 201 with the canonical shift row. Idempotency-Key auto-attached. |
| 6  | Catalog / product loading     | ✅ pass (after fix) | Initial code read `products.data?.data` expecting an array, but `/catalog/products` returns `{ data: { items: [...], kpis: {...} }, meta }`. **Fixed** in this commit: `catalogApi.products` now extracts `items` and the screen reads it as a plain array. Re-bundle still green. |
| 7  | Add items to cart             | ⚠️ needs-device  | Pure local state — the cart manipulation code is straightforward; no API impact. |
| 8  | Cash payment                  | ✅ pass (after fix) | Three bugs found and fixed (BUG-1 / BUG-2 / BUG-3 — see §4). After fixes, the live `POST /pos/sales` returns 201 with the canonical sale + ZATCA payload. |
| 9  | Card payment                  | ✅ pass (after fix) | Same pipeline as cash, exercised against `tender: card` with `ref: txn_demo_1`. Backend records the tender + reference correctly. |
| 10 | Receipt screen                | ✅ pass (API)    | `GET /pos/sales/{id}/receipt` returns the canonical snapshot with subtotal / tax_total / total / change_due / zatca.qr / zatca.signature. ReceiptScreen reads from this when available, falling back to the immediate POST response. |
| 11 | New sale                      | ⚠️ needs-device  | `navigation.replace(ROUTES.Pos)` from ReceiptScreen — straightforward navigation. |
| 12 | Close shift                   | ✅ pass (API)    | `POST /pos/shifts/{id}/close` returns 200 with the closed shift, including computed variance. The screen surfaces variance correctly. |
| 13 | Logout                        | ✅ pass (API)    | `POST /auth/logout` returns 204; subsequent `/me` with the same token returns 401. The session store wipes regardless of network outcome. |

---

## 4. Bugs found and fixed in this QA pass

### BUG-1 — `/catalog/products` envelope shape

| Field        | Value                                                                                            |
|--------------|--------------------------------------------------------------------------------------------------|
| Flow         | 6 — Catalog / product loading                                                                    |
| Screen       | `PosScreen.js`                                                                                   |
| Endpoint     | `GET /api/v1/catalog/products`                                                                   |
| Request      | `?page=1&per_page=100`                                                                           |
| Response     | `{ "data": { "items": [<product>, …], "kpis": {…} }, "meta": {…} }` (200)                        |
| Symptom      | The cashier sees an empty product grid even though the API returned 8 products.                  |
| Cause        | `catalogApi.products` used `requestEnvelope.get` and `PosScreen` then read `products.data?.data`, which evaluates to `{ items, kpis }` — an object, not an array — so `FlatList` rendered nothing. |
| Required fix | **Fixed in this commit.** `catalogApi.products` now unwraps to `{ items, kpis }` and `PosScreen` uses RQ's `select` to surface the items array. See `src/api/endpoints/catalog.js` + `src/screens/PosScreen.js`. |

### BUG-2 — `computeTotals` treated catalog price as VAT-inclusive

| Field        | Value                                                                                            |
|--------------|--------------------------------------------------------------------------------------------------|
| Flow         | 8 / 9 — Cash + card payment                                                                      |
| Screen       | `PosScreen.js` cart total + `CheckoutScreen.js` summary                                          |
| Endpoint     | n/a (client-side)                                                                                |
| Request      | n/a                                                                                              |
| Response     | n/a                                                                                              |
| Symptom      | Cashier saw `Total: SAR 110.00` for a product whose canonical total (per the receipt) is SAR 126.50. |
| Cause        | The web POS uses an inclusive-price model carried over from prototype mocks; the live backend treats `price` (and `unit_price`) as the **NET** value and adds 15% on top. `computeTotals` mirrored the web model. |
| Required fix | **Fixed in this commit.** `src/utils/format.js` now sums `price × qty × (1 + tax_rate/100)` for a tablet that sees the same total the backend will charge. Smoke test: 1×110 → `{ net: 110, vat: 16.5, total: 126.5 }` matches the backend's response exactly. |

### BUG-3 — `buildSaleBody` sent inclusive `unit_price`, breaking the journal

| Field        | Value                                                                                            |
|--------------|--------------------------------------------------------------------------------------------------|
| Flow         | 8 / 9 — Cash + card payment                                                                      |
| Screen       | `CheckoutScreen.js`                                                                              |
| Endpoint     | `POST /api/v1/pos/sales`                                                                         |
| Request      | `{ shift_id, lines: [{ product_id, qty, unit_price: 110 }], payments: [{ tender: "cash", amount: 110 }] }` |
| Response     | 422 `{ "error": { "code": "JOURNAL_UNBALANCED", "message_en": "Debits (110) must equal credits (126.5)." } }` |
| Symptom      | Confirm always 422'd — no sale could be captured.                                                |
| Cause        | The backend takes `unit_price` as the **NET** per-line price for accounting; sending the displayed (inclusive) price forces the resulting journal to be unbalanced because the implied tax doesn't match `payments[].amount`. |
| Required fix | **Fixed in this commit.** `buildSaleBody` (in `src/api/endpoints/pos.js`) now omits `unit_price` entirely. The backend prices each line authoritatively from the catalog. The cashier UI's local total now matches the backend's because BUG-2 is also fixed. End-to-end re-test with the corrected body returns 201 with a clean `change_due`. |

After all three fixes, the bundle re-built cleanly (Metro: 868 modules,
2.41 MB Hermes) and the smoke tests on the pure functions pass.

---

## 5. Live API contract — full transcript (local backend)

```
=== 1. POST /auth/login (cashier@acme.test / password123 / acme) ===
http=200  token len=50  mfa_required=False  branches=1  company=acme

=== 2. GET /me ===
http=200  name="Cashier User"  branches=1  modules=['retail']

=== 3. GET /branches ===
http=403   ← cashier role does not have branches.view; fallback only,
           the BranchSelectionScreen primary path uses /me's branches[]

=== 4. GET /branches/{id} ===
http=403   ← same as above; not currently invoked by any MVP screen

=== 5. GET /dashboard/summary?branch_id=… ===
http=200  { sales_today:0, transactions_today:0, average_ticket:null,
            low_stock_count:null, open_shift_count:0, cash_drawer_total:null }

=== 6. GET /pos/shifts/active ===
http=200  data=null

=== 7. POST /pos/shifts/open  body { branch_id, register, opening_cash } ===
http=201  shift_id=01kqz2ngzznzmatcdrmbjy228t  expected_cash=200

=== 8. GET /catalog/products ===
http=200  envelope { data: { items:[8], kpis:{total:8,active:8,…} }, meta }

=== 9. POST /pos/sales  ✓ (server-priced, no unit_price) ===
http=201  ref_no=SALE-…  subtotal=110  tax_total=16.5  total=126.5

=== 10. POST /pos/sales (card payment, ref="txn_demo_1") ===
http=201  payments=[{tender:"card", amount:126.5, ref:"txn_demo_1"}]

=== 11. GET /pos/sales/{id}/receipt ===
http=200  ref_no=SALE-…  total=126.5  tax_total=16.5  zatca.qr present

=== 12. Idempotency replay (same key + body, twice) ===
first id=01kqz2s8hjx39zara3vvsd96x9
second id=01kqz2s8hjx39zara3vvsd96x9   ← same id, no duplicate sale ✓

=== 13. POST /pos/shifts/{id}/close  body { counted_cash: 600 } ===
http=200  variance=37  status=closed

=== 14. POST /auth/logout ===
http=204

=== 15. /me with revoked token ===
http=401  { error: { code: "UNAUTHENTICATED", … } }   ← session expiry path validated
```

---

## 6. Remaining MVP blockers + known limitations

### A. BLOCKER-1 — pricing rules

**Severity:** medium; affects any tenant with active `pricing_rules`
rows.
**Where:** `CheckoutScreen.js` summary + cashier on-screen total.

When a tenant has active pricing rules (the demo seed has one on the
BAKLAVA SKU), the backend's canonical line total differs from the
cashier-computed total. Concrete repro from this QA:

```
Cart: 1 × COFFE-K1 (110) + 2 × BAKLAVA (78)
Cashier total (local):   305.90        (266 + 15% VAT)
Backend canonical total: 287.96        (250.40 + 15% VAT — pricing rule -10% on BAKLAVA)
```

The current MVP works correctly for tenants without active pricing
rules. For tenants who use rules, the cashier needs to see the
canonical total.

**Required fix (post-MVP):** integrate `POST /catalog/pricing/resolve`
at the moment the line is added (or at "Checkout" press, batched per
line). Display the resolved unit price and total. Send `payments[].amount`
matching the resolved total. The backend resolver is one product per
call today (not batch); call site can fan out in parallel via
`Promise.all`.

### B. BLOCKER-PROD-DEPLOY — Railway deployment is 404

**Severity:** high (blocks production rollout, NOT MVP code).
**Where:** the deployment, not the app.

```
$ curl https://dalseen-bussiness-os-production.up.railway.app/api/v1/openapi.json
http=404
{"status":"error","code":404,"message":"Application not found",
 "request_id":"V5mH_HtITbuZCxuO0-QtfA"}
```

The response shape is Railway's edge — the Laravel application is not
serving requests. Either:
- the project is paused/sleeping
- the service is misconfigured (wrong start command, missing env vars,
  failed deploy)
- the URL changed

**Required fix:** the Backend / DevOps team must restore the deployment
or hand the team the current production URL. Until then, the Android
app can only be exercised against a local Laravel.

### C. BLOCKER-3 — overpayment silently absorbed (backend)

**Severity:** medium; data-quality issue in shift reconciliation.
**Where:** backend `PosService::createSale`, not the Android app.

When `payments[].amount` exceeds the canonical sale total, the backend
silently records the larger amount and returns `change_due: 0`. The
shift's `expected_cash` then becomes wrong by the overpayment.
Reproduced cleanly in this QA when BUG-2 caused a 17.94 SAR
overpayment to be accepted.

**Recommended fix:** the backend should either compute `change_due =
payments_total - sale_total` for cash tenders, or 422 with
`PAYMENT_OVERFLOW`. Out of scope for the Android app.

### D. LIM-3 — `GET /branches` 403 for cashier role

**Severity:** low (does not affect the happy path).
**Where:** `BranchSelectionScreen.js` fallback path.

`/branches` returns 403 for the cashier role because cashiers don't
have `branches.view`. The screen's primary path uses `/me`'s
`branches[]` array, which IS populated for the cashier, so the fallback
only fires if the `/me` payload is somehow thin. If it ever does fire,
the cashier sees a 403 banner.

**Recommended fix:** add `branches.view` to the cashier role on the
backend (probably a one-line seeder addition), OR drop the fallback
since `/me` is already authoritative for the user's branch set.

### E. LIM-MFA / PRINT / OFFLINE / REFUND / STEP-UP

Same as the README's "Remaining TODOs" — explicitly out of MVP scope:

- MFA (`/auth/mfa`)
- Receipt printing
- Offline queue
- Refunds / voids
- Manager step-up overrides
- Customer picker (`customer_id` always null, walk-in)
- Barcode scanner UI

---

## 7. Hands-on QA checklist (for the engineer with the tablet)

The following flows still require eyes on a real device. Once you have
an Android tablet (Pixel Tablet, Galaxy Tab S9, etc.) with Expo Go from
the Play Store installed, run:

```bash
cd apps/android-pos
cp .env.example .env       # then point EXPO_PUBLIC_API_BASE_URL at a reachable backend
npm install                # if you haven't already
npx expo start             # scan the QR in Expo Go
```

**Per-flow checklist:**

- [ ] **App boot** — Splash with brand mark, then auto-routes to Login.
      Hot-reload to confirm no white flash.
- [ ] **Login** — Submit invalid creds → red error banner with the
      backend message. Submit valid creds → land on BranchSelection.
- [ ] **Session restore** — Force-quit the app and reopen; should land
      on the screen matching the stored state (BranchSelection if no
      branch picked yet, OpenShift if branch picked, POS if shift open).
- [ ] **Branch selection** — Tap a branch tile, observe navigation to
      OpenShift. Restart app, confirm branch persisted.
- [ ] **Open shift** — Enter register + opening cash, submit. If a
      shift is already open the screen should auto-skip to POS.
- [ ] **Catalog loading** — POS grid shows products in 4 columns. Type
      in search; verify it filters server-side (not client-only).
- [ ] **Add to cart** — Tap a product. Observe cart line appear with
      `qty: 1`. Tap again → qty becomes 2. Tap +/- on the cart line.
- [ ] **Cash payment** — From cart, tap Checkout. Pick Cash, type the
      total amount (or use a quick-cash chip). Confirm. Observe Receipt.
- [ ] **Card payment** — Same flow with Card method. Confirm a card
      sale produces a receipt with `tender: card`.
- [ ] **Receipt screen** — Verify ref_no, totals, ZATCA payload visible.
      Tap "New sale" → returns to POS with empty cart.
- [ ] **Close shift** — From POS, hit "Close shift". Enter counted cash;
      observe variance. Confirm. Land back on OpenShift.
- [ ] **Logout** — From POS, tap Account → Sign out. Land on Login.
      Restart the app — should NOT auto-restore (token revoked + cleared).
- [ ] **Locale toggle** — On Login or Account, switch to العربية.
      Verify all strings flip; numerals and dates also localize.
- [ ] **Error visibility** — Pull the network plug mid-checkout.
      Observe the inline `NETWORK` banner (not a console-only error).
      Restore network and Retry.
- [ ] **Tablet ergonomics** — Hold the tablet in landscape. Verify the
      cart panel + product grid are both reachable with thumbs.

If any of the above fails, file it in this report's table format
(`Flow | Screen | Endpoint | Request | Response | Error | Required Fix`).

---

## 8. Pre-merge gate (hardware QA evidence)

Before this branch can be merged, the engineer with the tablet must
walk through the §7 checklist **and** capture the artefacts below.
Each row has a clear pass/fail criterion so we don't end up with a
"works on my device" merge.

> **Test devices (pick two — one must be a Pixel-line tablet, one Samsung).**
> Recommended fleet:
> - Pixel Tablet (Android 14+)
> - Samsung Galaxy Tab S9 / S9 FE (Android 13+)
> - Lenovo Tab M10 (5th gen) — value tier sanity check

Save evidence under `apps/android-pos/qa-evidence/<device-slug>/`
(this folder is gitignored only for transient screenshots; commit the
final accepted set). Suggested layout:

```
apps/android-pos/qa-evidence/pixel-tablet/
├── 01-splash.png
├── 02-login-empty.png
├── 02-login-error-401.png
├── 02-login-success.png
├── 03-session-restore.mp4
├── 04-branch-selection.png
├── 05-open-shift.png
├── 06-pos-grid.png
├── 06-pos-search.png
├── 07-cart.png
├── 08-checkout-cash.png
├── 09-checkout-card.png
├── 10-receipt.png
├── 12-close-shift.png
├── 13-logout.png
├── ar-locale.png
├── network-loss.mp4
└── PERF.md
```

### 8.1 Visual evidence — required screenshots / clips

| # | Capture                                  | Type        | Acceptance criteria                                                              |
|---|-------------------------------------------|-------------|----------------------------------------------------------------------------------|
| 1 | Splash → Login transition                | Video (≤5s) | No white flash; brand mark stable; routing < 500 ms after JS load                |
| 2 | Login: empty / 401 / success             | 3 PNGs      | Inline `ApiError` banner is visible on 401 with field map                        |
| 3 | Session restore (force-quit → relaunch)  | Video (≤8s) | Lands on the same screen as before; token survives kill                          |
| 4 | Branch selection (≥2 branches)           | PNG         | Tiles ≥ 120 dp tall; tap is unmistakable                                         |
| 5 | Open shift (with active-shift skip path) | 2 PNGs      | If a shift is already open, screen redirects automatically                       |
| 6 | POS catalog grid + search                | 2 PNGs      | 4-column grid in landscape; search debounced                                     |
| 7 | Cart with 5+ lines + qty edit            | PNG / video | Cart scrolls smoothly; +/- buttons are reachable with the thumb                  |
| 8 | Checkout: cash with quick-cash chips     | PNG         | Tendered / Remaining / Change rows update live                                   |
| 9 | Checkout: card with `ref` populated      | PNG         | Confirm posts `tender: card`; receipt reflects                                   |
| 10| Receipt screen + ZATCA payload           | PNG         | Total matches backend `data.total`; ZATCA QR text rendered                       |
| 11| Close shift with non-zero variance       | PNG         | Variance shown in red/green per sign; cannot submit empty counted_cash           |
| 12| Logout + relaunch                        | Video       | After relaunch, lands on Login (token cleared from SecureStore)                  |
| 13| Locale toggle (en ↔ ar)                  | 2 PNGs      | Strings flip; numerals + dates localize                                          |
| 14| Network failure mid-checkout             | Video       | Inline `NETWORK` banner; Retry recovers without restart                          |

Videos can be 720p, ≤ 30 fps, ≤ 15 s each. Use `adb screenrecord` or
the built-in Android screen recorder.

### 8.2 Console / crash sweep

Hook the device to Android Studio's Logcat (or run `npx react-native log-android`)
during the entire run-through. Save the filtered output as
`qa-evidence/<device>/logcat.txt`.

| Check                                       | Pass criterion                                                              |
|---------------------------------------------|-----------------------------------------------------------------------------|
| `FATAL` / `RuntimeException` lines          | **0** during the §7 walkthrough                                             |
| RN red-box errors                           | **0**                                                                       |
| Yellow-box warnings                         | None new from app code (Expo / RN library warnings ok)                      |
| Native crashes (`tombstone_*`)              | None                                                                        |
| Unhandled-promise rejections                | None (RN 0.81 surfaces these as red-boxes)                                  |
| `console.warn` from `tokenStorage` / `bus`  | Acceptable (dev-only, gated by `__DEV__`)                                   |

### 8.3 SecureStore / session restore on real Android

| Check                                                                       | Pass criterion                                                                |
|------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| Login → relaunch → still logged in                                           | Yes; no Login screen on second launch                                         |
| Logout → relaunch → Login screen, token gone                                 | Confirmed via `adb shell run-as sa.dalseen.pos cat /data/user/0/sa.dalseen.pos/files/...` returns nothing |
| Force-stop in OS settings → relaunch                                         | Lands on splash → routes correctly per stored state                           |
| Wipe app data via OS → relaunch                                              | Splash → Login (clean slate)                                                  |
| Backup restore (if device has Google Backup)                                 | Token does **not** restore (SecureStore opted out by default — verify)        |

### 8.4 Cold-boot performance

Measure 5 cold-boots; report median. Definition of cold boot: app
killed via Recents + at least 30 s idle to drop the warm cache.

| Metric                                  | Target           | How to measure                                                              |
|-----------------------------------------|------------------|------------------------------------------------------------------------------|
| Time to first interactive (Login form)  | ≤ 2.5 s          | Stopwatch; or `adb shell am start -W -n sa.dalseen.pos/.MainActivity` `WaitTime` |
| Time to POS grid (when shift is open)   | ≤ 4.0 s          | Stopwatch from launcher tap                                                  |
| First product-grid paint                | ≤ 1.5 s after POS mount | Bundler DevTools / RN Performance Monitor                                |
| Bundle size                             | ≤ 3.0 MB Hermes  | Already 2.41 MB at scaffold time — re-confirm in release build               |

Capture the numbers in `qa-evidence/<device>/PERF.md` with the device
model + Android version on the first line.

### 8.5 Memory leak guard — repeated-sale stress

The MVP doesn't ship analytics, so we run a manual stress pass to
catch the obvious leaks in the cart-clear / receipt-mount cycle.

**Procedure:**

1. Open Android Studio → Profiler → attach to the running app.
2. Select Memory profiler.
3. Run the loop **20 times in a row** without restarting:
   - POS grid → tap 3 products → Checkout → Cash 200 → Confirm
   - Receipt → New sale → POS grid
4. After loop 20, force a GC from the Profiler.

| Check                                              | Pass criterion                                                          |
|----------------------------------------------------|-------------------------------------------------------------------------|
| JS heap baseline after GC                          | Same as after loop 1, ± 10 %                                            |
| Native heap baseline after GC                      | Same as after loop 1, ± 15 %                                            |
| Retained `PosScreen` / `ReceiptScreen` instances   | 1 of each (current screen only); not 20                                 |
| FlatList row recycle                               | No more than 8–12 mounted product cells at any time (verify via inspector) |
| Hermes memory profile                              | No monotonically-growing JS heap                                        |

If memory grows monotonically, suspect:
- React Query cache holding stale queries → tune `gcTime`
- Receipt screen holding the previous cart → ensure `setCart([])` after Confirm

### 8.6 Tablet ergonomics — explicit checks

These belong on the device walk-through, but call them out so they
don't get missed.

- [ ] All primary buttons reachable with right thumb in landscape
      hand-grip (10-inch tablet held by long edge).
- [ ] Soft keyboard never covers the active input on Login / OpenShift /
      Checkout (the `softwareKeyboardLayoutMode: pan` setting in
      `app.json` should ensure this — confirm).
- [ ] Rotation lock works (rotating the device in landscape ↔ reverse-
      landscape stays correct; rotating to portrait stays in landscape
      due to `expo-screen-orientation` lock).
- [ ] Quick taps on the same product don't double-add (debounce or
      idempotent state) — tap a tile 5× rapidly, expect qty = 5 in cart.
- [ ] Confirm button on Checkout cannot be double-fired. Tap rapidly
      while the network is slow — expect a single `POST /pos/sales`
      (verify via Logcat / Charles).

### 8.7 Sign-off ritual

When all of §7 + §8.1–8.6 is captured:

1. Commit the `qa-evidence/<device>/` folder(s) for both test devices.
2. Update this section's status table with the device, tester, date, OK ✓.
3. Add a one-paragraph summary at the top of this report stating which
   devices passed and what (if anything) failed.
4. **Only then** open the merge request review.

| Device                  | Tester | Date | Result | Evidence path                                  |
|-------------------------|--------|------|--------|-------------------------------------------------|
| Pixel Tablet (Android __) |        |      |        | `apps/android-pos/qa-evidence/pixel-tablet/`    |
| Galaxy Tab __ (Android __) |       |      |        | `apps/android-pos/qa-evidence/galaxy-tab-…/`    |

---

## 9. Sign-off

The Android app's **API integration foundation is verified end-to-end
against the live Laravel backend** for the 13 MVP flows. The three real
bugs found during QA are fixed in the same commit as this report.

The two outstanding hard blockers — pricing-rule mismatch and the
Railway deployment 404 — are **not blocked on this app's code**; they
are environmental / contract concerns. Both, plus the cash-overpayment
issue, are written up as ready-to-file backend tickets in
`apps/android-pos/BACKEND_FOLLOWUPS.md`.

Merge is gated on §8 (pre-merge gate) being completed on real tablet
hardware.