metatrondelivery/IMPLEMENTATION_REVIEW_2026-09-04.md

# Implementation Review — 2026-09-04

**Scope:** Coverage audit of the current implementation against
`DS_Delivery_Date_Time_App_Study.docx` (the "DS Pickup Delivery Date & Time"
teardown by C2C).

**Reviewed:** `app/` (routes, services, lib), `extensions/`, `prisma/schema.prisma`,
`widget-src/`, `shopify.app.toml`, `tests/`.

**Verdict:** The scheduling core, concurrency safety, multi-surface consistency,
zones/auto-assignment, and all-plan checkout enforcement + confirmation — the hard
parts and the competitive moat — are solid and tested. The meaningful gaps are
inventory-based location exclusion (dead code), payment customization (absent),
rate *application* vs. *display*, product-page placement, and live slot
re-validation at checkout. Several gaps are consciously documented deferrals; the
inventory one looks like an actual wiring bug.

---

## Fully covered

| Study requirement | Where |
|---|---|
| 3 independent fulfillment methods (Shipping / Local Delivery / Pickup) with own rules, calendars | `Method` enum; per-method `SlotTemplate` / `SlotOverride` / `BlackoutDate` |
| Date→time slot picker; unavailable dates/slots **hidden**, not rejected | `app/services/scheduling.server.ts:89` filters past-cutoff / under-lead / blacked-out / full |
| Cut-off times + preparation/lead time (incl. per-product) | `cutoffMin`, `leadTimeMin` on template; `ProductRule.leadTimeMin` folded in at `app/services/availability-request.server.ts:210` |
| Blackout dates; per-weekday / per-method / per-location enable-disable | `BlackoutDate`, `SlotTemplate` per weekday, `SlotOverride.closed` |
| Per-slot capacity limit | `capacity` + `remainingCapacity()` in `app/services/capacity.server.ts` |
| Multi-location; radius **and** driving-distance zones; postal zones; nearest-location auto-assign; delivery-density threshold | `app/services/zones.server.ts` |
| Product / collection / vendor / type / tag rules → allowed methods, lead time, allowed locations | `app/services/product-rules.server.ts` |
| Rate resolution by zone / distance per method | `app/services/rates.server.ts` |
| Cart + cart-drawer placement; cross-theme auto-inject before checkout button | `widget-src/datetime-widget/datetime-widget.ts:570` |
| Thank-you / order-status confirmation on **all plans** | `extensions/datetime-widget/blocks/order-confirmation.liquid` |
| POS scheduling against the **same** capacity pool | `app/routes/pos.scheduling.*` reuse `resolveAvailabilityRequest` |
| Last-slot race prevention | atomic Lua hold in `app/services/holds.server.ts:22` + `tests/integration/holds.concurrency.test.ts` |
| Server-side checkout enforcement on non-Plus | `extensions/validation-slot` Function |
| Single availability service across surfaces; multi-tenant `shopDomain` scoping; DST-safe Luxon math | ✅ |
| Order write-back (metafield + note attributes) | `app/routes/webhooks.orders.create.tsx` |
| Ops dashboard: bookings by day/slot/location, utilization, revenue by method, CSV export | `app/services/dashboard.server.ts` |
| DS review complaint (pickup vs "estimated delivery date" mismatch) | explicitly fixed via method-specific labels + `delivery-customization` rename |

---

## Partial / deviations from the study

1. **Inventory-based location exclusion is coded but never called.**
   `excludeLocationsWithoutStock` (`app/services/zones.server.ts:241`) has **zero
   callers** — `resolveAvailabilityRequest` never invokes it. Study §3.4
   "product-inventory-based location choice" is effectively absent at runtime.
   *Looks like a wiring bug, not a deliberate deferral.*

2. **Rates are displayed, not applied.** `delivery-customization` only *renames*
   the delivery option to append a price label
   (`extensions/delivery-customization/src/evaluate.js:23`). Nothing adjusts the
   actual charged shipping price or feeds a Shopify rate. Study §3.6 / the DS core
   value prop ("location-based shipping/delivery/pickup rates") is only half there.

3. **Checkout re-validation checks presence only.** `validation-slot`
   (`extensions/validation-slot/src/evaluate.js`) verifies the `dd_*` attributes
   exist; it does **not** re-check that the slot is still open
   (capacity / blackout / cutoff). Study §5.2 explicitly names "or has since become
   invalid." Mitigation is the 10-minute hold TTL, which the code comments
   acknowledge.

