PlaceOrder

1# PlaceOrder.intent
2# Domain: ecommerce checkout. Turning a cart into an order is where money, stock,
3# and trust all meet. One order per submission, never oversell, never charge before
4# stock is reserved. The checkout gate runs as a decision.
5
6mission PlaceOrder
7use product
8
9title "Place an order from a cart safely and exactly once"
10for StorefrontTeam
11
12note pm:
13  A double-click at checkout must never become two orders or two charges.
14
15goal
16  Convert a valid cart into exactly one order, with stock reserved before payment
17  is captured.
18
19why
20  Overselling, double charges, and duplicate orders each turn a sale into a refund,
21  a support ticket, and lost trust.
22
23requires
24  Cart
25  PaymentMethod
26
27input
28  cart: Cart
29  idempotencyKey: IdempotencyKey
30  inStock: Flag
31  paymentValid: Flag
32
33output
34  order: Order
35
36guarantee a resubmitted checkout with the same key returns the first order
37  because customers double-submit, and each retry must not create a new order
38  verify idempotent checkout test
39
40guarantee stock is reserved before the customer is charged
41  because charging for stock you cannot ship is the worst checkout failure
42  verify reserve before charge test
43
44never
45  create a second order for the same idempotency key
46  sell more units than are in stock
47  capture payment before stock is reserved
48
49never create a second order for the same idempotency key
50  because that is a duplicate order and a duplicate charge
51  verify idempotent checkout test
52
53never sell more units than are in stock
54  because overselling forces cancellations and breaks delivery promises
55  verify oversell prevention test
56
57never capture payment before stock is reserved
58  because a charge without reserved stock guarantees a refund
59  verify reserve before charge test
60
61# The checkout gate as a decision. `intent run` / `intent test`.
62decision CanPlaceOrder
63  inputs
64    keySeen
65    inStock
66    paymentValid
67  rule replay
68    when keySeen == true
69    return ReturnExisting
70  rule outOfStock
71    when inStock == false
72    return RejectOutOfStock
73  rule badPayment
74    when paymentValid == false
75    return RejectPayment
76  default
77    return CreateOrder
78
79target
80  TypeScript
81  OpenAPI
82  Tests
83
84test CanPlaceOrder
85  case first valid checkout creates the order
86    given keySeen false, inStock true, paymentValid true
87    expect CreateOrder
88  case retry returns the existing order
89    given keySeen true, inStock true, paymentValid true
90    expect ReturnExisting
91  case out of stock is rejected
92    given keySeen false, inStock false, paymentValid true
93    expect RejectOutOfStock
94  case invalid payment is rejected
95    given keySeen false, inStock true, paymentValid false
96    expect RejectPayment
97  case a seen key wins over stock and payment checks
98    given keySeen true, inStock false, paymentValid false
99    expect ReturnExisting