From cb367a38f9e40d516aca0b44578c0c5fa3e59b61 Mon Sep 17 00:00:00 2001
From: cproudlock <cproudlock@localhost>
Date: Fri, 17 Jul 2026 07:36:54 -0400
Subject: [PATCH] printedparts stage 4: catalog mutations, item photos, detail
 + form

POST/PUT/DELETE for items: create mints the itemcode from the
configured prefix plus the flushed row id, update refuses
quantityonhand (ledger-managed - restock/adjust arrive next stage),
delete soft-retires. The image upload/serve/delete trio replicates the
models.py pattern into instance/printedpartsimages/ with a public GET.
PrintedItemDetail follows the unified detail skeleton (hero photo,
info list, transaction history table); PrintedItemForm covers
create/edit plus photo management on edit.
---
 frontend/src/api/index.js                     |  19 ++
 .../views/printedparts/PrintedItemDetail.vue  | 214 ++++++-------
 .../views/printedparts/PrintedItemForm.vue    | 288 +++++++-----------
 plugins/printedparts/api/routes.py            | 146 +++++++++
 4 files changed, 379 insertions(+), 288 deletions(-)

diff --git a/frontend/src/api/index.js b/frontend/src/api/index.js
index e02d22e..5684439 100644
--- a/frontend/src/api/index.js
+++ b/frontend/src/api/index.js
@@ -1134,5 +1134,24 @@ export const printedpartsApi = {
   },
   get(printeditemid) {
     return api.get(`/printedparts/items/${printeditemid}`)
+  },
+  create(data) {
+    return api.post('/printedparts/items', data)
+  },
+  update(printeditemid, data) {
+    return api.put(`/printedparts/items/${printeditemid}`, data)
+  },
+  remove(printeditemid) {
+    return api.delete(`/printedparts/items/${printeditemid}`)
+  },
+  uploadImage(printeditemid, file) {
+    const formData = new FormData()
+    formData.append('file', file)
+    return api.post(`/printedparts/items/${printeditemid}/image`, formData, {
+      headers: { 'Content-Type': 'multipart/form-data' }
+    })
+  },
+  deleteImage(printeditemid) {
+    return api.delete(`/printedparts/items/${printeditemid}/image`)
   }
 }
diff --git a/frontend/src/views/printedparts/PrintedItemDetail.vue b/frontend/src/views/printedparts/PrintedItemDetail.vue
index be6a777..2c370a3 100644
--- a/frontend/src/views/printedparts/PrintedItemDetail.vue
+++ b/frontend/src/views/printedparts/PrintedItemDetail.vue
@@ -1,149 +1,133 @@
 <template>
-  <div class="detail-page" v-if="item">
-    <div class="hero-card">
-      <div class="hero-content">
-        <div class="hero-title-row">
-          <h1 class="hero-title">{{ item.name || item.assetnumber || 'Printedparts' }}</h1>
-          <router-link
-            v-if="authStore.isAuthenticated"
-            :to="`/printedparts/${itemId}/edit`"
-            class="btn btn-secondary"
-          >
-            Edit
-          </router-link>
-        </div>
-        <div class="hero-details">
-          <div class="detail-item" v-if="item.assetnumber">
-            <span class="label">Asset #</span>
-            <span class="value">{{ item.assetnumber }}</span>
+  <div class="detail-page">
+    <div v-if="loading" class="loading">Loading...</div>
+
+    <template v-else-if="item">
+      <div class="hero-card">
+        <img v-if="item.imageurl" :src="withBase(item.imageurl)"
+             :alt="item.itemname" class="hero-image" />
+        <div class="hero-content">
+          <h2 class="hero-title">{{ item.itemname }}</h2>
+          <div class="hero-meta">
+            <span class="badge badge-secondary">{{ item.itemcode }}</span>
+            <span :class="['badge', item.islowstock ? 'badge-danger' : 'badge-success']">
+              {{ item.quantityonhand }} on hand
+            </span>
+            <span v-if="item.islowstock" class="badge badge-warning">Low stock</span>
           </div>
