feat(facility): scan-to-verify orders (#52) and payout ledger with escrow terms (#53)

[oluwa1to9-web]

Summary

Closes #52
Closes #53

Implements the Phase W4 Facility core-flow extensions:

1. Scan-to-verify orders with device camera ([Phase W4] Scan-to-verify orders with the device camera #52) (implements PRD §8.1.6 verifiable order tokens)
2. Facility payout ledger with per-order escrow status and terms ([Phase W4] Facility payout ledger with per-order escrow status and terms #53) (implements PRD §9 custodial escrow payments with docforum-escrow Threat Model T8 terms verification)

---

What changed & why

1. Scan-to-Verify Orders with Device Camera (#52)

When patients arrive with digital or paper order tokens, facility staff need immediate verification that an order is authentic, current, and eligible for fulfillment, rather than relying on unverified screenshots.

• Dedicated Route & View: Added /facility/verify (OrderVerifyPage) accessible from facility navigation tabs.
• Camera QR Scanner with Fallback: Uses native browser BarcodeDetector API with targeting reticle and animated scan beam (respecting prefers-reduced-motion).
• Strict Camera Teardown: Automatically and cleanly terminates all active MediaStreamTracks (track.stop()) when navigating away, unmounting, or pausing.
• Manual Token Entry: Accessible fallback form for typing or pasting order tokens when camera permissions are denied or unsupported.
• 5 Verified Order States Handled:
  • valid: Shows authentic order confirmation, minimal order summary (patient name, medication/lab test, issued/expires dates, instructions), and an instant "Proceed to fulfil →" button that jumps straight into the fulfillment flow (/facility?orderId=...).
  • superseded: Warning banner displaying the physician replacement order ID (supersededBy) and instructing staff not to dispense.
  • expired: Clear expiration cutoff notice prohibiting fulfillment of expired prescriptions or lab orders.
  • fulfilled: Informs staff that the order was already completed, displaying previous fulfillment timestamp and dispensing facility to prevent duplicate dispensing.
  • not_eligible: Rejection notice explaining specialty tier or network restrictions.
• Rate-Limit Error Surface: Gracefully handles and prominently displays HTTP 429 rate-limit responses with retry guidance to guard against token enumeration attacks.

2. Facility Payout Ledger with Escrow Status & Terms (#53)

Under threat model T8 of docforum-escrow, payees must review escrow terms (releaser rules, refund deadlines) before relying on held funds. This page exposes escrow conditions in plain language.

• Dedicated Route & View: Added /facility/payments (FacilityPaymentsPage) with responsive tab navigation.
• Totals Summary Cards: Real-time breakdown of funds Held in Escrow, Released to Facility, and Refunded to Patient, separated by asset (XLM vs USDC).
• BigInt-Safe Precision: Stellar stroops (7 decimals: 10,000,000 stroops = 1 XLM/USDC) are computed and formatted with BigInt (formatStroops) to prevent IEEE 754 precision errors.
• Plain-Language Terms & Countdown: Displays clear releaser explanations (patient pickup sign-off, platform automation, lab ingestion) and refund deadlines with remaining hour countdowns.
• Approaching Deadline Warnings: Prominently highlights held escrows with $< 48$ hours remaining before automatic refund, alerting staff to fulfill immediately.
• Stellar Explorer Links: Provides direct links to Stellar Expert testnet explorer (https://stellar.expert/explorer/testnet/tx/...) for funding transactions, release transactions, and refund transactions.
• Cursor Pagination & Filtering: Filter ledger entries by status (all, held, released, refunded) and asset (all, XLM, USDC).

---

Verification & Test Output

All linters, TypeScript typechecks, test suites, and production builds pass green:

> npm run typecheck
tsc -b --noEmit
(0 errors)

> npm test
✓ src/features/payments/components/FacilityPayoutLedger.test.tsx (5 tests)
✓ src/features/order-verify/components/OrderVerify.test.tsx (7 tests)
...
Test Files  26 passed (26)
     Tests  124 passed (124)
  Duration  17.28s

> npm run build
✓ built in 3.13s
dist/index.html                   2.90 kB │ gzip:   1.32 kB
dist/assets/index-DLE_4ozI.css   64.72 kB │ gzip:  10.77 kB
dist/assets/index-DDfdYOhE.js   549.72 kB │ gzip: 169.82 kB

---

Screenshots

Captured at desktop (1280px) and mobile (390px) widths:

• screenshots/facility-verify-desktop.png (Desktop Order Verification screen with camera scanner, tabs, and manual entry)
• screenshots/facility-verify-mobile.png (Mobile Order Verification screen)
• screenshots/facility-payments-desktop.png (Desktop Payout Ledger with totals cards, approaching deadline warning, and explorer links)
• screenshots/facility-payments-mobile.png (Mobile Payout Ledger screen)

---

Documentation

• Updated ARCHITECTURE_ESSENTIALS.md with documented assumed API shapes for POST /facilities/me/verify-order and GET /facilities/:facilityId/payout-ledger.
• Updated ROADMAP.md Phase W4 checklist items and added contribution changelog line.

[drips-wave]

@oluwa1to9-web Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits