# Database Schema Documentation

## Database Overview
The database stores user accounts, user roles (`admin`, `vendor`, `customer`), unique seller identification codes (`seller_code`), approval/verification statuses, creator onboarding survey & address details, marketplace prompt products, orders, reviews, follows, favorites, support tickets, payouts, vendor settings, and vendor discount coupons.

> **Last verified:** 2026-10-31 against the live `promptery_db` (MySQL) schema (3,903 products including 3,851 Prompts.chat community prompts, 69 categories, RBAC, audit logs, Hybrid 2FA columns, enhanced `vendor_payouts` withdrawal system, and creator onboarding/survey columns).

---

## 1. Tables & Schema Definitions

### A. `users` Table
Stores system admins, vendors, and customers with profile, unique seller code, store identity, contact & billing address, creator onboarding survey responses, KYC verification, financial controls, and Hybrid 2FA attributes.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `seller_code` | `VARCHAR(50)` | `UNIQUE, INDEXED, NULLABLE` | Unique seller identifier code (format: `VND-XXXXXX`) |
| `username` | `VARCHAR(100)` | `UNIQUE, INDEXED, NULLABLE` | Unique SEO username identifier (e.g. `demo-vendor`, `promptschat`) |
| `store_name` | `VARCHAR(255)` | `NULLABLE` | Official vendor store/studio display name (captured during `/vendor/onboarding`) |
| `name` | `VARCHAR(255)` | `NOT NULL` | User full name |
| `email` | `VARCHAR(255)` | `UNIQUE, NOT NULL` | Login email address |
| `phone` | `VARCHAR(50)` | `NULLABLE` | Contact phone / WhatsApp number (with country code) |
| `country` | `VARCHAR(100)` | `NULLABLE` | Billing / residence country |
| `address` | `VARCHAR(255)` | `NULLABLE` | Street address |
| `city` | `VARCHAR(100)` | `NULLABLE` | City / state |
| `postal_code` | `VARCHAR(50)` | `NULLABLE` | Postal / ZIP code |
| `avatar` | `VARCHAR(255)` | `NULLABLE` | Profile picture / Avatar storage path |
| `headline` | `VARCHAR(255)` | `NULLABLE` | Short creator title / headline |
| `bio` | `TEXT` | `NULLABLE` | Detailed user bio |
| `website` | `VARCHAR(255)` | `NULLABLE` | Portfolio or website URL |
| `twitter` | `VARCHAR(255)` | `NULLABLE` | Twitter / X profile handle |
| `github` | `VARCHAR(255)` | `NULLABLE` | GitHub profile URL |
| `primary_ai_models` | `JSON` | `NULLABLE` | Array of primary AI models the creator specializes in (`Midjourney`, `ChatGPT`, `Claude`, etc.) |
| `focus_categories` | `JSON` | `NULLABLE` | Array of prompt categories the creator focuses on |
| `experience_level` | `VARCHAR(100)` | `NULLABLE` | Prompt engineering experience level (`Beginner`, `Intermediate`, `Pro Prompt Engineer`, `AI Agency`) |
| `referral_source` | `VARCHAR(100)` | `NULLABLE` | How the creator discovered the platform (`Google`, `YouTube`, `Facebook`, `Friend`, `Other`) |
| `onboarding_completed_at` | `TIMESTAMP` | `NULLABLE` | Timestamp when the vendor completed `/vendor/onboarding` (`NULL` triggers onboarding redirect) |
| `email_verified_at` | `TIMESTAMP` | `NULLABLE` | Email verification timestamp (auto-stamped on first OTP verification) |
| `password` | `VARCHAR(255)` | `NOT NULL` | Hashed password |
| `role` | `VARCHAR(255)` | `DEFAULT('customer')` | User role (`admin`, `vendor`, `customer`) |
| `is_approved` | `BOOLEAN` | `DEFAULT(TRUE)` | Vendor/User account approval status |
| `is_verified` | `BOOLEAN` | `DEFAULT(FALSE)` | Identity verification flag (grants Verified Seller Badge `✓`) |
| `verification_status` | `VARCHAR(255)` | `DEFAULT('unverified')` | KYC status (`unverified`, `pending`, `verified`, `approved`, `rejected`) |
| `id_document` | `VARCHAR(255)` | `NULLABLE` | Path to uploaded NID / Passport document (front side) |
| `id_document_back` | `VARCHAR(255)` | `NULLABLE` | Path to the reverse side of the NID / Passport |
| `id_document_selfie` | `VARCHAR(255)` | `NULLABLE` | Path to the liveness / selfie verification photo |
| `verification_note` | `TEXT` | `NULLABLE` | Admin verification or rejection note |
| `is_banned` | `BOOLEAN` | `DEFAULT(FALSE)` | Account restriction flag — blocked at login by `AuthController` |
| `ban_reason` | `TEXT` | `NULLABLE` | Reason surfaced to the banned user and stored by the admin Ban action |
| `is_suspended` | `BOOLEAN` | `DEFAULT(FALSE)` | Vendor suspension flag — hides vendor prompts from `Product::scopePublished()` and blocks login |
| `is_payout_frozen` | `BOOLEAN` | `DEFAULT(FALSE)` | Financial freeze flag — blocks vendor withdrawal initiation in `VendorBilling` |
| `custom_commission_rate` | `DECIMAL(5,4)` | `NULLABLE` | Optional per-vendor override for platform commission share |
| `two_factor_secret` | `TEXT` | `NULLABLE` | Encrypted RFC 6238 TOTP shared secret |
| `two_factor_recovery_codes` | `TEXT` | `NULLABLE` | Encrypted JSON list of single-use recovery codes |
| `two_factor_confirmed_at` | `TIMESTAMP` | `NULLABLE` | Timestamp when TOTP was successfully verified and confirmed |
| `email_otp_code` | `VARCHAR(255)` | `NULLABLE` | Bcrypt hashed 6-digit email one-time password |
| `email_otp_expires_at` | `TIMESTAMP` | `NULLABLE` | Expiration timestamp for active email OTP (10-minute window) |
| `preferred_2fa_method` | `VARCHAR(20)` | `DEFAULT('none')` | Preferred second factor method (`none`, `email`, `totp`) |
| `trusted_devices` | `JSON` | `NULLABLE` | Encrypted tokens and user-agent metadata for 30-day recognized devices (`trusted_device_{user_id}` cookie) |
| `remember_token` | `VARCHAR(100)` | `NULLABLE` | Auth session token |
| `last_read_sales_at` | `TIMESTAMP` | `NULLABLE` | Timestamp when vendor last viewed Sales & Earnings |
| `last_read_reviews_at` | `TIMESTAMP` | `NULLABLE` | Timestamp when vendor last viewed Customer Reviews |
| `last_read_followers_at` | `TIMESTAMP` | `NULLABLE` | Timestamp when vendor last viewed Followers |
| `deleted_at` | `TIMESTAMP` | `NULLABLE` | Soft delete timestamp (`SoftDeletes`) |
| `created_at` | `TIMESTAMP` | `NULLABLE` | Record creation timestamp |
| `updated_at` | `TIMESTAMP` | `NULLABLE` | Record update timestamp |

