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
order_fulfillment.py · 15.8 KB · 379 lines
1"""system_order_fulfillment -- the box left, so the shelf is lighter and
2the order says so.
3
4HANDLES shipments and shipment_lines writes. Two jobs, both of them reads
5turned into facts:
6
7**Stock moves when goods physically move.** One `sale` move PER SHIPMENT
8LINE at the moment a shipment reaches `shipped`, from shop.stock_location
9to shop.customer_location. Per line rather than per shipment because a
10level is a fold over moves per product, and per order rather than per
11line was only ever right while an order could not be split -- the whole
12point of the shipment noun is that it can.
13
14**The order's status is derived, never set.** Some of the ordered quantity
15on shipped-or-beyond shipments is `partial`; all of it is `shipped`; all of
16it delivered is `delivered` (docs/logic-decisions.md #1: the QUANTITIES on
17shipment lines are the facts, the order's status is a read of them). A
18human never types `partial` and no surface computes it at read time; it is
19stored, so the order list, the pick list and a report cannot disagree.
20
21Placement follows docs/logic-decisions.md #6 -- a REACTION, post-commit,
22best-effort, never blocking the write that triggered it. A warehouse that
23cannot record a stock move must still be able to send the parcel; the
24discrepancy is visible and fixable, whereas a refused shipment is a
25customer waiting for goods that are sitting in a box by the door.
26
27Idempotency by provenance (#7): each move is stamped
28`shipments/{shipment_id}:line/{line_id}` in its reference, PER LINE. A
29replayed event -- and events are replayed here, by design: the change
30dispatcher promises at-least-once (object_change_dispatch.py) -- finds its
31own marker and moves nothing. Per line and not per shipment because a
32shipment can gain a line while still open, and a shipment-level marker
33would 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
36shipment reaching `shipped` IS the handover, so shipped_on is a fact about
37that moment (#1) -- and until the carrier slice needed it, nothing in the
38box ever wrote it, so every shipment the shop's own automation raised
39carried a blank date and site_manifest, which keys on it, would have printed
40an empty page for a morning's real work. An operator-typed date is never
41overwritten: somebody backdating a parcel knows something this handler does
42not.
43
44Missing settings do not cost anybody a shipment. If shop.stock_location is
45unconfigured the parcel still ships, the order status still derives, and
46the gap is reported in `warning` -- the same posture the payment-side
47handler this one took the stock work over from has always had.
48"""
49
50import os
51from datetime import date
52from decimal import Decimal, InvalidOperation
53
54import object_ids
55import object_records
56
57HANDLES = [
58 "shipments.record.created",
59 "shipments.record.updated",
60 "shipment_lines.record.created",
61]
62
63ACTOR = "system_order_fulfillment"
64
65# The box is with a courier or a customer: the goods have left the shelf.
66SHIPPED_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.
70NOT_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.
75UNTOUCHABLE_ORDER_STATUSES = {"draft", "cancelled"}
76
77
78def _base_dir():
79 return os.environ.get("DBBASIC_DATA_DIR", "data")
80
81
82def _text(value):
83 return str(value if value is not None else "").strip()
84
85
86def _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
94def _number(value):
95 return format(value.normalize(), "f")
96
97
98def _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
113def _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
157def _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
166def _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
228def _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
285def _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
293def 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.
379POST = EVENT