4. **Validation Function can't be scoped by product.** Every order on an activated
   shop is treated as requiring a slot — no ProductRule-scoped enforcement
   (Functions can't read the app DB). A store mixing schedulable and
   non-schedulable items can't use it selectively.

5. **"Date range" selection reinterpreted.** The schema/engine implement a
   SHIPPING **arrival-range display** (`transitMinDays` / `transitMaxDays`), not a
   shopper-selectable multi-day range. Study §3.2 "support for picking a range
   rather than a single date."

6. **Product-rule "block a specific slot based on cart contents"** (§3.5, "fragile
   item that can't go on the earliest slot") is only expressible as a lead-time
   push. The planned `blockSlotRule Json?` field was dropped from `schema.prisma`.

7. **Pickup map is single-location.** The widget maps the one resolved location
   (`widget-src/datetime-widget/datetime-widget.ts:427`); there's no multi-pin
   pickup-location chooser. Study §3.4 "pickup locations shown visually on Google
   Maps."

8. **Multi-language is structure-only.** Locale keys exist but only
   `en.default.json` ships — no second translation.

9. **Per-day order cap not modeled** — only per-slot `capacity`. Study §3.3 "in a
   given slot **or day**."

---

## Not implemented

- **Payment customization** (§5.2 — "hide cash-on-delivery for a shipped order").
  `write_payment_customizations` scope is requested but no such Function exists.
- **Product-page placement** (§3.7). No product-page block — only cart / drawer /
  thank-you / order-status / POS.
- **Checkout UI Extension source** (`extensions/checkout-datetime/`) — only a
  gitignored `dist/` bundle; no `src/` or `shopify.extension.toml` tracked. The
  Plus native picker is not a maintained deliverable. (The all-plan Liquid
  confirmation block does cover thank-you / order-status.)
- **Returning-customer recognition** (§3.8) — `read_customers` deliberately
  dropped; documented as deferred.
- **Cart Transform** (deposits / fees) — scope requested, marked v2.
- **Named capacity resources** (oven / driver / picker pools) — capacity is a
  single integer; `CapacityResource` from the plan was never added.
- **GDPR compliance webhooks** are commented out in `shopify.app.toml` pending
  Shopify's Protected Customer Data approval (handlers exist). Blocks a
  Built-for-Shopify submission.

---

## Implementation follow-up — 2026-09-04 (same day)

Actioned in this pass ("Core + new Functions" scope; Cart Transform / deposits,
returning-customer recognition, and GDPR re-enable stay deferred).

### Done — code + passing unit tests (`npm test`, 156 green)

1. **Inventory-based location exclusion is now wired.**
   `resolveAvailabilityRequest` calls `excludeLocationsWithoutStock` when the
   app-proxy surface supplies an Admin client + cart variant GIDs; the widget
   now sends `variantIds`. Out-of-stock locations are dropped from both the
   single-location and delivery-zone paths, with a dedicated
   "no location stocks every item" message.
2. **Live slot re-validation at checkout.** New
   `app/services/checkout-snapshot.server.ts` writes a shop-metafield capacity
   snapshot; the `validation-slot` Function (`evaluateCheckout`) now rejects a
   complete selection when the snapshot shows the slot is full, blacked out,
   closed, past the daily cap, or gone from the schedule. Snapshot is refreshed
   on `orders/create|updated|cancelled` and on slot / blackout / location /
   enforcement edits.
3. **Scopable checkout enforcement.** `Shop.enforcementMode` (`all` / `tagged`
   / `off`) + `enforcementTag`, new **Checkout enforcement** admin page
   (`app.settings.tsx`), honoured by the Function via the snapshot's
   `enforcement` block and `schedulableProductIds`.
4. **Per-day order cap.** `Location.dailyOrderCap`, threaded through
   `getAvailability` (`dailyCap` + `consumedPerDate`) — the whole date drops
   once its bookings reach the cap, and per-slot `remainingCapacity` is clamped
   to the day's remaining budget. Admin field on the location edit screen.
5. **Product-rule slot blocking (§3.5).** `ProductRule.blockedStartMins`,
   unioned in `resolveProductRuleConstraints`, applied in `getAvailability` and
   re-enforced server-side in `resolveHoldRequest`. Admin field on the product
   rules screen.
6. **Product-page placement.** New `blocks/product-availability.liquid` +
   widget `data-mode="preview"` — a read-only "earliest available date per
   method" line that collects nothing.
7. **Second locale.** `extensions/datetime-widget/locales/fr.json` +
   `fr.schema.json` (French), proving the i18n path end-to-end.

New migration: `prisma/migrations/20260904120000_review_gaps` (hand-written;
apply with `prisma migrate deploy` — the dev DB was unreachable here).

### Done — source + unit tests, needs `shopify app deploy` / CLI to ship

8. **payment-customization Function** — new `extensions/payment-customization/`
   (`cart.payment-methods.transform.run`): hides cash-on-delivery / pay-in-store
   gateways on `SHIPPING` orders. Pure logic unit-tested
   (`tests/unit/payment-customization.test.ts`). Run
   `npm --prefix extensions/payment-customization run typegen` then
   `shopify app deploy`; merchant activates it under Settings → Payments.
9. **checkout-datetime Checkout UI Extension** — `src/` restored (was a
   gitignored `dist/` only): `Checkout.jsx` (Plus native picker →
   `checkout.scheduling.*` routes, same capacity pool), `ThankYou.jsx`,
   `OrderStatus.jsx`. `tsconfig` ships `checkJs:false` until the `<s-*>` props
   are reconciled against the live `@shopify/ui-extensions` checkout types
   (see its README) — the server side it calls is already tested.

### Not done (unchanged from above)

- Cart Transform / deposits — v2.
- Returning-customer recognition — needs `read_customers` + Protected Customer
  Data approval.
- GDPR compliance webhooks — still blocked on Shopify approval.
- Multi-pin pickup-location map picker — still single-location.
- Rates remain display-only (delivery-customization renames the option; it
  doesn't set the charged price). Left as a product decision.
- Worker periodic snapshot sweep — event-driven refresh covers the real cases;
  the 30-day horizon sweep needs offline-session storage first (noted in
  `jobs/worker.ts`).

## Suggested priority order

1. Wire `excludeLocationsWithoutStock` into `resolveAvailabilityRequest` (or
   delete it if intentionally cut). — *bug*
2. Decide rate strategy: real `delivery-customization` pricing / Shopify rate
   integration vs. accept display-only and document it.
3. Live slot re-validation at checkout (metafield capacity snapshot the
   Validation Function can read) — closes the §5.2 "since become invalid" gap.
4. Product-page placement block.
5. Payment customization Function (COD-on-shipping etc.).
6. Product-scoped enforcement toggle for the Validation Function.
7. Second locale + per-day cap + multi-pin pickup map as smaller follow-ups.
8. Re-enable GDPR webhooks once Protected Customer Data access is granted (launch
   blocker for BfS).