askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
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 |
| 2 | box goes out. |
| 3 | |
| 4 | HANDLES payment writes. When a payment lands against an invoice raised for |
| 5 | a web order, this confirms the order and -- unless the shop has taken over |
| 6 | its own packing bench -- ships it. |
| 7 | |
| 8 | The ordering is still the whole point. Checkout decrements nothing: an |
| 9 | order that is never paid for must not have consumed stock, or every |
| 10 | abandoned card leaves a phantom sale behind and the shop shows "sold out" |
| 11 | for 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 |
| 14 | stock moves itself, one per order line, at payment. That was right while |
| 15 | an order could only be fulfilled all at once; it became wrong the moment |
| 16 | shipments existed, because "the goods left" is a fact about a BOX, not |
| 17 | about a payment, and two objects claiming the same fact is how a system |
| 18 | learns to disagree with itself. So the old behavior now travels through |
| 19 | the shipment noun: this handler creates a shipment for everything |
| 20 | unshipped and marks it packed, then shipped, and app-shipping's |
| 21 | system_order_fulfillment does what it always does when a shipment leaves |
| 22 | -- one sale move per line, idempotent per line, order status derived. |
| 23 | Nothing about the zero-touch shop's experience changes; there is simply a |
| 24 | document 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 |
| 27 | wants payment to mean shipped and never wants to see a pick list; a shop |
| 28 | that picks and packs sets it false, and this handler then confirms the |
| 29 | order and stops, leaving the shipment to action_create_shipment and a |
| 30 | human with a trolley. Defaulting true is what keeps the proven chain |
| 31 | working for every existing installation without anybody configuring |
| 32 | anything. |
| 33 | |
| 34 | Placement follows docs/logic-decisions.md #6 -- a REACTION (post-commit, |
| 35 | best-effort, never blocks the payment). A shop that cannot record a |
| 36 | shipment must still be able to take the money; the discrepancy is visible |
| 37 | and fixable, whereas a refused payment is a lost sale nobody can recover. |
| 38 | Every failure below therefore lands in the RESULT, not in an exception: |
| 39 | no shipping app installed, no stock app installed, no configured |
| 40 | locations -- the order still confirms and the response says what did not |
| 41 | happen. |
| 42 | |
| 43 | Idempotency by provenance (#7): the shipment carries "orders/{id}" in its |
| 44 | notes and, more usefully, the remaining-quantity arithmetic in |
| 45 | action_create_shipment means a replayed payment finds nothing left to ship |
| 46 | and returns ok with a note rather than raising a second empty parcel. The |
| 47 | stock moves are stamped per shipment line by system_order_fulfillment, so |
| 48 | a replay moves nothing twice there either. The books entry is handled by |
| 49 | app-payments' system_books, unchanged -- this object deliberately does not |
| 50 | post anything itself. |
| 51 | """ |
| 52 | |
| 53 | import os |
| 54 | |
| 55 | import object_execution |
| 56 | import object_records |
| 57 | import python_object_runtime |
| 58 | |
| 59 | HANDLES = [ |
| 60 | "payments.record.created", |
| 61 | "payments.record.updated", |
| 62 | ] |
| 63 | |
| 64 | ACTOR = "system_shop_fulfillment" |
| 65 | |
| 66 | |
| 67 | def _base_dir(): |
| 68 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 69 | |
| 70 | |
| 71 | def _text(value): |
| 72 | return str(value if value is not None else "").strip() |
| 73 | |
| 74 | |
| 75 | def _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 | |
| 82 | def _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 | |
| 92 | def _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 | |
| 106 | def _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 | |
| 157 | def _int(value): |
| 158 | try: |
| 159 | return int(_text(value) or 0) |
| 160 | except (TypeError, ValueError): |
| 161 | return 0 |
| 162 | |
| 163 | |
| 164 | def _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 | |
| 177 | def _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 | |
| 200 | def _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 | |
| 260 | def 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. |
| 366 | POST = EVENT |