================================================================================ LIQUOR ECOMMERCE — PRE-MIGRATION AUDIT HANDOFF FOR CURSOR ================================================================================ Date: 2026-07-27 Project: D:\xampp\htdocs\liquor-ecommerce Phase: Architecture v1.3 → Pre-migration audit COMPLETE ================================================================================ WHAT WAS DONE IN THIS SESSION ================================================================================ A final PRD / schema / implementation audit was performed BEFORE migration generation. This was NOT a redesign. No migrations, models, controllers, services, APIs, or packages were created. Actions completed: 1. READ all architecture v1.3 docs + searched entire repo for PRD files 2. AUDITED Phase-1 requirements against docs/first-prompt.txt (authoritative PRD) 3. VERIFIED Laravel version: PRD=13, composer=^13.8, architecture=13 (aligned) 4. AUDITED promotions, collections, pickup, pre-arrival, tax, shipping, snapshots, payments, inventory, idempotency, outbox, FKs, indexes, migration order, table count (48), and documentation drift 5. CREATED docs/architecture/PRE_MIGRATION_AUDIT.md (full audit report) 6. FIXED incomplete/stale architecture documentation (see FILES CHANGED below) ================================================================================ CURRENT PROJECT STATE ================================================================================ Repository: Fresh Laravel 13 skeleton only - composer.json → laravel/framework ^13.8, PHP ^8.3 - Starter users/cache/jobs migrations only - NO domain code implemented yet Architecture: v1.3 IMPLEMENTATION FREEZE + pre-migration audit passed Authoritative PRD: docs/first-prompt.txt (No separate client marketing PRD exists in repo) Authoritative schema inputs (use these for migration generation): - docs/architecture/PHASE1_SCHEMA_SPEC.md ← column spec (48 tables) - docs/architecture/DATABASE_INDEX_REGISTRY.md ← indexes - docs/architecture/MIGRATION_IMPLEMENTATION_PLAN.md ← batch order - docs/architecture/TABLE_REGISTRY.md ← classification - docs/architecture/PRE_MIGRATION_AUDIT.md ← audit report ================================================================================ VERDICT ================================================================================ READY_TO_IMPLEMENT_MIGRATIONS = YES READY_TO_GENERATE_MIGRATIONS = YES Condition: Generate ONLY the 48 REQUIRED NOW tables. Do NOT migrate foundation tables until business gates close (B1,B2,B4,B6,B7). IMPORTANT: Audit authorizes DESIGN READINESS only. Do NOT create migration files until user explicitly requests implementation. ================================================================================ FRAMEWORK VERSION RESULT ================================================================================ PRD_LARAVEL_VERSION = Laravel 13 PROJECT_COMPOSER_VERSION = laravel/framework ^13.8 ARCHITECTURE_VERSION = Laravel 13 FINAL_REQUIRED_VERSION = Laravel 13 No Laravel 12 found anywhere. No upgrade/downgrade needed. ================================================================================ TABLE COUNT ================================================================================ CURRENT_REQUIRED_TABLES = 48 TABLES_ADDED = 0 TABLES_REMOVED = 0 FINAL_REQUIRED_TABLES = 48 Conditional if client gates close later: B6 promotions → +5 tables (53 total) B7 collections → +2 tables (50 total) B1 pre-arrival → +2 tables (50 total) B4 compliance → +2 tables (50 total) ================================================================================ KEY AUDIT FINDINGS (PRD vs ARCHITECTURE) ================================================================================ REQUIRED AT LAUNCH (48-table core path — COVERED): Products, variants, brands, categories, media, pricing, sale pricing (via prices.effective_from/to), inventory, multi-store foundation, location-aware inventory, cart, checkout, tax snapshots, static shipping via shipping_methods, payments, orders with snapshots, multiple shipments schema, CMS, SEO, admin RBAC OPEN / CLIENT DECISION (do NOT add to initial 48 without approval): B1 Pre-arrival SELLING → foundation only; CMS display OK B2 Store pickup at launch → schema ready; seed/UX gated B3 Guest checkout → schema ready (carts.customer_id nullable) B4 Compliance rules → foundation only B5 Age verification → adapter config B6 Promotions/coupons → foundation only; discount_minor on orders stores quoted discounts without promo tables B7 Collections first-class → CMS content_sections workaround for P1 ARCHITECTURAL SUPPORT ONLY (designed, not migrated now): promotions*, collections*, incoming_inventory*, service_zones*, shipping_zones/rates/providers, vendors*, compliance_rules*, integrations* PRE-ARRIVAL BREAKDOWN: PRE_ARRIVAL_DISPLAY = P1 via CMS content_sections PRE_ARRIVAL_SELLING = OPEN (B1) — foundation schema only PRE_ARRIVAL_RESERVATION = OPEN (B1) — incoming_inventory_reservations PRE_ARRIVAL_RECEIVING = Feature phase when B1=YES PICKUP: Schema supports pickup WITHOUT fake shipments. fulfillments.method_type=PICKUP, states READY_FOR_PICKUP→PICKED_UP→COMPLETED shipping_methods.method_type=PICKUP No shipment row for pickup orders. PROMOTIONS: NOT required at launch per PRD ("identify Phase 1 vs later"). orders.discount_minor + order_items.line_discount_minor hold snapshots. If B6=YES later: additive migration of 5 minimal promo tables. COLLECTIONS: NOT required as tables at launch per audit (B7 open). Featured Collections via content_sections JSON config referencing product IDs. TAX: TaxProvider at checkout; snapshotted on orders/order_items. No tax_rates table required for P1. SHIPPING: shipping_methods + config JSON sufficient for static P1 fees. Provider zones/rates deferred. MONEY: PRD says DECIMAL; ADR-004 accepted decision = BIGINT minor units + currency_code. Not a blocker. ================================================================================ DOCUMENTATION FIXES APPLIED IN THIS AUDIT ================================================================================ Problem: PHASE1_SCHEMA_SPEC had stub specs ("per v1.2") for critical tables. Fixed: Full column definitions added for: - idempotency_keys (fingerprint, status, response_body, expiry, recovery cols) - pages, content_sections, site_settings, seo_metadata, redirects - order_addresses, order_status_history (expanded) - fulfillment_items, fulfillment_status_history - shipments, shipment_items, shipment_tracking_events - payment_attempts (with UQ payment_id+attempt_number) - payment_webhook_events (composite dedup, nullable payment_id) Other fixes: - 21-open-decisions.md → restored full B1-B7, C1-C10 tables - 27-database-constraints.md → Phase-1 fulfillment (no vendor_id XOR yet) - 27-database-constraints.md → webhook UNIQUE(provider_code, provider_event_id) - ERD.md → Phase-1 vs future vendor fulfillment note - DATABASE_INDEX_REGISTRY.md → uq_orders_order_number, uq_attempts_payment_number - 23-idempotency.md → states + pointer to PHASE1_SCHEMA_SPEC - PRD_TRACEABILITY_MATRIX.md → v1.3 header - README.md → link to PRE_MIGRATION_AUDIT - ARCHITECTURE_V1_3_FREEZE.md → references audit + READY_TO_GENERATE_MIGRATIONS ================================================================================ FILES CHANGED (THIS SESSION) ================================================================================ CREATED: docs/architecture/PRE_MIGRATION_AUDIT.md docs/PRE_MIGRATION_AUDIT_COMPLETE_FOR_CURSOR.txt (this file) UPDATED: docs/architecture/PHASE1_SCHEMA_SPEC.md docs/architecture/21-open-decisions.md docs/architecture/27-database-constraints.md docs/architecture/ERD.md docs/architecture/DATABASE_INDEX_REGISTRY.md docs/architecture/23-idempotency.md docs/architecture/PRD_TRACEABILITY_MATRIX.md docs/architecture/README.md docs/architecture/ARCHITECTURE_V1_3_FREEZE.md NOT CHANGED (still authoritative, read before implementing): docs/architecture/TABLE_REGISTRY.md docs/architecture/MIGRATION_IMPLEMENTATION_PLAN.md docs/architecture/22-state-machines.md docs/architecture/EVENT_CATALOG.md docs/architecture/CRITICAL_SCENARIO_TEST_MATRIX.md docs/architecture/decisions/ADR-001 through ADR-013 docs/first-prompt.txt docs/ARCHITECTURE_V1.3_COMPLETE_FOR_CHATGPT.txt (may lag individual .md files) ================================================================================ FROZEN ARCHITECTURE RULES (DO NOT CHANGE DURING MIGRATION GEN) ================================================================================ IDs: BIGINT PK internal + CHAR(26) ULID public_id on API resources Money: BIGINT minor units + CHAR(3) currency_code (ADR-004) Sellable: product_variants Inventory: SALE commit at fulfillment ALLOCATED only (not at payment) Payment: Payments NEVER UPDATE orders (async via payment.captured consumer) Orders: Terminal states COMPLETED / CANCELLED only (CLOSED removed) Reservations: checkout_expires_at cleared on order.confirmed expiry only when order.status = PENDING_PAYMENT Pickup: No shipment row; fulfillment states only Fulfillments P1: inventory_location_id NOT NULL, NO vendor_id Outbox: transactional; event_id ULID unique Idempotency: UQ(actor_scope, operation_scope, idempotency_key) ================================================================================ MIGRATION BATCH ORDER (from MIGRATION_IMPLEMENTATION_PLAN.md) ================================================================================ Batch 0: outbox_messages, idempotency_keys, audit_logs, search_index_state Batch 1: customers, roles, permissions, role_permissions, user_roles, ALTER users Batch 2: brands, categories, products, product_variants, product_categories, media_assets, catalog_media Batch 3: stores, store_addresses, inventory_locations Batch 4: inventory_levels, inventory_reservations (order_id nullable, no FK yet), inventory_transactions Batch 5: price_lists, prices, carts, cart_items Batch 6: orders, order_items, order_addresses, order_status_history, ALTER inventory_reservations ADD FK order_id Batch 7: payments, payment_attempts, payment_transactions, refunds, payment_webhook_events Batch 8: shipping_methods, fulfillments, fulfillment_items, fulfillment_status_history, shipments, shipment_items, shipment_tracking_events Batch 9: pages, content_sections, site_settings, seo_metadata, redirects ================================================================================ UNRESOLVED CLIENT DECISIONS (mark OPEN — do not guess) ================================================================================ B1 Pre-arrival selling at launch? B2 Store pickup at launch? B3 Guest checkout required? B4 Initial compliance rules / jurisdictions? B5 Age verification at checkout and/or pickup? B6 Promotions/coupons at launch? B7 Collections first-class vs CMS-only? C1 USD confirmation C2 Reservation TTL default (15m proposed) C3 Async payment extension window C4 Split fulfillment at launch C5 Shipping zone granularity C6 Audit retention defaults C7 Customer auth session vs token C8 Admin 2FA at launch C9 Tax provider selection C10 Notification channels for P1 ================================================================================ WHAT CURSOR SHOULD DO NEXT (when user asks) ================================================================================ IF user says "generate migrations": 1. Read PHASE1_SCHEMA_SPEC.md + DATABASE_INDEX_REGISTRY.md + MIGRATION_IMPLEMENTATION_PLAN.md 2. Create Laravel migrations in batch order (0→9) 3. Exactly 48 domain tables (+ keep starter users/cache/jobs) 4. Do NOT invent columns not in PHASE1_SCHEMA_SPEC 5. Do NOT migrate foundation tables (promotions, collections, incoming_*, etc.) IF user has NOT asked to generate migrations: STOP. Architecture/documentation work is complete for this phase. DO NOT (unless explicitly requested): - Create Eloquent models - Create controllers / services / APIs - Install packages - Implement business logic - Migrate foundation tables based on assumptions ================================================================================ QUICK REFERENCE: 48 REQUIRED NOW TABLES ================================================================================ Identity (6): users, customers, roles, permissions, role_permissions, user_roles Catalog (7): brands, categories, products, product_variants, product_categories, media_assets, catalog_media Store (3): stores, store_addresses, inventory_locations Inventory (3): inventory_levels, inventory_reservations, inventory_transactions Pricing/Cart (4): price_lists, prices, carts, cart_items Orders (4): orders, order_items, order_addresses, order_status_history Payments (5): payments, payment_attempts, payment_transactions, refunds, payment_webhook_events Fulfillment (7): shipping_methods, fulfillments, fulfillment_items, fulfillment_status_history, shipments, shipment_items, shipment_tracking_events CMS/SEO (5): pages, content_sections, site_settings, seo_metadata, redirects Platform (4): outbox_messages, idempotency_keys, audit_logs, search_index_state Total: 48 ================================================================================ END OF HANDOFF ================================================================================