ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

printedparts stage 11: low-stock email alerts on threshold crossing
Some checks failed
CI / backend (push) Successful in 1m43s
Details
CI / naming (push) Successful in 1s
Details
CI / frontend (push) Successful in 8s
Details
CI / migrations-mysql (push) Failing after 8s
Details

Browse Source 
Contract 0.12.0: send_email/send_alert join the plugin surface (the
mailer was core-only), PLUGIN-HOOKS and status docs updated, manifest
pins the new floor. The alert fires inside _ledger_write only when a
decrement CROSSES the item's threshold - one alert per depletion,
rearmed by restocking above - and is best-effort after the commit so
mail trouble can never fail a take. Recipients come from
printedparts_alert_email, falling back to the site alert_recipients.
on_enable re-seeds settings idempotently so existing installs pick up
new keys. Crossing/rearm semantics proven by test.
This commit is contained in:
cproudlock
2026-07-17 08:15:50 -04:00
parent fc0d48a6a7
commit df918ed38f
10 changed files with 110 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/PLUGIN-LAB-PRINTEDPARTS.md
View File

@@ -286,6 +286,26 @@ Done means: a colleague can clone the repo, enable the plugin, print a bin
label, and take a part at the kiosk with their badge - without asking you
anything.
## Stage 11 (extension) - low-stock email alerts
Per-item thresholds already exist; alerting on them is a worked example of a
CONTRACT ADDITION, because the mailer was not on the plugin surface:
1. Export `send_email`/`send_alert` from `shopdb/api/__init__.py`, bump
`__contract_version__` 0.11.0 -> 0.12.0, and update PLUGIN-HOOKS.md - the
docs-drift guard test fails until the doc's version example matches.
Manifest pins `core_version >=0.12.0` since the plugin now needs it.
2. Fire the alert inside `_ledger_write` when a DECREMENT crosses the
threshold (before > threshold >= after). Crossing, not being-below, is the
natural debounce: one alert per depletion, restocking above rearms.
Best-effort try/except AFTER the commit - mail failure must never fail
the take.
3. Recipients: Setting `printedparts_alert_email` (comma-separated), empty
falls back to the site's alert_recipients via `send_alert`. Seed the new
setting in on_enable too (idempotent) so already-installed sites get it.
4. Test with a monkeypatched sender: no alert above threshold, one on the
crossing, no re-fire while below, rearm after restock (see
`test_lowstock_alert_fires_on_crossing_only`).
---
## Where each pattern lives (cheat sheet)