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
order_fulfillment.py · 15.8 KB · 379 lines
| 1 | """system_order_fulfillment -- the box left, so the shelf is lighter and |
| 2 | the order says so. |
| 3 | |
| 4 | HANDLES shipments and shipment_lines writes. Two jobs, both of them reads |
| 5 | turned into facts: |
| 6 | |
| 7 | **Stock moves when goods physically move.** One `sale` move PER SHIPMENT |
| 8 | LINE at the moment a shipment reaches `shipped`, from shop.stock_location |
| 9 | to shop.customer_location. Per line rather than per shipment because a |
| 10 | level is a fold over moves per product, and per order rather than per |
| 11 | line was only ever right while an order could not be split -- the whole |
| 12 | point of the shipment noun is that it can. |
| 13 | |
| 14 | **The order's status is derived, never set.** Some of the ordered quantity |
| 15 | on shipped-or-beyond shipments is `partial`; all of it is `shipped`; all of |
| 16 | it delivered is `delivered` (docs/logic-decisions.md #1: the QUANTITIES on |
| 17 | shipment lines are the facts, the order's status is a read of them). A |
| 18 | human never types `partial` and no surface computes it at read time; it is |
| 19 | stored, so the order list, the pick list and a report cannot disagree. |
| 20 | |
| 21 | Placement follows docs/logic-decisions.md #6 -- a REACTION, post-commit, |
| 22 | best-effort, never blocking the write that triggered it. A warehouse that |
| 23 | cannot record a stock move must still be able to send the parcel; the |
| 24 | discrepancy is visible and fixable, whereas a refused shipment is a |
| 25 | customer waiting for goods that are sitting in a box by the door. |
| 26 | |
| 27 | Idempotency by provenance (#7): each move is stamped |
| 28 | `shipments/{shipment_id}:line/{line_id}` in its reference, PER LINE. A |
| 29 | replayed event -- and events are replayed here, by design: the change |
| 30 | dispatcher promises at-least-once (object_change_dispatch.py) -- finds its |
| 31 | own marker and moves nothing. Per line and not per shipment because a |
| 32 | shipment can gain a line while still open, and a shipment-level marker |
| 33 | would silently skip the goods added after the first pass. |
| 34 | |
| 35 | **The handover date is stamped here too**, and only when it is blank. A |
| 36 | shipment reaching `shipped` IS the handover, so shipped_on is a fact about |
| 37 | that moment (#1) -- and until the carrier slice needed it, nothing in the |
| 38 | box ever wrote it, so every shipment the shop's own automation raised |
| 39 | carried a blank date and site_manifest, which keys on it, would have printed |
| 40 | an empty page for a morning's real work. An operator-typed date is never |
| 41 | overwritten: somebody backdating a parcel knows something this handler does |
| 42 | not. |
| 43 | |
| 44 | Missing settings do not cost anybody a shipment. If shop.stock_location is |
| 45 | unconfigured the parcel still ships, the order status still derives, and |
| 46 | the gap is reported in `warning` -- the same posture the payment-side |
| 47 | handler this one took the stock work over from has always had. |
| 48 | """ |
| 49 | |
| 50 | import os |
| 51 | from datetime import date |
| 52 | from decimal import Decimal, InvalidOperation |
| 53 | |
| 54 | import object_ids |
| 55 | import object_records |
| 56 | |
| 57 | HANDLES = [ |
| 58 | "shipments.record.created", |
| 59 | "shipments.record.updated", |
| 60 | "shipment_lines.record.created", |
| 61 | ] |
| 62 | |
| 63 | ACTOR = "system_order_fulfillment" |
| 64 | |
| 65 | # The box is with a courier or a customer: the goods have left the shelf. |
| 66 | SHIPPED_ONWARD = {"shipped", "in_transit", "delivered"} |
| 67 | |
| 68 | # Never reached the customer -- the order still owes those goods, so these |
| 69 | # shipments' lines count for nothing when deriving what has been fulfilled. |
| 70 | NOT_DELIVERED_STATUSES = {"lost", "returned_to_sender"} |
| 71 | |
| 72 | # An order in one of these is not something fulfillment may touch: a draft |
| 73 | # is not a commitment and a cancelled order must not quietly come back to |
| 74 | # life because somebody shipped against it by mistake. |
| 75 | UNTOUCHABLE_ORDER_STATUSES = {"draft", "cancelled"} |
| 76 | |
| 77 | |
| 78 | def _base_dir(): |
| 79 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 80 | |
| 81 | |
| 82 | def _text(value): |
| 83 | return str(value if value is not None else "").strip() |
| 84 | |
| 85 | |
| 86 | def _quantity(value): |
| 87 | """Decimal, never a bare float -- quantities may be fractional.""" |
| 88 | try: |
| 89 | return Decimal(_text(value) or "0") |
| 90 | except InvalidOperation: |
| 91 | return Decimal(0) |
| 92 | |
| 93 | |
| 94 | def _number(value): |
| 95 | return format(value.normalize(), "f") |
| 96 | |
| 97 | |
| 98 | def _setting(base, key, default=""): |
| 99 | """Duplicated on purpose, same as every other package that reads |
| 100 | app_settings: there is no shared settings module in this codebase yet, |
| 101 | and inventing one for a fourth copy is the layer this house rule |
| 102 | (docs/logic-decisions.md #4) says to wait on.""" |
| 103 | try: |
| 104 | for row in object_records.read_collection_records("app_settings", |
| 105 | base_dir=base): |
| 106 | if row.get("key") == key and _text(row.get("value")): |
| 107 | return _text(row["value"]) |
| 108 | except Exception: |
| 109 | pass |
| 110 | return default |
| 111 | |
| 112 | |
| 113 | def _shipment_for(request, base): |
| 114 | """The shipment this event is about, whichever collection fired it. |
| 115 | |
| 116 | A shipment_lines event names a line; the thing that matters is its |
| 117 | parent, because a line added to an already-shipped shipment is goods |
| 118 | that still have to leave the shelf. |
| 119 | |
| 120 | Both the record itself and a bare record_id are accepted: the HTTP |
| 121 | dispatcher and the change-log dispatcher both send record_id, while an |
| 122 | operator poking this by hand (or a sibling handler calling it in |
| 123 | process) has the row already. |
| 124 | """ |
| 125 | collection = _text(request.get("collection")) |
| 126 | record = request.get("record") |
| 127 | record_id = _text(request.get("record_id") or request.get("id")) |
| 128 | |
| 129 | if collection == "shipment_lines": |
| 130 | line = record if isinstance(record, dict) and record.get("id") else None |
| 131 | if line is None and record_id: |
| 132 | try: |
| 133 | line = object_records.get_collection_record( |
| 134 | "shipment_lines", record_id, base_dir=base) |
| 135 | except Exception: |
| 136 | return None |
| 137 | if not line: |
| 138 | return None |
| 139 | record_id = _text(line.get("shipment_id")) |
| 140 | record = None |
| 141 | |
| 142 | if isinstance(record, dict) and record.get("id") and collection != "shipment_lines": |
| 143 | # Re-read rather than trust the payload: an event carrying a stale |
| 144 | # copy (dispatched from the change log, minutes later) must not make |
| 145 | # this handler act on a status the shipment has since moved past. |
| 146 | record_id = _text(record.get("id")) |
| 147 | |
| 148 | if not record_id: |
| 149 | return None |
| 150 | try: |
| 151 | return object_records.get_collection_record("shipments", record_id, |
| 152 | base_dir=base) |
| 153 | except Exception: |
| 154 | return None |
| 155 | |
| 156 | |
| 157 | def _lines_of(base, shipment_id): |
| 158 | try: |
| 159 | rows = object_records.read_collection_records("shipment_lines", |
| 160 | base_dir=base) |
| 161 | except Exception: |
| 162 | return [] |
| 163 | return [row for row in rows if _text(row.get("shipment_id")) == shipment_id] |
| 164 | |
| 165 | |
| 166 | def _move_stock(base, shipment, order, moves): |
| 167 | """One sale move per line, idempotent per line by provenance marker. |
| 168 | |
| 169 | Returns (moved, skipped_reason). `moves` is the already-read stock_moves |
| 170 | log, or None when the collection does not exist at all (a shop selling |
| 171 | services and downloads has nothing to move and is not broken). |
| 172 | """ |
| 173 | if moves is None: |
| 174 | return 0, "stock not installed; nothing to move" |
| 175 | |
| 176 | # Drop-shipped goods never sat on our shelf. The vendor posted them |
| 177 | # straight to the customer, and the parcel is recorded here so the |
| 178 | # customer can be told and the order can complete -- but decrementing |
| 179 | # our own stock for it would invent a movement that never happened, |
| 180 | # and every count from then on would disagree with the room. |
| 181 | # |
| 182 | # `fulfillment_source` is read off the ORDER rather than the shipment |
| 183 | # because it is a property of how the sale is being met, not of one |
| 184 | # parcel: a part-drop-shipped order would still be answered honestly |
| 185 | # by splitting it into two orders, which is what the linked-order |
| 186 | # model already does. |
| 187 | if _text(order.get("fulfillment_source")) == "dropship": |
| 188 | return 0, "drop-shipped: the goods never touched our shelf" |
| 189 | |
| 190 | from_location = _setting(base, "shop.stock_location") |
| 191 | to_location = _setting(base, "shop.customer_location") |
| 192 | existing = [_text(move.get("reference")) for move in moves] |
| 193 | |
| 194 | moved = 0 |
| 195 | warning = "" |
| 196 | today = _text(shipment.get("shipped_on")) or date.today().isoformat() |
| 197 | for line in _lines_of(base, shipment["id"]): |
| 198 | product_id = _text(line.get("product_id")) |
| 199 | if not product_id: |
| 200 | continue # a service never sat on a shelf |
| 201 | marker = f"shipments/{shipment['id']}:line/{line['id']}" |
| 202 | if any(marker in reference for reference in existing): |
| 203 | continue # this line already moved |
| 204 | if not from_location: |
| 205 | warning = ("shop.stock_location is not configured, so nothing " |
| 206 | "left the shelf; the shipment still stands") |
| 207 | break |
| 208 | object_records.create_collection_record( |
| 209 | "stock_moves", |
| 210 | { |
| 211 | "id": object_ids.new_uuid4(), |
| 212 | "product_id": product_id, |
| 213 | "from_location_id": from_location, |
| 214 | "to_location_id": to_location, |
| 215 | "quantity": _text(line.get("quantity")) or "1", |
| 216 | "reason": "sale", |
| 217 | "reference": f"{marker} {_text(order.get('number'))}".strip(), |
| 218 | "occurred_at": today, |
| 219 | "owner_id": _text(shipment.get("owner_id")), |
| 220 | "entity_id": _text(shipment.get("entity_id")), |
| 221 | }, |
| 222 | base_dir=base, actor=ACTOR) |
| 223 | existing.append(marker) |
| 224 | moved += 1 |
| 225 | return moved, warning |
| 226 | |
| 227 | |
| 228 | def _derive_order_status(base, order): |
| 229 | """What the shipment lines say this order's status is. |
| 230 | |
| 231 | Returns "" when the facts say nothing yet (nothing shipped), so the |
| 232 | order is left exactly as a human last set it rather than being dragged |
| 233 | backwards by a machine that knows less than they do. |
| 234 | """ |
| 235 | try: |
| 236 | order_lines = [line for line in object_records.read_collection_records( |
| 237 | "order_lines", base_dir=base) |
| 238 | if _text(line.get("order_id")) == order["id"]] |
| 239 | except Exception: |
| 240 | return "" |
| 241 | if not order_lines: |
| 242 | return "" |
| 243 | |
| 244 | try: |
| 245 | shipments = [row for row in object_records.read_collection_records( |
| 246 | "shipments", base_dir=base) |
| 247 | if _text(row.get("order_id")) == order["id"] |
| 248 | and _text(row.get("direction")) != "inbound"] |
| 249 | except Exception: |
| 250 | return "" |
| 251 | |
| 252 | counted = {row["id"]: _text(row.get("status")) for row in shipments |
| 253 | if _text(row.get("status")) not in NOT_DELIVERED_STATUSES} |
| 254 | if not counted: |
| 255 | return "" |
| 256 | |
| 257 | shipped_lines = [line for line in _all_shipment_lines(base) |
| 258 | if counted.get(_text(line.get("shipment_id")), "") |
| 259 | in SHIPPED_ONWARD] |
| 260 | |
| 261 | shipped_by_line = {} |
| 262 | for line in shipped_lines: |
| 263 | key = _text(line.get("order_line_id")) |
| 264 | shipped_by_line[key] = shipped_by_line.get(key, Decimal(0)) + \ |
| 265 | _quantity(line.get("quantity")) |
| 266 | |
| 267 | total_shipped = sum(shipped_by_line.values(), Decimal(0)) |
| 268 | if total_shipped <= 0: |
| 269 | return "" |
| 270 | |
| 271 | everything = all( |
| 272 | shipped_by_line.get(line["id"], Decimal(0)) >= _quantity(line.get("quantity")) |
| 273 | for line in order_lines) |
| 274 | if not everything: |
| 275 | return "partial" |
| 276 | |
| 277 | # Everything is on a shipment that has left. "delivered" is the further |
| 278 | # claim that every one of those shipments arrived -- never inferred from |
| 279 | # "it has been a while", which is how systems learn to lie about parcels. |
| 280 | if all(status == "delivered" for status in counted.values()): |
| 281 | return "delivered" |
| 282 | return "shipped" |
| 283 | |
| 284 | |
| 285 | def _all_shipment_lines(base): |
| 286 | try: |
| 287 | return object_records.read_collection_records("shipment_lines", |
| 288 | base_dir=base) |
| 289 | except Exception: |
| 290 | return [] |
| 291 | |
| 292 | |
| 293 | def EVENT(request): |
| 294 | base = _base_dir() |
| 295 | shipment = _shipment_for(request, base) |
| 296 | if not shipment: |
| 297 | return {"ok": True, "skipped": "no shipment in the event"} |
| 298 | |
| 299 | if _text(shipment.get("direction")) == "inbound": |
| 300 | # A return has not decided whether it is restock or waste yet, and |
| 301 | # guessing would put damaged goods back on the shelf. The |
| 302 | # disposition flow is a later slice, deliberately absent. |
| 303 | return {"ok": True, "skipped": "inbound shipments are dispositioned " |
| 304 | "by hand, not by this handler", |
| 305 | "shipment_id": shipment["id"]} |
| 306 | |
| 307 | try: |
| 308 | order = object_records.get_collection_record( |
| 309 | "orders", _text(shipment.get("order_id")), base_dir=base) |
| 310 | except Exception: |
| 311 | return {"ok": True, "skipped": "no order for this shipment", |
| 312 | "shipment_id": shipment["id"]} |
| 313 | |
| 314 | order_status = _text(order.get("status")) |
| 315 | if order_status in UNTOUCHABLE_ORDER_STATUSES: |
| 316 | return {"ok": True, "skipped": f"order is {order_status}", |
| 317 | "shipment_id": shipment["id"], "order_id": order["id"]} |
| 318 | |
| 319 | result = {"ok": True, "shipment_id": shipment["id"], "order_id": order["id"], |
| 320 | "moved": 0} |
| 321 | |
| 322 | if _text(shipment.get("status")) in SHIPPED_ONWARD: |
| 323 | if not _text(shipment.get("shipped_on")): |
| 324 | # The handover date, stamped at the moment we observe the handover |
| 325 | # (docs/logic-decisions.md #1 -- a fact about a moment). Nothing |
| 326 | # stamped it before, which meant the field was blank on every |
| 327 | # shipment the shop's own automation raised, and a manifest keyed |
| 328 | # on it printed an empty page. Only when blank: an operator who |
| 329 | # typed a date knows something this handler does not, and a |
| 330 | # backdated shipment must keep the day it actually went. The write |
| 331 | # re-fires this handler once through the change dispatcher; the |
| 332 | # second pass finds the date set and the provenance markers |
| 333 | # already there, so it writes nothing and stops. |
| 334 | today = _text(request.get("today")) or date.today().isoformat() |
| 335 | try: |
| 336 | object_records.update_collection_record( |
| 337 | "shipments", shipment["id"], {"shipped_on": today}, |
| 338 | base_dir=base, actor=ACTOR) |
| 339 | shipment["shipped_on"] = today |
| 340 | result["shipped_on"] = today |
| 341 | except Exception as exc: |
| 342 | # The parcel still went; a date we could not write is a gap |
| 343 | # to see, not a shipment to refuse. |
| 344 | result["shipped_on_error"] = str(exc)[:200] |
| 345 | try: |
| 346 | moves = object_records.read_collection_records("stock_moves", |
| 347 | base_dir=base) |
| 348 | except Exception: |
| 349 | moves = None |
| 350 | moved, warning = _move_stock(base, shipment, order, moves) |
| 351 | result["moved"] = moved |
| 352 | if warning: |
| 353 | # The parcel stands and the gap is visible, which is the right |
| 354 | # way round: a missing setting must not cost a customer their |
| 355 | # goods, and an invisible discrepancy is the one nobody fixes. |
| 356 | result["warning"] = warning |
| 357 | |
| 358 | derived = _derive_order_status(base, order) |
| 359 | result["order_status"] = order_status |
| 360 | if derived and derived != order_status: |
| 361 | try: |
| 362 | object_records.update_collection_record( |
| 363 | "orders", order["id"], {"status": derived}, |
| 364 | base_dir=base, actor=ACTOR) |
| 365 | result["order_status"] = derived |
| 366 | result["order_status_changed"] = True |
| 367 | except Exception as exc: |
| 368 | # A ladder that refuses the derived move is a real answer, not a |
| 369 | # crash: say so and leave the order where a human put it. |
| 370 | result["order_status_error"] = str(exc)[:200] |
| 371 | return result |
| 372 | |
| 373 | |
| 374 | # EVENT is the verb the change dispatcher calls handlers with (see |
| 375 | # object_change_dispatch); POST stays as an alias so an operator can poke |
| 376 | # the handler by hand over HTTP. The alias is not decoration -- a handler |
| 377 | # shipped with only POST silently matched nothing in production once, and |
| 378 | # every handler in this house has carried both ever since. |
| 379 | POST = EVENT |