-          <div class="detail-item" v-if="item.serialnumber">
-            <span class="label">Serial</span>
-            <span class="value mono">{{ item.serialnumber }}</span>
+          <div class="hero-details">
+            <p v-if="item.itemdescription">{{ item.itemdescription }}</p>
+          </div>
+          <div class="hero-actions">
+            <router-link :to="`/printedparts/${item.printeditemid}/edit`"
+                         class="btn btn-secondary btn-sm">Edit</router-link>
           </div>
         </div>
       </div>
-    </div>
 
-    <div class="content-grid">
-      <div class="content-column">
-        <div class="section-card">
-          <h3 class="section-title">Printedparts Information</h3>
-          <div class="info-list">
-            <div class="info-row">
-              <span class="info-label">Example Field</span>
-              <span class="info-value">{{ item.examplefield || '-' }}</span>
+      <div class="content-grid">
+        <div class="content-column">
+          <div class="section-card">
+            <h3 class="section-title">Details</h3>
+            <div class="info-list">
+              <div class="info-row">
+                <span class="info-label">Item code</span>
+                <span class="info-value">{{ item.itemcode }}</span>
+              </div>
+              <div class="info-row">
+                <span class="info-label">Bin location</span>
+                <span class="info-value">{{ item.binlocation || '-' }}</span>
+              </div>
+              <div class="info-row">
+                <span class="info-label">Quantity on hand</span>
+                <span class="info-value">{{ item.quantityonhand }}</span>
+              </div>
+              <div class="info-row">
+                <span class="info-label">Low-stock threshold</span>
+                <span class="info-value">{{ item.lowstockthreshold }}</span>
+              </div>
+              <div class="info-row" v-if="item.printnotes">
+                <span class="info-label">Print notes</span>
+                <span class="info-value">{{ item.printnotes }}</span>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="content-column">
+          <div class="section-card">
+            <h3 class="section-title">Recent transactions</h3>
+            <div class="table-container">
+              <table>
+                <thead>
+                  <tr>
+                    <th>When</th>
+                    <th>Type</th>
+                    <th>Qty</th>
+                    <th>Who</th>
+                    <th>Reason</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr v-for="transaction in item.recenttransactions"
+                      :key="transaction.transactionid">
+                    <td>{{ formatDate(transaction.transactiondate) }}</td>
+                    <td>{{ transaction.transactiontype }}</td>
+                    <td :class="transaction.quantitychange < 0 ? 'qty-out' : 'qty-in'">
+                      {{ transaction.quantitychange > 0 ? '+' : '' }}{{ transaction.quantitychange }}
+                    </td>
+                    <td>{{ transaction.employeename || transaction.employeesso }}</td>
+                    <td>{{ transaction.reason || '-' }}</td>
+                  </tr>
+                  <tr v-if="!item.recenttransactions?.length">
+                    <td colspan="5" class="empty-state">No transactions yet</td>
+                  </tr>
+                </tbody>
+              </table>
             </div>
           </div>
         </div>
       </div>
 
-      <div class="content-column">
-        <div class="section-card">
-          <h3 class="section-title">Asset Information</h3>
-          <div class="info-list">
-            <div class="info-row">
-              <span class="info-label">Asset Number</span>
-              <span class="info-value">{{ item.assetnumber || '-' }}</span>
-            </div>
-            <div class="info-row">
-              <span class="info-label">Name</span>
-              <span class="info-value">{{ item.name || '-' }}</span>
-            </div>
-            <div class="info-row">
-              <span class="info-label">Serial Number</span>
-              <span class="info-value mono">{{ item.serialnumber || '-' }}</span>
-            </div>
-          </div>
-        </div>
+      <div class="audit-footer">
+        Created {{ formatDate(item.createddate) }} -
+        Modified {{ formatDate(item.modifieddate) }}
       </div>
