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
orders.json · 23.1 KB · 423 lines
| 1 | { |
| 2 | "name": "orders", |
| 3 | "title": "Orders", |
| 4 | "version": 8, |
| 5 | "description": "Sales and purchase orders (doc_type on one shared schema, mirroring app-invoices' doc_type split). Lines live in order_lines; subtotal/tax/total are stamped by the order_totals handler, never typed by hand. Reconciled against a private predecessor-system audit, not part of this repo (its Order+Lines note: 'SO/PO; convert_to_invoice'). v4 carries the two fields a shopper types at checkout -- customer_note and gift_message -- because the packing slip is printed from the ORDER, not from the basket somebody abandoned on the way to it. v5 adds portal_token, the customer's own door: the shop sells to guests, so a buyer has no account to sign into and no way to ask 'where is my order?' without one. It is the same capability-URL shape invoices already use for /pay/{token}, and it is what finally lets a guest start a return. v6 is drop-shipping, and it is five fields rather than a new collection precisely because the shared SO/PO schema was the right call in v1: 'the vendor ships straight to my customer' is a SALE order and a PURCHASE order pointing at each other, which this collection could already almost express. fulfillment_source (stock | dropship, defaulting to stock so nothing existing changes meaning) is the fact every other package needs to know; linked_order_id is the counterpart, written both ways so either end answers on its own; vendor_id is who actually ships it; and ship_to_name/ship_to_address exist for the one case in this whole repo where the counterparty on a document and the destination of its goods are different people -- a drop-ship PO addressed to a vendor whose parcel goes to our customer. Margin needs no field at all, because both orders already carry money. v7 is TIME, and it is the whole of what a food business needed that a parcel business did not (plan/pickup-and-counter-service-spec.md): everything about the MONEY was already built and almost nothing about the time was, so this collection could say `shipped` and `delivered` and had no way at all to say 'ready at 6:15'. fulfillment_method (shipping | pickup | delivery | counter, defaulting to shipping so nothing existing changes meaning) is the field every downstream behaviour keys off. requested_at and promised_at are deliberately TWO fields -- what the customer asked for and what the business committed to -- because collapsing them hides every capacity failure the shop ever had. ready_at and collected_at are stamped as they happen and never predicted. The status enum grows preparing/ready/collected rather than reusing shipped/delivered, because a status a customer sees must use the customer's word and 'your order has shipped' about a sandwich is the kind of detail that makes software look borrowed; which subset of the ladder applies is decided by fulfillment_method IN THE OBJECTS, because an enum cannot condition on another field -- the same note shipments already carries for its inbound and outbound ladders.", |
| 6 | "fields": [ |
| 7 | { |
| 8 | "name": "id" |
| 9 | }, |
| 10 | { |
| 11 | "name": "doc_type", |
| 12 | "type": "enum", |
| 13 | "label": "Document Type", |
| 14 | "default": "sale", |
| 15 | "enum": [ |
| 16 | "sale", |
| 17 | "purchase" |
| 18 | ], |
| 19 | "help": "sale/purchase share this schema -- the real predecessor's SO/PO split, carried as one field the same way app-invoices folds invoice/credit_note/quote into doc_type." |
| 20 | }, |
| 21 | { |
| 22 | "name": "number", |
| 23 | "type": "text", |
| 24 | "required": true, |
| 25 | "label": "Number", |
| 26 | "help": "Human order number, e.g. SO-0001 or PO-0001. v1 is typed by the owner, not auto-assigned -- a sequenced counter + closed create route is a later slice, same deferral app-invoices documents for its own number field." |
| 27 | }, |
| 28 | { |
| 29 | "name": "customer_id", |
| 30 | "label": "Customer (contact)", |
| 31 | "relation": { |
| 32 | "collection": "contacts", |
| 33 | "display_field": "first_name" |
| 34 | }, |
| 35 | "help": "Optional cross-reference only. The snapshot fields below are what every surface renders -- editing the contact later never rewrites an already-placed order. Same snapshot decision as app-invoices' customer_id." |
| 36 | }, |
| 37 | { |
| 38 | "name": "customer_name", |
| 39 | "type": "text", |
| 40 | "required": true, |
| 41 | "label": "Customer", |
| 42 | "validation": { |
| 43 | "min_length": 1, |
| 44 | "max_length": 200 |
| 45 | } |
| 46 | }, |
| 47 | { |
| 48 | "name": "customer_email", |
| 49 | "type": "text", |
| 50 | "label": "Customer Email", |
| 51 | "validation": { |
| 52 | "max_length": 254 |
| 53 | } |
| 54 | }, |
| 55 | { |
| 56 | "name": "currency", |
| 57 | "type": "text", |
| 58 | "default": "USD", |
| 59 | "label": "Currency (ISO 4217)", |
| 60 | "validation": { |
| 61 | "pattern": "^[A-Z]{3}$" |
| 62 | } |
| 63 | }, |
| 64 | { |
| 65 | "name": "status", |
| 66 | "type": "enum", |
| 67 | "label": "Status", |
| 68 | "default": "draft", |
| 69 | "enum": [ |
| 70 | "draft", |
| 71 | "confirmed", |
| 72 | "processing", |
| 73 | "partial", |
| 74 | "shipped", |
| 75 | "delivered", |
| 76 | "received", |
| 77 | "preparing", |
| 78 | "ready", |
| 79 | "collected", |
| 80 | "cancelled" |
| 81 | ], |
| 82 | "transitions": { |
| 83 | "draft": [ |
| 84 | { |
| 85 | "to": "confirmed", |
| 86 | "when": { |
| 87 | "owner_id": "$user_id" |
| 88 | } |
| 89 | }, |
| 90 | { |
| 91 | "to": "cancelled", |
| 92 | "when": { |
| 93 | "owner_id": "$user_id" |
| 94 | } |
| 95 | } |
| 96 | ], |
| 97 | "confirmed": [ |
| 98 | { |
| 99 | "to": "processing", |
| 100 | "when": { |
| 101 | "owner_id": "$user_id" |
| 102 | } |
| 103 | }, |
| 104 | { |
| 105 | "to": "partial", |
| 106 | "when": { |
| 107 | "owner_id": "$user_id" |
| 108 | } |
| 109 | }, |
| 110 | { |
| 111 | "to": "shipped", |
| 112 | "when": { |
| 113 | "owner_id": "$user_id" |
| 114 | } |
| 115 | }, |
| 116 | { |
| 117 | "to": "received", |
| 118 | "when": { |
| 119 | "owner_id": "$user_id" |
| 120 | } |
| 121 | }, |
| 122 | { |
| 123 | "to": "preparing", |
| 124 | "when": { |
| 125 | "owner_id": "$user_id" |
| 126 | } |
| 127 | }, |
| 128 | { |
| 129 | "to": "ready", |
| 130 | "when": { |
| 131 | "owner_id": "$user_id" |
| 132 | } |
| 133 | }, |
| 134 | { |
| 135 | "to": "cancelled", |
| 136 | "when": { |
| 137 | "owner_id": "$user_id" |
| 138 | } |
| 139 | } |
| 140 | ], |
| 141 | "processing": [ |
| 142 | { |
| 143 | "to": "partial", |
| 144 | "when": { |
| 145 | "owner_id": "$user_id" |
| 146 | } |
| 147 | }, |
| 148 | { |
| 149 | "to": "shipped", |
| 150 | "when": { |
| 151 | "owner_id": "$user_id" |
| 152 | } |
| 153 | }, |
| 154 | { |
| 155 | "to": "received", |
| 156 | "when": { |
| 157 | "owner_id": "$user_id" |
| 158 | } |
| 159 | }, |
| 160 | { |
| 161 | "to": "cancelled", |
| 162 | "when": { |
| 163 | "owner_id": "$user_id" |
| 164 | } |
| 165 | } |
| 166 | ], |
| 167 | "partial": [ |
| 168 | { |
| 169 | "to": "shipped", |
| 170 | "when": { |
| 171 | "owner_id": "$user_id" |
| 172 | } |
| 173 | }, |
| 174 | { |
| 175 | "to": "received", |
| 176 | "when": { |
| 177 | "owner_id": "$user_id" |
| 178 | } |
| 179 | }, |
| 180 | { |
| 181 | "to": "cancelled", |
| 182 | "when": { |
| 183 | "owner_id": "$user_id" |
| 184 | } |
| 185 | } |
| 186 | ], |
| 187 | "shipped": [ |
| 188 | { |
| 189 | "to": "delivered", |
| 190 | "when": { |
| 191 | "owner_id": "$user_id" |
| 192 | } |
| 193 | } |
| 194 | ], |
| 195 | "preparing": [ |
| 196 | { |
| 197 | "to": "ready", |
| 198 | "when": { |
| 199 | "owner_id": "$user_id" |
| 200 | } |
| 201 | }, |
| 202 | { |
| 203 | "to": "cancelled", |
| 204 | "when": { |
| 205 | "owner_id": "$user_id" |
| 206 | } |
| 207 | } |
| 208 | ], |
| 209 | "ready": [ |
| 210 | { |
| 211 | "to": "collected", |
| 212 | "when": { |
| 213 | "owner_id": "$user_id" |
| 214 | } |
| 215 | }, |
| 216 | { |
| 217 | "to": "cancelled", |
| 218 | "when": { |
| 219 | "owner_id": "$user_id" |
| 220 | } |
| 221 | } |
| 222 | ] |
| 223 | }, |
| 224 | "help": "delivered, received and cancelled are terminal. Every other move requires the order owner. Matches the real order lifecycle (reconciled against a private predecessor-system audit, not part of this repo): draft->confirmed/cancelled, confirmed->processing/cancelled, processing->shipped/cancelled, shipped->delivered. v2 adds `partial`, and it is MACHINE-DERIVED: system_order_fulfillment (app-shipping) folds shipment lines against ordered quantities and stamps partial when some but not all of what was ordered is on a shipment that has left, shipped when all of it is, delivered when every one of those shipments arrived. Never hand-set -- typing partial into this field claims a fact about boxes that no box supports, and the next derivation pass will disagree with you. confirmed->shipped is allowed alongside confirmed->partial for the same reason: the zero-touch shop (app-shop's auto_fulfill) ships a whole order the moment it is paid for and never passes through processing, and forcing a bookkeeping hop nobody performed would leave paid, shipped orders sitting at confirmed forever. v3 adds `received`, the PURCHASE side's terminal state, also machine-derived: system_receipt_posting (app-receiving) folds receipt lines against ordered quantities and stamps partial when some of what was ordered has turned up on the dock and received when all of it has. It is a new value rather than a reuse of `delivered` because this enum is shared by SO and PO (doc_type), and `delivered` on a purchase order reads as a claim about something WE sent -- in a status-filtered list, where doc_type is two columns away, that is actively misleading. `received` can only ever mean one thing in either direction: the goods turned up HERE. `partial` is therefore shared by both sides and means the same thing on both -- some of what this document promised has physically moved -- which is the point of one shared lifecycle rather than two. v7 adds `preparing`, `ready` and `collected`: the PICKUP ladder, confirmed -> preparing -> ready -> collected, with confirmed -> ready allowed directly for the same reason confirmed -> shipped is (a counter that makes the coffee while the customer is standing there never passes through a `preparing` anybody observed, and fake precision is worse than a short ladder), and preparing/ready -> cancelled for the customer who calls back or never turns up. `collected` is terminal, like `delivered` and `received`. WHICH SUBSET OF THIS ENUM BELONGS TO AN ORDER IS DECIDED BY fulfillment_method, IN THE OBJECTS, NOT HERE: shipping and dropship orders use draft/confirmed/processing/partial/shipped/delivered, purchase orders use draft/confirmed/processing/partial/received, and pickup, delivery and counter orders use draft/confirmed/preparing/ready/collected. The enum holds all of them because an enum cannot condition on another field -- exactly the note `shipments` already carries about its own inbound and outbound ladders sharing one status column. They are NEW values rather than a reuse of shipped/delivered because a status a customer reads must use the customer's word: 'your order has shipped' about a sandwich waiting on a counter is the kind of detail that makes software look borrowed, and site_order_status translates each of these into 'Being prepared' / 'Ready for collection' / 'Collected'." |
| 225 | }, |
| 226 | { |
| 227 | "name": "order_date", |
| 228 | "type": "date", |
| 229 | "label": "Order Date" |
| 230 | }, |
| 231 | { |
| 232 | "name": "expected_date", |
| 233 | "type": "date", |
| 234 | "label": "Expected Date" |
| 235 | }, |
| 236 | { |
| 237 | "name": "subtotal_cents", |
| 238 | "type": "integer", |
| 239 | "default": "0", |
| 240 | "label": "Subtotal (cents)", |
| 241 | "help": "Stamped by the order_totals handler: sum of every line's line_total_cents. Never user-entered -- not schema read_only for the same reason invoice_totals' fields aren't; see objects/system/order_totals.py's module docstring." |
| 242 | }, |
| 243 | { |
| 244 | "name": "tax_cents", |
| 245 | "type": "integer", |
| 246 | "default": "0", |
| 247 | "label": "Tax (cents)", |
| 248 | "help": "Stamped by order_totals: sum of every line's line_tax_cents (line_total_cents * tax_rate_bps // 10000, floored)." |
| 249 | }, |
| 250 | { |
| 251 | "name": "total_cents", |
| 252 | "type": "integer", |
| 253 | "default": "0", |
| 254 | "label": "Total (cents)", |
| 255 | "help": "Stamped by order_totals: subtotal_cents + tax_cents." |
| 256 | }, |
| 257 | { |
| 258 | "name": "invoice_id", |
| 259 | "type": "text", |
| 260 | "label": "Converted Invoice", |
| 261 | "help": "Provenance link recorded once this order has been converted to an invoice (real predecessor's convert_to_invoice). The conversion ACTION itself is deferred -- not built in this slice -- but the field is kept now so a future convert-to-invoice flow has somewhere to write without a backfill." |
| 262 | }, |
| 263 | { |
| 264 | "name": "portal_token", |
| 265 | "type": "text", |
| 266 | "label": "Tracking Token", |
| 267 | "read_only": true, |
| 268 | "help": "The customer's capability URL for this one order: /orders/track/{token}, rendered by site_order_status. Unguessable (secrets.token_urlsafe), minted by action_checkout while the shopper is still standing there and by system_order_portal_link for every other non-draft order, and looked up BY TOKEN ONLY with a constant-time compare so a guessed order id opens nothing. read_only exactly as invoices.portal_token is: a capability URL a client can choose is not a capability, so only a server-side writer passing preserve_read_only may set it. Kept out of forms.default, list_fields and search for the same reason -- a bearer token that turns up in a list response has already leaked." |
| 269 | }, |
| 270 | { |
| 271 | "name": "fulfillment_source", |
| 272 | "type": "enum", |
| 273 | "label": "Fulfilled From", |
| 274 | "default": "stock", |
| 275 | "enum": [ |
| 276 | "stock", |
| 277 | "dropship" |
| 278 | ], |
| 279 | "help": "Where the goods for this order physically come from. `stock` is the default and means our own shelf -- so nothing that existed before v6 changes meaning by gaining this field, the same argument billing_mode and fulfillment_method make in their own packages. `dropship` says the vendor ships straight to the customer: the goods never touch our shelf, receiving is skipped because there is nothing to receive, and OUR STOCK MUST NEVER MOVE against this order. That last sentence is the whole reason this is a stored field on the order rather than a fact derived from the existence of a linked purchase order -- a derived answer would be computed differently by every handler that needed it, and the one that got it wrong would quietly decrement a shelf that never held the goods. It is set by action_dropship_order on BOTH orders (the sale order and the purchase order it spawns), so either document answers the question on its own without walking the link. NOTE, because it is the honest half: system_order_fulfillment (app-shipping) does not read this field yet, so a shipment raised against a drop-ship sale order still composes a `sale` stock move. The data is here for it to read; the read is a required follow-up in a package the disputes/drop-ship slice does not own, and tests/test_dropship.py holds it as a strict xfail so it cannot be forgotten." |
| 280 | }, |
| 281 | { |
| 282 | "name": "linked_order_id", |
| 283 | "type": "text", |
| 284 | "label": "Linked Order", |
| 285 | "validation": { |
| 286 | "max_length": 64 |
| 287 | }, |
| 288 | "help": "The counterpart document: on a drop-ship SALE order, the purchase order it spawned; on that purchase order, the sale order it serves. Linked both ways at creation so either end answers 'what is the other half of this?' without a scan, and so margin is a read over two rows rather than a join nobody maintains. Deliberately ONE meaning: it is tempting to reuse this for a replacement order, an amended order or a converted quote, and every one of those would make the field unreadable by a gate -- app-disputes raises its replacement orders with provenance in `notes` instead, precisely so this field keeps meaning exactly one thing. Plain text rather than a relation to `orders` for the same reason invoice_id is: a self-referential relation on the collection that seeds itself is a chicken-and-egg the loader does not need to solve to make this link work." |
| 289 | }, |
| 290 | { |
| 291 | "name": "vendor_id", |
| 292 | "type": "text", |
| 293 | "label": "Vendor", |
| 294 | "validation": { |
| 295 | "max_length": 64 |
| 296 | }, |
| 297 | "help": "Who ships it, on a drop-ship pair -- carried on both orders so the sale order can answer 'who is actually sending this?' without opening the PO. Plain text and NOT a relation, which is a deliberate choice rather than laziness: a vendor in this repo may be a contact, an organization, or neither (a supplier somebody bought from once and never filed), and a relation to any one of those three collections would refuse the other two. The PO's own customer_name still carries the vendor's name the way every purchase order here already does, so nothing downstream has to learn a new field to print a document." |
| 298 | }, |
| 299 | { |
| 300 | "name": "ship_to_name", |
| 301 | "type": "text", |
| 302 | "label": "Ship To", |
| 303 | "validation": { |
| 304 | "max_length": 200 |
| 305 | }, |
| 306 | "help": "Where this order's goods are going, when that is NOT the counterparty named on it. On an ordinary sale order it is blank and every surface reads customer_name, which is the same person -- the field would be a duplicate with a chance to disagree. The one place they genuinely differ is a drop-ship purchase order, where the counterparty is the vendor and the destination is somebody else's customer entirely, and a PO that cannot say that is a PO the vendor cannot fulfill. That is the whole reason the field exists, and it is why it is optional and blank almost everywhere." |
| 307 | }, |
| 308 | { |
| 309 | "name": "ship_to_address", |
| 310 | "type": "textarea", |
| 311 | "label": "Ship To Address", |
| 312 | "help": "The delivery address, for the same reason and in the same one case. app-shipping's action_create_shipment already reads orders.ship_to_address when stamping a shipment (it has looked for this field since the shipments slice, against the day the storefront collects an address), so filling it in here needs no change there. ship_to_name is the half app-shipping does not read yet -- it stamps a shipment's ship_to_name from customer_name -- which is a small, named follow-up in a package this slice does not own, not a reason to leave the address homeless." |
| 313 | }, |
| 314 | { |
| 315 | "name": "fulfillment_method", |
| 316 | "type": "enum", |
| 317 | "label": "Fulfilment Method", |
| 318 | "default": "shipping", |
| 319 | "enum": [ |
| 320 | "shipping", |
| 321 | "pickup", |
| 322 | "delivery", |
| 323 | "counter" |
| 324 | ], |
| 325 | "help": "How this order reaches the customer. `shipping` is the default and means a carrier takes it, so NOTHING THAT EXISTED BEFORE v7 CHANGES MEANING by gaining this field -- the same argument billing_mode and fulfillment_source already make in their own packages, and the reason a food slice could be added to a parcel system without restating a single old row. `pickup` is the customer collecting it themselves at a promised time; `delivery` is us driving it (no dispatch layer, and deliberately none -- drivers, routes and live tracking are a different product); `counter` is an order taken and completed at once, face to face. Every downstream behaviour keys off this, which is exactly why it is a STATED field rather than one inferred from whether a shipment or a slot exists: a derived answer would be computed differently by every handler that needed it, and the one that got it wrong would apply a pickup rule to somebody's parcel. It is also what decides WHICH SUBSET of the status enum an order may climb -- see status's own help -- because an enum cannot condition on another field, so the objects do it instead." |
| 326 | }, |
| 327 | { |
| 328 | "name": "requested_at", |
| 329 | "type": "datetime", |
| 330 | "label": "Requested For", |
| 331 | "help": "When the CUSTOMER asked to have it. Kept apart from promised_at, always, because the two differ and the difference is the business's problem: 'you wanted 6:00, we said 6:20' is a fact worth keeping, and one field holding whichever of them was written last hides every capacity failure the shop has ever had. A shop that cannot see it turned twenty people away from a 6pm slot has no way to learn it needs a bigger 6pm. Blank on a shipping order, where nobody asked for a time." |
| 332 | }, |
| 333 | { |
| 334 | "name": "promised_at", |
| 335 | "type": "datetime", |
| 336 | "label": "Promised For", |
| 337 | "help": "When the BUSINESS committed to have it ready. Stamped at checkout from the slot the shopper chose (app-shop's action_checkout writes the slot's start, because the start is the moment the customer will turn up), and it is the clock every pickup surface reads: the kitchen queue sorts by it, and app-pickup's attention provider counts the orders that are past it and not ready. Never derived from requested_at and never quietly equal to it -- see requested_at." |
| 338 | }, |
| 339 | { |
| 340 | "name": "ready_at", |
| 341 | "type": "datetime", |
| 342 | "label": "Ready At", |
| 343 | "help": "When it actually became ready, stamped as it happens and NEVER predicted. promised_at is the commitment; this is the observation, and the gap between them is the only honest measure of whether the promise was any good. A predicted ready_at would make that measurement always read zero." |
| 344 | }, |
| 345 | { |
| 346 | "name": "collected_at", |
| 347 | "type": "datetime", |
| 348 | "label": "Collected At", |
| 349 | "help": "When the customer actually took it away. Same posture as ready_at: an observation, stamped when it happens. Together the four times say what was asked for, what was promised, what happened, and when it ended -- which is the whole of what a scheduling business needs and none of what a parcel business ever had a field for." |
| 350 | }, |
| 351 | { |
| 352 | "name": "customer_note", |
| 353 | "type": "textarea", |
| 354 | "label": "Special Instructions", |
| 355 | "help": "What the shopper needs the PACKER to know -- leave it with the neighbour, do not ring the bell, this one is fragile. Stamped from the basket at checkout and printed on the packing slip and pick list, because the picker and the packer are the only people it is any use to. Distinct from `notes`, which is the shop talking to itself: merging them would print an internal remark into a stranger's parcel." |
| 356 | }, |
| 357 | { |
| 358 | "name": "gift_message", |
| 359 | "type": "textarea", |
| 360 | "label": "Gift Message", |
| 361 | "help": "Printed on the packing slip when present. There is no gift FLAG and there need not be one: the slip carries no prices by construction, so every parcel is already gift-safe, and a flag somebody forgets to tick is exactly how a present arrives with the amount paid stapled to it." |
| 362 | }, |
| 363 | { |
| 364 | "name": "notes", |
| 365 | "type": "textarea", |
| 366 | "label": "Notes" |
| 367 | }, |
| 368 | { |
| 369 | "name": "owner_id", |
| 370 | "type": "text", |
| 371 | "label": "Owner" |
| 372 | }, |
| 373 | { |
| 374 | "name": "created_at", |
| 375 | "type": "datetime", |
| 376 | "label": "Created", |
| 377 | "read_only": true |
| 378 | } |
| 379 | ], |
| 380 | "forms": { |
| 381 | "default": { |
| 382 | "fields": [ |
| 383 | "doc_type", |
| 384 | "number", |
| 385 | "customer_id", |
| 386 | "customer_name", |
| 387 | "customer_email", |
| 388 | "currency", |
| 389 | "order_date", |
| 390 | "expected_date", |
| 391 | "status", |
| 392 | "fulfillment_method", |
| 393 | "notes" |
| 394 | ] |
| 395 | } |
| 396 | }, |
| 397 | "views": { |
| 398 | "list_mode": "table", |
| 399 | "list_fields": [ |
| 400 | "number", |
| 401 | "customer_name", |
| 402 | "status", |
| 403 | "total_cents", |
| 404 | "expected_date" |
| 405 | ], |
| 406 | "filter_fields": [ |
| 407 | "status", |
| 408 | "doc_type", |
| 409 | "fulfillment_source", |
| 410 | "fulfillment_method" |
| 411 | ] |
| 412 | }, |
| 413 | "search": { |
| 414 | "fields": [ |
| 415 | "number", |
| 416 | "customer_name" |
| 417 | ] |
| 418 | }, |
| 419 | "capabilities": { |
| 420 | "comments": true, |
| 421 | "attachments": true |
| 422 | } |
| 423 | } |