vmall/openspec/specs/frontend-mall/spec.md

frontend-mall Specification

Purpose

TBD - created by archiving change frontend-apps. Update Purpose after archive.

Requirements

Requirement: Localized storefront

The mall SHALL render every UI string and all catalog/store/marketing mock content in en or zh from one switcher, defaulting to en. Switching locale SHALL update the desktop shell and current page without a full reload.

Scenario: switch to Chinese

• WHEN a shopper switches locale to zh
• THEN navigation, buttons, product/store names and mock marketing content render in Chinese without reload errors

Requirement: Multi-currency display

The mall SHALL offer a currency switcher sourced from the selected API adapter and SHALL convert product, cart and order prices through integer minor units and each currency's exponent. Mock mode SHALL use deterministic fixed conversion rates; live mode SHALL use the API.

Scenario: switch currency

• WHEN a shopper switches from USD to JPY on a product priced $10.00
• THEN the displayed price reflects the selected adapter's conversion rate with JPY exponent 0 and no floating-point money arithmetic

Requirement: Shopping flow

A shopper SHALL be able to browse, view detail, add to cart, checkout with a shipping address, pay (mock), track orders/shipments, confirm delivery, and request an invoice through the selected API adapter. The MVP SHALL default to the fixed-data mock adapter and SHALL not require the live API.

Scenario: end-to-end purchase

• WHEN a shopper completes checkout on a non-empty mock cart
• THEN the resulting order appears in the buyer center and the cart is empty

Requirement: B2B2C mall-style PC storefront shell

The mall SHALL render a buyer-facing desktop shell modeled on a classic B2B2C PC mall: a 30px utility bar, logo/search/cart header, dark primary navigation with a hover category mega-menu, a 1200px content grid, and a value-proposition footer. The header SHALL remain fully visible while scrolling; no part of the shell SHALL auto-hide based on scroll position. The category mega-menu SHALL appear as a hover dropdown under the navigation "All Categories" entry on every page except the home page, where it is instead pinned in the hero row. The visual language SHALL use #ca151e for brand/price/active states, #f5f5f5 section backgrounds, gray hairline borders, compact controls, and product-card hover lift/shadow. The implementation SHALL use Nuxt-native semantic components and SHALL NOT depend on Element Plus.

Scenario: shopper opens any mall page

• WHEN a shopper navigates to a buyer-facing route
• THEN the shared desktop shell wraps the route content and its nav/search/cart controls are usable

Scenario: header persists while scrolling

• WHEN a shopper scrolls any mall page
• THEN the logo/search/cart header bar remains visible and is never collapsed or hidden by scroll position

Scenario: hover categories on a non-home page

• WHEN a shopper hovers "All Categories" in the navigation on a page other than /
• THEN the category mega-menu dropdown appears below the navigation and hides again on mouse leave

Requirement: Mock API adapter

The mall SHALL default to a fixed-data mock adapter that implements the existing @vmall/shared API client surface. The adapter SHALL support auth, catalog, currency conversion, cart mutation, checkout, order/payment/shipment state, and invoices without a backend. A runtime configuration switch SHALL select the live API client later without changing page call sites.

Scenario: mall runs without backend

• WHEN the mall starts with mock mode enabled and the API service is unavailable
• THEN browsing, cart, checkout, payment, orders and invoice pages return deterministic mock data and remain functional

Requirement: Mock PC home page

The mall home page SHALL render a hero row composed of a pinned 240px category sidebar on the left and a hero carousel filling the remainder of the 1200px grid, both 450px tall and occupying layout space (not overlaid). The sidebar SHALL list all top-level categories with up to three child links each; hovering a top-level category SHALL expand the mega-menu panel to the right over the carousel. Banner images SHALL render at fixed 450px height, center-cropped horizontally to the narrower carousel width. Below the hero, the page SHALL render a six-item quick-link strip with promotion tiles and bilingual product floors with a left advert and product-card grid.

Scenario: shopper lands on home

• WHEN / loads in mock mode
• THEN the category sidebar is visible to the left of the carousel without any hover or click, the carousel renders center-cropped banners at 450px height, and the quick links, promotions and every non-empty product floor render fixed mock content

Scenario: sidebar stays while scrolling

• WHEN a shopper scrolls the home page beyond 200px
• THEN the category sidebar remains rendered in the hero row and does not auto-hide

Scenario: expand a category

• WHEN a shopper hovers a top-level category in the pinned sidebar
• THEN the mega-menu panel expands to the right, overlaying the carousel with that category's child and grandchild links

Requirement: Product discovery pages

The mall SHALL provide /search with breadcrumb, category, brand and sort controls, a five-column desktop product grid, pagination and an empty state. It SHALL provide /goods/[id] with image gallery/zoom, bilingual name/subtitle, integer-minor-unit prices, attribute and SKU selection, stock-aware quantity, coupons/activity summary, store card, sales rail, and detail/comments/after-sale tabs.

Scenario: filter and inspect a product

• WHEN a shopper filters the search page and opens a product
• THEN matching mock cards are shown and selecting an in-stock SKU updates the displayed price, stock and cart target

Requirement: Mock transaction flow

The mall SHALL provide a store-grouped cart, address-selecting checkout preview, mock payment selection and payment-success result. Cart quantity/removal, selection totals, checkout and mock payment SHALL update the in-memory mock state for the current browser session.

Scenario: complete mock purchase

• WHEN a shopper adds an in-stock SKU, checks out with a mock address and confirms a mock payment
• THEN the cart is cleared, the success page is shown and the new order appears in the user order list

Requirement: Auth and buyer center

The mall SHALL provide B2B2C mall-style login, register and forgot-password panels backed by deterministic mock auth. /user SHALL render a two-column buyer center with dashboard, order list/detail, addresses, favorites, coupons and invoices.

Scenario: sign in and inspect buyer data

• WHEN a shopper submits the mock login form and opens /user
• THEN the buyer-center shell and fixed account/order/address/favorite/coupon/invoice data render without backend access

Requirement: Store and marketing pages

The mall SHALL provide a store directory, store home, timed seckill page, collective-buy list and points-mall home using fixed bilingual mock content. Marketing pages MAY be display-only except navigation to product detail.

Scenario: navigate storefront discovery channels

• WHEN a shopper opens stores, seckill, collective or integral routes
• THEN each page renders the appropriate B2B2C mall-style banner/filter/session/card layout and product links resolve to mock product details