---

### B. `products` Table
Stores prompt items available for purchase or free interactive exploration on the marketplace.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `product_code` | `VARCHAR(50)` | `UNIQUE, INDEXED, NOT NULL` | Unique item identifier (e.g. `PRD-123456`) |
| `title` | `VARCHAR(255)` | `NOT NULL` | Title of the AI prompt |
| `slug` | `VARCHAR(255)` | `UNIQUE, INDEXED, NOT NULL` | URL-friendly SEO slug identifier |
| `description` | `TEXT` | `NOT NULL` | Public product description |
| `price` | `DECIMAL(8,2)` | `NOT NULL` | Item price in USD ($0.00 for Free, or $1.99+ for paid) |
| `compare_price` | `DECIMAL(10,2)` | `NULLABLE` | Optional compare-at (was) price shown alongside `price` |
| `license_type` | `VARCHAR(255)` | `DEFAULT('personal')` | License tier offered (`personal` default) |
| `is_original_confirmed` | `BOOLEAN` | `DEFAULT(FALSE)` | Vendor attestation that the prompt is original work |
| `views_count` | `BIGINT` | `DEFAULT(0)` | Product detail view counter (incremented in `ProductController@show`) |
| `rejection_reason` | `TEXT` | `NULLABLE` | Admin rejection feedback shown to the vendor |
| `last_reviewed_at` | `TIMESTAMP` | `NULLABLE` | When an admin last reviewed this prompt |
| `ai_model` | `VARCHAR(255)` | `NULLABLE` | AI Model (ChatGPT, Midjourney, DALL-E, Gemini, Veo, Claude, Flux, Stable Diffusion, Sora) |
| `category` | `VARCHAR(255)` | `NULLABLE` | Prompt category (Coding, Writing, Photography, Marketing, Roleplay, Art & Design, Video Generation, etc.) |
| `sub_category` | `VARCHAR(255)` | `NULLABLE` | Second-level taxonomy value (filterable via `?sub_category=`) |
| `class_category` | `VARCHAR(255)` | `NULLABLE` | Third-level taxonomy value (filterable via `?class_category=`) |
| `prompt_text` | `TEXT` | `NULLABLE` | AI prompt payload (supports `${variable:default}` and `[Variable]` placeholders for the Interactive Prompt Engine) |
| `prompt_file` | `VARCHAR(255)` | `NULLABLE` | Storage path for attached prompt package file (.zip, .txt, .json, .pdf, .docx) |
| `instructions` | `TEXT` | `NULLABLE` | Usage instructions and parameter guidelines for buyer |
| `cover_image` | `VARCHAR(255)` | `NULLABLE` | Path or remote CDN URL to stored cover image preview (or dark-mode SVG cover placeholder under `prompts/covers/placeholders/`) |
| `gallery_images` | `JSON` | `NULLABLE` | Array-cast list of extra gallery image paths (`Product::$casts`) |
| `preview_video` | `VARCHAR(255)` | `NULLABLE` | Path or remote URL to optional short preview clip (MP4 / WebM) |
| `status` | `VARCHAR(255)` | `DEFAULT('pending')` | Prompt review status (`pending`, `approved`, `rejected`) |
| `user_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE RESTRICT, NULLABLE` | Owner seller/vendor user ID |
| `is_active` | `BOOLEAN` | `DEFAULT(FALSE)` | Marketplace visibility flag (Requires approval) |
| `is_featured` | `BOOLEAN` | `DEFAULT(FALSE)` | Featured prompt badge flag |
| `deleted_at` | `TIMESTAMP` | `NULLABLE` | Soft delete timestamp (`SoftDeletes`) |
| `created_at` | `TIMESTAMP` | `NULLABLE` | Record creation timestamp |
| `updated_at` | `TIMESTAMP` | `NULLABLE` | Record update timestamp |

