134 lines
8.8 KiB
Markdown
134 lines
8.8 KiB
Markdown
# 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
|
|
|
|
### Requirement: Merchant freight template management
|
|
Shop-admin SHALL provide a freight template management page for the signed-in shop user's own shop only, listing the shop's templates with their default flag, always-free toggle, pricing method, minor-unit fees, integer unit sizes, free-shipping threshold, and region rules. Create, edit, default-toggle, region-rule editing, and delete SHALL go through the shared `@vmall/shared` contract, and making a template default SHALL reflect the server's single-default outcome. The page SHALL use `@vmall/ui` primitives and shared tokens.
|
|
|
|
#### Scenario: manage a template and its region rules
|
|
- **WHEN** a shop user creates a by-piece template, adds a region rule with higher fees, and saves
|
|
- **THEN** reloading the page shows the template and rule from the backend
|
|
|
|
#### Scenario: default template toggle
|
|
- **WHEN** a shop user marks a second template as default
|
|
- **THEN** the page shows exactly that template as default after the server confirms
|
|
|
|
### Requirement: Merchant shipping company selection
|
|
When a shop user ships an order from the fulfillment view, shop-admin SHALL offer the shipping companies from the shared dictionary and require a selection before marking the order shipped. The chosen company SHALL reach the backend through the shared contract and appear on the order after shipping.
|
|
|
|
#### Scenario: ship with a selected company
|
|
- **WHEN** a shop user selects a shipping company and confirms shipment
|
|
- **THEN** the order shows the shipped state and the selected company
|
|
|
|
### Requirement: Merchant review management
|
|
Shop users SHALL list only their own shop's reviews in shop-admin through the shared API contract, with pagination and visible reply state, and SHALL submit at most one reply per review. Shop-admin SHALL expose a review management entry beside existing shop operations.
|
|
|
|
#### Scenario: reply to a review
|
|
- **WHEN** a merchant opens an unreplied review of their shop and submits a reply
|
|
- **THEN** the reply is stored once and the review row shows it as replied
|
|
|
|
#### Scenario: already replied review offers no second reply
|
|
- **WHEN** a merchant opens a review that already carries their shop's reply
|
|
- **THEN** no reply submission is offered and other shops' reviews are unreachable
|
|
|