Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
shop_fulfillment.py · 15.9 KB · 366 lines
1"""system_shop_fulfillment -- money arrived, so the sale is real and the
2box goes out.
3
4HANDLES payment writes. When a payment lands against an invoice raised for
5a web order, this confirms the order and -- unless the shop has taken over
6its own packing bench -- ships it.
7
8The ordering is still the whole point. Checkout decrements nothing: an
9order that is never paid for must not have consumed stock, or every
10abandoned card leaves a phantom sale behind and the shop shows "sold out"
11for goods sitting on the shelf. Stock moves when money moves.
12
13**What changed, and why this object got smaller.** It used to write the
14stock moves itself, one per order line, at payment. That was right while
15an order could only be fulfilled all at once; it became wrong the moment
16shipments existed, because "the goods left" is a fact about a BOX, not
17about a payment, and two objects claiming the same fact is how a system
18learns to disagree with itself. So the old behavior now travels through
19the shipment noun: this handler creates a shipment for everything
20unshipped and marks it packed, then shipped, and app-shipping's
21system_order_fulfillment does what it always does when a shipment leaves
22-- one sale move per line, idempotent per line, order status derived.
23Nothing about the zero-touch shop's experience changes; there is simply a
24document now saying what went out, and a packing slip to put in the box.
25
26**shop.auto_fulfill (default TRUE)** is the seam. A shop with no warehouse
27wants payment to mean shipped and never wants to see a pick list; a shop
28that picks and packs sets it false, and this handler then confirms the
29order and stops, leaving the shipment to action_create_shipment and a
30human with a trolley. Defaulting true is what keeps the proven chain
31working for every existing installation without anybody configuring
32anything.
33
34Placement follows docs/logic-decisions.md #6 -- a REACTION (post-commit,
35best-effort, never blocks the payment). A shop that cannot record a
36shipment must still be able to take the money; the discrepancy is visible
37and fixable, whereas a refused payment is a lost sale nobody can recover.
38Every failure below therefore lands in the RESULT, not in an exception:
39no shipping app installed, no stock app installed, no configured
40locations -- the order still confirms and the response says what did not
41happen.
42
43Idempotency by provenance (#7): the shipment carries "orders/{id}" in its
44notes and, more usefully, the remaining-quantity arithmetic in
45action_create_shipment means a replayed payment finds nothing left to ship
46and returns ok with a note rather than raising a second empty parcel. The
47stock moves are stamped per shipment line by system_order_fulfillment, so
48a replay moves nothing twice there either. The books entry is handled by
49app-payments' system_books, unchanged -- this object deliberately does not
50post anything itself.
51"""
52
53import os
54
55import object_execution
56import object_records
57import python_object_runtime
58
59HANDLES = [
60 "payments.record.created",
61 "payments.record.updated",
62]
63
64ACTOR = "system_shop_fulfillment"
65
66
67def _base_dir():
68 return os.environ.get("DBBASIC_DATA_DIR", "data")
69
70
71def _text(value):
72 return str(value if value is not None else "").strip()
73
74
75def _truthy(value, default):
76 text = _text(value).lower()
77 if not text:
78 return default
79 return text in ("true", "1", "yes", "on")
80
81
82def _setting(base, key, default=""):
83 try:
84 for row in object_records.read_collection_records("app_settings", base_dir=base):
85 if row.get("key") == key and _text(row.get("value")):
86 return _text(row["value"])
87 except Exception:
88 pass
89 return default
90
91
92def _payment_for(request, base):
93 record = request.get("record")
94 if isinstance(record, dict) and record.get("id"):
95 return record
96 payment_id = _text(request.get("record_id") or request.get("id"))
97 if not payment_id:
98 return None
99 try:
100 return object_records.get_collection_record("payments", payment_id,
101 base_dir=base)
102 except Exception:
103 return None
104
105
106def _invoice_is_settled(base, invoice_id):
107 """(True, "") when the bill is fully paid, else (False, why).
108
109 Trusts the invoice's own status where it is decisive, and falls back
110 to comparing what has been paid against the total -- because a shop
111 with app-payments' status handler absent would otherwise never ship
112 anything, and "your money arrived and nothing happened" is a worse
113 failure than shipping a shade early.
114 """
115 if not invoice_id:
116 return True, "" # nothing to settle; not a web order's bill
117 try:
118 invoice = object_records.get_collection_record(
119 "invoices", invoice_id, base_dir=base)
120 except Exception:
121 # Cannot read the bill: do not hold the goods hostage to a lookup
122 # failure. The stock move is idempotent and visible either way.
123 return True, ""
124 if _text(invoice.get("status")) in ("paid", "void"):
125 return True, ""
126 total = _int(invoice.get("total_cents"))
127 if not total:
128 return True, ""
129
130 # Sum the payments HERE rather than trusting invoice.amount_paid_cents.
131 # That field is derived by a rollup, and this handler runs ON the write
132 # that just created the payment -- so at this instant the invoice has
133 # not been told about the money that triggered us. Reading it would
134 # mean the first payment never ships anything and the SECOND one ships
135 # everything, which is a bug that only appears for customers who pay
136 # in instalments.
137 paid = 0
138 try:
139 for row in object_records.read_collection_records("payments", base_dir=base):
140 if (_text(row.get("invoice_id")) == invoice_id
141 and _text(row.get("status")) == "received"):
142 paid += _int(row.get("amount_cents"))
143 except Exception:
144 return True, "" # cannot tell; do not hold the goods
145 try:
146 for row in object_records.read_collection_records("refunds", base_dir=base):
147 if _text(row.get("invoice_id")) == invoice_id:
148 paid -= _int(row.get("amount_cents"))
149 except Exception:
150 pass # no refunds app installed is not a refund
151
152 if paid >= total:
153 return True, ""
154 return False, f"invoice not settled: {paid} of {total} paid"
155
156
157def _int(value):
158 try:
159 return int(_text(value) or 0)
160 except (TypeError, ValueError):
161 return 0
162
163
164def _order_for_invoice(base, invoice_id):
165 if not invoice_id:
166 return None
167 try:
168 orders = object_records.read_collection_records("orders", base_dir=base)
169 except Exception:
170 return None
171 for order in orders:
172 if _text(order.get("invoice_id")) == invoice_id:
173 return order
174 return None
175
176
177def _call(object_id, payload, *, method="POST"):
178 """Run another installed object in process, the same way site_shop calls
179 its siblings: this package owns the payment-to-order join and nothing
180 about boxes, so it asks the object that does.
181
182 Returns (result, error). A missing object -- app-shipping simply not
183 installed -- is an error string, never an exception: see the module
184 docstring's posture about what a failure here is allowed to cost.
185 """
186 try:
187 runtime = python_object_runtime.PythonObjectRuntime()
188 outcome = object_execution.execute_object(
189 runtime,
190 object_execution.ObjectExecutionRequest(
191 object_id, method=method, payload=payload))
192 except Exception as exc:
193 return None, str(exc)[:200]
194 if not outcome.ok:
195 message = getattr(outcome.error, "message", "") if outcome.error else ""
196 return None, _text(message)[:200] or f"{object_id} failed"
197 return outcome.result, ""
198
199
200def _ship_everything(base, order):
201 """Create a shipment for everything still unshipped and send it.
202
203 packed then shipped as two separate updates, deliberately: the schema's
204 transition ladder is open -> packed -> shipped, and a handler that
205 jumped straight to shipped would either be refused or would force the
206 ladder to be loosened for everybody, which would let a real packing
207 bench skip the step that means "somebody actually put this in a box".
208 """
209 created, error = _call("action_create_shipment", {"order_id": order["id"]})
210 if error:
211 return {"shipped": False, "warning":
212 f"no shipment was created ({error}); the order still stands"}
213 if not isinstance(created, dict) or not created.get("ok"):
214 detail = _text((created or {}).get("error")) or "unknown reason"
215 return {"shipped": False,
216 "warning": f"no shipment was created ({detail}); the order still stands"}
217
218 shipment_id = _text(created.get("shipment_id"))
219 if not shipment_id:
220 # Nothing left to ship: a replayed payment, or an order somebody
221 # already packed by hand. Idempotent, and not a failure.
222 return {"shipped": False, "note": _text(created.get("note"))}
223
224 for status in ("packed", "shipped"):
225 try:
226 object_records.update_collection_record(
227 "shipments", shipment_id, {"status": status},
228 base_dir=base, actor=ACTOR)
229 except Exception as exc:
230 return {"shipped": False, "shipment_id": shipment_id,
231 "warning": (f"shipment {shipment_id} could not move to "
232 f"{status}: {str(exc)[:120]}")}
233
234 # Fire the fulfillment handler in process rather than waiting for the
235 # change-log dispatcher: this write came from a handler, not from an
236 # HTTP request, so nothing dispatched it, and the stock move has to
237 # happen now for exactly the reason it always did -- the goods have
238 # gone. The handler is idempotent per line, so the dispatcher's later
239 # at-least-once redelivery moves nothing twice.
240 result, error = _call("system_order_fulfillment",
241 {"collection": "shipments", "record_id": shipment_id},
242 method="EVENT")
243 out = {"shipped": True, "shipment_id": shipment_id,
244 "lines": created.get("lines", 0),
245 "slip_path": created.get("slip_path", "")}
246 if error:
247 out["warning"] = (f"the shipment went out but its stock move did not "
248 f"({error}); the goods left the shelf without the "
249 f"ledger saying so")
250 return out
251 if isinstance(result, dict):
252 out["moved"] = result.get("moved", 0)
253 if result.get("warning"):
254 out["warning"] = result["warning"]
255 if result.get("order_status"):
256 out["order_status"] = result["order_status"]
257 return out
258
259
260def EVENT(request):
261 base = _base_dir()
262 payment = _payment_for(request, base)
263 if not payment:
264 return {"ok": True, "skipped": "no payment in the event"}
265 if _text(payment.get("status")) != "received":
266 return {"ok": True, "skipped": "payment not received"}
267
268 order = _order_for_invoice(base, _text(payment.get("invoice_id")))
269 if order is None:
270 # Most payments are not for web orders. Saying so plainly beats a
271 # silent return that looks identical to a bug.
272 return {"ok": True, "skipped": "no web order for this payment"}
273
274 # Goods leave when the BILL is settled, not when money merely arrives.
275 #
276 # This checked only that a payment existed and was received, so any
277 # amount shipped the order: a 14.00 payment against a 20.00 invoice
278 # fulfilled it in full, and the invoice was left sitting at `partial`
279 # saying so. Found by paying the wrong amount by hand on the live shop.
280 #
281 # The invoice already knows the answer -- system_invoice_status folds
282 # payments and refunds and flips it to paid or partial -- so this asks
283 # the document rather than doing its own arithmetic on one payment,
284 # which is also what makes a deposit followed by a balance work: the
285 # second payment is what tips it to paid, and that is the event that
286 # ships.
287 settled, reason = _invoice_is_settled(base, _text(payment.get("invoice_id")))
288 if not settled:
289 return {"ok": True, "skipped": reason, "order_id": order["id"]}
290 if _text(order.get("status")) not in ("draft", "confirmed"):
291 return {"ok": True, "skipped": f"order already {_text(order.get('status'))}"}
292
293 if _text(order.get("status")) == "draft":
294 try:
295 object_records.update_collection_record(
296 "orders", order["id"], {"status": "confirmed"},
297 base_dir=base, actor=ACTOR,
298 expected_rev=object_records.compute_record_rev(order))
299 except object_records.VersionConflictError:
300 return {"ok": True, "order_id": order["id"],
301 "skipped": "another pass is already handling this order"}
302 order = object_records.get_collection_record("orders", order["id"],
303 base_dir=base)
304
305 result = {"ok": True, "order_id": order["id"], "confirmed": True}
306
307 if not _truthy(_setting(base, "shop.auto_fulfill"), True):
308 # A shop with a packing bench: the order is confirmed and appears on
309 # the pick list, and a human decides what goes in which box.
310 # Deliberately NOT claimed below -- the order is supposed to sit at
311 # `confirmed` waiting for a person, and claiming it would take it
312 # off the very list it needs to be on.
313 result["note"] = ("shop.auto_fulfill is off; this order is confirmed "
314 "and waiting on the pick list")
315 result["shipped"] = False
316 return result
317
318 # CLAIM THE ORDER BEFORE SHIPPING ANYTHING.
319 #
320 # Two concurrent deliveries of the same payment event -- the change
321 # dispatcher is at-least-once, and an operator can POST this handler by
322 # hand -- both read the order as `confirmed`, both walked past the guard
323 # above, and both shipped it. Reproduced reliably, three times in three:
324 # two shipments, FOUR units against an order of two, two sale moves. The
325 # goods left the shelf twice.
326 #
327 # Nothing below could have stopped it. action_create_shipment computes
328 # what is unshipped by reading shipment_lines, and hook_shipment_lines
329 # refuses an over-ship by summing them -- but both are check-then-write
330 # and a hook runs BEFORE the write lock, so under real concurrency both
331 # passes read an empty history and both wrote. Layered advisory checks
332 # do not compose into an atomic one.
333 #
334 # The only thing on this box that IS atomic is a compare-and-set on a
335 # single record: expected_rev, compared inside the write lock (63,
336 # plan/vocabulary/63-concurrency-spec.md). So the claim is the write
337 # that moves the order out of the shippable set, and the loser finds the
338 # row already changed.
339 #
340 # THE TRADE, stated because it is a real one: the ladder has no
341 # processing -> confirmed step, so an order whose shipment then FAILS
342 # stays at `processing` rather than falling back to `confirmed` for a
343 # redelivered event to retry. That is deliberate. A stuck order is
344 # visible on the pick list and a person ships it; a double shipment is
345 # goods out of the door against one payment, and no one finds out until
346 # the stock count.
347 try:
348 object_records.update_collection_record(
349 "orders", order["id"], {"status": "processing"},
350 base_dir=base, actor=ACTOR,
351 expected_rev=object_records.compute_record_rev(order))
352 except object_records.VersionConflictError:
353 result["shipped"] = False
354 result["skipped"] = "another pass claimed this order first"
355 return result
356
357 result.update(_ship_everything(base, order))
358 return result
359
360
361# EVENT is the verb the change dispatcher calls handlers with (see
362# object_change_dispatch); it went unnoticed here because in-process tests
363# invoked POST directly and the dispatcher's method-not-supported error
364# only surfaced on the live box. POST stays as an alias so an operator can
365# poke the handler by hand over HTTP.
366POST = EVENT