---

### C. `orders` Table
Stores customer payment transactions, user linkages, and prompt access tokens.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `user_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE SET NULL, NULLABLE` | Registered buyer user ID |
| `product_id` | `BIGINT` | `FOREIGN KEY (products.id) ON DELETE RESTRICT` | Linked product ID |
| `email` | `VARCHAR(255)` | `NOT NULL` | Customer email address |
| `amount` | `DECIMAL(8,2)` | `NOT NULL` | Amount paid for order (after any coupon discount) |
| `commission_rate` | `DECIMAL(5,4)` | `DEFAULT(0.80)` | Vendor commission snapshot (`config('marketplace.vendor_commission')`) |
| `vendor_earning` | `DECIMAL(10,2)` | `DEFAULT(0)` | Vendor's net cut snapshot for this order |
| `platform_fee` | `DECIMAL(10,2)` | `DEFAULT(0)` | Platform's share snapshot for this order |
| `coupon_code` | `VARCHAR(255)` | `NULLABLE` | Discount coupon code applied at checkout |
| `discount_amount` | `DECIMAL(10,2)` | `DEFAULT(0)` | Coupon discount subtracted from the gross amount |
| `stripe_session_id` | `VARCHAR(255)` | `UNIQUE, NOT NULL` | Stripe Checkout Session ID — free ($0.00) claims store the sentinel `free_<16 random chars>` because the column is NOT NULL |
| `status` | `ENUM` | `['pending', 'paid', 'failed', 'refunded', 'partially_refunded', 'disputed'], DEFAULT('pending')` | Order lifecycle status (refund/dispute states managed via admin `OrderResource`) |
| `access_token` | `VARCHAR(255)` | `UNIQUE, NOT NULL` | Secure token for prompt reveal URL |
| `created_at` | `TIMESTAMP` | `NULLABLE` | Record creation timestamp |
| `updated_at` | `TIMESTAMP` | `NULLABLE` | Record update timestamp |

