printedparts stage 13: pick alert recipients from shopdb users

Contract 0.13.0 puts the User model on the plugin surface. The
settings page gains a checkbox picker over the user list; selected
users receive low-stock alerts at their account email, merged and
deduped with the free-text address list, inactive accounts skipped,
site alert_recipients still the fallback when both are empty.

CLAUDE.md

@@ -43,7 +43,7 @@ Refactor phases 0-5 landed; phase 6 (multi-site distribution readiness) largely
 ### Active state
 
 - 966 tests, naming/style check green, Gitea Actions CI (backend + naming + frontend build + a migrations-mysql job that runs the real fresh upgrade on utf8mb4 MySQL 8)
-- `__contract_version__` at 0.12.0 (0.12.0 adds the mailer to the plugin surface) (product `__version__` 0.7.0, tags v0.5.0/v0.6.0/v0.7.0 - distinct series, ADR-007)
+- `__contract_version__` at 0.13.0 (0.12.0 added the mailer, 0.13.0 the User model, to the plugin surface) (product `__version__` 0.7.0, tags v0.5.0/v0.6.0/v0.7.0 - distinct series, ADR-007)
 - 12 bundled plugins all satisfy contract: computers, employees, geenforce, knowledgebase, machines, measuringtools, network, notifications, printers, slides, usb, warranty
 - Core Alembic chain: baseline `68b3947ae14f` -> head `7d25_drop_redundant_indexes` (32 core migrations). Each plugin owns its own chain (ADR-008); deploy runs `flask db upgrade` then `flask plugin upgrade-all`. Reproducible + idempotent from empty (env.py relaxes session sql_mode so the chain runs on strict MySQL 8).
 - Legacy import: `docs/IMPORT-API.md` is the schema-agnostic import contract; `docs/IMPORT-ADOPTION.md` + `docs/PILOT-DEPLOY.md` cover adopting a site; `scripts/site_imports/wjf/` is the West Jefferson reference loader (all 15 stages, validated end-to-end including on a Windows + MySQL 8 VM).

docs/PLUGIN-HOOKS.md

@@ -9,7 +9,7 @@ The contract is locked in [ADR-001](../docs/adr/ADR-001-asset-as-platform-contra
 The framework declares its contract version in `shopdb/__init__.py`:
 
 ```python
-__contract_version__ = '0.12.0'
+__contract_version__ = '0.13.0'
 ```
 
 Each plugin's `manifest.json` declares the range of contract versions it supports:
@@ -479,6 +479,8 @@ What `shopdb.api` exposes:
 - Import mode: `apply_import_timestamps`, `import_mode_active`,
   `parse_import_datetime`
 - Legacy employee directory: `employee_connection`
+- `User` (0.13.0) - the account model, e.g. resolving alert recipients'
+  emails from selected user ids
 - Mailer (0.12.0): `send_email(to, subject, html, text=None)` and
   `send_alert(subject, html, text=None)` - settings-first, no-op safe when
   email is unconfigured; send_alert targets the site's alert_recipients

docs/PLUGIN-LAB-PRINTEDPARTS.md

@@ -306,6 +306,35 @@ CONTRACT ADDITION, because the mailer was not on the plugin surface:
    crossing, no re-fire while below, rearm after restock (see
    `test_lowstock_alert_fires_on_crossing_only`).
 
+## Stage 12 (extension) - the admin settings page
+
+A get_settings_cards card needs a PAGE to link, which is why stage 9 deferred
+it. The page is ordinary:
+1. `frontend/src/views/settings/PrintedPartsSettings.vue` - load the four
+   keys via `settingsApi.list({category: 'printedparts'})`, save each with
+   `settingsApi.update(key, value)` (admin-gated server-side).
+2. Route in the PLUGIN's router file with path `settings/printedparts` +
+   `requiresAuth, requiresAdmin, plugin` meta - the router shell
+   automatically nests any `settings/...` path under the two-pane settings
+   rail.
+3. `get_settings_cards` on the plugin pointing at `/settings/printedparts` -
+   the card appears in the rail's catalog while the plugin is enabled.
+
+## Stage 13 (extension) - alert recipients picked from shopdb users
+
+Free-text emails rot; user accounts do not. Another contract addition:
+`User` joins the surface (0.13.0 - export, PLUGIN-HOOKS, version bump, the
+docs-drift guard again).
+1. Setting `printedparts_alert_userids` (comma-separated user ids), seeded
+   beside the others.
+2. `_alert_recipients()`: resolve each selected id to an ACTIVE user's
+   account email, merge with the free-text list, dedupe order-preserving;
+   empty result still falls back to the site alert_recipients.
+3. Settings page: checkbox picker over `usersApi.list()` (the page is
+   admin-only, matching the endpoint), saving joined ids.
+4. Test: active user's email + free-text merge deduped, inactive user
+   skipped (`test_alert_recipients_merge_users_and_freetext`).
+
 ---
 
 ## Where each pattern lives (cheat sheet)

docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-shopdb-flask is at `__contract_version__ = '0.12.0'` (pre-1.0; product `__version__ 0.7.0`, tags through v0.7.0). This document captures what stands between today and a stable `1.0.0` release. Maintained as scope evolves; supersedes nothing in the ADRs.
+shopdb-flask is at `__contract_version__ = '0.13.0'` (pre-1.0; product `__version__ 0.7.0`, tags through v0.7.0). This document captures what stands between today and a stable `1.0.0` release. Maintained as scope evolves; supersedes nothing in the ADRs.
 
 ## Phase status
 

frontend/src/router/routes/printedparts.js

@@ -31,5 +31,11 @@ export default [
     name: 'printedparts-edit',
     component: () => import('../../views/printedparts/PrintedItemForm.vue'),
     meta: { requiresAuth: true, plugin: 'printedparts' }
+  },
+  {
+    path: 'settings/printedparts',
+    name: 'settings-printedparts',
+    component: () => import('../../views/settings/PrintedPartsSettings.vue'),
+    meta: { requiresAuth: true, requiresAdmin: true, plugin: 'printedparts' }
   }
 ]

