shopdb-flask/docs/PLUGIN-LAB-PRINTEDPARTS.md

Plugin lab: build the printedparts plugin yourself

A guided, milestone-based exercise: build the 3D-printed-parts storefront + kiosk plugin specified in docs/proposals/printedparts-plugin.md. Each milestone lists what to build, which existing code to imitate, and a checkpoint that proves you are done. Read the spec first, keep it open.

Prerequisites: a working dev environment (README quick start), the three plugin docs skimmed once - PLUGIN-QUICKSTART.md (mechanics), PLUGIN-GUIDE.md (the measuringtools walkthrough - your narrative reference), PLUGIN-HOOKS.md (hook reference). Naming rules: CONTRIBUTING.md - the pre-commit hook enforces them, read it before naming anything.

Ground rules

• Import core ONLY via shopdb.api (+ shopdb.plugins.base). The contract test fails your build otherwise.
• DB columns: lowercase concatenated (quantityonhand, not quantity_on_hand).
• Run bash scripts/check-naming-and-style.sh and the test suite at every checkpoint.

---

Milestone 1 - skeleton, models, migration (backend exists)

Build

1. flask plugin new printedparts - scaffolds plugins/printedparts/.
2. The scaffold assumes an Asset-extension plugin; ours is standalone. In plugin.py strip the AssetType seeding from on_install (imitate plugins/knowledgebase/plugin.py instead of the template).
3. Replace the scaffold model with the two spec tables: PrintedItem, PrintedItemTransaction (models/printeditem.py). Use BaseModel + AuditMixin from shopdb.api. Itemcode: leave generation to the API layer (M2), column just unique=True, index=True.
4. Register both tables in PLUGIN_TABLE_OWNERS (shopdb/plugins/alembic_template.py).
5. Create plugins/printedparts/migrations/ with the 3-line env.py + script.py.mako (copy from measuringtools) and a REAL baseline versions/0001_printedparts_baseline.py - hand-written op.create_table(...) for both tables (see plugins/measuringtools/migrations/versions/0001_measuringtools_baseline.py).
6. Manifest: api_prefix /api/printedparts, dependencies: ["employees"], default_enabled: false.

Checkpoint

flask plugin install printedparts && flask plugin enable printedparts
flask plugin upgrade-all      # applies your 0001
mysql> SHOW TABLES LIKE 'printed%';          -- both tables
mysql> SELECT * FROM alembic_version_printedparts;   -- your revision id
pytest tests/ -q               # nothing broken, contract tests green

Milestone 2 - CRUD API + permissions + itemcode

Build

1. api/routes.py: list/detail/create/update/soft-delete per the spec table. Imitate a clean plugin blueprint (plugins/measuringtools/api/routes.py) for pagination (perpage, dir), search, and the shared success_response/error_response helpers from shopdb.api.
2. Itemcode on create: <prefix>-<id zero-padded to 4>; prefix from Setting printedparts_code_prefix (read via self.get_setting or Setting model through shopdb.api). Two-step: insert, flush to get the id, set code.
3. get_permissions() on the plugin class: view/create/edit/delete/restock (tuples, category printedparts - copy shape from plugins/usb/plugin.py). Gate mutations with @jwt_required() + @require_permission(...); reads are @jwt_required(optional=True).
4. Restock + adjust endpoints: both write a LEDGER row and move quantityonhand in the same commit. Adjust requires reason, rejects a result below zero. Both record the operator: accept badge in the body and resolve it (M4 extracts the resolver - for now digits=SSO is enough).
5. Seed the 3 settings in on_install (Setting.set pattern - see how other plugins seed in on_install; category printedparts).

Checkpoint

pytest plugins/printedparts/tests/ -q      # write tests as you go:
# - create mints 3DP-0001 style codes
# - restock/adjust move both ledger and cache atomically
# - adjust below zero -> 400/422
# - permission gates: anonymous create -> 401, wrong-perm user -> 403
curl -s localhost:5001/api/printedparts/items | jq   # anonymous list OK

Milestone 3 - management frontend + images

Build

1. The scaffold already dropped PrintedpartsList/Detail/Form.vue starters and a router file; rename/build them into PrintedItemsList/Detail/Form per the spec. Master templates: PrintersList.vue (list), PrinterDetail.vue (detail). Global CSS only; CSS variables for colors (frontend/CLAUDE.md rules).
2. Register the API client in frontend/src/api/index.js (paste the generated frontend-api-snippet.js, extend with restock/adjust/image calls).
3. Low-stock highlighting on the list (quantityonhand <= lowstockthreshold -> danger badge). Filters: search + low-stock-only checkbox.
4. Image upload: replicate the models-image trio - upload/serve/delete - from shopdb/core/api/models.py INTO the plugin blueprint (instance/printedpartsimages/, public GET serve, imageurl column, prefix-guarded delete). Wire the Form upload + Detail hero image.
5. Nav: get_navigation_items() -> "3D Parts" (usb plugin shape). Router meta: list/detail plugin-gated, new/edit requiresAuth (see frontend/src/router/routes/usb.js).

Checkpoint: create an item with a photo in the UI; thumbnail on list, hero on detail; restock from detail updates qty + shows in history; frontend build + npx vitest run green; naming hook green.

Milestone 4 - badge resolution + kiosk

Build