---

### D. `follows` Table
Tracks user community follows on seller profiles.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `user_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE CASCADE` | The follower user ID |
| `vendor_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE CASCADE` | The followed vendor user ID |
| `created_at` | `TIMESTAMP` | `NULLABLE` | Record creation timestamp |
| `updated_at` | `TIMESTAMP` | `NULLABLE` | Record update timestamp |

*Unique Index*: `UNIQUE(['user_id', 'vendor_id'])`

---

### E. `favorites` Table
Stores user wishlist items with instant toggle states.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `user_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE CASCADE` | User saving favorite |
| `product_id` | `BIGINT` | `FOREIGN KEY (products.id) ON DELETE CASCADE` | Favorited product ID |
| `created_at` | `TIMESTAMP` | `NULLABLE` | Record creation timestamp |
| `updated_at` | `TIMESTAMP` | `NULLABLE` | Record update timestamp |

*Unique Index*: `UNIQUE(['user_id', 'product_id'])`

---

### F. `reviews` Table
Stores 1-5 star ratings and reviews for products and sellers.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `user_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE CASCADE` | Reviewer user ID |
| `product_id` | `BIGINT` | `FOREIGN KEY (products.id) ON DELETE CASCADE, NULLABLE` | Reviewed product ID |
| `vendor_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE CASCADE, NULLABLE` | Reviewed vendor user ID |
| `rating` | `TINYINT UNSIGNED` | `NOT NULL` | Star rating between 1 and 5 |
| `comment` | `TEXT` | `NULLABLE` | Review feedback comment |
| `vendor_reply` | `TEXT` | `NULLABLE` | Public vendor response to the review (Etsy-style) |
| `replied_at` | `TIMESTAMP` | `NULLABLE` | When the vendor posted the reply |
| `status` | `VARCHAR(255)` | `DEFAULT('approved')` | Review status (`approved`, `pending`, `rejected`) |
| `deleted_at` | `TIMESTAMP` | `NULLABLE` | Soft delete timestamp (`SoftDeletes`) |
| `created_at` | `TIMESTAMP` | `NULLABLE` | Record creation timestamp |
| `updated_at` | `TIMESTAMP` | `NULLABLE` | Record update timestamp |

---

### G. `tickets` & `ticket_messages` Tables
Stores seller support tickets and back-and-forth conversational response threads.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `ticket_id` | `VARCHAR(50)` | `UNIQUE, INDEXED, NOT NULL` | Formatted identifier (e.g. `TCK-849201`) |
| `user_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE CASCADE` | Ticket creator vendor user ID |
| `subject` | `VARCHAR(255)` | `NOT NULL` | Support inquiry subject |
| `category` | `VARCHAR(255)` | `NOT NULL` | Category (Payouts, Prompt Approval, KYC, General) |
| `priority` | `ENUM` | `['low', 'medium', 'high', 'urgent']` | Ticket urgency level |
| `status` | `ENUM` | `['open', 'answered', 'closed']` | Current lifecycle state |
| `created_at` | `TIMESTAMP` | `NULLABLE` | Record creation timestamp |
| `updated_at` | `TIMESTAMP` | `NULLABLE` | Record update timestamp |

