printedparts stage 7: the kiosk - scan bin, scan badge, keypad, take

Two open endpoints: an item lookup by scanned code and the take POST -
the product's first unauthenticated write, held to the decision
record's bar (decrement-only, badge-attributed server-side, bounded,
physically rate-limited; justification in the plugin README). The
/parts-kiosk route is a full-screen no-auth view beside /shopfloor: a
hidden always-focused input consumes keyboard-wedge scans for
whichever step is active, TouchKeypad (net-new 3x4 grid) takes the
quantity, and a success screen resets after a few seconds. Manual
type-in fallbacks cover damaged labels. Kiosk test proves open access,
the over-take guard, the badge policy, and cache==ledger afterward.

frontend/src/api/index.js

@@ -1153,5 +1153,17 @@ export const printedpartsApi = {
   },
   deleteImage(printeditemid) {
     return api.delete(`/printedparts/items/${printeditemid}/image`)
+  },
+  restock(printeditemid, data) {
+    return api.post(`/printedparts/items/${printeditemid}/restock`, data)
+  },
+  adjust(printeditemid, data) {
+    return api.post(`/printedparts/items/${printeditemid}/adjust`, data)
+  },
+  kioskItem(itemcode) {
+    return api.get(`/printedparts/kiosk/item/${encodeURIComponent(itemcode)}`)
+  },
+  kioskTake(data) {
+    return api.post('/printedparts/kiosk/take', data)
   }
 }

frontend/src/components/TouchKeypad.vue

@@ -0,0 +1,38 @@
+<template>
+  <div class="touch-keypad">
+    <button v-for="digit in digits" :key="digit" type="button"
+            class="keypad-button" @click="$emit('digit', digit)">
+      {{ digit }}
+    </button>
+    <button type="button" class="keypad-button keypad-muted"
+            @click="$emit('clear')">C</button>
+    <button type="button" class="keypad-button" @click="$emit('digit', '0')">0</button>
+    <button type="button" class="keypad-button keypad-muted"
+            @click="$emit('backspace')">&lt;</button>
+  </div>
+</template>
+
+<script setup>
+const digits = ['1', '2', '3', '4', '5', '6', '7', '8', '9']
+defineEmits(['digit', 'clear', 'backspace'])
+</script>
+
+<style scoped>
+.touch-keypad {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 0.6rem;
+  max-width: 20rem;
+}
+.keypad-button {
+  font-size: 1.8rem;
+  padding: 1rem 0;
+  border-radius: 0.5rem;
+  border: 1px solid var(--border);
+  background: var(--bg-card);
+  color: var(--text);
+  cursor: pointer;
+}
+.keypad-button:active { background: var(--primary); color: #fff; }
+.keypad-muted { color: var(--text-light); }
+</style>

frontend/src/router/index.js

@@ -65,6 +65,14 @@ const routes = [
     name: 'shopfloor',
     component: () => import('../views/ShopfloorDashboard.vue')
   },
+  {
+    // Touch kiosk for taking 3D-printed parts: scan bin, scan badge, keypad.
+    // Open on purpose - see the decision record in the printedparts proposal.
+    path: '/parts-kiosk',
+    name: 'parts-kiosk',
+    component: () => import('../views/printedparts/PartsKiosk.vue'),
+    meta: { plugin: 'printedparts' }
+  },
   {
     path: '/tv',
     name: 'tv',

frontend/src/views/printedparts/PartsKiosk.vue

@@ -0,0 +1,242 @@
+<template>
+  <div class="parts-kiosk" @click="focusWedge">
+    <!-- keyboard-wedge scanners type the code + Enter into this hidden,
+         always-focused input; whichever step is active consumes the scan -->
+    <input ref="wedgeInput" v-model="wedgeBuffer" class="wedge-input"
+           autocomplete="off" @keydown.enter.prevent="onWedgeEnter" />
+
+    <header class="kiosk-header">
+      <h1>3D Printed Parts</h1>
+      <button v-if="step !== 'item'" class="btn btn-secondary" @click="reset">
+        Start over
+      </button>
+    </header>
+
+    <div v-if="error" class="kiosk-error">{{ error }}</div>
+
+    <!-- step 1: scan the bin -->
+    <section v-if="step === 'item'" class="kiosk-step">
+      <p class="kiosk-prompt">Scan the barcode on the bin</p>
+      <p class="kiosk-hint">
+        No scanner?
+        <a href="#" @click.prevent="manualEntry = !manualEntry">Type the code</a>
+      </p>
+      <div v-if="manualEntry" class="manual-row">
+        <input v-model="manualCode" class="form-control" placeholder="3DP-0001"
+               @keydown.enter="lookupItem(manualCode)" />
+        <button class="btn btn-primary" @click="lookupItem(manualCode)">Go</button>
+      </div>
+    </section>
+
+    <!-- step 2: badge -->
+    <section v-else-if="step === 'badge'" class="kiosk-step">
+      <div class="item-card">
+        <img v-if="item.imageurl" :src="withBase(item.imageurl)" class="item-photo" />
+        <div>
+          <h2>{{ item.itemname }}</h2>
+          <p class="kiosk-hint">{{ item.itemcode }} - {{ item.quantityonhand }} on hand</p>
+        </div>
+      </div>
+      <p class="kiosk-prompt">Scan your badge</p>
+      <div class="manual-row">
+        <input v-model="manualBadge" class="form-control" placeholder="or type your SSO"
+               @keydown.enter="acceptBadge(manualBadge)" />
+        <button class="btn btn-primary" @click="acceptBadge(manualBadge)">Next</button>
+      </div>
+    </section>
+
+    <!-- step 3: quantity -->
+    <section v-else-if="step === 'quantity'" class="kiosk-step">
+      <div class="item-card">
+        <img v-if="item.imageurl" :src="withBase(item.imageurl)" class="item-photo" />
+        <div>
+          <h2>{{ item.itemname }}</h2>
+          <p class="kiosk-hint">{{ item.quantityonhand }} on hand</p>
+        </div>
+      </div>
+      <p class="kiosk-prompt">How many are you taking?</p>
+      <div class="quantity-display">{{ quantity || '0' }}</div>
+      <TouchKeypad @digit="quantity += $event"
+                   @clear="quantity = ''"
+                   @backspace="quantity = quantity.slice(0, -1)" />
+      <button class="btn btn-primary take-button" :disabled="!quantity || submitting"
+              @click="submitTake">
+        {{ submitting ? 'Working...' : 'TAKE' }}
+      </button>
+    </section>
+
+    <!-- done -->
+    <section v-else-if="step === 'done'" class="kiosk-step">
+      <p class="kiosk-success">Done - {{ doneMessage }}</p>
+      <p class="kiosk-hint">Starting over in a few seconds...</p>
+    </section>
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted, onBeforeUnmount } from 'vue'
+import { printedpartsApi } from '../../api'
+import { withBase } from '../../utils/basePath'
+import TouchKeypad from '../../components/TouchKeypad.vue'
+
+const step = ref('item')
+const item = ref(null)
+const badge = ref('')
+const quantity = ref('')
+const error = ref('')
+const doneMessage = ref('')
+const submitting = ref(false)
+const manualEntry = ref(false)
+const manualCode = ref('')
+const manualBadge = ref('')
+const wedgeInput = ref(null)
+const wedgeBuffer = ref('')
+let resetTimer = null
+
+onMounted(focusWedge)
+onBeforeUnmount(() => clearTimeout(resetTimer))
+
+function focusWedge() {
+  wedgeInput.value?.focus()
+}
+
+function onWedgeEnter() {
+  const scanned = wedgeBuffer.value.trim()
+  wedgeBuffer.value = ''
+  if (!scanned) return
+  if (step.value === 'item') lookupItem(scanned)
+  else if (step.value === 'badge') acceptBadge(scanned)
+}
+
+async function lookupItem(itemcode) {
+  error.value = ''
+  if (!itemcode) return
+  try {
+    const response = await printedpartsApi.kioskItem(itemcode.trim())
+    item.value = response.data.data
+    step.value = 'badge'
+    manualEntry.value = false
+    manualCode.value = ''
+  } catch (lookupError) {
+    error.value = lookupError.response?.data?.data?.error?.message ||
+      'No part matches that barcode'
+  }
+  focusWedge()
+}
+
+function acceptBadge(value) {
+  error.value = ''
+  const scanned = (value || '').trim()
+  if (!scanned) return
+  badge.value = scanned
+  manualBadge.value = ''
+  step.value = 'quantity'
+  focusWedge()
+}
+
+async function submitTake() {
+  submitting.value = true
+  error.value = ''
+  try {
+    const response = await printedpartsApi.kioskTake({
+      itemcode: item.value.itemcode,
+      badge: badge.value,
+      quantity: parseInt(quantity.value, 10)
+    })
+    doneMessage.value = response.data.message
+    step.value = 'done'
+    resetTimer = setTimeout(reset, 4000)
+  } catch (takeError) {
+    error.value = takeError.response?.data?.data?.error?.message ||
+      'Could not complete - see the parts team'
+    if (takeError.response?.status === 422) {
+      // badge problem: go back a step so the next scan retries cleanly
+      step.value = 'badge'
+    }
+  } finally {
+    submitting.value = false
+  }
+}
+
+function reset() {
+  clearTimeout(resetTimer)
+  step.value = 'item'
+  item.value = null
+  badge.value = ''
+  quantity.value = ''
+  error.value = ''
+  doneMessage.value = ''
+  focusWedge()
+}
+</script>
+
+<style scoped>
+.parts-kiosk {
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--text);
+  padding: 2rem;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 1.5rem;
+}
+.kiosk-header {
+  width: 100%;
+  max-width: 40rem;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+.wedge-input {
+  position: absolute;
+  opacity: 0;
+  height: 1px;
+  width: 1px;
+}
+.kiosk-step {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 1.25rem;
+  max-width: 40rem;
+  width: 100%;
+}
+.kiosk-prompt { font-size: 1.6rem; font-weight: 600; }
+.kiosk-hint { color: var(--text-light); }
+.kiosk-error {
+  background: var(--danger);
+  color: #fff;
+  padding: 0.75rem 1.25rem;
+  border-radius: 0.5rem;
+}
+.kiosk-success { font-size: 1.6rem; color: var(--success); font-weight: 600; }
+.item-card {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  background: var(--bg-card);
+  border: 1px solid var(--border);
+  border-radius: 0.6rem;
+  padding: 1rem 1.5rem;
+  width: 100%;
+}
+.item-photo {
+  width: 5rem;
+  height: 5rem;
+  object-fit: cover;
+  border-radius: 0.4rem;
+}
+.quantity-display {
+  font-size: 3rem;
+  font-weight: 700;
+  min-width: 8rem;
+  text-align: center;
+  border-bottom: 3px solid var(--primary);
+}
+.take-button {
+  font-size: 1.5rem;
+  padding: 0.9rem 3.5rem;
+}
+.manual-row { display: flex; gap: 0.6rem; }
+</style>

frontend/src/views/printedparts/PrintedItemDetail.vue

@@ -19,6 +19,12 @@
             <p v-if="item.itemdescription">{{ item.itemdescription }}</p>
           </div>
           <div class="hero-actions">
+            <button class="btn btn-primary btn-sm" @click="openLedger('restock')">
+              Restock
+            </button>
+            <button class="btn btn-secondary btn-sm" @click="openLedger('adjust')">
+              Adjust
+            </button>
             <router-link :to="`/printedparts/${item.printeditemid}/edit`"
                          class="btn btn-secondary btn-sm">Edit</router-link>
           </div>
@@ -96,6 +102,30 @@
     </template>
 
     <div v-else class="card">Item not found</div>
+
+    <Modal v-model="ledgerOpen" :title="ledgerMode === 'restock' ? 'Restock' : 'Adjust count'">
+      <div v-if="ledgerError" class="error-message">{{ ledgerError }}</div>
+      <div class="form-group">
+        <label>{{ ledgerMode === 'restock' ? 'Quantity printed' : 'Change (+/-)' }}</label>
+        <input v-model.number="ledgerQuantity" type="number" class="form-control" />
+      </div>
+      <div v-if="ledgerMode === 'adjust'" class="form-group">
+        <label>Reason *</label>
+        <input v-model="ledgerReason" type="text" class="form-control"
+               placeholder="e.g., damaged parts scrapped, recount" />
+      </div>
+      <div class="form-group">
+        <label>Your badge / SSO *</label>
+        <input v-model="ledgerBadge" type="text" class="form-control"
+               placeholder="Scan badge or type SSO" />
+      </div>
+      <template #footer>
+        <button class="btn btn-primary" :disabled="ledgerSaving" @click="submitLedger">
+          {{ ledgerSaving ? 'Saving...' : 'Submit' }}
+        </button>
+        <button class="btn btn-secondary" @click="ledgerOpen = false">Cancel</button>
+      </template>
+    </Modal>
   </div>
 </template>
 
@@ -104,6 +134,7 @@ import { ref, onMounted } from 'vue'
 import { useRoute } from 'vue-router'
 import { printedpartsApi } from '../../api'
 import { withBase } from '../../utils/basePath'
+import Modal from '../../components/Modal.vue'
 
 const route = useRoute()
 const item = ref(null)
@@ -120,6 +151,50 @@ onMounted(async () => {
   }
 })
 
+const ledgerOpen = ref(false)
+const ledgerMode = ref('restock')
+const ledgerQuantity = ref(null)
+const ledgerReason = ref('')
+const ledgerBadge = ref('')
+const ledgerSaving = ref(false)
+const ledgerError = ref('')
+
+function openLedger(mode) {
+  ledgerMode.value = mode
+  ledgerQuantity.value = null
+  ledgerReason.value = ''
+  ledgerBadge.value = ''
+  ledgerError.value = ''
+  ledgerOpen.value = true
+}
+
+async function submitLedger() {
+  ledgerSaving.value = true
+  ledgerError.value = ''
+  try {
+    if (ledgerMode.value === 'restock') {
+      await printedpartsApi.restock(item.value.printeditemid, {
+        quantity: ledgerQuantity.value, badge: ledgerBadge.value
+      })
+    } else {
+      await printedpartsApi.adjust(item.value.printeditemid, {
+        quantitychange: ledgerQuantity.value,
+        reason: ledgerReason.value,
+        badge: ledgerBadge.value
+      })
+    }
+    ledgerOpen.value = false
+    const response = await printedpartsApi.get(item.value.printeditemid)
+    item.value = response.data.data
+  } catch (submitError) {
+    ledgerError.value =
+      submitError.response?.data?.data?.error?.message ||
+      submitError.response?.data?.error?.message || 'Submit failed'
+  } finally {
+    ledgerSaving.value = false
+  }
+}
+
 function formatDate(value) {
   if (!value) return '-'
   return new Date(value).toLocaleString()

plugins/printedparts/README.md

@@ -41,3 +41,19 @@ pytest plugins/printedparts/tests/
 - `docs/PLUGIN-QUICKSTART.md` - 30-minute walkthrough
 - `migrations/adr/ADR-001-asset-as-platform-contract.md` - the platform contract
 - `migrations/adr/ADR-002-plugin-versioning.md` - versioning rules
+
+## Why the kiosk take endpoint is unauthenticated
+
+`POST /api/printedparts/kiosk/take` is the product's first open WRITE (every
+other kiosk endpoint is a read). Accepted deliberately, against the criteria
+in docs/proposals/printedparts-plugin.md:
+
+1. Decrement-only: it can reduce stock of an active item, nothing else.
+2. Fully attributed: it refuses to act without a badge that resolves under
+   the site policy; every action lands in the ledger with SSO + name + time.
+3. Bounded blast radius: worst case is stock counts driven low - visible in
+   the ledger and reversible with an adjust.
+4. Physically rate-limited: it serves a touch screen on the shop floor;
+   nothing enumerable, nothing worth scraping.
+
+Any future open-write endpoint must clear the same bar.

