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: fulfillment-invoices
+
+## Why
+After payment, merchants ship goods (发货单) and customers request invoices (发票). This phase closes the post-order loop of the MVP.
+
+## What changes
+- Schema: shipments (carrier, tracking, status, per-item qty), invoices (title, tax_no, kind, amount, status).
+- Shipment lifecycle: created(pending) → shipped → delivered; order becomes fulfilling on first shipment, shipped when all items shipped, completed when all delivered (customer confirm allowed).
+- Merchant APIs: create shipment for paid/fulfilling orders, mark shipped, list shipments/invoices, issue invoice.
+- Customer APIs: my shipments, confirm delivery, request invoice per order, my invoices.
+
+## Non-goals
+- Carrier API integrations, e-invoice/PDF generation, partial invoice amounts.
+
+## Capabilities
+- `shipment`: 发货单 lifecycle.
+- `invoice`: 发票 request/issue lifecycle.
@@ -0,0 +1,21 @@
+# Spec delta: invoice
+
+## ADDED Requirements
+
+### Requirement: Invoice request
+Customers SHALL request at most one open invoice (发票) per order, with title, kind (`personal | company`), and tax_no required for company invoices. Amount equals the order total in the order currency.
+
+#### Scenario: company invoice requires tax number
+- **WHEN** requesting a company invoice without tax_no
+- **THEN** the API returns 400
+
+#### Scenario: duplicate rejected
+- **WHEN** an order already has a requested or issued invoice
+- **THEN** a second request returns 409
+
+### Requirement: Invoice issuance
+Merchants SHALL issue requested invoices of their own shop's orders; issuing sets invoice_no, issued_at and status `issued`.
+
+#### Scenario: issue flow
+- **WHEN** the shop issues a requested invoice
+- **THEN** the customer sees status `issued` with an invoice number
@@ -0,0 +1,23 @@
+# Spec delta: shipment
+
+## ADDED Requirements
+
+### Requirement: Shipment creation
+Merchants SHALL create shipments (发货单) for their own orders in `paid` or `fulfilling` status, specifying carrier, tracking_no and per-item quantities.
+
+#### Scenario: partial shipment
+- **WHEN** an order has 3 units of item X and a shipment covers 2
+- **THEN** a later shipment may cover the remaining 1; requesting more than the remainder returns 400
+
+#### Scenario: status propagation
+- **WHEN** the first shipment is created for a paid order
+- **THEN** the order becomes `fulfilling`
+- **WHEN** all ordered quantities are covered by shipped shipments
+- **THEN** the order becomes `shipped`
+
+### Requirement: Delivery confirmation
+Customers SHALL confirm delivery of their own shipments; when every shipment of an order is delivered the order becomes `completed`.
+
+#### Scenario: confirm delivered
+- **WHEN** the customer confirms the only shipment of a shipped order
+- **THEN** shipment becomes `delivered` and the order `completed`
@@ -0,0 +1,17 @@
+# Tasks: fulfillment-invoices
+
+## 1. Schema
+- [x] Migration: shipments, shipment_items, invoices; status enums; shipment_no/invoice_no sequences
+
+## 2. Shipments
+- [x] POST /api/shop/orders/{id}/shipments (qty validation vs unshipped remainder)
+- [x] POST /api/shop/shipments/{id}/ship; order status propagation (fulfilling/shipped)
+- [x] GET /api/shipments (customer), POST /api/shipments/{id}/confirm-delivered → order completed when done
+- [x] GET /api/shop/shipments
+
+## 3. Invoices
+- [x] POST /api/orders/{id}/invoice (one open invoice per order; amount = order total)
+- [x] GET /api/invoices (customer), GET /api/shop/invoices, POST /api/shop/invoices/{id}/issue
+
+## 4. Tests
+- [x] cargo test: partial shipment qty math, order status propagation, duplicate invoice rejected, issue flow