Files
vmall/docs/domains/orders.md
T
Chengdong ZhangandCursor cc9a522589 feat(orders): provision paid services through shop tasks
Payment opens one provision task and a pending subscription. Delivery completes the order, a cancelled claim reopens it, and renewal records the chosen term without taking anchor stock.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-18 16:44:36 +08:00

4.0 KiB
Raw Blame History

Domain: Orders, Checkout, Fulfillment, Freight

Lifecycle

cart → checkout (one tx) → order per shop          physical shipment flow
─────────────────────────                          ─────────────────────────
pending_payment ──pay──► paid ──first shipment──► fulfilling ──all shipped──► shipped
      │                                                    │
      └──cancel──► cancelled                    delivered (all shipments) ──► completed

direct purchase (one non-physical SKU, cart untouched)
pending_payment ──pay──► paid ──claim provision task──► fulfilling ──deliver task──► completed
                              ▲                              │
                              └──── cancel provision task ───┘
renewal payment applies as paid ──► completed and extends the subscription

orders.fulfillment_kind is snapshotted from the product. Physical orders keep a shipping address. A new provisioned-service purchase stores contact (the buyer email) and fulfillment_details, leaves shipping_address null, and completes only when its provision task is delivered: the same transaction marks the task done, sets completed_at, and activates the subscription with the public access URL and region. Cancelling a claimed provision task returns the order to paid and opens a new pending task for the same item. The old /shop/orders/{id}/start-fulfilment and /deliver routes return 409. A renewal sets term_months to the chosen term and clears termination_marked_at. A renewal stores fulfillment_details.renew_subscription_id, skips the anchor stock decrement, and completes when payment is applied. Shipments, return-refund after-sales, coupons, threshold promotions, flash sales, group buying, and growth accrual do not apply to a service order. Every arrow is a guarded UPDATE … WHERE status = …; stale actions → 409.

Subscription status is separate: pending until delivery, then active, grace at end_at, suspended 15 days later, and a terminate task 30 days after suspension. Renewal is refused while a terminate task is open.

Checkout invariants (modules/order/service.rs)

One transaction per checkout: lock SKUs (FOR UPDATE in id order) → resolve flash-sale activity pricing → per-shop coupon discount (server-computed, client sends only coupon ids) → per-shop freight fee → insert order + items + stock decrements → commit → clear cart. A direct purchase resolves one published non-physical SKU at quantity 1, does not read or clear the cart, hashes only that input for idempotency, and skips freight (fee 0, no template snapshot). Cart checkout drops any non-physical line before pricing. Orders are split per shop; each order carries total_minor = subtotal − discount + shipping_fee_minor.

Snapshots make history immutable: order items keep unit_price_minor, product_name, flash_sale_item_id, and the freight freight_template_id/freight_pricing_method resolved at checkout. Later template edits never touch past orders.

Freight (modules/freight/)

Templates are shop-scoped (own_shop): by_piece or by_weight (grams on skus.weight_grams), first-unit + additional-unit fees with part-unit round-up, always_free, free_threshold_minor, and region rules overriding default fees by case-insensitive match against address region/city/country. Resolution per line: product template → shop default → zero fee. Fees merge per template group within a shop order and convert from the group's SKU currency to the order currency.

POST /orders/shipping-quote is the read-only quote (normal prices only); checkout recomputes authoritatively in the order transaction. Client-supplied fees are never read.

Shipping companies are a dictionary (shipping_companies); shipments record shipping_company_code validated against it.

Key files

See docs/code_index/order.md.