plugins/printedparts/api/routes.py

@@ -17,6 +17,7 @@ from shopdb.api import (
     ErrorCodes,
     get_pagination_params,
     paginate_query,
+    require_permission,
 )
 
 from ..models import PrintedItem
@@ -95,6 +96,7 @@ def _mint_itemcode(item):
 
 @printedparts_bp.route('/items', methods=['POST'])
 @jwt_required()
+@require_permission('printedparts.create')
 def create_item():
     """Create a printed item; the itemcode is minted from the row id."""
     data = request.get_json() or {}
@@ -124,6 +126,7 @@ def create_item():
 
 @printedparts_bp.route('/items/<int:item_id>', methods=['PUT'])
 @jwt_required()
+@require_permission('printedparts.edit')
 def update_item(item_id: int):
     """Update catalog fields. Quantity moves ONLY through the ledger."""
     item = db.session.get(PrintedItem, item_id)
@@ -144,6 +147,7 @@ def update_item(item_id: int):
 
 @printedparts_bp.route('/items/<int:item_id>', methods=['DELETE'])
 @jwt_required()
+@require_permission('printedparts.delete')
 def delete_item(item_id: int):
     """Soft-retire an item; its ledger history stays."""
     item = db.session.get(PrintedItem, item_id)
@@ -159,6 +163,7 @@ def delete_item(item_id: int):
 
 @printedparts_bp.route('/items/<int:item_id>/image', methods=['POST'])
 @jwt_required()
