105 lines
7.4 KiB
Markdown
105 lines
7.4 KiB
Markdown
# frontend-admin Specification
|
|
|
|
## Purpose
|
|
The platform console for managing users, shops and currencies.
|
|
## Requirements
|
|
### Requirement: Platform user and shop management
|
|
Platform admins SHALL assign user roles (with shop scope), create shops, and suspend/activate shops. Suspended shops' products MUST NOT be purchasable (enforced by API, reflected in UI).
|
|
|
|
#### Scenario: assign shop owner
|
|
- **WHEN** an admin assigns role shop_owner with a shop to a user
|
|
- **THEN** that user can log into shop-admin and manage that shop
|
|
|
|
### Requirement: Currency management
|
|
Platform admins SHALL view currencies and update exchange rates; new rates affect subsequent conversions.
|
|
|
|
#### Scenario: rate update
|
|
- **WHEN** an admin updates CNY rate_to_base
|
|
- **THEN** the mall conversion endpoint returns amounts computed with the new rate
|
|
|
|
### Requirement: Platform points mall management
|
|
Platform admins SHALL manage points products and inspect and fulfill redemption orders through the admin console using the shared API contract. Admin SHALL expose points-mall navigation beside existing platform operations.
|
|
|
|
#### Scenario: manage a redemption catalog item
|
|
- **WHEN** a platform admin publishes a configured points product
|
|
- **THEN** it becomes available in the customer points mall
|
|
|
|
#### Scenario: points mall appears in admin navigation
|
|
- **WHEN** an authenticated platform admin opens the admin console
|
|
- **THEN** points-product and redemption-order management are reachable from the console nav
|
|
|
|
### Requirement: Shared design system in the platform console
|
|
The platform 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 platform admin opens the dashboard
|
|
- **THEN** primary actions and page chrome render through the shared kit with the current accent preset
|
|
|
|
### Requirement: Accent preset switcher
|
|
Platform admin SHALL expose the shared accent preset control (`red`, `blue`, `teal`, `violet`) in the authenticated shell header.
|
|
|
|
#### Scenario: switcher visible
|
|
- **WHEN** an authenticated platform admin opens the console
|
|
- **THEN** they can select an accent preset without leaving the current page
|
|
|
|
### Requirement: Storefront content management
|
|
The platform console SHALL manage the four home-content kinds — banners, promos, quick links and floor adverts — on a content page reachable from the console navigation, loading every entry including inactive ones through the shared API adapter. Each kind SHALL be edited as its ordered list of rows with add, remove and reorder controls (no drag and drop), the per-entry fields the API accepts, an active flag per entry, and a preview of how the storefront renders each entry. Saving a kind SHALL submit the whole edited list in its displayed order as one replacement with the semantics of `PUT /api/admin/content/{kind}`, so positions follow the submitted order and the other three kinds are untouched. Rows SHALL be validated before any request with the rules the API enforces — non-empty image and destination URLs, non-empty glyph, and non-empty `en` and `zh` quick-link labels in `{ en, zh }` JSONB text — with inline field errors on failing rows. Saves SHALL give clear success feedback; a rejected save SHALL keep the edited rows and show a visible failure message.
|
|
|
|
#### Scenario: save replaces one kind only
|
|
- **WHEN** an admin reorders banners, saves that kind, and the mall reloads its home content
|
|
- **THEN** banners appear in the new order while promos, quick links and floor adverts are unchanged
|
|
|
|
#### Scenario: invalid row is blocked before submit
|
|
- **WHEN** an admin leaves a banner image URL empty and saves
|
|
- **THEN** the row shows an inline field error and no replacement request is sent
|
|
|
|
#### Scenario: rejected save keeps the editor state
|
|
- **WHEN** the API rejects a replacement
|
|
- **THEN** the page shows a failure message and keeps the edited rows for correction
|
|
|
|
### Requirement: Brand management
|
|
Platform admins SHALL manage the ordered brand registry on a brands page reachable from the console navigation, through the shared API adapter. The page SHALL edit the whole list — slug, non-empty `{ en, zh }` names and an active flag per row — with add, remove and reorder controls and a preview of each brand as the public list serves it. Saving SHALL replace the whole list in its displayed order so positions follow the submitted order. Slugs SHALL be validated against the ascii `a-z`, `0-9`, `-` pattern and duplicate slugs and incomplete bilingual names SHALL be rejected with inline errors before any request is sent. Saves SHALL give clear success feedback; a rejected save SHALL keep the edited rows and show a visible failure message.
|
|
|
|
#### Scenario: replace round-trips to the public list
|
|
- **WHEN** an admin reorders brands, renames one, and saves
|
|
- **THEN** the public brand list returns the same entries in the submitted order
|
|
|
|
#### Scenario: duplicate slug is blocked before submit
|
|
- **WHEN** an admin saves with two rows carrying the same slug
|
|
- **THEN** the duplicate rows show inline errors and no replacement request is sent
|
|
|
|
#### Scenario: save feedback distinguishes success and failure
|
|
- **WHEN** a save succeeds or the API refuses the list
|
|
- **THEN** the page shows a success confirmation or keeps the edited rows with a failure message, respectively
|
|
|
|
### Requirement: Platform aftersale monitoring and arbitration
|
|
The platform admin console SHALL provide a read-only cross-shop aftersale list and detail view with customer, shop, order-item, amount, evidence, status, message history, and refund-total context. A platform administrator SHALL be able to resolve an escalated dispute with a terminal refund or rejection through the guarded service path, without directly editing balances or bypassing shop ownership checks.
|
|
|
|
#### Scenario: admin inspects a cross-shop application
|
|
- **WHEN** a platform administrator opens the aftersale workspace
|
|
- **THEN** applications from all shops are listed with filters and authoritative status and refund amounts
|
|
|
|
#### Scenario: admin grants terminal refund
|
|
- **WHEN** a platform administrator resolves an eligible dispute in favor of the customer
|
|
- **THEN** the aftersale reaches refunded, the customer ledger is credited once, and the order refund total refreshes from the API
|
|
|
|
#### Scenario: admin rejects terminal dispute
|
|
- **WHEN** a platform administrator rejects an escalated dispute
|
|
- **THEN** the aftersale reaches rejected and the console shows that only the permitted one-time customer reopen can resume it
|
|
|
|
### Requirement: Platform review moderation
|
|
Platform admins SHALL review a paginated moderation list of all reviews with their product, customer, and shop context and SHALL hide or delete reviews through the shared API contract. Admin SHALL expose review moderation navigation beside existing platform operations.
|
|
|
|
#### Scenario: hide a review from the moderation list
|
|
- **WHEN** a platform admin hides a review
|
|
- **THEN** the list shows it as hidden and the review leaves the mall storefront and rating summary
|
|
|
|
#### Scenario: delete a review
|
|
- **WHEN** a platform admin deletes a review
|
|
- **THEN** the row is removed and absent from both admin and storefront listings
|
|
|
|
#### Scenario: moderation appears in admin navigation
|
|
- **WHEN** an authenticated platform admin opens the admin console
|
|
- **THEN** a review moderation entry is reachable from the console nav
|
|
|