---

### H. `vendor_settings`, `vendor_payouts` & `payout_methods` Tables
Stores vendor personal address/KYC data, creator onboarding survey responses, withdrawal payout methods, and transaction requests.

| Table | Key Columns | Purpose |
| :--- | :--- | :--- |
| `vendor_settings` | `user_id`, `store_name`, `phone`, `country`, `city`, `address`, `zip_code`, `postal_code`, `primary_ai_models` (JSON), `focus_categories` (JSON), `experience_level`, `referral_source`, `onboarding_completed_at`, `store_banner`, `announcement`, `vacation_mode`, `refund_policy`, `license_policy`, `nid_passport_number`, `date_of_birth`, `payout_method`, `payout_details` | Vendor profile configuration, creator onboarding survey, storefront customization & payout credentials payload |
| `vendor_payouts` | `id`, `reference_id` (`WDR-XXXXXX` unique), `user_id`, `payout_method_id` (nullable FK to `payout_methods`), `amount` (`DECIMAL(10,2)`), `payout_method`, `payout_details` (immutable JSON snapshot at request time), `status` (`pending`, `processing`, `completed`, `rejected`), `vendor_note`, `rejection_reason`, `admin_notes`, `admin_note`, `reference_no`, `processed_at` | End-to-End withdrawal request system (`MARKETPLACE_MIN_WITHDRAWAL`, default $20) and payout ledger |
| `payout_methods` | `user_id`, `type`, `label`, `identifier`, `details` (encrypted JSON), `is_default`, `is_verified`, `deleted_at` | Saved Bank, Card, PayPal, and Crypto payout destinations |

---

