vmall/openspec/specs/frontend-shop-admin/spec.md

frontend-shop-admin Specification

Purpose

The merchant console for managing a shop's products and fulfilling its orders.

Requirements

Requirement: Merchant product management

Shop users SHALL manage only their own shop's products: create/edit bilingual content, manage SKUs, publish/unpublish with immediate effect on the storefront.

Scenario: publish visible in mall

• WHEN a merchant publishes a product in shop-admin
• THEN it appears in the mall product list for the matching locale

Requirement: Merchant fulfillment

Shop users SHALL see incoming orders, create shipments, mark them shipped, and issue requested invoices.

Scenario: ship an order

• WHEN a merchant creates a shipment for a paid order and marks it shipped
• THEN the shopper sees the shipment with tracking info

Requirement: Merchant coupon management

Shop users SHALL manage only their shop's coupon templates from shop-admin, including localized title, amount and threshold in minor units, currency, claim stock, active window, and enabled state. Shop-admin SHALL expose a coupons navigation entry beside existing shop operations.

Scenario: create an active template

• WHEN a shop owner creates a valid coupon template
• THEN the template is available for eligible customers to claim during its active window

Scenario: coupons appear in shop navigation

• WHEN an authenticated shop user opens shop-admin
• THEN a coupons management entry is reachable without leaving the shop-scoped console

Requirement: Merchant flash-sale management

Shop users SHALL manage only their flash-sale sessions and items in shop-admin, choosing their own SKU, active window, minor-unit sale price, reserved stock, and per-customer limit. Shop-admin SHALL expose a flash-sale navigation entry beside existing shop operations.

Scenario: configure item

• WHEN a merchant creates an active valid flash-sale item for its SKU
• THEN it appears to customers through active flash-sale discovery

Scenario: flash sales appear in shop navigation

• WHEN an authenticated shop user opens shop-admin
• THEN a flash-sale management entry is reachable without leaving the shop-scoped console

Requirement: Merchant group-buying management

Shop users SHALL manage only their shop's group-buying activities in shop-admin, configuring an owned SKU, localized display content, minor-unit group price, required paid-member count, active window, and group lifetime. Shop-admin SHALL expose a group-buying navigation entry beside existing shop operations.

Scenario: publish activity

• WHEN a merchant publishes a valid group-buying activity
• THEN shoppers can discover it during its active window

Scenario: group buying appears in shop navigation

• WHEN an authenticated shop user opens shop-admin
• THEN a group-buying management entry is reachable without leaving the shop-scoped console

Requirement: Shared design system in the merchant console

The shop-admin console SHALL use @vmall/ui primitives and @vmall/shared theme tokens for chrome (buttons, fields, cards, tables, page headers, nav). It MUST NOT depend on Element Plus or the removed ui.css stylesheet.

Scenario: console chrome from the kit

• WHEN an authenticated shop user opens shop-admin
• THEN primary actions and page chrome render through the shared kit with the current accent preset

Requirement: Accent preset switcher

Shop-admin SHALL expose the shared accent preset control (red, blue, teal, violet) in the authenticated shell header.

Scenario: switcher visible

• WHEN an authenticated shop user opens shop-admin
• THEN they can select an accent preset without leaving the current page

Requirement: Merchant shop profile editing

Shop users SHALL edit their own shop's profile from a shop-admin page reachable from the shop-scoped navigation, through the shared API adapter's shop-scoped profile update. The form SHALL prefill from the shop's current profile and cover the merchant-writable fields only: logo and banner URLs, company, region, and { en, zh } bilingual address, notice and after-sale copy. Bilingual fields SHALL be validated with non-empty en and zh text before any request is sent, every write SHALL target the caller's own shop, and profile scores SHALL NOT be editable — they remain platform-set and saving never changes them. Saves SHALL give clear success feedback; a refused save SHALL keep the form values and show a visible failure message.

Scenario: merchant updates their own profile

• WHEN a shop owner edits their notice, saves, and the mall store page reloads
• THEN only that shop shows the new notice and no other shop's profile changes

Scenario: incomplete bilingual text is blocked before submit

• WHEN a shop owner leaves the zh after-sale text empty and saves
• THEN the field shows an inline error and no update request is sent

Scenario: scores are not editable

• WHEN the profile page loads and is saved
• THEN no score fields are offered and the platform-set scores remain unchanged

Scenario: refused save keeps the form

• WHEN the API refuses an update
• THEN the page keeps the entered values and shows a failure message

Requirement: Shop-scoped aftersale workspace

Shop-admin SHALL provide an aftersale list and detail workspace filtered to the authenticated shop's own_shop resources. Authorized shop users SHALL inspect order-item evidence and messages, approve or reject pending applications, and confirm returned goods with the guarded refund action. The UI SHALL show status transitions, remaining amount, ledger-backed refund result, and stale-action errors through the shared API contract.

Scenario: merchant approves a request

• WHEN a shop user opens a pending application for an item belonging to their shop and approves it
• THEN the status advances according to the selected aftersale type and the customer can see the persisted result

Scenario: merchant confirms return and refunds

• WHEN a shop user confirms receipt of a buyer-shipped return
• THEN the service records merchant confirmation, credits the customer's account once, and displays the refunded status and order total

Scenario: shop scope is enforced

• WHEN a shop user requests or mutates an aftersale for another shop
• THEN the API denies the operation and the workspace exposes no cross-shop data

Scenario: merchant messages buyer

• WHEN an authorized shop user appends a localized message
• THEN the message appears in the same chronological aftersale thread visible to the buyer