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
dbbasic-package.json · 11.9 KB · 175 lines
| 1 | { |
| 2 | "id": "app-catalog", |
| 3 | "name": "Catalog", |
| 4 | "version": "0.8.0", |
| 5 | "description": "Product catalog + STOCK: owner-scoped CRUD on products, locations, and stock_moves. Money is integer cents (price_cents/cost_cents/salvage_value_cents/unit_cost_cents), never a float or currency type. Locations are a self-parent hierarchy (warehouse->zone->aisle->shelf->bin) plus virtual customer/supplier/virtual counterparties, reconciled against a private predecessor-system catalog audit, not part of this repo (its Location model: 'warehouse->bin hierarchy + virtual customer/supplier'). stock_moves is an append-mode, immutable ledger (docs/append-only-storage-design.md) -- stock LEVELS are never stored, only derived by folding the log (see object_stock.py at the repo root, imported by objects/site/stock.py the same way app-orders' order_totals.py imports object_records), matching the source model's own 'StockMove immutable, levels DERIVED not stored.' /stock computes its owner-scoped summary server-side rather than adding a new API endpoint -- see objects/site/stock.py's own module docstring for why. Deferred to a later slice: orders/invoices wiring a stock_moves row on ship/receive (the source's own WEAK note: 'order confirm/deliver does NOT create StockMoves'), the actual finance-account linkage / depreciation-schedule behavior behind income_account/expense_account/the ASSET fields (carried as plain fields now so nothing needs a backfill later), and a public storefront view (products stay owner-scoped, same posture as app-invoices). The /products/{product_id:uuid} permalink is a seeded 59 detail view (site_view_render) with an owner-aware editable/deletable detail block -- no bespoke per-product page. 0.5.0 deletes the bespoke /products and /locations list page objects too: both were ~85-90 lines of chrome around two generator calls with no business logic of their own, and are now seeded VIEW records over the same `list` block the product detail's own retrofit already established the precedent for. 0.6.0 is merchandising, and it is four fields and no new machinery: category, parent_product_id, options and image_file_id. The decision worth writing down is that A VARIANT IS A PRODUCT. A size or a colour gets its own products row -- own SKU, own price_cents, own stock level -- with parent_product_id naming the row it displays under and options ({\"size\": \"M\", \"colour\": \"navy\"}) saying what it is. stock_moves, pricing, checkout, fulfillment and system_stock_books ALL key on product_id today, so variants-as-products means every one of them keeps working with zero changes, and \"how many medium navy totes are left?\" is answered by the same fold that answers every other stock question, on the same ledger, with no special case. The alternative -- a variants table hanging under one product, which is the model most platforms ship -- gives every integration a products-vs-variants split personality, two ids for one sellable thing, and a stock report that cannot answer the question anybody actually asks. The whole cost of the decision lands in one place, the shop page, which collapses children under the parent card and offers a picker; nothing else in the building learns a new noun. category is ONE FLAT TEXT FIELD on purpose: a taxonomy tree is what a store builds because a platform offers one and then argues about forever, while a small business has eight categories and knows their names, and tags already exist for anyone who genuinely outgrows flat. image_file_id is a POINTER into the owner's files served by the endpoint app-files already has (/api/files/{id}) -- the catalogue stores an id, never bytes, exactly as digital_file_id does, which is what keeps a product row a row. 0.7.0 is the catalogue's half of the commerce money layer, and it is four product fields plus two small collections. BACKORDERS: products.backorder_policy (refuse | allow | notify) decides what checkout does when the shelf is empty, and it defaults to REFUSE, which is exactly today's behaviour -- that default is the whole safety of the feature, because a catalogue written before the column existed, or a value typed wrong, behaves as the shop behaved yesterday and nothing starts selling stock it does not have. allow takes the order and records a backorders row, because real stores sell the incoming shipment and a hard refusal on every empty shelf is a shop turning away money; notify still refuses but keeps the customer's interest, since refusing while remembering beats refusing and forgetting. REORDER POINTS: reorder_point and reorder_quantity feed system_reorder_check, a nightly pass that folds the stock ledger and writes a SUGGESTION -- never a purchase order, and the noun is the design. The fold can see the shelf; it cannot see the supplier's minimum, the lead time, the case size, the promotion about to triple demand or the cash in the bank, and a machine that orders on its own is how a business ends up with forty pallets of the wrong thing. The server notices, the person decides. One OPEN suggestion per product, refreshed rather than appended, because a nightly pass that added a row a night would turn one true fact into ninety and a queue nobody reads. Both collections carry an attention count at severity warning: nobody chose to be in either queue, and in the backorder case somebody has already paid. is_gift_card is the fourth field and belongs to app-billing's half of the slice: it marks a product that sells STORED VALUE rather than a thing, an ordinary sale whose fulfilment credits a wallet instead of putting something in a box. It is a flag and not a sixth product_type on purpose -- a gift card can be physical or digital, and folding it into that enum would make every place that asks 'does this sit on a shelf?' learn a new answer. 0.8.0 closes the COGS-on-sale gap, and the decision that took the time was the valuation method rather than the journal, which was always two lines. INVENTORY IS VALUED AT A MOVING WEIGHTED AVERAGE (object_stock.weighted_average_cost_cents), folded from the same append log everything else here folds. FIFO is more precise and is right for a lot-tracked warehouse, but it needs cost LAYERS -- which units, from which receipt, are still on the shelf -- and stock_moves has no lot dimension at all; adding one to satisfy a journal entry would be a storage change driven by an accounting report, which is the tail wagging the dog. LIFO is not permitted under IFRS. Weighted average needs nothing new, and it is what most small shops actually run. MOVING average specifically, folded in move order rather than 'total spent over total ever bought': buy ten at 100, sell all ten, buy one at 300, and the lifetime average answers 118 by averaging in ten units the shop no longer owns, while the moving average answers 300, which is what the next sale actually costs. The split that keeps it honest is that hook_stock_moves VALUES the sale at write time (doctrine #1: a point-in-time fact is stamped, so tomorrow's purchase cannot reprice yesterday's sale) and system_stock_books only ever READS the stamped cost -- a costless sale still skips rather than reaching for products.cost_cents, because a valuation method picked by accident inside a handler is exactly what the old boundary existed to prevent. products.cost_cents stays the fallback for a product with no priced acquisitions, and stays the PRIMARY for losses: writing off a broken mug at standard cost is fine, while reporting cost of SALES at a number somebody typed is how gross margin quietly becomes fiction. The COGS account is read from inventory.journal.cogs_account or inventory.journal.sale_account and NEVER falls back to the shrinkage account the loss reasons default to -- goods sold are not goods lost, and routing one into the other misstates the P&L while still balancing, which is the failure mode nobody notices.", |
| 6 | "compatibility": { |
| 7 | "dbbasic_object_server": ">=0.1.0" |
| 8 | }, |
| 9 | "dependencies": [ |
| 10 | "app-views" |
| 11 | ], |
| 12 | "objects": [ |
| 13 | { |
| 14 | "id": "site_stock", |
| 15 | "path": "objects/site/stock.py" |
| 16 | }, |
| 17 | { |
| 18 | "id": "hook_stock_moves", |
| 19 | "path": "objects/hook/stock_moves.py" |
| 20 | }, |
| 21 | { |
| 22 | "id": "system_stock_books", |
| 23 | "path": "objects/system/stock_books.py" |
| 24 | }, |
| 25 | { |
| 26 | "id": "action_apply_count", |
| 27 | "path": "objects/action/apply_count.py" |
| 28 | }, |
| 29 | { |
| 30 | "id": "system_reorder_check", |
| 31 | "path": "objects/system/reorder_check.py" |
| 32 | }, |
| 33 | { |
| 34 | "id": "system_reorder_attention", |
| 35 | "path": "objects/system/reorder_attention.py" |
| 36 | }, |
| 37 | { |
| 38 | "id": "system_backorder_attention", |
| 39 | "path": "objects/system/backorder_attention.py" |
| 40 | } |
| 41 | ], |
| 42 | "schemas": [ |
| 43 | { |
| 44 | "collection": "products", |
| 45 | "path": "schemas/products.json" |
| 46 | }, |
| 47 | { |
| 48 | "collection": "locations", |
| 49 | "path": "schemas/locations.json" |
| 50 | }, |
| 51 | { |
| 52 | "collection": "stock_moves", |
| 53 | "path": "schemas/stock_moves.json" |
| 54 | }, |
| 55 | { |
| 56 | "collection": "backorders", |
| 57 | "path": "schemas/backorders.json" |
| 58 | }, |
| 59 | { |
| 60 | "collection": "reorder_suggestions", |
| 61 | "path": "schemas/reorder_suggestions.json" |
| 62 | } |
| 63 | ], |
| 64 | "permissions": [ |
| 65 | { |
| 66 | "path": "permissions/rules.json" |
| 67 | } |
| 68 | ], |
| 69 | "seed": [ |
| 70 | { |
| 71 | "collection": "products", |
| 72 | "path": "seed/products.tsv" |
| 73 | }, |
| 74 | { |
| 75 | "collection": "locations", |
| 76 | "path": "seed/locations.tsv" |
| 77 | }, |
| 78 | { |
| 79 | "collection": "stock_moves", |
| 80 | "path": "seed/stock_moves.tsv" |
| 81 | }, |
| 82 | { |
| 83 | "collection": "views", |
| 84 | "path": "seed/views.tsv" |
| 85 | }, |
| 86 | { |
| 87 | "collection": "site_routes", |
| 88 | "path": "seed/site_routes.tsv" |
| 89 | }, |
| 90 | { |
| 91 | "collection": "backorders", |
| 92 | "path": "seed/backorders.tsv" |
| 93 | }, |
| 94 | { |
| 95 | "collection": "reorder_suggestions", |
| 96 | "path": "seed/reorder_suggestions.tsv" |
| 97 | } |
| 98 | ], |
| 99 | "migrations": [], |
| 100 | "nav": [ |
| 101 | { |
| 102 | "id": "products", |
| 103 | "label": "Products", |
| 104 | "path": "/products", |
| 105 | "blurb": "Things you sell, with SKUs, variants and prices in cents", |
| 106 | "surface": "member", |
| 107 | "group": "Commerce", |
| 108 | "order": 410 |
| 109 | }, |
| 110 | { |
| 111 | "id": "stock", |
| 112 | "label": "Stock", |
| 113 | "path": "/stock", |
| 114 | "blurb": "On-hand levels per location, derived from stock moves", |
| 115 | "surface": "member", |
| 116 | "group": "Warehouse", |
| 117 | "order": 500 |
| 118 | }, |
| 119 | { |
| 120 | "id": "locations", |
| 121 | "label": "Locations", |
| 122 | "path": "/locations", |
| 123 | "blurb": "Where stock is held", |
| 124 | "surface": "member", |
| 125 | "group": "Warehouse", |
| 126 | "order": 510 |
| 127 | }, |
| 128 | { |
| 129 | "id": "reorder", |
| 130 | "label": "Reorder", |
| 131 | "path": "/reorder", |
| 132 | "blurb": "Products at or below their reorder point, with how many to buy", |
| 133 | "surface": "member", |
| 134 | "group": "Warehouse", |
| 135 | "order": 505 |
| 136 | }, |
| 137 | { |
| 138 | "id": "backorders", |
| 139 | "label": "Backorders", |
| 140 | "path": "/backorders", |
| 141 | "blurb": "Goods somebody is waiting for, and people to tell when stock lands", |
| 142 | "surface": "member", |
| 143 | "group": "Warehouse", |
| 144 | "order": 507 |
| 145 | } |
| 146 | ], |
| 147 | "schedules": [ |
| 148 | { |
| 149 | "id": "reorder_check_daily", |
| 150 | "object_id": "system_reorder_check", |
| 151 | "schedule": "15 4 * * *", |
| 152 | "description": "Fold stock levels and suggest what to reorder. Nightly rather than hourly because a reorder point is a decision somebody makes once a day at most, and a queue that changed every hour would be one nobody trusts. Early, at 4:15, so the suggestion is waiting when the shop opens and so it does not collide with the accounting passes later in the morning. It never raises a purchase order: the shelf is the only thing it can see." |
| 153 | } |
| 154 | ], |
| 155 | "attention": [ |
| 156 | { |
| 157 | "id": "products_to_reorder", |
| 158 | "object_id": "system_reorder_attention", |
| 159 | "label": "Products to reorder", |
| 160 | "path": "/reorder", |
| 161 | "group": "Warehouse", |
| 162 | "severity": "warning", |
| 163 | "nav_id": "reorder" |
| 164 | }, |
| 165 | { |
| 166 | "id": "backorders_waiting", |
| 167 | "object_id": "system_backorder_attention", |
| 168 | "label": "Backorders waiting", |
| 169 | "path": "/backorders", |
| 170 | "group": "Warehouse", |
| 171 | "severity": "warning", |
| 172 | "nav_id": "backorders" |
| 173 | } |
| 174 | ] |
| 175 | } |