From a8a6baf979fbfc4c1a7d0ab01b073b1ddf4ecf3c Mon Sep 17 00:00:00 2001
From: cproudlock <cproudlock@localhost>
Date: Fri, 17 Jul 2026 08:30:04 -0400
Subject: [PATCH] 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                                     |  2 +-
 docs/PLUGIN-HOOKS.md                          |  4 +-
 docs/PLUGIN-LAB-PRINTEDPARTS.md               | 15 ++++++
 docs/ROADMAP.md                               |  2 +-
 .../views/settings/PrintedPartsSettings.vue   | 51 +++++++++++++++++--
 plugins/printedparts/api/routes.py            | 26 ++++++++--
 plugins/printedparts/plugin.py                |  3 ++
 shopdb/__init__.py                            |  2 +-
 shopdb/api/__init__.py                        |  2 +
 .../test_plugins/test_printedparts_ledger.py  | 40 +++++++++++++++
 10 files changed, 136 insertions(+), 11 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index adc9001..3516a50 100644
--- a/CLAUDE.md
+++ b/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).
diff --git a/docs/PLUGIN-HOOKS.md b/docs/PLUGIN-HOOKS.md
index 4c32eff..05f47d8 100644
--- a/docs/PLUGIN-HOOKS.md
+++ b/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
diff --git a/docs/PLUGIN-LAB-PRINTEDPARTS.md b/docs/PLUGIN-LAB-PRINTEDPARTS.md
index 44116ba..75b53a9 100644
--- a/docs/PLUGIN-LAB-PRINTEDPARTS.md
+++ b/docs/PLUGIN-LAB-PRINTEDPARTS.md
@@ -320,6 +320,21 @@ it. The page is ordinary:
 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)
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index f460428..6e83d00 100644
--- a/docs/ROADMAP.md
+++ b/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
 
diff --git a/frontend/src/views/settings/PrintedPartsSettings.vue b/frontend/src/views/settings/PrintedPartsSettings.vue
index 605d40a..d06096e 100644
--- a/frontend/src/views/settings/PrintedPartsSettings.vue
+++ b/frontend/src/views/settings/PrintedPartsSettings.vue
@@ -34,7 +34,23 @@
       </div>
 
       <div class="form-group">
-        <label>Low-stock alert recipients</label>
+        <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">
@@ -53,21 +69,25 @@
 
 <script setup>
 import { ref, onMounted } from 'vue'
-import { settingsApi } from '@/api'
+import { settingsApi, usersApi } from '@/api'
 
 const KEYS = [
   'printedparts_code_prefix',
   'printedparts_default_threshold',
   'printedparts_unknown_badge',
-  'printedparts_alert_email'
+  '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_email: '',
+  printedparts_alert_userids: ''
 })
+const users = ref([])
+const selectedUserids = ref([])
 const saving = ref(false)
 const message = ref('')
 const error = ref('')
@@ -81,6 +101,11 @@ onMounted(async () => {
     }
     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)
@@ -92,6 +117,7 @@ async function save() {
   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] ?? ''))
     }
@@ -106,4 +132,21 @@ async function save() {
 
 <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>
diff --git a/plugins/printedparts/api/routes.py b/plugins/printedparts/api/routes.py
index 1ac9408..f44f3bf 100644
--- a/plugins/printedparts/api/routes.py
+++ b/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:
diff --git a/plugins/printedparts/plugin.py b/plugins/printedparts/plugin.py
index ee7cd3e..f2327b2 100644
--- a/plugins/printedparts/plugin.py
+++ b/plugins/printedparts/plugin.py
@@ -133,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:
diff --git a/shopdb/__init__.py b/shopdb/__init__.py
index 19cef02..a209c4d 100644
--- a/shopdb/__init__.py
+++ b/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
diff --git a/shopdb/api/__init__.py b/shopdb/api/__init__.py
index 88cb7fd..ae0f605 100644
--- a/shopdb/api/__init__.py
+++ b/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',
 ]
diff --git a/tests/test_plugins/test_printedparts_ledger.py b/tests/test_plugins/test_printedparts_ledger.py
index fc53323..7835216 100644
--- a/tests/test_plugins/test_printedparts_ledger.py
+++ b/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']