+@require_permission('printedparts.edit')
 def upload_item_image(item_id: int):
     """Upload (or replace) the photo for an item (multipart file=<image>)."""
     item = db.session.get(PrintedItem, item_id)
@@ -195,6 +200,7 @@ def serve_item_image(filename):
 
 @printedparts_bp.route('/items/<int:item_id>/image', methods=['DELETE'])
 @jwt_required()
+@require_permission('printedparts.delete')
 def delete_item_image(item_id: int):
     """Clear an item image; delete the file only if this plugin owns it."""
     item = db.session.get(PrintedItem, item_id)
@@ -210,3 +216,133 @@ def delete_item_image(item_id: int):
     item.imageurl = None
     db.session.commit()
     return success_response(item.to_dict(), message='Item image removed')
+
+
+# --- the ledger: restock and adjust (stage 6 gates with printedparts.restock)
+
+from ..models import PrintedItemTransaction
+from ..services.badges import BadgeError, resolve_badge
+
+
+def _ledger_write(item, transactiontype, quantitychange, sso, name, reason=None):
+    """Append a ledger row and move the cached quantity in ONE commit.
+
+    The single-commit invariant is what keeps quantityonhand equal to the
+    ledger sum; every write path must go through here.
+    """
+    item.quantityonhand += quantitychange
+    db.session.add(PrintedItemTransaction(
+        printeditemid=item.printeditemid,
+        transactiontype=transactiontype,
+        quantitychange=quantitychange,
+        employeesso=sso,
+        employeename=name,
+        reason=reason,
+    ))
+    db.session.commit()
+
+
+@printedparts_bp.route('/items/<int:item_id>/restock', methods=['POST'])
+@jwt_required()
+@require_permission('printedparts.restock')
+def restock_item(item_id: int):
+    """Add freshly printed stock. Body: {quantity, badge}."""
+    item = db.session.get(PrintedItem, item_id)
+    if not item or not item.isactive:
+        return error_response(ErrorCodes.NOT_FOUND,
+                              f'Printed item {item_id} not found', http_code=404)
+    data = request.get_json() or {}
+    quantity = data.get('quantity')
+    if not isinstance(quantity, int) or quantity < 1:
+        return error_response(ErrorCodes.VALIDATION_ERROR,
+                              'quantity must be a positive integer')
+    try:
+        sso, name = resolve_badge(data.get('badge'))
+    except BadgeError as badge_error:
+        return error_response(ErrorCodes.VALIDATION_ERROR, str(badge_error),
+                              http_code=422)
+    _ledger_write(item, 'restock', quantity, sso, name)
+    return success_response(item.to_dict(), message='Stock added')
+
+
+@printedparts_bp.route('/items/<int:item_id>/adjust', methods=['POST'])
+@jwt_required()
+@require_permission('printedparts.restock')
+def adjust_item(item_id: int):
+    """Correct the count (damage, recount). Body: {quantitychange, reason, badge}."""
+    item = db.session.get(PrintedItem, item_id)
+    if not item or not item.isactive:
+        return error_response(ErrorCodes.NOT_FOUND,
+                              f'Printed item {item_id} not found', http_code=404)
+    data = request.get_json() or {}
+    quantitychange = data.get('quantitychange')
+    if not isinstance(quantitychange, int) or quantitychange == 0:
+        return error_response(ErrorCodes.VALIDATION_ERROR,
+                              'quantitychange must be a non-zero integer')
+    reason = (data.get('reason') or '').strip()
+    if not reason:
+        return error_response(ErrorCodes.VALIDATION_ERROR,
+                              'reason is required for an adjustment')
+    if item.quantityonhand + quantitychange < 0:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            f'Adjustment would drive stock below zero '
+            f'(on hand: {item.quantityonhand})')
+    try:
+        sso, name = resolve_badge(data.get('badge'))
+    except BadgeError as badge_error:
+        return error_response(ErrorCodes.VALIDATION_ERROR, str(badge_error),
+                              http_code=422)
+    _ledger_write(item, 'adjust', quantitychange, sso, name, reason=reason)
+    return success_response(item.to_dict(), message='Stock adjusted')
+
+
+# --- kiosk: UNauthenticated by decision record --------------------------------
+# The take endpoint is the product's first open WRITE. The proposal's decision
+# record sets the bar it must meet: decrement-only, badge-attributed, bounded,
+# physically rate-limited. It can reduce stock of an active item and nothing
+# else; identity comes from the badge resolved server-side, never the client.
+
+@printedparts_bp.route('/kiosk/item/<itemcode>', methods=['GET'])
+def kiosk_item(itemcode):
+    """Item summary for a scanned bin barcode (open read for the kiosk)."""
+    item = PrintedItem.query.filter(
+        PrintedItem.itemcode == itemcode.strip(),
+        PrintedItem.isactive == True).first()
+    if not item:
+        return error_response(ErrorCodes.NOT_FOUND,
+                              'No part matches that barcode', http_code=404)
+    return success_response(item.to_dict())
+
+
+@printedparts_bp.route('/kiosk/take', methods=['POST'])
+def kiosk_take():
+    """Take parts from a bin. Body: {itemcode, badge, quantity}."""
+    data = request.get_json() or {}
+
+    item = PrintedItem.query.filter(
+        PrintedItem.itemcode == (data.get('itemcode') or '').strip(),
+        PrintedItem.isactive == True).first()
+    if not item:
+        return error_response(ErrorCodes.NOT_FOUND,
+                              'No part matches that barcode', http_code=404)
+
+    quantity = data.get('quantity')
+    if not isinstance(quantity, int) or quantity < 1:
+        return error_response(ErrorCodes.VALIDATION_ERROR,
+                              'Enter how many you are taking')
+    if quantity > item.quantityonhand:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            f'Only {item.quantityonhand} on hand - take fewer or see the '
+            f'parts team')
+
+    try:
+        sso, name = resolve_badge(data.get('badge'))
+    except BadgeError as badge_error:
+        return error_response(ErrorCodes.VALIDATION_ERROR, str(badge_error),
+                              http_code=422)
+
+    _ledger_write(item, 'take', -quantity, sso, name)
+    return success_response(item.to_dict(),
+                            message=f'Took {quantity}, {item.quantityonhand} left')