### I. `coupons` Table
Vendor-issued discount coupons consumed at checkout. Managed through the vendor `CouponResource` (`/vendor/coupons`) and validated by `ProductController@checkout` (code must belong to the product's creator).

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `user_id` | `BIGINT` | `FOREIGN KEY (users.id) ON DELETE CASCADE` | Owning vendor |
| `code` | `VARCHAR(255)` | `UNIQUE, NOT NULL` | Uppercase coupon code (auto-generated if empty) |
| `type` | `ENUM` | `['percent', 'fixed'], DEFAULT('percent')` | Discount calculation type |
| `value` | `DECIMAL(10,2)` | `NOT NULL` | Discount value (percent or fixed USD) |
| `min_order_amount` | `DECIMAL(10,2)` | `DEFAULT(0)` | Minimum order amount required to redeem |
| `usage_limit` | `INT UNSIGNED` | `NULLABLE` | Maximum total redemptions (`NULL` = unlimited) |
| `used_count` | `INT UNSIGNED` | `DEFAULT(0)` | Redemptions so far (incremented on paid orders) |
| `expires_at` | `TIMESTAMP` | `NULLABLE` | Expiry datetime (`NULL` = never expires) |
| `is_active` | `BOOLEAN` | `DEFAULT(TRUE)` | Enable/disable toggle |
| `deleted_at` | `TIMESTAMP` | `NULLABLE` | Soft delete timestamp (`SoftDeletes`) |
| `created_at` / `updated_at` | `TIMESTAMP` | `NULLABLE` | Record timestamps |

*Index*: `INDEX(['user_id', 'is_active'])` — see migration `2026_09_28_000001_vendor_panel_international_hardening`.

---

### J. `categories` Table
Self-referencing taxonomy powering the nested marketplace filters, the seller storefront filters, inline category creation inside product forms, and automatic category mapping in `ImportPromptsChatCommand`.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `parent_id` | `BIGINT` | `NULLABLE, INDEXED` | Parent category (self-reference) for nested levels |
| `type` | `VARCHAR(255)` | `NULLABLE` | Category level selected in the admin form (`Category Level`) |
| `name` | `VARCHAR(255)` | `NOT NULL` | Display name |
| `slug` | `VARCHAR(255)` | `UNIQUE, INDEXED` | URL-friendly identifier (auto-generated from `name`) |
| `icon` | `VARCHAR(255)` | `NULLABLE` | Heroicon name used in navigation / filter pills |
| `description` | `TEXT` | `NULLABLE` | Optional description |
| `is_active` | `BOOLEAN` | `DEFAULT(TRUE)` | Visibility toggle |
| `sort_order` | `INTEGER` | `DEFAULT(0)` | Manual ordering |
| `deleted_at` | `TIMESTAMP` | `NULLABLE` | Soft delete timestamp (`SoftDeletes`) |
| `created_at` / `updated_at` | `TIMESTAMP` | `NULLABLE` | Record timestamps |

Managed **only in the admin panel** through `App\Filament\Resources\CategoryResource` (`heroicon-o-tag`, "Marketplace" group). Vendors create categories inline from the prompt upload form (`Category::firstOrCreate`), and `php artisan prompts:import-community` automatically maps/creates main categories (`Coding`, `Writing`, `Photography`, `Marketing`, `Roleplay`, `Video Generation`, etc.).

---

### K. `site_settings` Table
Key/value store for admin-editable global content.

| Column | Type | Attributes | Description |
| :--- | :--- | :--- | :--- |
| `id` | `BIGINT` | `PRIMARY KEY, AUTO_INCREMENT` | Unique identifier |
| `key` | `VARCHAR(255)` | `UNIQUE, NOT NULL` | `telegram_link`, `discord_link`, `community_title`, `community_description` |
| `value` | `TEXT` | `NULLABLE` | Setting value |
| `created_at` / `updated_at` | `TIMESTAMP` | `NULLABLE` | Record timestamps |

Accessed via `SiteSetting::get($key, $default)` / `SiteSetting::set($key, $value)` (`app/Models/SiteSetting.php`) and edited on the **Community & Social Links** page (`ManageSiteSettings`, `/admin/site-settings`).

---

### L. Security, Audit, RBAC & Analytics Tables (Phases 35–41)
- **`roles`, `permissions`, `permission_role`, `role_user`**: Core Laravel + Filament RBAC tables (`owner`, `admin`, `finance`, `moderator`, `support`, `analyst`) evaluated via `User::hasPermission()`.
- **`audit_logs`**: Append-only compliance audit trail (`actor_id`, `actor_name`, `actor_role`, `event`, `auditable_type`, `auditable_id`, `auditable_label`, `old_values`, `new_values`, `changed_keys`, `ip_address`, `user_agent`, `panel`, `is_sensitive`).
- **`webhook_events`**: Idempotent Stripe webhook ledger (`stripe_event_id` unique, `type`, `payload`, `status`, `processed_at`).
- **`product_view_logs`**: 24-hour deduplicated product view analytics (`product_id`, `user_id`, `ip_hash`, `referrer`) powering `AnalyticsDashboard` (`/admin/analytics`).
- **`exports`**: Filament queued export metadata (`file_disk`, `file_name`, `exporter`, `processed_rows`, `total_rows`, `successful_rows`, `user_id`).
- **Framework & Infrastructure Tables**: `migrations`, `cache`, `cache_locks`, `jobs`, `job_batches`, `failed_jobs`, `sessions` (`SESSION_DRIVER=database`), `password_reset_tokens`, and `notifications` (Filament database notifications, 30s polling).

### M. Order Reference Format
Filament tables display a human-friendly reference derived from the primary key: `#ORD-` + zero-padded id (5 digits) — see `App\Filament\Vendor\Resources\VendorSalesResource`.
