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

# frontend-mall Specification

## Purpose
The buyer-facing storefront: shell, home page, discovery, shopping and transaction flows, and the buyer center.

## 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, track orders/shipments, confirm delivery, and request an invoice against the live API. Cart, order, shipment and invoice state SHALL be the backend's rather than the browser's, and the fixed-data adapter SHALL remain available as a configured fallback rather than the default. Adding to the cart SHALL require an authenticated shopper: an anonymous add SHALL send the shopper to sign in and return them to where they left off.

#### Scenario: end-to-end purchase
- **WHEN** a shopper completes checkout on a non-empty cart
- **THEN** the resulting order appears in the buyer center and the cart is empty

#### Scenario: anonymous add prompts sign-in
- **WHEN** a signed-out shopper adds an in-stock SKU from a product page
- **THEN** they are sent to sign in and, once signed in, returned to that product page

### 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 select its API adapter per domain, so one domain can be served by the live backend while the others stay on fixed data. The mall SHALL still ship a fixed-data adapter implementing the whole `@vmall/shared` API client surface, and the live/fixed choice SHALL be configurable per domain without changing page call sites. The fixed-data adapter SHALL remain able to serve every domain when the live backend is unavailable.

#### Scenario: mall runs without backend
- **WHEN** the mall starts with the API service unavailable and every domain configured to fixed data
- **THEN** browsing, cart, checkout, payment, orders and invoice pages return deterministic fixed data and remain functional

#### Scenario: domains migrate independently
- **WHEN** the live backend serves the catalog and currency domains while auth, cart, orders, shipments and invoices remain on fixed data
- **THEN** browsing and prices come from the backend while those other flows keep working against fixed data

### 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 the catalog's 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, where each floor's products come from the catalog API and the banners, promotions, quick links and floor advert art come from the content API.

#### Scenario: shopper lands on home
- **WHEN** `/` loads
- **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, with floor products from the catalog API and the marketing content from the content API

#### 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 from the catalog API

#### Scenario: home renders with no content published
- **WHEN** the content API returns empty lists
- **THEN** the page still renders its category sidebar and product floors instead of failing

### 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, listing products from the catalog API filtered by the selected category's subtree and brand. The sort control SHALL offer newest-first, price and sales. It SHALL provide `/goods/[id]` rendering product and SKU data from the catalog API with image gallery/zoom, bilingual name/subtitle, integer-minor-unit prices, attribute and SKU selection, stock-aware quantity, store card, and detail/after-sale tabs. Product cards and the product detail page SHALL show the product's real sold count, and the mall SHALL NOT present reviews, ratings or reviewer comments while no reviews capability exists.

#### Scenario: filter and inspect a product
- **WHEN** a shopper filters the search page by a parent category and a brand, then opens a product
- **THEN** products from that category's subtree matching the brand are listed, and selecting an in-stock SKU updates the displayed price, stock and cart target from the catalog API

#### Scenario: sort by sales
- **WHEN** a shopper sorts the search results by sales
- **THEN** the order follows the products' reported sold counts

#### Scenario: no invented reviews
- **WHEN** a shopper opens a product
- **THEN** the page shows the shop's own after-sale copy and no rating, review count or reviewer comment

### Requirement: Mock transaction flow
The mall SHALL provide a store-grouped cart, address-selecting checkout preview, payment selection and payment-success result, all reading and writing the live cart and order APIs. Quantity changes, removals, selection totals, checkout and payment SHALL be persisted by the backend for the signed-in shopper, so they survive a page reload.

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

#### Scenario: cart survives a reload
- **WHEN** a signed-in shopper adds an item and then reloads the page
- **THEN** the cart still holds that item, priced and stocked from the catalog

### Requirement: Auth and buyer center
The mall SHALL provide B2B2C mall-style login, register and forgot-password panels backed by the live auth API, so credentials, roles and tokens belong to the real user rather than a fixed demo account. Registration SHALL require a password of at least 8 characters, matching the API's rule, and the register panel SHALL NOT ask for a verification code because no endpoint issues one. Failures SHALL be reported distinctly: invalid credentials on sign-in, and an already-registered email on registration. A token restored from storage SHALL be validated against the auth API on load, and a rejected token SHALL clear the session and return the shopper to sign-in. `/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 signs in with valid credentials and opens `/user`
- **THEN** the session carries the authenticated user, and the buyer-center shell and its fixed account/order/address/favorite/coupon/invoice data render

#### Scenario: wrong password rejected
- **WHEN** a shopper submits a password that does not match the account
- **THEN** sign-in fails with an invalid-credentials message and no session is established

#### Scenario: short password refused before the API call
- **WHEN** a shopper submits a registration password shorter than 8 characters
- **THEN** the panel asks for at least 8 characters without calling the API

#### Scenario: duplicate email reported
- **WHEN** a shopper registers an email that already has an account
- **THEN** the panel reports that the email is already registered rather than a generic failure

#### Scenario: rejected token clears the session
- **WHEN** a token restored from storage is rejected by the auth API
- **THEN** the stored session is cleared and the shopper is returned to sign-in

### Requirement: Store and marketing pages
The mall SHALL provide a store directory and store home reading live shops from the shop API, with each store's products coming from the catalog API, and SHALL keep the timed seckill page, collective-buy list and points-mall home on fixed bilingual content for now. The cart, payment and order surfaces SHALL show each order's shop by name from the shop API rather than a generic label. 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, the store directory and store home list real shops, and product links resolve to product detail

#### Scenario: order surfaces name the shop
- **WHEN** a shopper views a cart line, a payment group or an order card
- **THEN** the shop is shown by its name, not a placeholder

#### Scenario: a shop without a profile still renders
- **WHEN** a shop has no profile row
- **THEN** the directory and store home render it without inventing logo, scores or copy