1. Badge resolver in the plugin (services/badges.py): copy the USB contract
   • all-digits -> SSO; ^0(\d+)BZ$ case-insensitive -> PayNo; resolve display name via the employees plugin directory the way plugins/usb/api/selfhosted.py::_resolve_name does (lazy import inside the function, degrade gracefully when the plugin is absent). Policy setting printedparts_unknown_badge (deny -> 422).
2. Kiosk endpoints (UNauthenticated - the notifications/employees open-read precedent): GET /kiosk/item/<itemcode> and POST /kiosk/take {itemcode, badge, quantity}. Take: validate active item, 1 <= qty <= onhand, resolve badge, single-commit ledger row + decrement. Clear error strings - the kiosk displays them verbatim.
3. Kiosk view /parts-kiosk: top-level route, NO requiresAuth, outside AppLayout (register beside /shopfloor in frontend/src/router/index.js). Three-step flow per the spec. The scanner is a keyboard wedge: hidden always-focused input, submit on Enter, route the scan to whichever step is active. Build TouchKeypad.vue (3x4 grid of big buttons, emits digits/ clear/backspace) - net-new, nothing to copy, keep it dumb.
4. Manual fallback path (typed item search + badge entry) behind a small "no scanner?" link.

Checkpoint: full kiosk walkthrough on a touchscreen (or browser): scan/type an itemcode -> item card; badge 0123456BZ and plain SSO both resolve; take 3 -> success screen, qty down 3, ledger row has your name; taking more than onhand -> friendly error; unknown badge -> denied message. Backend tests for the resolver shapes + take validation.

Milestone 5 - labels (1in x 0.5in)

Build

1. Public print route /print/printedparts-labels + view (imitate USBLabelBatch.vue - USB is the precedent for a plugin OWNING its label page instead of joining TYPE_CONFIG).
2. New stock size: @page { size: 1in 0.5in; margin: 0 }, one label per page (roll-fed label printers treat each page as one label). Layout: CODE128 via JsBarcode (~0.9in wide, displayValue false), itemcode text ~7pt under it, optional truncated name. Offer QR as a variant but default barcode.
3. Batch: multi-select items -> sequence of labels; plus a ULINE mini-grid sheet fallback (mini72 pattern in AssetLabelBatch.vue).
4. Print buttons on Detail (single) and List (batch selected).

Checkpoint: print preview shows one 1x0.5 label per page; a printed (or PDF-zoomed) barcode scans back into the kiosk and pulls up the right item. That round trip - label printed from the catalog, scanned at the kiosk, stock decremented with your name on it - is the demo moment; make it work end to end before polishing.

Milestone 6 - metrics, reports, widget

Build

1. get_reports() -> stock, consumption (date range), by-person; endpoints in the plugin blueprint, @jwt_required(optional=True), ?format=csv via the generate_csv helper pattern (shopdb/core/api/reports.py shows the shape; a plugin report lives in the plugin and is merged into GET /api/reports automatically when enabled).
2. Stock report includes the reconcile check: flag rows where cached quantityonhand != SUM(ledger). Should always be empty; if not, you have a non-atomic write path - find it.
3. OPTIONAL/deferred: get_dashboard_widgets() -> low-stock count. Caveat: this hook predates the ADR-010 data-only renderers - the widget names a frontend component that must already exist in core, so a plugin widget only renders if you also add that component. Reports are the primary monitoring surface; skip the widget unless you want the extra credit.
4. Nice-to-have if time: burn rate (avg weekly takes over trailing 4 weeks + weeks-to-empty). Plain SQL over the ledger.

Checkpoint: reports appear on /reports grouped under the plugin, CSV downloads; widget renders on the dashboard; reconcile column all-clear after a kiosk session.

Milestone 7 - lifecycle + closeout

Build/verify

1. Disable/enable cycle: flask plugin disable printedparts - nav entry, routes, reports, and grantable permissions all disappear; enable restores.
2. Fresh-database proof: point DATABASE_URL at a scratch DB, flask db upgrade + flask plugin install/enable/upgrade-all - everything works with zero manual SQL.
3. Full suite: backend pytest, vitest, frontend build, naming hook.
4. End checklist from PLUGIN-GUIDE.md section 12.

Done means: a colleague can clone the repo, enable the plugin, print a bin label, and take a part at the kiosk with their badge - without asking you anything.

---

Where each pattern lives (cheat sheet)

Need	Copy from
Standalone (non-asset) plugin shape	plugins/knowledgebase/
Checkout/ledger + badge contract	plugins/usb/ (api/routes.py badge regex, api/selfhosted.py name resolve)
Real-baseline plugin migration	plugins/measuringtools/migrations/
Blueprint style, pagination, authz	plugins/measuringtools/api/routes.py
Image upload/serve/delete	shopdb/core/api/models.py
Open kiosk endpoints precedent	plugins/employees/api/routes.py, plugins/notifications/api/routes.py
Plugin-owned label print view	frontend/src/views/print/USBLabelBatch.vue
Barcode/QR rendering	JsBarcode usage in AssetLabel.vue, qrLogo.js
Kiosk route posture	/shopfloor in frontend/src/router/index.js
List/Detail master templates	PrintersList.vue, PrinterDetail.vue
Reports hook + CSV	plugins/warranty/ report + shopdb/core/api/reports.py
Permissions declaration	plugins/usb/plugin.py::get_permissions