feat: three nuxt frontends, demo seed, rounding + money-exponent + rate-cast fixes, archived specs

2026-09-17 13:34:38 +08:00
parent dc9fd31c5e
commit 653f13161a
85 changed files with 4327 additions and 106 deletions
@@ -0,0 +1,17 @@
+# Proposal: cart-checkout-orders
+
+## Why
+Shoppers must be able to collect items and place orders. Checkout splits the cart into one order per shop (B2B2C requirement), snapshots prices, and decrements stock atomically.
+
+## What changes
+- Redis-backed cart per authenticated user (add/update/remove/list), merged SKU + product snapshot at read time.
+- Checkout: validate stock + published status, create orders (one per shop) with items, decrement stock in a transaction, clear cart.
+- Order lifecycle: pending_payment → paid (mock pay endpoint) → fulfilling → shipped → completed; customer cancel while pending_payment.
+- Customer APIs: my orders list/detail, cancel, mock-pay.
+
+## Non-goals
+- Real payment gateways, partial refunds, guest checkout.
+
+## Capabilities
+- `cart`: server-side cart.
+- `order`: checkout, order lifecycle, customer order APIs.
@@ -0,0 +1,14 @@
+# Spec delta: cart
+
+## ADDED Requirements
+
+### Requirement: Server-side cart
+Authenticated shoppers SHALL have a Redis-backed cart keyed by user id, containing sku_id + qty entries.
+
+#### Scenario: add and update
+- **WHEN** a shopper POSTs sku + qty, then PUTs a new qty
+- **THEN** GET /api/cart reflects the latest qty with current price/name snapshot
+
+#### Scenario: unpurchasable SKU rejected
+- **WHEN** adding a SKU that is inactive or whose product is not published
+- **THEN** the API returns 400
@@ -0,0 +1,32 @@
+# Spec delta: order
+
+## ADDED Requirements
+
+### Requirement: Checkout splits by shop
+`POST /api/orders/checkout` SHALL create one order per distinct shop in the cart, in a single database transaction: stock decrement, order + item insert with price snapshots, cart clear. All amounts use the cart's SKU currencies converted into the buyer-chosen display currency at checkout time.
+
+#### Scenario: two shops → two orders
+- **WHEN** the cart contains SKUs from shops A and B
+- **THEN** two orders are created, each with only its shop's items, and the cart is empty
+
+#### Scenario: insufficient stock
+- **WHEN** any line's qty exceeds SKU stock
+- **THEN** the whole checkout returns 409 and no order is created and stock is unchanged
+
+### Requirement: Order lifecycle
+Status transitions SHALL be: pending_payment → paid → fulfilling → shipped → completed; cancellable only from pending_payment, which MUST restore stock.
+
+#### Scenario: cancel restores stock
+- **WHEN** a customer cancels a pending_payment order
+- **THEN** stock of each SKU increases by the ordered qty and status is cancelled
+
+#### Scenario: illegal transition rejected
+- **WHEN** cancelling a paid order via the customer endpoint
+- **THEN** the API returns 409
+
+### Requirement: Order ownership
+Customers SHALL see only their own orders; shop roles only their shop's orders; platform_admin sees all.
+
+#### Scenario: cross-customer read denied
+- **WHEN** customer X requests customer Y's order id
+- **THEN** the API returns 404
@@ -0,0 +1,17 @@
+# Tasks: cart-checkout-orders
+
+## 1. Schema
+- [x] Migration: orders, order_items; order status enum; order_no sequence
+
+## 2. Cart (Redis)
+- [x] GET /api/cart, POST /api/cart/items, PUT/DELETE /api/cart/items/{sku_id}
+- [x] Cart read joins SKU/product snapshots; rejects inactive/unpublished SKUs
+
+## 3. Checkout & orders
+- [x] POST /api/orders/checkout (one order per shop, tx: stock decrement + order insert, cart clear)
+- [x] GET /api/orders (mine, paged), GET /api/orders/{id}
+- [x] POST /api/orders/{id}/pay (mock) and /cancel with state rules
+- [x] GET /api/shop/orders for merchants; platform admin list
+
+## 4. Tests
+- [x] cargo test: multi-shop checkout splits orders, insufficient stock → 409, cancel rules, stock restored on cancel