plugins/printedparts/plugin.py

@@ -51,6 +51,17 @@ class PrintedpartsPlugin(BasePlugin):
     def init_app(self, app: Flask, db_instance) -> None:
         logger.info(f'Printedparts plugin initialized (v{self.meta.version})')
 
+    def get_permissions(self) -> List:
+        """RBAC permissions this plugin owns (seeded on install/enable)."""
+        return [
+            ('printedparts.view', 'View 3D printed parts', 'printedparts'),
+            ('printedparts.create', 'Create printed parts', 'printedparts'),
+            ('printedparts.edit', 'Edit printed parts', 'printedparts'),
+            ('printedparts.delete', 'Retire printed parts', 'printedparts'),
+            ('printedparts.restock', 'Restock and adjust stock counts',
+             'printedparts'),
+        ]
+
     def get_navigation_items(self) -> List[dict]:
         return [
             {

plugins/printedparts/services/__init__.py

@@ -0,0 +1 @@
+"""Printedparts plugin services."""

plugins/printedparts/services/badges.py

@@ -0,0 +1,69 @@
+"""Badge resolution for the printedparts plugin.
+
+Same input contract as the USB plugin (deliberately copied, not imported -
+cross-plugin imports break the shopdb.api-only contract):
+
+- all digits            -> an SSO typed or scanned directly
+- 0<digits>BZ           -> a physical badge wrapping a PayNo (keyboard-wedge
+                           scanners emit this shape)
+- anything else         -> unresolvable
+
+Names come from the employees plugin's self-hosted directory, looked up by
+SSO. The directory carries no PayNo column, so PayNo badges resolve only when
+the wrapped digits are themselves the SSO (true at sites whose badges encode
+the SSO); otherwise they fall to the unknown-badge policy.
+
+Policy (Setting printedparts_unknown_badge): 'deny' (default) rejects a badge
+with no directory match; 'allow' records the SSO with an empty name.
+"""
+
+import re
+
+from shopdb.api import Setting
+
+_PAYNO_BADGE = re.compile(r'^0(\d+)BZ$', re.IGNORECASE)
+
+
+class BadgeError(ValueError):
+    """Raised when a badge cannot be accepted under the site policy."""
+
+
+def _directory_name(sso):
+    """Best-effort display name from the employees plugin directory."""
+    try:
+        from plugins.employees.models import DirectoryEmployee
+        from shopdb.api import db
+        if sso and str(sso).isdigit():
+            employee = db.session.get(DirectoryEmployee, int(sso))
+            if employee:
+                return f'{employee.firstname} {employee.lastname}'.strip()
+    except Exception:
+        pass
+    return None
+
+
+def resolve_badge(badge):
+    """Return (sso, name) for a scanned badge, enforcing the site policy.
+
+    Raises BadgeError with a kiosk-displayable message when the badge shape is
+    unrecognized or the policy denies an unmatched badge.
+    """
+    badge = (badge or '').strip()
+    if not badge:
+        raise BadgeError('Scan or enter a badge')
+
+    if badge.isdigit():
+        sso = badge
+    else:
+        match = _PAYNO_BADGE.match(badge)
+        if not match:
+            raise BadgeError('Unrecognized badge format')
+        sso = match.group(1)
+
+    name = _directory_name(sso)
+    if name is None:
+        policy = (Setting.get('printedparts_unknown_badge') or 'deny').lower()
+        if policy != 'allow':
+            raise BadgeError('Badge not recognized - see the parts team')
+        return sso, ''
+    return sso, name

tests/test_plugins/test_printedparts_ledger.py

@@ -0,0 +1,168 @@
+"""Printedparts ledger + badge tests.
+
+The invariants that make the plugin trustworthy: itemcode minting, the
+single-commit cache==ledger rule, the below-zero guard, quantity edits
+forced through the ledger, and the badge contract (SSO digits, PayNo
+wrap, unknown-badge policy).
+"""
+
+import pytest
+
+from shopdb.api import db
+from shopdb.core.models import Setting
+from plugins.printedparts.models import PrintedItem, PrintedItemTransaction
+
+
+@pytest.fixture
+def item(app, db):
+    with app.app_context():
+        row = PrintedItem(itemcode='3DP-9001', itemname='Test clip',
+                          quantityonhand=0, lowstockthreshold=5)
+        db.session.add(row)
+        db.session.commit()
+        yield row.printeditemid
+
+
+@pytest.fixture
+def directory_employee(app):
+    with app.app_context():
+        from plugins.employees.models import DirectoryEmployee
+        if not db.session.get(DirectoryEmployee, 502000001):
+            db.session.add(DirectoryEmployee(
+                sso=502000001, firstname='Pat', lastname='Printer'))
+            db.session.commit()
+    return '502000001'
+
+
+def test_create_mints_itemcode(client, auth_headers):
+    response = client.post('/api/printedparts/items', json={'itemname': 'Bracket'},
+                           headers=auth_headers)
+    assert response.status_code == 201
+    data = response.get_json()['data']
+    assert data['itemcode'] == f"3DP-{data['printeditemid']:04d}"
+    assert data['quantityonhand'] == 0
+
+
+def test_update_refuses_quantity(client, auth_headers, item):
+    response = client.put(f'/api/printedparts/items/{item}',
+                          json={'quantityonhand': 50}, headers=auth_headers)
+    assert response.status_code == 400
+
+
+def test_restock_writes_ledger_and_cache(client, auth_headers, app, item,
+                                         directory_employee):
+    response = client.post(f'/api/printedparts/items/{item}/restock',
+                           json={'quantity': 10, 'badge': directory_employee},
+                           headers=auth_headers)
+    assert response.status_code == 200
+    assert response.get_json()['data']['quantityonhand'] == 10
+    with app.app_context():
+        rows = PrintedItemTransaction.query.filter_by(printeditemid=item).all()
+        assert len(rows) == 1
+        assert rows[0].transactiontype == 'restock'
+        assert rows[0].quantitychange == 10
+        assert rows[0].employeename == 'Pat Printer'
+        cached = db.session.get(PrintedItem, item).quantityonhand
+        assert cached == sum(r.quantitychange for r in rows)
+
+
+def test_payno_badge_shape_resolves(client, auth_headers, item,
+                                    directory_employee):
+    response = client.post(f'/api/printedparts/items/{item}/restock',
+                           json={'quantity': 1,
+                                 'badge': f'0{directory_employee}BZ'},
+                           headers=auth_headers)
+    assert response.status_code == 200
+
+
+def test_adjust_requires_reason_and_floors_at_zero(client, auth_headers, item,
+                                                   directory_employee):
+    no_reason = client.post(f'/api/printedparts/items/{item}/adjust',
+                            json={'quantitychange': -1,
+                                  'badge': directory_employee},
+                            headers=auth_headers)
+    assert no_reason.status_code == 400
+
+    below_zero = client.post(f'/api/printedparts/items/{item}/adjust',
+                             json={'quantitychange': -1, 'reason': 'test',
+                                   'badge': directory_employee},
+                             headers=auth_headers)
+    assert below_zero.status_code == 400
+
+
+def test_unknown_badge_denied_then_allowed_by_policy(client, auth_headers, app,
+                                                     item):
+    denied = client.post(f'/api/printedparts/items/{item}/restock',
+                         json={'quantity': 1, 'badge': '999999999'},
+                         headers=auth_headers)
+    assert denied.status_code == 422
+
+    with app.app_context():
+        Setting.set('printedparts_unknown_badge', 'allow',
+                    valuetype='string', category='printedparts')
+        db.session.commit()
+    try:
+        allowed = client.post(f'/api/printedparts/items/{item}/restock',
+                              json={'quantity': 1, 'badge': '999999999'},
+                              headers=auth_headers)
+        assert allowed.status_code == 200
+        assert allowed.get_json()['data']['quantityonhand'] == 1
+    finally:
+        with app.app_context():
+            Setting.set('printedparts_unknown_badge', 'deny',
+                        valuetype='string', category='printedparts')
+            db.session.commit()
+
+
+def test_anonymous_cannot_mutate(client, item):
+    assert client.post('/api/printedparts/items',
+                       json={'itemname': 'X'}).status_code == 401
+    assert client.post(f'/api/printedparts/items/{item}/restock',
+                       json={'quantity': 1, 'badge': '1'}).status_code == 401
+
+
+def test_member_without_permission_gets_403(client, member_headers, item):
+    """Authentication alone is not authorization: a role-less user is denied."""
+    assert client.post('/api/printedparts/items', json={'itemname': 'X'},
+                       headers=member_headers).status_code == 403
+    assert client.post(f'/api/printedparts/items/{item}/restock',
+                       json={'quantity': 1, 'badge': '1'},
+                       headers=member_headers).status_code == 403
+
+
+def test_kiosk_take_is_open_decrement_only(client, auth_headers, app, item,
+                                           directory_employee):
+    """The kiosk endpoint needs no auth but only ever decrements stock."""
+    itemcode = '3DP-9001'
+    stocked = client.post(f'/api/printedparts/items/{item}/restock',
+                          json={'quantity': 5, 'badge': directory_employee},
+                          headers=auth_headers)
+    assert stocked.status_code == 200
+
+    lookup = client.get(f'/api/printedparts/kiosk/item/{itemcode}')
+    assert lookup.status_code == 200
+
+    take = client.post('/api/printedparts/kiosk/take', json={
+        'itemcode': itemcode, 'badge': directory_employee, 'quantity': 2})
+    assert take.status_code == 200, take.get_json()
+    assert take.get_json()['data']['quantityonhand'] == 3
+
+    too_many = client.post('/api/printedparts/kiosk/take', json={
+        'itemcode': itemcode, 'badge': directory_employee, 'quantity': 99})
+    assert too_many.status_code == 400
+
+    unknown = client.post('/api/printedparts/kiosk/take', json={
+        'itemcode': itemcode, 'badge': '111111111', 'quantity': 1})
+    assert unknown.status_code == 422
+
+    with app.app_context():
+        rows = PrintedItemTransaction.query.filter_by(
+            printeditemid=item, transactiontype='take').all()
+        assert len(rows) == 1
+        assert rows[0].quantitychange == -2
+        assert rows[0].employeename == 'Pat Printer'
+        cached = db.session.get(PrintedItem, item).quantityonhand
+        ledgersum = sum(r.quantitychange for r in
+                        PrintedItemTransaction.query.filter_by(
+                            printeditemid=item).all())
+        assert cached == ledgersum