shopdb-flask/docs/proposals/printedparts-plugin.md

Proposal: printedparts plugin (3D-printed parts storefront + kiosk)

Status: BUILT. The plugin ships as plugins/printedparts/, kiosk route included. This page is the design behind it, kept as the record of why, and it is also the reference design for the plugin-development lab in docs/PLUGIN-LAB-PRINTEDPARTS.md. It is NOT current guidance: where it and the shipped plugin disagree, the code wins.

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.12.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).

Decision: the kiosk take endpoint is an unauthenticated WRITE

This is the first open mutation in the product - every existing kiosk endpoint (notifications, employees, shopfloor) is a read, and the closest write (USB checkout) is JWT + permission gated. Accepted deliberately, on these grounds, and any future open-write endpoint must meet the same bar:

1. Decrement-only: it can reduce stock of an active item, nothing else - no catalog edits, no restocks, no reads it does not already expose.
2. Fully attributed: it refuses to act without a badge that resolves per the site policy; every action lands in the ledger with SSO + name + time.
3. Bounded blast radius: worst case is stock counts driven low, which the ledger makes visible and reversible (adjust with reason).
4. Physically rate-limited: it exists for a touch screen on the shop floor; there is nothing to enumerate and nothing returned worth scraping.

• 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).