frontend/src/views/settings/PrintedPartsSettings.vue

@@ -0,0 +1,152 @@
+<template>
+  <div>
+    <div class="page-header">
+      <h2>3D Printed Parts</h2>
+    </div>
+
+    <div class="card form-card">
+      <div v-if="message" class="settings-success">{{ message }}</div>
+      <div v-if="error" class="error-message">{{ error }}</div>
+
+      <div class="form-group">
+        <label>Item code prefix</label>
+        <input v-model="values.printedparts_code_prefix" type="text"
+               class="form-control" maxlength="8" />
+        <p class="field-hint">
+          New items mint codes like {{ values.printedparts_code_prefix || '3DP' }}-0042.
+          Changing it does not rename existing items.
+        </p>
+      </div>
+
+      <div class="form-group">
+        <label>Default low-stock threshold</label>
+        <input v-model.number="values.printedparts_default_threshold"
+               type="number" min="0" class="form-control" />
+        <p class="field-hint">Seed value for new items; each item can override.</p>
+      </div>
+
+      <div class="form-group">
+        <label>Unknown badge at the kiosk</label>
+        <select v-model="values.printedparts_unknown_badge" class="form-control">
+          <option value="deny">Deny - refuse badges with no directory match</option>
+          <option value="allow">Allow - record the SSO with no name</option>
+        </select>
+      </div>
+
+      <div class="form-group">
+        <label>Alert shopdb users</label>
+        <div class="user-picker">
+          <label v-for="candidate in users" :key="candidate.userid" class="user-row">
+            <input type="checkbox" :value="String(candidate.userid)"
+                   v-model="selectedUserids" />
+            <span>{{ candidate.username }}</span>
+            <span class="user-email">{{ candidate.email }}</span>
+          </label>
+          <p v-if="users.length === 0" class="field-hint">No users loaded</p>
+        </div>
+        <p class="field-hint">
+          Selected users receive low-stock alerts at their account email.
+        </p>
+      </div>
+
+      <div class="form-group">
+        <label>Additional alert emails</label>
+        <input v-model="values.printedparts_alert_email" type="text"
+               class="form-control" placeholder="parts-team@example.com, lead@example.com" />
+        <p class="field-hint">
+          Comma-separated. Empty uses the site-wide alert recipients
+          (Settings &gt; System &gt; Email). Alerts fire once when an item
+          crosses its threshold; restocking above re-arms.
+        </p>
+      </div>
+
+      <button class="btn btn-primary" :disabled="saving" @click="save">
+        {{ saving ? 'Saving...' : 'Save' }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue'
+import { settingsApi, usersApi } from '@/api'
+
+const KEYS = [
+  'printedparts_code_prefix',
+  'printedparts_default_threshold',
+  'printedparts_unknown_badge',
+  'printedparts_alert_email',
+  'printedparts_alert_userids'
+]
+
+const values = ref({
+  printedparts_code_prefix: '3DP',
+  printedparts_default_threshold: 5,
+  printedparts_unknown_badge: 'deny',
+  printedparts_alert_email: '',
+  printedparts_alert_userids: ''
+})
+const users = ref([])
+const selectedUserids = ref([])
+const saving = ref(false)
+const message = ref('')
+const error = ref('')
+
+onMounted(async () => {
+  try {
+    const response = await settingsApi.list({ category: 'printedparts' })
+    const rows = response.data.data || []
+    for (const row of rows) {
+      if (KEYS.includes(row.key)) values.value[row.key] = row.value
+    }
+    values.value.printedparts_default_threshold =
+      parseInt(values.value.printedparts_default_threshold, 10) || 0
+    selectedUserids.value = (values.value.printedparts_alert_userids || '')
+      .split(',').map(id => id.trim()).filter(Boolean)
+    const usersResponse = await usersApi.list()
+    users.value = (usersResponse.data.data || []).filter(
+      candidate => candidate.isactive && candidate.email)
+  } catch (loadError) {
+    error.value = 'Could not load settings'
+    console.error(loadError)
+  }
+})
+
+async function save() {
+  saving.value = true
+  message.value = ''
+  error.value = ''
+  try {
+    values.value.printedparts_alert_userids = selectedUserids.value.join(',')
+    for (const key of KEYS) {
+      await settingsApi.update(key, String(values.value[key] ?? ''))
+    }
+    message.value = 'Settings saved'
+  } catch (saveError) {
+    error.value = saveError.response?.data?.data?.error?.message || 'Save failed'
+  } finally {
+    saving.value = false
+  }
+}
+</script>
+
+<style scoped>
+.field-hint { color: var(--text-light); font-size: 0.85rem; margin-top: 0.25rem; }
+.user-picker {
+  max-height: 12rem;
+  overflow-y: auto;
+  border: 1px solid var(--border);
+  border-radius: 0.35rem;
+  padding: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+.user-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  cursor: pointer;
+}
+.user-email { color: var(--text-light); font-size: 0.85rem; }
+</style>

plugins/printedparts/api/routes.py

@@ -250,6 +250,27 @@ def _ledger_write(item, transactiontype, quantitychange, sso, name, reason=None)
         _send_lowstock_alert(item)
 
 
+def _alert_recipients():
+    """Merge selected shopdb users' account emails with the free-text list.
+
+    Empty result means fall back to the site-wide alert_recipients."""
+    from shopdb.api import User
+    recipients = []
+    userids = (Setting.get('printedparts_alert_userids') or '').strip()
+    for rawid in userids.split(','):
+        rawid = rawid.strip()
+        if not rawid.isdigit():
+            continue
+        user = db.session.get(User, int(rawid))
+        if user and user.isactive and user.email:
+            recipients.append(user.email)
+    extra = (Setting.get('printedparts_alert_email') or '').strip()
+    recipients.extend(address.strip() for address in extra.split(',')
+                      if address.strip())
+    # dedupe, order-preserving
+    return list(dict.fromkeys(recipients))
+
+
 def _send_lowstock_alert(item):
     """Best-effort email when an item crosses its low-stock threshold.
 
@@ -265,10 +286,9 @@ def _send_lowstock_alert(item):
             f'<p>Bin: {item.binlocation or "-"}</p>'
             f'<p>Time to print more.</p>')
     try:
-        recipients = (Setting.get('printedparts_alert_email') or '').strip()
+        recipients = _alert_recipients()
         if recipients:
-            send_email([address.strip() for address in recipients.split(',')
-                        if address.strip()], subject, html)
+            send_email(recipients, subject, html)
         else:
             send_alert(subject, html)
     except Exception:

plugins/printedparts/plugin.py

@@ -62,6 +62,19 @@ class PrintedpartsPlugin(BasePlugin):
              'printedparts'),
         ]
 
+    def get_settings_cards(self) -> List[dict]:
+        return [
+            {
+                'group': '3D Printed Parts',
+                'to': '/settings/printedparts',
+                'icon': 'box',
+                'title': '3D Parts Settings',
+                'description': 'Item code prefix, default threshold, kiosk '
+                               'badge policy, low-stock alert recipients',
+                'position': 47,
+            },
+        ]
+
     def get_reports(self) -> List[dict]:
         return [
             {
@@ -120,6 +133,9 @@ class PrintedpartsPlugin(BasePlugin):
             ('printedparts_alert_email', '', 'string',
              'Comma-separated low-stock alert recipients; empty uses the '
              'site alert_recipients'),
+            ('printedparts_alert_userids', '', 'string',
+             'Comma-separated shopdb user ids whose account emails receive '
+             'low-stock alerts'),
         ]
         for key, value, valuetype, description in defaults:
             if Setting.get(key) is None:

shopdb/__init__.py

@@ -36,7 +36,7 @@ from .plugins import plugin_manager
 # unattended endpoints (e.g. the GE-Enforce fetch API) can authorize a scoped
 # managed service token without importing core token internals. Additive name
 # on the import surface, minor bump.
-__contract_version__ = '0.12.0'
+__contract_version__ = '0.13.0'
 
 # Product release version (see ADR-007). The product version and the
 # plugin-contract version above are distinct series with independent

shopdb/api/__init__.py

@@ -44,6 +44,7 @@ from shopdb.core.models import (
     OperatingSystem,
     AssetRelationship,
     RelationshipType,
+    User,
 )
 
 # Response + pagination helpers for plugin API blueprints
@@ -269,6 +270,7 @@ __all__ = [
     'employee_connection',
     'send_email',
     'send_alert',
+    'User',
     # CMMC USB check-in/out database
     'cmmc_usb_connection',
 ]

tests/test_plugins/test_printedparts_ledger.py

@@ -200,3 +200,43 @@ def test_lowstock_alert_fires_on_crossing_only(client, auth_headers, app, item,
     restock(20)                          # 22: rearmed
     assert take(18).status_code == 200  # 4: crosses again -> second alert
     assert sent == ['3DP-9001', '3DP-9001']
+
+
+def test_alert_recipients_merge_users_and_freetext(client, auth_headers, app,
+                                                   item, directory_employee,
+                                                   monkeypatch):
+    """Selected shopdb users' account emails merge with the free-text list,
+    deduped; inactive users are skipped."""
+    import shopdb.api as contract_surface
+    captured = {}
+    monkeypatch.setattr(contract_surface, 'send_email',
+                        lambda to, subject, html, text=None:
+                        captured.setdefault('to', to) or True)
+
+    with app.app_context():
+        from shopdb.api import User
+        from werkzeug.security import generate_password_hash
+        active = User(username='partslead', email='lead@site.test',
+                      passwordhash=generate_password_hash('x'), isactive=True)
+        inactive = User(username='oldtimer', email='gone@site.test',
+                        passwordhash=generate_password_hash('x'),
+                        isactive=False)
+        db.session.add_all([active, inactive])
+        db.session.commit()
+        Setting.set('printedparts_alert_userids',
+                    f'{active.userid},{inactive.userid}',
+                    valuetype='string', category='printedparts')
+        Setting.set('printedparts_alert_email',
+                    'extra@site.test, lead@site.test',
+                    valuetype='string', category='printedparts')
+        db.session.commit()
+
+    client.post(f'/api/printedparts/items/{item}/restock',
+                json={'quantity': 10, 'badge': directory_employee},
+                headers=auth_headers)
+    take = client.post('/api/printedparts/kiosk/take',
+                       json={'itemcode': '3DP-9001',
+                             'badge': directory_employee, 'quantity': 6})
+    assert take.status_code == 200          # 4 on hand: crossed threshold 5
+
+    assert captured['to'] == ['lead@site.test', 'extra@site.test']