### Weight Verification — Project Integration Guide

This document explains how the Weight Verification plugin is installed, configured, and used within this project. It covers the patient and prescriber flows, routes, integration points, and how to test the feature.

---

### What the plugin does

- After payment, any order containing an item flagged `requires_weight_verification` puts the patient into a photo-verification flow.
- The patient submits **two full-length photos** (front + side) via a live camera capture component.
- A prescriber reviews the photos in the existing doctor order screen; **item approval is blocked until the photos are submitted**.
- The prescriber can **request new photos**, which re-opens the patient's tab and notifies them via the existing messaging system (message + email).
- Photos are stored as **private** Clinic `PatientFile`s and are only viewable through the admin file route.

---

### Installation and enabling

The plugin is pre-installed as part of this project. The steps below are only needed when migrating into an older project.

1. **Register the service provider** in `config/app.php` providers:
   - `\Mtc\Plugins\WeightVerification\Providers\WeightVerificationServiceProvider::class`

2. **Run migrations**
   - `php artisan migrate`
   - Adds the `weight_verifications` table and the `items.requires_weight_verification` column.

3. **Feature flag** (enabled by default)
   - Config: `plugins/WeightVerification/config/weight_verification.php`
     - `enabled => env('WEIGHT_VERIFICATION_ENABLED', true)`
   - To disable, set in `.env`:
     - `WEIGHT_VERIFICATION_ENABLED=false`

The service provider:
- Loads plugin routes, migrations and config.
- Registers the `WeightVerificationService` as a singleton.
- Listens for `Mtc\Shop\Events\OrderPaidEvent` to create a pending verification when a flagged order is paid (only when the feature is enabled).

---

### Configuration options

`plugins/WeightVerification/config/weight_verification.php`

#### enabled
- **Type:** boolean
- **Default:** true
- **Environment variable:** `WEIGHT_VERIFICATION_ENABLED`
- **Description:** Master switch for the feature. When disabled: no patient tab, no order-complete banner, no approval gating, and no verification lookups run.

#### default_resubmission_message
- **Type:** string
- **Description:** Default message pre-filled for the prescriber (and used as the fallback sent to the patient) when requesting new photos. Single source of truth for the admin controller fallback and the doctor-screen prompt default — edit here rather than in code.

---

### Flagging a product

- Admin → Products → edit a doctor/prescription item → tick **"Requires weight verification (photos)"** → save.
- This sets `items.requires_weight_verification = 1`.

---

### Statuses

| Status | Meaning |
| --- | --- |
| `pending` | Awaiting the patient's photos (initial state). |
| `submitted` | Photos uploaded, awaiting prescriber review. |
| `approved` | Prescriber approved the photos; item approval proceeds. |
| `resubmit_required` | Prescriber requested new photos; patient must resubmit. |

`pending` and `resubmit_required` are the "action required" states shown to the patient.

---

### Routes overview

Front-end (authenticated member)
- `GET members/weight-verification` → `WeightVerificationController@index` (route: `members-weight-verification`)
- `POST members/weight-verification` → `WeightVerificationController@store` (route: `members-weight-verification-store`)

Admin (authenticated)
- `POST admin/weight-verification/request-resubmission` → `Admin\WeightVerificationAdminController@requestResubmission` (route: `admin-weight-verification-request-resubmission`)

---

### End-to-end flow

1. **Order paid → pending verification**
   - The plugin listens to `OrderPaidEvent`. If the paid order contains a flagged item, a single `pending` verification is created (idempotent; one record per order).

2. **Patient submits photos**
   - A **Weight verification** tab appears in the member menu with an **Action Required** indicator.
   - The patient captures a front photo and a side photo (live camera, 10-second auto-capture countdown), then submits.
   - Photos are stored as private `PatientFile`s (`weight_front` / `weight_side`) and the verification moves to `submitted`.

3. **Prescriber review**
   - A **Weight verification** panel in the doctor order screen shows both photos and the submitted timestamp.
   - The item's **Approve** button is disabled (and approval is blocked server-side) until photos are submitted.
   - Approving the item flips the verification to `approved`.
   - **Request new photos** sets the verification to `resubmit_required`, notifies the patient, and re-opens their tab. On resubmission, the previous photos are replaced and removed.

---

### Integration points

- `core/includes/functions.twig.php` — `member_weight_verification()` Twig function, used by the member menu to show the action-required indicator.
- `plugins/Clinic/Src/Models/PatientFile.php` — new file types `weight_front` / `weight_side`.
- `shop/admin/ajax.php` — approval gating (`approvalBlockedForOrder`) and marking approved on item approval; injects the verification into the doctor item view.
- `shop/admin/orders/manage.order.doctor.php` — "Request new photos" handler.
- `shop/admin/products/item.php` + `shop/classes/class.item.php` + `shop/src/Item.php` — the `requires_weight_verification` product flag.
- `shop/checkout/order_complete.php` — order-complete CTA (gated by the feature flag).
- Front-end Vue components: `sites/default/js/components/weight_verification/` (registered in `sites/default/js/main-app.js`).

---

### Front-end notes

- The patient flow needs **camera access** (`getUserMedia`), which requires a secure context — use `https` or `localhost`, on a device with a webcam.
- Photo uploads are restricted to image formats (`jpg`, `jpeg`, `png`) with a 16 MB cap.
- Run a front-end build after pulling: `npm run build` (or `npm run dev` for HMR).

---

### Testing

Automated:
```sh
docker exec -it pharmacy-starter-web ./vendor/bin/phpunit --filter=WeightVerification
```
Covers: the OrderPaid trigger (flagged / unflagged / idempotent), approval gating, review outcomes (approve / request resubmission), the upload flow, resubmission supersede + cleanup, and the double-submit guard.

Manual:
1. Flag a product (see **Flagging a product**).
2. Order it and complete payment so the order is marked paid.
3. As the patient: confirm the order-complete banner, the dashboard tab with the action-required dot, capture + submit both photos.
4. As the prescriber: confirm the review panel shows both photos, approval is blocked until submission, approving flips to `approved`, and **Request new photos** re-opens the patient tab and messages them (check Mailhog at `http://localhost:8025`).
5. Edge cases: resubmission replaces old photos; disabling the flag removes the tab/banner/gating; an order without a flagged item creates no verification.

---

### Troubleshooting

- **No tab / banner / gating** — confirm `WEIGHT_VERIFICATION_ENABLED` is not `false` and migrations have run.
- **Verification not created on payment** — confirm the order is actually marked paid (fires `OrderPaidEvent`) and contains an item with `requires_weight_verification = 1`.
- **Camera won't start** — must be a secure context (`https`/`localhost`) with camera permission granted.
- **Photos not visible to prescriber** — they are served via the admin file route; confirm you are logged into the admin panel.
- **Resubmission notification not received** — check the queue/mailer config and Mailhog; the tab still re-opens even if the message fails to send.
