feat: backend MVP (auth/rbac, catalog, orders, fulfillment, invoices) + specs + scaffolds

2026-09-17 12:43:22 +08:00
commit dc9fd31c5e
96 changed files with 17550 additions and 0 deletions
@@ -0,0 +1,18 @@
+# Proposal: frontend-apps
+
+## Why
+The API needs its three user-facing surfaces: customer storefront (mall), merchant console (shop-admin), and platform console (admin) — all Nuxt 3, all bilingual (en/zh), with the mall offering multi-currency display.
+
+## What changes
+- Shared package @vmall/shared: API contract types, typed API client, en/zh locales, base stylesheet.
+- mall (port 3000): product browsing w/ search+category, product detail, cart, checkout, orders, shipments, invoices, login/register, currency switcher (display conversion).
+- shop-admin (3001): dashboard, product CRUD + publish/unpublish + SKU editing, order list, shipment creation/ship, invoice issue.
+- admin (3002): user role assignment, shop creation/suspension, order oversight, currency management (rates).
+
+## Non-goals
+- SSR SEO tuning, design-system polish beyond the shared stylesheet, e2e test suites (smoke-verified in browser).
+
+## Capabilities
+- `frontend-mall`: shopper experience.
+- `frontend-shop-admin`: merchant experience.
+- `frontend-admin`: platform operator experience.
@@ -0,0 +1,17 @@
+# Spec delta: frontend-admin
+
+## ADDED 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
@@ -0,0 +1,24 @@
+# Spec delta: frontend-mall
+
+## ADDED Requirements
+
+### Requirement: Localized storefront
+The mall SHALL render UI strings and catalog content in en or zh from one switcher, defaulting to en.
+
+#### Scenario: switch to Chinese
+- **WHEN** a shopper switches locale to zh
+- **THEN** navigation, buttons and product names render in Chinese without reload errors
+
+### Requirement: Multi-currency display
+The mall SHALL offer a currency switcher (enabled currencies from the API) converting SKU prices for display; checkout uses the selected currency.
+
+#### Scenario: switch currency
+- **WHEN** a shopper switches from USD to JPY on a product priced $10.00
+- **THEN** the displayed price reflects the API conversion rate (integer minor units)
+
+### Requirement: Shopping flow
+A shopper SHALL be able to browse, view detail, add to cart, checkout with a shipping address, pay (mock), track shipments, confirm delivery, and request an invoice — all against the live API.
+
+#### Scenario: end-to-end purchase
+- **WHEN** a registered shopper completes checkout on a non-empty cart
+- **THEN** orders appear under Orders and the cart is empty
@@ -0,0 +1,17 @@
+# Spec delta: frontend-shop-admin
+
+## ADDED 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
@@ -0,0 +1,22 @@
+# Tasks: frontend-apps
+
+## 1. Shared package
+- [x] @vmall/shared: types, API client, locales (en/zh), ui.css
+
+## 2. Scaffolds
+- [x] Three Nuxt apps: config, i18n, pinia session store, api plugin, layouts
+
+## 3. mall
+- [ ] Home: product grid + search + category filter + paging
+- [ ] Product detail with SKU picker, localized content, converted price
+- [ ] Cart page, checkout page (address form), orders list/detail, shipments, invoices, login/register
+
+## 4. shop-admin
+- [ ] Login guard, dashboard, products list/new/edit (i18n fields, SKUs), publish/unpublish
+- [ ] Orders, shipment creation + mark shipped, invoices list + issue
+
+## 5. admin
+- [ ] Login guard, users (role assignment), shops (create/suspend), orders, currencies (rate edit)
+
+## 6. Verification
+- [ ] All three apps build; browser smoke: register→shop create→product publish→purchase→ship→invoice in en + zh