# Laravel Migration — Progress Tracker

Full architecture plan: `~/.claude/plans/commercedex-master-lexical-stroustrup.md`

Sequencing: **Foundation → Leaf modules → Core modules → Intelligence modules → Growth Automation Foundation → 12 Automations → API parity/cutover**, each phase independently verified (`deptrac analyse`, `php artisan test`, live curl checks) before moving to the next.

Local dev: server at `http://127.0.0.1:8000` (`php artisan serve`), MySQL/MariaDB via the existing XAMPP install (databases `commercedex_laravel` / `commercedex_laravel_test`).

---

## Phase 1 — Foundation ✅ DONE

- [x] Laravel 12 scaffolded, MySQL/MariaDB connected (table-prefix-per-module convention, e.g. `catalog_product`)
- [x] `deptrac.yaml` — Public/Internal boundary enforcement for all 18 modules, `deptrac analyse` clean
- [x] `php artisan make:module <Name>` scaffold generator
- [x] `App\Support\Result` — the `{ok, reason}` pattern PHP lacks natively
- [x] `App\Contracts\DomainEvent` + wildcard `LogDomainEvent` listener → `system_event_log` audit table
- [x] Sanctum bearer-token auth (matches admin SPA's existing `Authorization: Bearer` contract)
- [x] `EnsurePermission` middleware (`permission:products.manage` route alias)

## Phase 2 — Leaf modules (no cross-module dependencies) ✅ DONE

- [x] **Settings** — KV store + feature flags (`SettingsService`, no direct routes — other modules configure themselves through it, matching the original design)
- [x] **Users** — staff accounts, 5 default roles (Owner/Store Manager/Order Fulfillment/Marketing/Support), RBAC via `Gate::before`, audit log, bootstrap-owner console command
  - Verified live: login, staff CRUD, permission allow/deny (401/403), all behaving correctly
- [x] **Tax** — flat jurisdiction rate table — verified live: create/list rate
- [x] **Shipping** — flat-rate shipping + shipment/tracking records — verified live: create/list rate
- [x] **Discounts** — discount codes, pure-calculation/usage-recording split — verified live: create/list discount
- [x] **Analytics** — event log + daily metric rollups — verified live: `recordEvent()` correctly rolled up both `order_count` and `revenue` from one `order.placed`-shaped event
- [x] **Inventory** — stock levels, reservation/commit/release lifecycle, movement ledger — verified live: restock → set reorder point → sale that crosses the reorder point → `stock.low` fires → shows up in `/api/inventory/low-stock`
- [x] **Media** — image upload/processing (Intervention Image), disk storage — verified live: real PNG upload produced correctly-sized thumbnail/medium/large WebP variants + original, all four files present on disk and servable at `/media/<id>/<variant>.webp`

All 8 leaf modules done. `deptrac analyse`: 0 violations. `php artisan test`: passing. DB reset to a clean slate (fresh migrate + re-bootstrap owner) after verification.

## Phase 3 — Core commerce modules ✅ DONE

- [x] **Catalog** — products/variants/categories/collections (depends on Media)
- [x] **Search** — MySQL FULLTEXT product search (depends on Catalog) — *known gap: weaker typo-tolerance than the old Postgres trigram search, flagged for this task*
- [x] **Customers** — customer records, addresses, segments (depends on Orders)
- [x] **Payments** — gateway abstraction (manual + Paystack), depends on Settings
- [x] **Orders** — order/line-item persistence, guest lookup (depends on Customers, Notifications, Payments, Shipping)
- [x] **Notifications** — resolves recipient + dispatches via Laravel's native Notification system (depends on Customers, Users)
- [x] **Commerce Core** — the checkout saga (`CommerceCoreService::checkout()`/`quoteCheckout()`): reserve stock → charge → commit-or-release. Ported `checkout.test.ts`'s exact scenarios as the first Pest suite (`tests/Feature/CheckoutTest.php`) — insufficient stock, payment decline, invalid discount, empty cart, quote/checkout parity, stock decrement — all 6 passing live against MySQL.

`deptrac analyse`: 0 violations. `php artisan test` (Pest): 8 passed. Verified live via `php artisan serve` + curl: `/api/storefront/quote` and `/api/checkout` reproduce the exact quote-then-charge totals ($20 subtotal + $5 shipping + $2 tax = $27 total), order line items carry correct product/variant/SKU snapshots, and every failure path (insufficient stock, payment decline, invalid discount) leaves zero dangling stock reservations.

## Phase 4 — Intelligence modules ✅ DONE

- [x] **Automation Engine** — 4 detectors (low_stock, missing_info, duplicate_product, broken_category) + 4 recommenders (reorder_suggestion, catalog_quality_fix, frequently_bought_together, reengagement_campaign). "Don't nag" (one open detection/pending recommendation per subject) enforced at the DB level via MySQL's generated-column trick standing in for Postgres's partial unique index (see decisions log). `stock.low` → `HandleStockLow` queued listener → `reorder_suggestion` verified live end-to-end through the real Laravel queue. All 4 manual-trigger endpoints (`/api/automation/run-*`) and the recommendations CRUD (`GET /api/recommendations`, accept/dismiss) verified live via curl.
- [x] **Marketing** — campaigns + segments. Send loop moved off the request thread into `Jobs\SendCampaignJob` (real improvement over the old blocking synchronous send) — `sendCampaign()` now returns `{queued:true}` immediately; the admin UI polls `GET /api/campaigns/:id/stats` for final counts. The "suggested campaign from a recommendation" bridge (`POST /api/recommendations/:id/create-campaign`) lives in `app/Http/Controllers/RecommendationCampaignController.php` — app-layer composition of Automation+Customers+Marketing, since Marketing deliberately doesn't depend on Automation. Verified live: created a segment + campaign, sent it through the real queue (5 customers notified, status flipped to `sent`, stats correct), confirmed a duplicate send now 409s, and confirmed the recommendation→campaign bridge creates a real segment+draft campaign end-to-end.
- [x] **Merchant Health** — 0–100 score + 5 signals (catalog_quality, low_stock, fulfillment_speed, refund_rate, order_volume_trend), each a coaching sentence, not a bare number. Depends on Analytics (order volume trend), Automation (pending recommendation counts), Orders (stale-fulfillment + refund-rate stats). Fires `health_score.updated`. Verified live: `GET /api/health-score` correctly 404s `NOT_YET_COMPUTED` before any score exists, `POST /api/health-score/recompute` computes a real score (80/100, deducting 20 for an elevated refund rate) from live dev-DB data, and the follow-up `GET` returns the persisted result.

`deptrac analyse`: 0 violations (168 checked). `php artisan test` (Pest): 8 passed. All three Phase 4 modules verified live end-to-end via `php artisan serve` + curl, using the real MySQL-backed database queue (not `sync`) throughout.

## Phase 5 — Growth Automation Foundation ✅ DONE

- [x] Events → Listeners → Queue → Notifications pipeline — proven end-to-end by 4 real queued listeners across 3 modules so far (`SendOrderConfirmationEmail`, `IndexProduct`, `HandleStockLow`, `SendCampaignJob`), each dispatched via `Event::listen()` in `AppServiceProvider` and processed by `php artisan queue:work` against the real `jobs` table (`QUEUE_CONNECTION=database`). This is the exact substrate the 12 automations (Phase 6) plug into — each one is "one new Event + one new Listener + one new Notification," nothing else.
- [x] Channel abstraction — `Modules\Notifications\Internal\Channel` interface now has 5 implementations: `ConsoleChannel` (dev fallback), `ResendChannel` (real email), and new `PushChannel`/`SmsChannel`/`WhatsAppChannel` stubs (log-only, swappable for a real provider later with zero changes to any calling automation). `resolveChannel()` routes on the channel string via a plain `match`. `notifications_notification.channel` enum expanded to accept `push`/`whatsapp` (new migration).
- [x] `after_commit` queue config — `config/queue.php`'s `database` connection now sets `after_commit => true`, so a job/event dispatched inside a `DB::transaction()` only becomes visible to workers once that transaction actually commits (defensive backstop; every module already fires its events after the transaction closure returns, not inside it).

**Bugs found and fixed while building this phase** (both pre-existing, not introduced this session):
- `NotificationsService::resolveEmailChannel()` was reading `apiKey` off `getNotificationSettings()`'s public DTO, which only ever exposes a masked `apiKeyPreview` — meaning `ResendChannel` could never actually be selected regardless of merchant configuration, silently falling back to `ConsoleChannel`. Fixed by reading the raw (unmasked) setting directly.
- `UsersService::getStaffUser('owner')` treated the literal `"owner"` sentinel (used by Automation Engine's low-stock alert and elsewhere for "notify the merchant") as a real ULID, always returning null — so every staff notification addressed to `"owner"` silently failed to resolve a recipient and never actually sent. Fixed by special-casing `"owner"` to look up whichever staff user currently holds the Owner role. This directly blocked Phase 6's Low Stock Alert automation from ever notifying anyone, so it was fixed now rather than deferred.

Verified live: sent a real notification through all 5 channel types (email/push/sms/whatsapp/in_app) to the `staff:owner` sentinel — all 5 now correctly resolve the recipient and log/deliver, confirmed via `storage/logs/laravel.log`. `deptrac analyse`: 0 violations (172 checked). `php artisan test`: 8 passed.

## Phase 6 — The 12 required automations ✅ DONE (all 12)

**Customer Lifecycle**
- [x] Welcome Email — `Modules\Notifications\Listeners\SendWelcomeEmail` on `CustomerRegistered`
- [x] Order Confirmation (direct port)
- [x] Payment Confirmation — `Modules\Orders\Listeners\SendPaymentConfirmationEmail` on `PaymentSucceeded`
- [x] Shipping Confirmation — `Modules\Orders\Listeners\SendShippingConfirmationEmail` on `ShipmentCreated`
- [x] Delivery Confirmation — new `OrdersService::markDelivered()` (staff-triggered, `POST /api/orders/:id/mark-delivered`) fires `OrderDelivered`; `SendDeliveryConfirmationEmail` listens
- [x] Product Review Request — `ScheduleReviewRequestEmail` also listens to `OrderDelivered`, using the queued listener's `withDelay()` (7 days) rather than a separate scheduled job — verified live: job's `available_at` landed ~604,788s (~7.0 days) out

**Conversion**
- [x] Abandoned Cart Recovery — new `CartRecovery` module (`cart_recovery_checkout_attempt`, one open row per email). `CommerceCoreService::quoteCheckout()` calls `recordAttempt()` on every successful quote (the customer has reached the Contact step and priced a cart); `checkout()` calls `markRecovered()` on success. `Jobs\SendAbandonedCartRecoveryEmails` scans hourly (`Schedule::job(...)->hourly()`) for rows 24h+ old with no recovery/reminder yet, sends one recovery email per attempt, marks it reminded (never re-sent). Verified live: an abandoner (backdated 25h, never checked out) correctly got a recovery email naming the real product; a customer who completed checkout in between was correctly excluded from the scan.
  - Found and fixed a MySQL identifier-length bug while building this: an auto-named composite index (`cart_recovery_checkout_attempt_recovered_at_reminder_sent_at_index`) exceeded MySQL's 64-char limit, causing the `CREATE TABLE` to leave an orphaned, un-migrated table on first attempt — fixed by giving the index an explicit short name.
- [x] Wishlist Back-in-Stock — new `Wishlist` module (`wishlist_wishlist_item`, ephemeral rows), `POST /api/storefront/wishlist` (public, guest email via `findOrCreateCustomer`, same as guest checkout). **Storefront "Notify me" button deferred to Phase 7** (the storefront currently points at the old TS backend, which has no such route — wiring the button now would be pointing UI at a backend that isn't live yet; the API itself is built and verified).
- [x] Back-in-Stock Notification — shares `Modules\Wishlist\Listeners\NotifyWishlistSubscribers` on `StockBackInStock` with Wishlist Back-in-Stock, exactly as the plan anticipated ("can share infrastructure"). Verified live: subscribed a variant at 0 stock, restocked it, confirmed the real product name appeared in the notification body and the wishlist row was cleared after firing (so a later out-of-stock/back-in-stock cycle can be resubscribed to).

**Merchant Operations**
- [x] Low Stock Alert (direct port, done in Phase 4)
- [x] Weekly Merchant Summary — new `Jobs\SendWeeklyMerchantSummary`, scheduled via `Schedule::job(...)->weekly()->mondays()->at('09:00')` in `routes/console.php` (confirmed via `php artisan schedule:list`: `0 9 * * 1`). Pulls from Merchant Health (score + attention signals) and Analytics (order/revenue trend). Requires `MerchantHealthPublic` to depend on `NotificationsPublic` (added). Verified live via `dispatchSync()`: real digest email composed with actual score/trend/signal data.
- [x] Slow-Moving Inventory Alert — new `SlowMovingInventoryDetector`/`Recommender` pair (variants with stock on hand but no `sale` movement in 30 days; `InventoryService::listSlowMovingVariants()`), `POST /api/automation/run-slow-moving-inventory-detection`. Verified live: a variant with a recent sale was correctly excluded while an otherwise-identical variant with no sale correctly surfaced a `slow_moving_inventory_alert` recommendation ranked by capital tied up (price × qty on hand).

## Phase 7 — API parity + cutover ✅ DONE

The Laravel migration is functionally complete and cutover-ready: all 7 phases done, both admin and storefront React apps verified live against the new backend with zero frontend code changes, full checkout flow completed end-to-end through the real UI. `deptrac analyse`: 0 violations (197 checked). `php artisan test` (Pest): 29 passed.

- [x] All 78 TS routes reproduced with identical paths/payloads/status codes (78, not ~70 — the plan's estimate). Cross-checked programmatically: extracted every `app.<method>(...)` route from `src/index.ts` and diffed against `php artisan route:list`, normalizing `:param`/`{param}` syntax. Result: **zero missing, zero unexpected** (the only Laravel-side extras are the intentionally-new Phase 6 automation routes plus framework defaults `/up`, `/sanctum/csrf-cookie`, `/storage/{}`).
  - Found and fixed 3 genuinely missing routes this surfaced: `GET`/`POST /api/settings/store` + public `GET /api/storefront/store` (new `App\Http\Controllers\StoreSettingsController`, composes Settings+Catalog+Shipping for the currency-change price-relabel side effect), and `POST /api/storefront/variants/prices` (added to `StorefrontProductController`).
  - Found and fixed `GET /robots.txt` and `GET /sitemap.xml` were entirely missing (new `App\Http\Controllers\SeoController`) — and a stray default Laravel scaffold `public/robots.txt` static file was silently shadowing the dynamic route once added (PHP's built-in server serves static files before routing); deleted.
  - **Found and fixed a real functional gap**: `GET /api/products` and `GET /api/storefront/products` were never actually wired to the Search module at all — the `q` param fell through to a crude `LIKE '%q%'`-on-name-only match, meaning the fully-working, previously-verified FULLTEXT search (Phase 3) was unreachable from any product listing endpoint. The original TS composes Search+Catalog at the route layer (rank via `search.searchProducts()`, re-fetch full rows via `catalog.listProductsByIds()`, sort by rank) — ported as new `App\Http\Controllers\ProductSearchController` (app-layer composition, since `Search` already depends on `Catalog` and `Catalog` can't depend back without a cycle). Also added the missing `categoryId` filter to `CatalogService::listProducts()` and removed the incorrect ad-hoc `q` handling that lived there. Verified live via curl: both endpoints now return FULLTEXT-ranked results for a real query, plain listing still works with no `q`.
- [x] Full Pest suite green — ported `discounts.test.ts`, `pagination.test.ts`, `permissions.test.ts`, `search.test.ts` (checkout.test.ts was already ported in Phase 3). **29 tests passing, 0 failing.**
  - Ported `pagination.test.ts` first by *creating* the shared `App\Support\Pagination` helper it exercises (`src/pagination.ts` had no Laravel equivalent yet) — each list method was independently inlining its own clamp logic, none of which clamped a zero/negative `limit` up to 1 the way the original did. Refactored `CatalogService::listProducts()`, `OrdersService::listOrders()`, `CustomersService::listCustomers()` to use the shared helper, fixing that gap everywhere at once instead of three times.
  - Porting `permissions.test.ts` surfaced a real seed-data bug: the Store Manager and Support roles' permission grants (reconstructed by hand during Phase 2, since the exact TS grant matrix wasn't available then) didn't match `src/migrations/0003_users.sql`'s actual matrix — Store Manager was missing `orders.refund`/`marketing.*`, Support was missing `orders.refund`/`customers.manage`. Fixed the migration source (for future fresh installs) and patched the existing dev + test databases' `users_role_permission` rows directly to match.
  - Porting `search.test.ts` surfaced that InnoDB FULLTEXT indexes are **not visible within an open transaction** — confirmed empirically (`MATCH...AGAINST` returns empty for a row inserted earlier in the same uncommitted transaction) — so wrapping this suite in the project's standard `RefreshDatabase` (which runs every test inside a rolled-back transaction) made every assertion false-negative. Moved it to a new `tests/Integration/` suite (own `phpunit.xml` entry, no `RefreshDatabase`) that commits normally and cleans up its own fixture in `afterEach`. Also dropped the single-character-typo assertion (MySQL FULLTEXT has no trigram-equivalent fuzzy matching — pre-existing known regression, not new) and fixed the "unrelated query" fixture to avoid accidental word-token overlap between the fixture description and the query string (a MySQL-specific tokenization difference from Postgres trigram matching that the original test's wording didn't have to account for).
- [x] Side-by-side smoke test — **both apps**, driven live in a real browser against the Laravel backend on `php artisan serve --port=3000` (matches the Vite dev servers' existing proxy target, zero frontend config changes).
  - **Admin app**: Login → Home (Store Health Score + signals) → Orders list → Products list/search UI → Settings (Store details tab) → Marketing (Campaigns tab). All loaded and rendered correctly.
  - **Storefront app**: Home/browse → product detail (in-stock + out-of-stock states both correct) → add to cart → cart page (live-repriced via the newly-added `/api/storefront/variants/prices`) → full 4-step checkout (Contact → Shipping → Review → Payment, manual test gateway) → **order placed successfully**, confirmation page showed the real order number and total.
  - **Found and fixed a real contract bug this way**: the admin Orders list showed "Invalid Date" for every row. `OrdersService::listOrders()`/`toDto()` were returning the timestamp as `createdAt`, but the original TS API (and the admin app's hand-written TypeScript types, `admin/src/api/orders.ts`) both use `placedAt`. Renamed the DTO key in both places — confirmed live afterward: dates render correctly. This is exactly the class of bug route-parity checking and Pest tests can't catch (both only check that *a* field of the right type exists, not that its *name* matches what the frontend actually reads) — only driving the real UI surfaced it.

---

## Known issues / decisions log

- **Database engine**: switched Postgres → MySQL/MariaDB mid-Phase-1 for universal cheap cPanel shared-hosting compatibility (your call). Uses the existing local XAMPP MariaDB instance, not a separate install.
- **Search typo-tolerance gap**: MySQL FULLTEXT has no trigram equivalent — flag when Search is ported (Phase 3).
- **Sanctum + ULID gotcha**: `personal_access_tokens` migration needed `ulidMorphs()` instead of the default `morphs()`, since every model here uses ULID primary keys, not auto-increment integers.
- **API-only auth**: had to disable Sanctum's default "redirect to login page" behavior (`Authenticate::redirectUsing`) since there's no session-based login route — was throwing a confusing 500 instead of a clean `401 UNAUTHENTICATED`.
- **Intervention Image is actually v4, not v3** (the plan assumed v3's API) — `read()`/`toWebp()` don't exist in v4; it's `decodeBinary()` + `encode(new WebpEncoder(...))`. Fixed in `Modules\Media\Internal\ImageProcessor`.
- **Eloquent + MySQL doesn't reload DB column defaults after INSERT** (unlike Postgres's `RETURNING`) — `InventoryService`'s stock-level creation now sets `quantity_on_hand`/`quantity_reserved`/`reorder_point` explicitly to `0` rather than relying on the migration's column defaults, otherwise the freshly-created in-memory model reported `null`.
- **deptrac ruleset direction**: initially had `XInternal: [XPublic]` (backwards) — a module's Public service needs to depend on its own Internal repositories/models, not the other way around. Fixed to `XPublic: [XInternal]` for every module.
- **PHP's eager DI vs TS's lazy module imports**: a genuine 3-node circular dependency (`Customers → Orders → Notifications → Customers`, all constructor-injected) caused infinite recursion / memory exhaustion — PHP's container eagerly builds the whole graph, unlike TS's lazy `import * as x`. Fixed by resolving `NotificationsService`'s `CustomersService` dependency lazily (`app(CustomersService::class)` inside the method) instead of constructor-injecting it — the only edge in the whole module graph needing this.
- **Queued listeners don't get full container method-injection**: `CallQueuedListener` calls `handle($event)` with just the event, not the extra-parameter injection a synchronous `Event::dispatch()` gives — `SendOrderConfirmationEmail` and similar listeners need their dependencies constructor-injected, not method-injected.
- **`CatalogService::getVariantDetails()` was missing `productName`/`variantName`/`sku`** until Commerce Core needed them for order line-item snapshots — added an Eloquent `product()` relation on `ProductVariant` and expanded the DTO.
- **MySQL has no partial unique index** (Postgres's `WHERE resolved_at IS NULL` / `WHERE status = 'pending'`, used by Automation Engine's "don't nag" rule) — worked around with the standard generated-column trick: a virtual column that's `NULL` unless the row is open/pending, with a plain unique index on it (MySQL unique indexes treat multiple `NULL`s as distinct, so the constraint only bites while a row is actually open/pending).