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
shipments.json · 13.6 KB · 187 lines
1{
2 "name": "shipments",
3 "title": "Shipments",
4 "version": 3,
5 "description": "What physically moved. An order says what is OWED; a shipment says what left the building -- when, in which box, with which tracking number -- and the two are different facts that small systems collapse into one status field and then cannot uncollapse. Partial fulfillment is the proof: it is not a flag on the order, it is a COUNT of shipments, and the order's status is DERIVED from shipment lines by system_order_fulfillment (docs/logic-decisions.md #1: the quantities are the facts, the order status is the read). Everything else the warehouse asks for falls out of this noun as a view -- a packing slip is one shipment printed, a manifest is today's shipments folded by carrier, a pick list is what is not on a shipment yet. ship_to_name/ship_to_address are STAMPED from the order at creation and never re-read: an address is what it was when the box left, and a customer who moves house next month must not silently rewrite where last month's parcel went. direction carries the return case (plan/fulfillment-logistics-spec.md): an RMA is this same document with the sign reversed, which is why there is no separate returns collection -- v2 lands the inbound half of the status ladder (authorized -> in_transit -> received -> dispositioned, plus expired), driven by app-returns' authorize and disposition actions. v3 adds the three honest fields the carrier-facing layer needs -- tracking_checked_at, tracking_attempts, tracking_error -- and adds nothing else, because carrier, service, tracking_number, tracking_status and label_file_id were already here waiting for something to fill them in. They are the same three fields scans carries for the same reason: a machine that talks to somebody else's system will sometimes get no answer, and the difference between 'nobody has asked yet', 'we asked and the carrier said nothing new' and 'we asked three times and this parcel cannot be read' is the difference between a queue that drains and a queue nobody trusts. What is deliberately still absent is a weight column: the manifest prints one when a deployment adds `weight` as an extra field, and inventing a schema field the packing bench has no scale for would only produce a column of blanks on a document a driver signs.",
6 "fields": [
7 {
8 "name": "id"
9 },
10 {
11 "name": "order_id",
12 "type": "relation",
13 "required": true,
14 "relation": {
15 "collection": "orders",
16 "display_field": "number"
17 },
18 "label": "Order",
19 "help": "The order this shipment is against, and the provenance link every derived status walks back along. Set once at creation and not intended to change after -- not schema read_only for the same reason order_lines.order_id is not: a required, client-submitted-at-creation field cannot also be read_only on this platform."
20 },
21 {
22 "name": "direction",
23 "type": "enum",
24 "label": "Direction",
25 "default": "outbound",
26 "enum": ["outbound", "inbound"],
27 "help": "outbound is goods leaving us; inbound is a customer return coming back (an RMA IS a shipment with the sign reversed, which is why there is no separate returns collection). system_order_fulfillment still skips inbound entirely, because a return that has not been dispositioned yet has not decided whether it is restock or waste, and guessing would put damaged goods back on the shelf; the decision -- and the only stock move a return ever composes -- belongs to app-returns' action_disposition_return, where a human names restock or dispose per line."
28 },
29 {
30 "name": "status",
31 "type": "enum",
32 "label": "Status",
33 "default": "open",
34 "enum": ["open", "packed", "shipped", "in_transit", "delivered", "returned_to_sender", "lost", "authorized", "received", "dispositioned", "expired"],
35 "transitions": {
36 "open": [
37 {"to": "packed", "when": {"owner_id": "$user_id"}}
38 ],
39 "packed": [
40 {"to": "shipped", "when": {"owner_id": "$user_id"}},
41 {"to": "open", "when": {"owner_id": "$user_id"}}
42 ],
43 "shipped": [
44 {"to": "in_transit", "when": {"owner_id": "$user_id"}},
45 {"to": "delivered", "when": {"owner_id": "$user_id"}},
46 {"to": "returned_to_sender", "when": {"owner_id": "$user_id"}},
47 {"to": "lost", "when": {"owner_id": "$user_id"}}
48 ],
49 "in_transit": [
50 {"to": "delivered", "when": {"owner_id": "$user_id"}},
51 {"to": "returned_to_sender", "when": {"owner_id": "$user_id"}},
52 {"to": "lost", "when": {"owner_id": "$user_id"}},
53 {"to": "received", "when": {"owner_id": "$user_id"}}
54 ],
55 "authorized": [
56 {"to": "in_transit", "when": {"owner_id": "$user_id"}},
57 {"to": "received", "when": {"owner_id": "$user_id"}},
58 {"to": "expired", "when": {"owner_id": "$user_id"}}
59 ],
60 "received": [
61 {"to": "dispositioned", "when": {"owner_id": "$user_id"}}
62 ]
63 },
64 "help": "ONE enum, two ladders, told apart by direction. OUTBOUND: open -> packed -> shipped -> in_transit -> delivered, and shipped -> delivered directly is deliberately allowed as well: a shop that hands parcels to a driver and never touches a tracking API would otherwise have to fake an in_transit it never observed, and fake precision is worse than a short ladder. packed -> open is the repacking move (the box was opened again before it left; nothing has physically happened yet, so nothing needs compensating). Nothing moves BACK from shipped: once it has left the dock the correction is a new document -- a return is an inbound shipment referencing this one, never an edit to this row (docs/logic-decisions.md #3). delivered, returned_to_sender and lost are terminal. Stock moves are composed when this reaches shipped, once per line, idempotent by provenance marker. INBOUND (an RMA, raised by action_authorize_return): authorized -> in_transit -> received -> dispositioned, with authorized -> received allowed directly for the customer who walks the goods into the shop and never posts anything, the same honesty the outbound shortcut buys. authorized means we granted the return and the goods are still with the customer; received means the parcel is on our dock and nobody has judged it yet; dispositioned means a human decided per line what each item is, which is the only moment a return moves stock or composes a refund (action_disposition_return). A RETURN THAT NEVER ARRIVES IS `expired`, NOT `lost`, and the distinction is not pedantry: `lost` is a claim about a parcel that was handed to a carrier and vanished -- it feeds carrier disputes and insurance, and a shop filtering on it is looking for money somebody owes them. An RMA the customer simply never posted is the opposite fact: nothing ever moved, nobody is at fault, and the OFFER lapsed at expires_on. Filing those under `lost` would salt the dispute list with parcels that never existed. A return genuinely lost IN THE POST still reaches `lost` the ordinary way, from in_transit, because by then there really was a parcel. There is deliberately no `cancelled`: this collection has never had one, an authorized RMA is an offer rather than a commitment, and `expired` already says what happens to an offer nobody takes up. Mixing the two ladders -- moving an outbound shipment to `received`, or an inbound one to `packed` -- is prevented by the OBJECTS, not by this enum: an enum cannot condition on a sibling field, so the transition map here is the union of both ladders and the guards live where they can see `direction` (action_disposition_return refuses anything not inbound-and-received, system_order_fulfillment skips inbound outright, system_return_posting skips outbound). Naming that here rather than letting a reader assume the enum is airtight is the point of this paragraph."
65 },
66 {
67 "name": "carrier",
68 "type": "text",
69 "label": "Carrier",
70 "validation": {"max_length": 100},
71 "help": "Free text on purpose. A carrier list is a connector's job (plan/fulfillment-logistics-spec.md's label boundary), and until credentials exist the honest field is the one the packer can type 'my brother-in-law's van' into."
72 },
73 {
74 "name": "service",
75 "type": "enum",
76 "label": "Service",
77 "default": "ground",
78 "enum": ["ground", "express", "freight", "pickup", "digital", "other"],
79 "help": "The carrier service level -- 'shipment types' in the warehouse's own words. pickup and digital are here because they are real fulfillment methods that never touch a carrier, and a shipment noun that could not express them would push those sales back into the untracked hand-wave the whole package exists to replace."
80 },
81 {
82 "name": "tracking_number",
83 "type": "text",
84 "label": "Tracking Number",
85 "validation": {"max_length": 120},
86 "help": "Typed by hand today; written by the label connector when one is configured. Manual-first is the point: the flow works fully without carrier credentials."
87 },
88 {
89 "name": "tracking_status",
90 "type": "text",
91 "label": "Tracking Status",
92 "validation": {"max_length": 200},
93 "help": "The carrier's own last words about this parcel, kept as text rather than folded into status: their vocabulary is theirs and changes without asking us, and mapping it into our enum is a decision the tracking poll makes explicitly (a later slice) rather than a coincidence of string equality."
94 },
95 {
96 "name": "label_file_id",
97 "type": "text",
98 "label": "Label File",
99 "help": "The label PDF, stored as a file the same way a scanned receipt is: evidence posture (docs/logic-decisions.md #8). Blank on every manual shipment, which is most of them. Written by action_buy_label -- with no carrier configured that action refuses and names the setting rather than inventing a label, and with carrier.provider=manual it stores the PDF the operator bought at the post office counter, because a label somebody paid for is evidence whoever printed it."
100 },
101 {
102 "name": "tracking_checked_at",
103 "type": "datetime",
104 "label": "Tracking Checked",
105 "help": "When system_tracking_poll last got an ANSWER out of the carrier -- not when it last tried. A parcel whose tracking has not been read for three days is a different fact from a parcel the carrier says has not moved for three days, and a field that conflated them would let a broken poll look like a stalled van."
106 },
107 {
108 "name": "tracking_attempts",
109 "type": "integer",
110 "default": "0",
111 "label": "Tracking Attempts",
112 "help": "Failed reads against THIS parcel, counted the way scans.attempts is: a shipment that keeps failing stops being polled and starts being visible, rather than churning a metered carrier API forever. Reset to 0 by a successful read. Deliberately NOT incremented when the host is the problem -- an unconfigured or unloadable provider declines the tick (the connector contract's `skip`), leaving the row untouched, because counting the shop's missing credentials against a parcel would quietly retire every shipment on the box while somebody was still fetching the API key."
113 },
114 {
115 "name": "tracking_error",
116 "type": "text",
117 "label": "Tracking Error",
118 "validation": {"max_length": 500},
119 "help": "What the carrier said when it could not answer, kept verbatim and short. The honest half of the attempt counter: a number saying a parcel failed three times is a mystery, and 'unknown tracking number' is a job."
120 },
121 {
122 "name": "ship_to_name",
123 "type": "text",
124 "label": "Ship To",
125 "validation": {"max_length": 200},
126 "help": "STAMPED from the order at creation, never re-read from the customer record. An address is what it was when the box left; re-deriving it would let somebody moving house rewrite where last month's parcel went (docs/logic-decisions.md #1)."
127 },
128 {
129 "name": "ship_to_address",
130 "type": "textarea",
131 "label": "Ship To Address",
132 "help": "Stamped, for the same reason as ship_to_name. Blank when the order carried no address field at all -- the storefront does not collect one yet, and a shipment that says nothing is honest where a shipment that invents a plausible address is not."
133 },
134 {
135 "name": "shipped_on",
136 "type": "date",
137 "label": "Shipped"
138 },
139 {
140 "name": "delivered_on",
141 "type": "date",
142 "label": "Delivered"
143 },
144 {
145 "name": "notes",
146 "type": "textarea",
147 "label": "Notes",
148 "help": "Also where the provenance marker lands ('Generated by action_create_shipment [orders/{id}]'), the same house pattern app-shop's checkout uses for the invoices it raises."
149 },
150 {
151 "name": "owner_id",
152 "type": "text",
153 "label": "Owner"
154 },
155 {
156 "name": "entity_id",
157 "type": "text",
158 "label": "Entity",
159 "relation": {
160 "collection": "entities",
161 "display_field": "name"
162 },
163 "help": "The set of books this belongs to (65 multi-entity). Optional during rollout, same posture as stock_moves.entity_id."
164 },
165 {
166 "name": "created_at",
167 "type": "datetime",
168 "label": "Created",
169 "read_only": true
170 }
171 ],
172 "forms": {
173 "default": {
174 "fields": ["order_id", "direction", "status", "carrier", "service",
175 "tracking_number", "ship_to_name", "ship_to_address",
176 "shipped_on", "delivered_on", "notes"]
177 }
178 },
179 "views": {
180 "list_mode": "table",
181 "list_fields": ["order_id", "status", "carrier", "tracking_number", "shipped_on"],
182 "filter_fields": ["status", "direction", "service"]
183 },
184 "search": {
185 "fields": ["tracking_number", "ship_to_name", "carrier"]
186 }
187}