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
shipment_attention.py · 3.9 KB · 113 lines
| 1 | """system_shipment_attention -- how many parcels stopped moving. |
| 2 | |
| 3 | COUNT {} -> {count, detail} |
| 4 | |
| 5 | A parcel that has been `in_transit` for longer than a fortnight is a |
| 6 | customer about to write in, and the shop nearly always finds out from the |
| 7 | customer rather than from the system. That asymmetry is the whole reason |
| 8 | this count exists: the facts were already on the shipment (the carrier's |
| 9 | own status, the day it was handed over, the day it was last read), and |
| 10 | nothing was folding them into the one sentence somebody can act on. |
| 11 | |
| 12 | `in_transit` and nothing else, deliberately. `shipped` means we handed it |
| 13 | over and have heard nothing since -- for a manual shop that is EVERY parcel |
| 14 | forever, and a band that is permanently lit is a band nobody reads. |
| 15 | `in_transit` is the stronger fact: a carrier told us this parcel was moving, |
| 16 | and then it stopped. `delivered`, `lost` and `returned_to_sender` have all |
| 17 | had an answer, even if it was a bad one. |
| 18 | |
| 19 | Age is measured from shipped_on -- the handover, stamped when the shipment |
| 20 | reaches `shipped` -- because that is the clock the customer is counting too. |
| 21 | A row with no handover date is not counted: "we do not know when this left" |
| 22 | is not a claim that it is late, and a queue padded with parcels whose age |
| 23 | nobody knows is a queue that gets ignored. |
| 24 | |
| 25 | Severity `warning` rather than `normal` in the manifest: unlike a receipt |
| 26 | waiting to be confirmed, nobody chose to put this here, and the clock is |
| 27 | running somewhere else -- in a customer's inbox. |
| 28 | |
| 29 | The threshold is one setting, `carrier.stuck_days`, default 10. Ten days is |
| 30 | long enough that ordinary ground post in a large country is not flagged and |
| 31 | short enough to beat the email. |
| 32 | |
| 33 | Degrades to zero when shipments is absent (a deployment without app-shipping |
| 34 | installed) rather than raising, the same posture system_scan_attention takes, |
| 35 | because the pass should not log an error every five minutes about an app |
| 36 | nobody installed. |
| 37 | """ |
| 38 | |
| 39 | import os |
| 40 | from datetime import date |
| 41 | |
| 42 | import object_records |
| 43 | |
| 44 | ACTOR = "system_shipment_attention" |
| 45 | |
| 46 | # The one status that means a carrier said it was moving and then stopped. |
| 47 | WAITING_STATUS = "in_transit" |
| 48 | |
| 49 | DEFAULT_STUCK_DAYS = 10 |
| 50 | |
| 51 | |
| 52 | def _base_dir(): |
| 53 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 54 | |
| 55 | |
| 56 | def _text(value): |
| 57 | return str(value if value is not None else "").strip() |
| 58 | |
| 59 | |
| 60 | def _setting(base, key, default=""): |
| 61 | """Duplicated on purpose, same as every other package that reads |
| 62 | app_settings (docs/logic-decisions.md #4).""" |
| 63 | try: |
| 64 | for row in object_records.read_collection_records("app_settings", |
| 65 | base_dir=base): |
| 66 | if row.get("key") == key and _text(row.get("value")): |
| 67 | return _text(row["value"]) |
| 68 | except Exception: |
| 69 | pass |
| 70 | return default |
| 71 | |
| 72 | |
| 73 | def _days_since(value, today): |
| 74 | """Whole days since a YYYY-MM-DD date, or None when it will not parse. |
| 75 | |
| 76 | A hand-typed or empty shipped_on returns None and the row is skipped |
| 77 | rather than counted at age zero: an unreadable date must not silently |
| 78 | become evidence that a parcel is fine. |
| 79 | """ |
| 80 | try: |
| 81 | return (today - date.fromisoformat(_text(value))).days |
| 82 | except ValueError: |
| 83 | return None |
| 84 | |
| 85 | |
| 86 | def COUNT(request): |
| 87 | base = _base_dir() |
| 88 | try: |
| 89 | rows = object_records.read_collection_records("shipments", base_dir=base) |
| 90 | except Exception: |
| 91 | return {"count": 0} |
| 92 | |
| 93 | try: |
| 94 | limit = int(_setting(base, "carrier.stuck_days", str(DEFAULT_STUCK_DAYS))) |
| 95 | except ValueError: |
| 96 | limit = DEFAULT_STUCK_DAYS |
| 97 | |
| 98 | today = date.today() |
| 99 | ages = [] |
| 100 | for row in rows: |
| 101 | if _text(row.get("direction")) == "inbound": |
| 102 | continue |
| 103 | if _text(row.get("status")) != WAITING_STATUS: |
| 104 | continue |
| 105 | age = _days_since(row.get("shipped_on"), today) |
| 106 | if age is None or age < limit: |
| 107 | continue |
| 108 | ages.append(age) |
| 109 | |
| 110 | if not ages: |
| 111 | return {"count": 0} |
| 112 | return {"count": len(ages), |
| 113 | "detail": f"oldest {max(ages)} days out"} |