printedparts plugin: design proposal + hands-on development lab

Design for a 3D-printed-parts storefront: item catalog with images and
quantity on hand, a transaction ledger attributing every take/restock/
adjust to a badge-scanned employee, an unauthenticated touch kiosk
(scan bin barcode, scan badge, keypad quantity), 1x0.5in CODE128 bin
labels, and stock/consumption/by-person reports.

The lab guide walks a developer through building it in seven
checkpointed milestones, reusing the USB badge contract, the
measuringtools migration baseline, the models-image upload trio, and
the open kiosk-endpoint precedents.

docs/proposals/printedparts-plugin.md

@@ -0,0 +1,194 @@
+# Proposal: printedparts plugin (3D-printed parts storefront + kiosk)
+
+Status: PROPOSED (also serves as the reference design for the plugin-development
+lab in `docs/PLUGIN-LAB-PRINTEDPARTS.md`)
+
+## 1. Problem
+
+The 3D-printer engineers stock bins of printed parts (fixtures, clips, covers,
+spacers). Anyone on the floor can take parts, so stock silently runs out and
+nobody knows who took what or how fast items burn down. They need:
+
+- a catalog ("storefront") of printable items: photo, description, quantity on
+  hand;
+- a barcode label per item (1in x 0.5in) stuck on each bin;
+- a touch-screen kiosk: scan the bin barcode, scan your badge, enter how many
+  you took, submit;
+- restock and correction flows for the engineers;
+- stock monitoring plus consumption metrics.
+
+## 2. Shape: standalone model plugin, NOT an asset type
+
+These are quantity-based consumables: one row represents a *kind* of part with
+a count, not an individually tracked machine. ADR-001 assets are one-row-per-
+physical-thing (a PC, a printer). So printedparts follows the
+knowledgebase/usb shape - own tables, own blueprint, no AssetType row - and
+does NOT join the asset-label TYPE_CONFIG; it ships its own print view the way
+USB labels do.
+
+Item identity: `itemcode`, generated `3DP-<zero-padded id>` (prefix
+configurable via setting `printedparts_code_prefix`). Short, CODE128-friendly,
+human-readable. This is what the bin label encodes.
+
+## 3. Data model (2 tables, LOCKED naming, per-plugin Alembic)
+
+### printeditems
+| column | type | notes |
+|---|---|---|
+| printeditemid | int PK autoincrement | |
+| itemcode | varchar(20) unique, indexed | generated on create |
+| itemname | varchar(120) NOT NULL | |
+| itemdescription | varchar(500) | brief description |
+| imageurl | varchar(255) | served upload, models.py pattern |
+| quantityonhand | int NOT NULL default 0 | cached; ledger is truth |
+| lowstockthreshold | int NOT NULL default 5 | per-item, seeds from setting |
+| binlocation | varchar(100) | where the bin lives |
+| printnotes | mediumtext | material, print time, slicer file path |
+| isactive | tinyint(1) | soft retire |
+| createddate / modifieddate | datetime | AuditMixin/BaseModel |
+
+### printeditemtransactions (the ledger - source of truth)
+| column | type | notes |
+|---|---|---|
+| transactionid | int PK | |
+| printeditemid | int FK -> printeditems CASCADE, indexed | |
+| transactiontype | varchar(10) NOT NULL | take / restock / adjust |
+| quantitychange | int NOT NULL | negative for take, signed for adjust |
+| employeesso | varchar(20) NOT NULL, indexed | who (badge-resolved) |
+| employeename | varchar(120) | resolved at write time (USB pattern) |
+| reason | varchar(255) | required for adjust |
+| transactiondate | datetime NOT NULL default naive-UTC, indexed | |
+
+Invariants: `quantityonhand` = sum of `quantitychange` (enforced by writing
+both in one session/commit; an `adjust` can never drive it below 0 - reject).
+Every write records WHO via badge scan; there is no anonymous mutation.
+
+Both tables registered in `PLUGIN_TABLE_OWNERS`
+(`shopdb/plugins/alembic_template.py`); migration 0001 is a REAL baseline
+(measuringtools pattern - hand-written `op.create_table`, no cross-schema FK
+so `create_plugin_tables` would also work, but write the ops explicitly for
+the exercise).
+
+## 4. Badge resolution (reuse the USB contract exactly)
+
+Same input shapes as `plugins/usb/api/routes.py`:
+- all digits -> SSO;
+- `0<digits>BZ` (case-insensitive) -> physical badge wrapping a PayNo;
+- resolution to a display name via the employees plugin directory
+  (`DirectoryEmployee`, selfhosted mode) with graceful "" fallback.
+
+Extract-or-copy decision for the lab: copy the small `_PAYNO_BADGE` regex +
+lookup into the plugin (contract-pure, no cross-plugin import of usb).
+Resolution happens SERVER-side on the kiosk endpoint - the kiosk client never
+supplies a name, only the raw badge string.
+
+Manifest `dependencies: ["employees"]` (name lookup). Badge that resolves to
+no employee: configurable policy setting `printedparts_unknown_badge`
+(`allow` = record SSO with empty name, `deny` = 422). Default deny.
+
+## 5. API surface (blueprint at /api/printedparts)
+
+Authenticated management (JWT + permission):
+| route | method | permission |
+|---|---|---|
+| `/items` | GET list (search, paginate, lowstock filter) | open read (jwt optional) |
+| `/items/<id>` | GET detail + recent transactions | open read |
+| `/items` | POST create (mints itemcode) | printedparts.create |
+| `/items/<id>` | PUT update | printedparts.edit |
+| `/items/<id>` | DELETE soft-retire | printedparts.delete |
+| `/items/<id>/image` | POST/DELETE upload/remove | printedparts.edit |
+| `/image/<filename>` | GET serve | public (models.py pattern) |
+| `/items/<id>/restock` | POST {quantity, badge} | printedparts.restock |
+| `/items/<id>/adjust` | POST {quantitychange, reason, badge} | printedparts.restock |
+| `/items/<id>/transactions` | GET history, ?format=csv | open read |
+
+Kiosk (unauthenticated, notifications/employees open-endpoint precedent):
+| route | method | body |
+|---|---|---|
+| `/kiosk/item/<itemcode>` | GET | item summary by scanned code |
+| `/kiosk/take` | POST | {itemcode, badge, quantity} |
+
+`/kiosk/take` validation: item exists + active; quantity 1..quantityonhand
+(clamp/reject configurable? no - reject with clear message, kiosk shows it);
+badge resolves per policy. Writes ledger row (negative) + decrements cached
+quantity in one commit. Rate of abuse is low (plant floor), but the endpoint
+only ever DECREMENTS stock with a recorded badge - it cannot edit the catalog.
+
+Permissions declared via `get_permissions()`: printedparts.view/create/edit/
+delete/restock (category `printedparts`), seeded on install/enable.
+
+## 6. Frontend
+
+Management pages (scaffold output, standard layout, master templates
+PrintersList/PrinterDetail):
+- `PrintedItemsList.vue` - table: image thumb, code, name, qty (red badge when
+  <= threshold), bin; filters: search, low-stock-only; row click -> detail.
+- `PrintedItemDetail.vue` - hero image + fields, transaction history table,
+  restock/adjust buttons (modal w/ quantity + badge + reason).
+- `PrintedItemForm.vue` - create/edit incl. image upload, threshold, bin.
+- Router file `router/routes/printedparts.js`, list/detail plugin-gated only,
+  new/edit + requiresAuth (ADR-009, usb.js precedent).
+- Nav via `get_navigation_items()` -> "3D Parts".
+
+Kiosk (net-new, top-level route `/parts-kiosk`, NO requiresAuth, outside
+AppLayout - shopfloor precedent):
+- Full-screen, 3-step flow: (1) SCAN ITEM - a focused invisible input catches
+  the keyboard-wedge scan of the bin barcode, shows item card w/ photo + qty;
+  (2) SCAN BADGE - same wedge input pattern for the badge; (3) QUANTITY - big
+  touch keypad (0-9, clear, backspace - net-new component
+  `TouchKeypad.vue`) + TAKE button. Success screen w/ remaining count, auto
+  reset after a few seconds. All state client-side; one POST at the end.
+- Scanner UX rule: keyboard-wedge scanners type the code + Enter. A hidden
+  always-focused input with @keydown.enter handles both scans; on-screen
+  prompt tells the user what to scan. Touch fallback: item search + manual
+  badge entry (small link, for damaged labels).
+
+Labels (own print view, USBLabelBatch precedent):
+- `/print/printedparts-labels` public print route.
+- NEW physical size: 1in x 0.5in stock -> `@page { size: 1in 0.5in; margin: 0 }`
+  one label per page (label printers feed roll stock; per-page = per-label).
+  Layout: CODE128 barcode (JsBarcode, ~0.9in x 0.28in, displayValue false) +
+  itemcode text under it (~7pt) + optional item name truncated. QR variant
+  offered but barcode is default at this size (a 0.4in QR is at the edge of
+  scanner tolerance; CODE128 of `3DP-0042` is comfortable).
+- Batch mode: pick items -> one label per page sequence for roll printers;
+  also a ULINE mini-grid fallback for sheet printers (reuse mini72 pattern).
+
+## 7. Metrics / reports (get_reports hook)
+
+- `printedparts-stock` - current stock levels w/ threshold flags (CSV).
+- `printedparts-consumption` - takes per item over a date range (CSV).
+- `printedparts-by-person` - takes grouped by employee (CSV).
+- Dashboard widget via `get_dashboard_widgets()`: low-stock item count.
+- Nice-to-have later: burn-rate (avg takes/week per item + weeks-to-empty
+  projection) - plain SQL over the ledger, add once basics work.
+
+## 8. Settings (get_settings_cards, category printedparts)
+
+| key | default | purpose |
+|---|---|---|
+| printedparts_code_prefix | 3DP | itemcode prefix |
+| printedparts_default_threshold | 5 | seed for new items |
+| printedparts_unknown_badge | deny | kiosk policy for unresolvable badges |
+
+## 9. Manifest
+
+name printedparts, version 0.1.0, api_prefix /api/printedparts,
+core_version ">=0.11.0,<1.0.0", dependencies ["employees"],
+default_enabled false (site opts in - USB precedent).
+
+## 10. Explicitly out of scope (v1)
+
+- Reservations/approvals, per-item cost, print-queue integration, multi-bin
+  per item, email low-stock alerts (the reports + dashboard widget cover
+  monitoring; alerting can ride the existing report-email endpoint later).
+
+## 11. Risks / decisions taken
+
+- Cached quantity vs ledger drift: single-commit writes + a reconcile query in
+  the stock report (flags items where cache != ledger sum).
+- Unauthenticated kiosk take: accepted (matches shopfloor kiosk posture);
+  it is decrement-only, fully attributed, and rate-limited by physics.
+- 1x0.5in QR marginal: default to CODE128 barcode.
+- Not an Asset: no floor-map plotting or warranty for items. If a site later
+  wants bins on the floor map, revisit via get_map_overlays (ADR-010).