Files

cproudlock 22e623c1f6 Plugin framework maturation, reports overhaul, theming, and USB frontend repair

Framework:
- Per-plugin Alembic migration chains (ADR-008): every bundled plugin
  carries its own chain with a stamp-only anchor at the ownership cutover;
  new plugin schema lands in plugins/<name>/migrations/, never the core
  chain. Deploys add flask plugin upgrade-all. Fixed a latent bug in the
  shared alembic template (engine URL resolution) and taught the metadata
  filter to include FK-referenced core tables.
- Frontend plugin route gating (ADR-009): plugin routes carry meta.plugin;
  a disabled plugin's pages redirect to the dashboard via a cached,
  fail-open check against the new public GET /api/plugins/enabled.
- get_reports() plugin hook (contract 0.5.0 -> 0.6.0): plugins contribute
  report cards; warranty and toner cards moved off the hardcoded list.

Reports:
- Hub grouped by category with search; inline reports render at the top,
  are URL-backed (?report=id, back-button and deep links work), expose
  their server-side filter params as controls, and export CSV. Warranty
  and Toner pages gained CSV export.
- Deleted the dead legacy Warranty Status report (always-zero buckets
  from a retired column).

Theming and fonts:
- Inter (variable) bundled locally via @fontsource, replacing the Google
  Fonts Roboto import - air-gapped installs now render correctly; tables
  use tabular numerals.
- Optional brand_primary_dark_color, brand_accent_color,
  brand_sidebar_color settings applied to CSS vars at bootstrap.

USB frontend repair (views were reading a dead legacy shape):
- List/detail/form and the employee profile USB panels remapped to the
  real API shape (device_id/device_desc/checkinoutlog); employee panels
  now use /usb/checkouts endpoints; external-mode /usb/checkouts/active
  honors the badge filter; dead client methods pruned.

Also: warranties list page no longer requires login (matches app
convention); collector doc rewritten with a GE-Enforce integration guide
and paste-ready PowerShell reporter; ADR index and CHANGELOG updated.

Verified: 323 tests pass, naming/style green, frontend builds, plugin
migration dry-run green on scratch MySQL.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-11 10:01:47 -04:00

4.5 KiB

Raw Blame History

Plugins

shopdb-flask is a framework. The plugins listed here are the pieces other GE Aerospace facilities can install, build, or skip per ADR-003. Bundled plugins ship in the framework repo. External plugins live in their own repos and drop into <repo>/plugins/<name>/ at install time.

Bundled (ship with the framework)

These plugins are in plugins/ in this repo. Enable per site with flask plugin install <name>.

Plugin	Tracks	Notes
`equipment`	Manufacturing machinery: 5-axis mills, lathes, broachers, heat treatment ovens	Manually entered. See ADR-005. Subtype tables for FOCAS / CLM / MTConnect controller protocols (planned).
`computers`	Shop-floor PCs and engineering workstations	Fed by the PXE pipeline collector per ADR-006.
`printers`	Network and shop-floor printers	Optional Zabbix integration for supply tracking. Legacy `PrinterData` retiring per ADR-001.
`network`	Switches, routers, access points, IDFs as locations	Asset-only; cleanest of the bundled set.
`usb`	USB devices issued to shop-floor users	Lightweight checkout / check-in.
`notifications`	Shop-floor notifications, recognitions, kiosk feed	Used by `ShopfloorDashboard.vue`.
`measuringtools`	Metrology and inspection instruments: calipers, micrometers, thread/bore/height gages, indicators	Per ADR-005. Calibration lifecycle with derived status. First plugin built on the matured scaffold; its walkthrough is PLUGIN-GUIDE.md. Ships `default_enabled: false`.

Building your own

Two guides:

PLUGIN-QUICKSTART.md - generate, customize, install, and test a plugin in 30 minutes using flask plugin new.
PLUGIN-GUIDE.md - the full narrative walkthrough of building the measuringtools plugin, the exemplar that exercises every current framework feature (models, per-plugin migrations, authz, hooks, frontend integration, tests).

The contract is locked in ADR-001 and versioned per ADR-002.

Quick path:

flask plugin new cameras --description "Tracks shop-floor surveillance cameras"
# edit plugins/cameras/models/cameras.py with your fields
flask plugin install cameras

Migrations (per-plugin chains)

Each plugin that owns tables carries its own Alembic chain under plugins/<name>/migrations/, with a per-plugin version table alembic_version_<name> independent of the core alembic_version. Ownership is split at a fixed cutover (see ADR-008):

The core chain (flask db upgrade) created every table that existed through its head, including the bundled-plugin tables. Each bundled plugin's 0001 migration is a stamp-only no-op anchor recording that fact.
From the cutover forward, a change to a plugin's schema lands as plugins/<name>/migrations/versions/000N_*.py, never in the core chain. The core chain is reserved for core tables.
A plugin built AFTER the cutover (e.g. measuringtools) is different: the core chain never created its tables, so its 0001 is a REAL baseline that creates them, not a no-op anchor. See PLUGIN-GUIDE.md for the anchor-vs-baseline distinction.

Deploys and upgrades run flask db upgrade then flask plugin upgrade-all. upgrade-all stamps every plugin anchor and applies any later plugin migrations; it is idempotent. The registry (instance/plugins.json) records which revisions each plugin has applied in migrations_applied.

Distribution conventions

For sister-site plugins (per ADR-003):

Plugin lives in its own git repo: gitea.proudtech.net/<your-site>/<pluginname>
Adopting site clones or symlinks into their <repo>/plugins/<name>/
Plugin manifest declares core_version range matching the framework version they target
Plugin readme explains: what it tracks, who maintains it, where to file issues

Naming policy

Plugin names follow the framework's naming convention (lowercase concatenated, no underscores or dashes; full words preferred over acronyms). See CONTRIBUTING.md. Plugin name collisions across sites are not enforced; the convention recommends prefixing site-specific plugins with the site code (e.g., wjsf-shippingstation) when there is risk of overlap.

4.5 KiB Raw Blame History