# Vexlora Complete eCommerce Suite

Milestone 39 extends the 28-screen commerce suite from image-led product management into a connected order, customer and growth workflow while remaining frontend-only and buyer-replaceable.

## Product workflow

- **Product List** — image-led shared DataTable with thumbnail, brand, SKU, category, compare-at price, inventory, variants and review context.
- **Create / Edit Product** — React Hook Form + Zod architecture with local media gallery, primary image, pricing, stock, reusable product attributes/options, variant preview, organization, SEO and shipping metadata.
- **Product Details** — gallery, variants, inventory, recent orders, review health, marketing eligibility and product activity.
- **Variants / Categories / Tags / Reviews** — dedicated product-management interfaces rather than generic resource queues.
- **Product Attributes** — reusable attribute definitions with slug, display type, sort order, variant/filter/search/required/visible behavior and value management for Color, Size, Material or buyer-defined fields.
- **Product attribute assignment** — Product Create/Edit selects attributes and values from the same library and previews generated variant combinations before per-SKU price/stock management.
- Brands and Collections remain typed domain resource configurations.

## Attribute / option workflow

The frontend sample models the attribute lifecycle as a reusable catalog contract:

1. Create an attribute definition such as **Color** or **Size**.
2. Add reusable values such as **White / Graphite / Blue** or **S / M / L / XL**.
3. Mark whether the attribute drives variants, storefront filters, search, required selection or general specification display.
4. In Product Create/Edit, attach the reusable attribute to the product and select only the values that product offers.
5. Variant-driving selections generate a combination preview; SKU, price and stock remain variant-level commercial fields.

Sample attribute definitions and product selections persist in browser-local storage. Buyers can replace this adapter with their REST/GraphQL/custom backend without changing the page composition.

## Product media

Preview assets are stored locally in `public/images/products/` so the sample is not dependent on remote image hosts. Buyers can replace these files or map the mock fields to their own CDN/storage response without changing component architecture.

See `docs/ASSET_CREDITS.md` for preview-asset sources.

## Order workflow

Order List now keeps business context visible before a buyer opens the record:

- purchased-product thumbnail and primary product name;
- customer identity and email;
- payment and fulfillment status;
- shipping method and destination;
- low/medium/high operational risk;
- expandable Customer 360 link;
- a dedicated **Needs attention** queue for payment/refund/risk exceptions.

Order Details uses image-led line items with coherent quantity/subtotal/total math, shared customer lifetime value, shipping context and a direct link to CRM Customer 360. Order Tracking, Returns, Refunds and Cancelled Orders retain specialized workflow surfaces.

## Inventory relationship

- Stock Overview is product-led: image, SKU, variants, location, available, committed and inbound quantities appear in the same row.
- Product Details links directly to stock.
- Stock rows link back to product edit/details workflows.
- Warehouses, Transfers, Low Stock, Adjustments and Suppliers keep the same physical-product vocabulary.

## Marketing relationship

**Commerce Campaigns** is now a dedicated growth workspace instead of a generic operational queue:

- product image and merchandised product identity;
- channel, audience and campaign owner;
- spend, attributed revenue, conversions and ROAS;
- conversion-funnel health;
- Marketing Analytics link;
- AI Marketing Copilot optimization entry point;
- merchandising recommendation grounded in catalog and stock context.

Coupons, Discounts, Promotions and Gift Cards remain typed operational workspaces and share the same catalog vocabulary.


## Multi-vendor marketplace workflow

The optional Marketplace module is now a complete nine-workspace seller-operations suite:

- **Overview** — marketplace sales, platform commission, pending commission, vendor earnings, waiting applications, product moderation, open orders, disputes and recent marketplace activity.
- **Vendors** — seller access, verification, performance, catalog ownership, commission rate and activation/suspension controls.
- **Applications** — identity/business review, uploaded-document readiness, payout readiness and approve/request-info/reject actions.
- **Product Approvals** — vendor catalog moderation with product media, readiness, policy/compliance context and publish/change/block actions.
- **Vendor Orders** — marketplace order ledger with seller ownership, customer, sale, commission, vendor net and fulfillment context.
- **Commissions** — order-level commission lineage, seller earnings and commission-policy visibility.
- **Payouts** — seller payout readiness, schedule/hold/paid states and explicit Payment Core handoff.
- **Settings** — marketplace enablement, moderation, seller permissions, commission, payout and dispute policy defaults.
- **Disputes** — vendor/order/commission dispute ownership, priority, investigation and resolution state.