-    </div>
+    </template>
 
-    <div class="action-bar" v-if="authStore.isAuthenticated">
-      <router-link :to="`/printedparts/${itemId}/edit`" class="btn btn-primary">Edit</router-link>
-      <button @click="confirmDelete" class="btn btn-danger">Delete</button>
-    </div>
-  </div>
-
-  <div v-else-if="loading" class="loading-container">
-    <div class="loading">Loading...</div>
-  </div>
-
-  <div v-else class="error-container">
-    <p>Record not found</p>
-    <router-link to="/printedparts" class="btn btn-secondary">Back to Printedparts</router-link>
+    <div v-else class="card">Item not found</div>
   </div>
 </template>
 
 <script setup>
 import { ref, onMounted } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
-import api from '../../api'
-import { useAuthStore } from '../../stores/auth'
-
-// local api client. move into src/api/index.js (see
-// plugins/printedparts/frontend-api-snippet.js) then swap for:
-//   import { printedpartsApi } from '../../api'
-const printedpartsApi = {
-  list(params = {}) { return api.get('/printedparts', { params }) },
-  get(itemId) { return api.get(`/printedparts/${itemId}`) },
-  create(data) { return api.post('/printedparts', data) },
-  update(itemId, data) { return api.put(`/printedparts/${itemId}`, data) },
-  remove(itemId) { return api.delete(`/printedparts/${itemId}`) }
-}
+import { useRoute } from 'vue-router'
+import { printedpartsApi } from '../../api'
+import { withBase } from '../../utils/basePath'
 
 const route = useRoute()
-const router = useRouter()
-const authStore = useAuthStore()
-
-const itemId = route.params.id
 const item = ref(null)
 const loading = ref(true)
 
-onMounted(loadItem)
-
-async function loadItem() {
-  loading.value = true
+onMounted(async () => {
   try {
-    const response = await printedpartsApi.get(itemId)
+    const response = await printedpartsApi.get(route.params.id)
     item.value = response.data.data
-  } catch (error) {
-    console.error('Error loading printedparts:', error)
-    item.value = null
+  } catch (loadError) {
+    console.error('Error loading printed item:', loadError)
   } finally {
     loading.value = false
   }
-}
+})
 