The sample uses a shared browser-local marketplace store so actions on one workspace update overview counts and recent activity across routes. It remains frontend-only: production identity/KYC, secret storage, split payments, payout execution, tax/legal compliance and durable audit storage belong to buyer-owned backend/provider integrations.


## Online Store Studio

The eCommerce suite now includes a seven-workspace **Online Store** area above Reports: Overview, Menus & Navigation, Pages, Blog, Testimonials, Contact us and Popups.

- The Menu Builder consumes live Pages, Products, Blog Posts, Categories and Brands plus custom links/image blocks.
- Product categories and brands created through catalog quick actions flow into the Menu Builder source library.
- Menus support Header, Vertical, Footer and Mobile location hooks, three-level nesting, drag/drop ordering, keyboard-friendly move/indent controls, 2–6 column mega menus and an admin-side responsive preview.
- Pages use structured Hero/Rich text/Feature grid/CTA/Image/FAQ blocks with SEO, visibility and publication controls.
- Blog, Testimonials, Contact and Popups share the same buyer-replaceable browser-safe sample state layer.
- No storefront frontend, CMS backend, database or provider secrets are bundled; buyers map the data contracts into their own Next.js/storefront architecture.

See `docs/ONLINE_STORE_2026.md` for the full integration and customization contract.

## Architecture rules

- Frontend admin template only: no payment processor, database, inventory service, shipping API or campaign backend is bundled.
- Product and order core screens reuse the typed data layer, DataTable system and form system.
- Tailwind utilities and shared semantic tokens remain the styling source of truth; no copied custom CSS was introduced.
- Buyers can replace mock repositories with REST, GraphQL or their own generated backend APIs.

## Key files

```text
src/features/ecommerce/
├── components/
│   ├── catalog-management-pages.tsx
│   ├── commerce-campaigns-page.tsx
│   ├── ecommerce-resource-page.tsx
│   ├── order-columns.tsx
│   ├── order-data-table.tsx
│   ├── order-details-page.tsx
│   ├── product-attribute-manager.tsx
│   ├── product-attribute-configurator.tsx
│   ├── product-details-page.tsx
│   ├── product-editor.tsx
│   └── stock-overview-page.tsx
├── data/
│   ├── catalog-attribute-store.ts
│   ├── commerce-campaigns.mock.ts
│   ├── ecommerce-config.ts
│   └── ecommerce-pages/
└── schemas/product-editor-schema.ts
```

## Validation

Run `npm run check:ecommerce` and `npm run check`. When dependencies are installed, also run `npm run typecheck`, `npm run lint` and `npm run build`.

## Commerce AI Command Center

`/ecommerce/ai-commerce` is the cross-module AI orchestration layer for the commerce suite, not a duplicate product-writing tool.

- **Commerce Copilot** — asks cross-module questions across product, order, inventory, returns, campaigns and marketplace context.
- **Opportunity & Risk Radar** — ranks profitable growth opportunities, stockout exposure, return anomalies and other material commerce signals.
- **AI Action Center** — keeps proposed actions human-approved before handoff to Promotions, Inventory, SEO, CRM or other operational workspaces.
- **Commerce Automations** — browser-local sample controls for recurring stock, SEO, margin, cart-recovery and marketplace-quality monitoring.
- **Cross-module execution map** — routes work to Product Studio, Image Studio, SEO Copilot, Inventory Copilot, Pricing & Promotions, Marketing Copilot, CRM Copilot and Marketplace operations instead of rebuilding those tools inside one page.
- **AI Business Impact + Activity** — shows reviewed AI influence, prevented stockouts, saved time, approval quality and an audit-friendly recent activity trail.

The sample persists automation toggles and approved-draft states in browser-local storage. Production model calls, secrets, external messages and business writes remain buyer-owned backend responsibilities.