-async function confirmDelete() {
-  if (confirm('Delete this record?')) {
-    try {
-      await printedpartsApi.remove(itemId)
-      router.push('/printedparts')
-    } catch (error) {
-      console.error('Error deleting printedparts:', error)
-    }
-  }
+function formatDate(value) {
+  if (!value) return '-'
+  return new Date(value).toLocaleString()
 }
 </script>
 
 <style scoped>
-.mono {
-  font-family: 'SF Mono', 'Monaco', 'Consolas', monospace;
-}
-
-.action-bar {
-  display: flex;
-  gap: 1rem;
-  margin-top: 2rem;
-  padding-top: 1.5rem;
-  border-top: 1px solid var(--border);
-}
-
-.loading-container,
-.error-container {
-  text-align: center;
-  padding: 3rem;
-  color: var(--text-light);
-}
+.hero-actions { margin-top: 0.75rem; }
+.qty-out { color: var(--danger); }
+.qty-in { color: var(--success); }
 </style>
diff --git a/frontend/src/views/printedparts/PrintedItemForm.vue b/frontend/src/views/printedparts/PrintedItemForm.vue
index 32e1036..10058d0 100644
--- a/frontend/src/views/printedparts/PrintedItemForm.vue
+++ b/frontend/src/views/printedparts/PrintedItemForm.vue
@@ -1,74 +1,66 @@
 <template>
   <div>
     <div class="page-header">
-      <h2>{{ isEdit ? 'Edit Printedparts' : 'Add Printedparts' }}</h2>
+      <h2>{{ isEdit ? 'Edit Part' : 'Add Part' }}</h2>
     </div>
 
     <div class="card form-card">
-      <form @submit.prevent="submitForm">
-        <fieldset>
-          <legend>Asset Information</legend>
+      <div v-if="error" class="error-message">{{ error }}</div>
 
-          <div class="form-row">
-            <div class="form-group">
-              <label for="assetnumber">Asset Number *</label>
-              <input
-                id="assetnumber"
-                v-model="form.assetnumber"
-                type="text"
-                class="form-control"
-                required
-                :disabled="isEdit"
-              />
-            </div>
-            <div class="form-group">
-              <label for="name">Name</label>
-              <input
-                id="name"
-                v-model="form.name"
-                type="text"
-                class="form-control"
-              />
-            </div>
+      <form @submit.prevent="save">
+        <div class="form-row">
+          <div class="form-group">
+            <label>Name *</label>
+            <input v-model="form.itemname" type="text" class="form-control" required />
           </div>
-
-          <div class="form-row">
-            <div class="form-group">
-              <label for="serialnumber">Serial Number</label>
-              <input
-                id="serialnumber"
-                v-model="form.serialnumber"
-                type="text"
-                class="form-control"
-              />
-            </div>
+          <div class="form-group">
+            <label>Bin location</label>
+            <input v-model="form.binlocation" type="text" class="form-control"
+                   placeholder="e.g., Bin A3" />
           </div>
-        </fieldset>
-
-        <fieldset>
-          <legend>Printedparts Details</legend>
-
-          <div class="form-row">
-            <div class="form-group">
-              <label for="examplefield">Example Field</label>
-              <input
-                id="examplefield"
-                v-model="form.examplefield"
-                type="text"
-                class="form-control"
-              />
-            </div>
-          </div>
-        </fieldset>
-
-        <div class="form-actions">
-          <button type="button" class="btn btn-secondary" @click="cancel">Cancel</button>
-          <button type="submit" class="btn btn-primary" :disabled="saving">
-            {{ saving ? 'Saving...' : (isEdit ? 'Save Changes' : 'Create') }}
-          </button>
         </div>
 
-        <div v-if="error" class="error-message">{{ error }}</div>
+        <div class="form-group">
+          <label>Description</label>
+          <input v-model="form.itemdescription" type="text" class="form-control"
+                 maxlength="500" placeholder="Brief description shown on the storefront" />
+        </div>
+
+        <div class="form-row">
+          <div class="form-group">
+            <label>Low-stock threshold</label>
+            <input v-model.number="form.lowstockthreshold" type="number" min="0"
+                   class="form-control" />
+          </div>
+          <div v-if="isEdit" class="form-group">
+            <label>Item code</label>
+            <input :value="itemcode" type="text" class="form-control" disabled />
+          </div>
+        </div>
+
+        <div class="form-group">
+          <label>Print notes</label>
+          <textarea v-model="form.printnotes" class="form-control" rows="3"
+                    placeholder="Material, print time, slicer file path"></textarea>
+        </div>
+
+        <div v-if="isEdit" class="form-group">
+          <label>Photo</label>
+          <div class="image-row">
+            <img v-if="imageurl" :src="withBase(imageurl)" class="image-preview" />
+            <input type="file" accept="image/*" @change="onImagePicked" />
+            <button v-if="imageurl" type="button" class="btn btn-secondary btn-sm"
+                    @click="removeImage">Remove photo</button>
+          </div>
+        </div>
+        <p v-else class="form-hint">Save first, then add a photo from the edit page.</p>
+
+        <div class="form-actions">
+          <button type="submit" class="btn btn-primary" :disabled="saving">
+            {{ saving ? 'Saving...' : 'Save' }}
+          </button>
+          <router-link :to="cancelTarget" class="btn btn-secondary">Cancel</router-link>
+        </div>
       </form>
     </div>
   </div>
@@ -77,152 +69,102 @@
 <script setup>
 import { ref, computed, onMounted } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
-import api from '../../api'
-
-// local api client. move into src/api/index.js (see
-// plugins/printedparts/frontend-api-snippet.js) then swap for:
-//   import { printedpartsApi } from '../../api'
-const printedpartsApi = {
-  list(params = {}) { return api.get('/printedparts', { params }) },
-  get(itemId) { return api.get(`/printedparts/${itemId}`) },
-  create(data) { return api.post('/printedparts', data) },
-  update(itemId, data) { return api.put(`/printedparts/${itemId}`, data) },
-  remove(itemId) { return api.delete(`/printedparts/${itemId}`) }
-}
+import { printedpartsApi } from '../../api'
+import { withBase } from '../../utils/basePath'
 
 const route = useRoute()
 const router = useRouter()
 
-const itemId = route.params.id
-const isEdit = computed(() => !!itemId)
+const isEdit = computed(() => !!route.params.id)
+const cancelTarget = computed(() =>
+  isEdit.value ? `/printedparts/${route.params.id}` : '/printedparts')
 
 const form = ref({
-  assetnumber: '',
-  name: '',
-  serialnumber: '',
-  examplefield: ''
+  itemname: '',
+  itemdescription: '',
+  lowstockthreshold: null,
+  binlocation: '',
+  printnotes: ''
 })
+const itemcode = ref('')
+const imageurl = ref(null)
 const saving = ref(false)
 const error = ref('')
 
 onMounted(async () => {
-  if (isEdit.value) {
-    await loadItem()
+  if (!isEdit.value) return
+  try {
+    const response = await printedpartsApi.get(route.params.id)
+    const item = response.data.data
+    for (const key of Object.keys(form.value)) {
+      form.value[key] = item[key]
+    }
+    itemcode.value = item.itemcode
+    imageurl.value = item.imageurl
+  } catch (loadError) {
+    error.value = 'Could not load the item'
+    console.error(loadError)
   }
 })
 
-async function loadItem() {
-  try {
-    const response = await printedpartsApi.get(itemId)
-    const data = response.data.data
-    form.value.assetnumber = data.assetnumber || ''
-    form.value.name = data.name || ''
-    form.value.serialnumber = data.serialnumber || ''
-    form.value.examplefield = data.examplefield || ''
-  } catch (loadError) {
-    console.error('Error loading printedparts:', loadError)
-    error.value = 'Failed to load record'
-  }
-}
-
-async function submitForm() {
+async function save() {
   saving.value = true
   error.value = ''
-
   try {
-    const payload = {
-      assetnumber: form.value.assetnumber,
-      name: form.value.name || null,
-      serialnumber: form.value.serialnumber || null,
-      examplefield: form.value.examplefield || null
+    const payload = { ...form.value }
+    if (payload.lowstockthreshold === null || payload.lowstockthreshold === '') {
+      delete payload.lowstockthreshold
     }
-
-    let redirectId = itemId
+    let printeditemid
     if (isEdit.value) {
-      await printedpartsApi.update(itemId, payload)
+      await printedpartsApi.update(route.params.id, payload)
+      printeditemid = route.params.id
     } else {
       const response = await printedpartsApi.create(payload)
-      redirectId = response.data.data?.assetid
+      printeditemid = response.data.data.printeditemid
     }
-
-    router.push(redirectId ? `/printedparts/${redirectId}` : '/printedparts')
-  } catch (submitError) {
-    console.error('Error saving printedparts:', submitError)
-    error.value = 'Failed to save record'
+    router.push(`/printedparts/${printeditemid}`)
+  } catch (saveError) {
+    error.value = saveError.response?.data?.error?.message || 'Save failed'
   } finally {
     saving.value = false
   }
 }
 
-function cancel() {
-  if (isEdit.value) {
-    router.push(`/printedparts/${itemId}`)
-  } else {
-    router.push('/printedparts')
+async function onImagePicked(event) {
+  const file = event.target.files?.[0]
+  if (!file) return
+  try {
+    const response = await printedpartsApi.uploadImage(route.params.id, file)
+    imageurl.value = response.data.data.imageurl
+  } catch (uploadError) {
+    error.value = uploadError.response?.data?.error?.message || 'Image upload failed'
+  }
+}
+
+async function removeImage() {
+  try {
+    await printedpartsApi.deleteImage(route.params.id)
+    imageurl.value = null
+  } catch (deleteError) {
+    error.value = 'Could not remove the image'
+    console.error(deleteError)
   }
 }
 </script>
 
 <style scoped>
-.form-card {
-  max-width: 800px;
+.image-row {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
 }
-
-fieldset {
+.image-preview {
+  width: 6rem;
+  height: 6rem;
+  object-fit: cover;
+  border-radius: 0.35rem;
   border: 1px solid var(--border);
-  border-radius: 8px;
-  padding: 1.5rem;
-  margin-bottom: 1.5rem;
-}
-
-legend {
-  font-weight: 600;
-  padding: 0 0.5rem;
-  color: var(--text);
-}
-
-.form-row {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 1rem;
-  margin-bottom: 1rem;
-}
-
-.form-row:last-child {
-  margin-bottom: 0;
-}
-
-.form-group {
-  display: flex;
-  flex-direction: column;
-}
-
-.form-group label {
-  margin-bottom: 0.375rem;
-  font-weight: 500;
-  color: var(--text);
-}
-
-.form-actions {
-  display: flex;
-  gap: 1rem;
-  justify-content: flex-end;
-  margin-top: 1.5rem;
-  padding-top: 1.5rem;
-  border-top: 1px solid var(--border);
-}
-
-.error-message {
-  margin-top: 1rem;
-  padding: 0.75rem 1rem;
-  background: var(--danger);
-  color: white;
-  border-radius: 6px;
-}
-
-@media (max-width: 600px) {
-  .form-row {
-    grid-template-columns: 1fr;
-  }
 }
+.form-hint { color: var(--text-light); }
 </style>
diff --git a/plugins/printedparts/api/routes.py b/plugins/printedparts/api/routes.py
index 6028e8d..8cb7753 100644
--- a/plugins/printedparts/api/routes.py
+++ b/plugins/printedparts/api/routes.py
@@ -64,3 +64,149 @@ def get_item(item_id: int):
               .limit(25).all())
     data['recenttransactions'] = [t.to_dict() for t in recent]
     return success_response(data)
+
+
+# --- catalog mutations (stage 6 adds permission gates on top of jwt) --------
+
+import glob
+import os
+
+from flask import current_app
+from werkzeug.utils import secure_filename
+
+from shopdb.api import Setting
+
+IMAGE_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.gif', '.webp'}
+IMAGE_URL_PREFIX = '/api/printedparts/image/'
+
+EDITABLE_FIELDS = ('itemname', 'itemdescription', 'lowstockthreshold',
+                   'binlocation', 'printnotes')
+
+
+def _imagedir():
+    return os.path.join(current_app.instance_path, 'printedpartsimages')
+
+
+def _mint_itemcode(item):
+    """Set itemcode from the configured prefix + the flushed row id."""
+    prefix = Setting.get('printedparts_code_prefix') or '3DP'
+    item.itemcode = f'{prefix}-{item.printeditemid:04d}'
+
+
+@printedparts_bp.route('/items', methods=['POST'])
+@jwt_required()
+def create_item():
+    """Create a printed item; the itemcode is minted from the row id."""
+    data = request.get_json() or {}
+    itemname = (data.get('itemname') or '').strip()
+    if not itemname:
+        return error_response(ErrorCodes.VALIDATION_ERROR, 'itemname is required')
+
+    threshold = data.get('lowstockthreshold')
+    if threshold is None:
+        threshold = int(Setting.get('printedparts_default_threshold') or 5)
+
+    item = PrintedItem(
+        itemname=itemname,
+        itemdescription=data.get('itemdescription'),
+        lowstockthreshold=threshold,
+        binlocation=data.get('binlocation'),
+        printnotes=data.get('printnotes'),
+        quantityonhand=0,
+    )
+    db.session.add(item)
+    db.session.flush()          # assigns printeditemid
+    _mint_itemcode(item)
+    db.session.commit()
+    return success_response(item.to_dict(), message='Printed item created',
+                            http_code=201)
+
+
+@printedparts_bp.route('/items/<int:item_id>', methods=['PUT'])
+@jwt_required()
+def update_item(item_id: int):
+    """Update catalog fields. Quantity moves ONLY through the ledger."""
+    item = db.session.get(PrintedItem, item_id)
+    if not item:
+        return error_response(ErrorCodes.NOT_FOUND,
+                              f'Printed item {item_id} not found', http_code=404)
+    data = request.get_json() or {}
+    if 'quantityonhand' in data:
+        return error_response(
+            ErrorCodes.VALIDATION_ERROR,
+            'quantityonhand is ledger-managed; use restock or adjust')
+    for field in EDITABLE_FIELDS:
+        if field in data:
+            setattr(item, field, data[field])
+    db.session.commit()
+    return success_response(item.to_dict(), message='Printed item updated')
+
+
+@printedparts_bp.route('/items/<int:item_id>', methods=['DELETE'])
+@jwt_required()
+def delete_item(item_id: int):
+    """Soft-retire an item; its ledger history stays."""
+    item = db.session.get(PrintedItem, item_id)
+    if not item:
+        return error_response(ErrorCodes.NOT_FOUND,
+                              f'Printed item {item_id} not found', http_code=404)
+    item.isactive = False
+    db.session.commit()
+    return success_response(message='Printed item retired')
+
+
+# --- item image: the models.py upload/serve/delete trio ---------------------
+
+@printedparts_bp.route('/items/<int:item_id>/image', methods=['POST'])
+@jwt_required()
+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)
+    if not item:
+        return error_response(ErrorCodes.NOT_FOUND,
+                              f'Printed item {item_id} not found', http_code=404)
+    upload = request.files.get('file')
+    if not upload or not upload.filename:
+        return error_response(ErrorCodes.VALIDATION_ERROR, 'No file provided')
+    ext = os.path.splitext(upload.filename)[1].lower()
+    if ext not in IMAGE_EXTENSIONS:
+        return error_response(ErrorCodes.VALIDATION_ERROR,
+                              f'Unsupported image type {ext}')
+
+    imagedir = _imagedir()
+    os.makedirs(imagedir, exist_ok=True)
+    for old in glob.glob(os.path.join(
+            imagedir, secure_filename(f'printeditem-{item_id}') + '.*')):
+        os.remove(old)
+
+    filename = secure_filename(f'printeditem-{item_id}{ext}')
+    upload.save(os.path.join(imagedir, filename))
+    item.imageurl = f'{IMAGE_URL_PREFIX}{filename}'
+    db.session.commit()
+    return success_response(item.to_dict(), message='Item image uploaded')
+
+
+@printedparts_bp.route('/image/<path:filename>', methods=['GET'])
+def serve_item_image(filename):
+    """Serve an uploaded item image (public - kiosk and list read it)."""
+    from flask import send_from_directory
+    return send_from_directory(_imagedir(), filename)
+
+
+@printedparts_bp.route('/items/<int:item_id>/image', methods=['DELETE'])
+@jwt_required()
+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)
+    if not item:
+        return error_response(ErrorCodes.NOT_FOUND,
+                              f'Printed item {item_id} not found', http_code=404)
+    url = item.imageurl or ''
+    if url.startswith(IMAGE_URL_PREFIX):
+        filename = secure_filename(url[len(IMAGE_URL_PREFIX):])
+        path = os.path.join(_imagedir(), filename)
+        if os.path.exists(path):
+            os.remove(path)
+    item.imageurl = None
+    db.session.commit()
+    return success_response(item.to_dict(), message='Item image removed')