4995456136
The publishability gate caught internal tooling names and developer paths but nothing site-specific, so roughly sixty leaks reached the wiki: the site name in ten documents, real fleet hostnames in the collector and GE-Enforce examples, an internal database name through the whole import guide, imaging-share paths, and a maintainer's username as the Deciders line of every ADR and inside a generated curl example. None of it is a security matter on an air-gapped fleet. It matters because these pages are read by engineers at other plants, and a document that names one site throughout reads as that site's notes rather than a product's documentation - which is exactly what it then gets treated as. Examples now use neutral hostnames, the site is "the reference site" where the distinction carries meaning, and ADRs are decided by "ShopDB maintainers". The gate carries all of these patterns, so the next one fails a build. Two documents leave docs/ because they were never written for an outside reader. PROJECT-REVIEW.md is an internal health memo pinned to a commit from July, whose headline finding (an untracked playbook) has since been fixed - it is history, and git holds it. PILOT-DEPLOY.md is one site's own cutover runbook, complete with a "re-measure before publishing" placeholder; it moves next to the loader it belongs to, in scripts/site_imports/wjf/. ADR-015 is AMENDED rather than rewritten. Its enforcement section still said report-only and its backlog still listed hardcodes that are now cleared, which left the record contradicting itself. The amendment says what changed and why the report-only period ended; the original text stays, because what the decision looked like when it was taken is the part worth keeping. Also corrects llms.txt's response envelope, which had errors at the top level and pagination at meta.total. Both are nested one deeper, so anything written against that description read undefined on every error it tried to handle.
7.3 KiB
Proposal: a dashboard that shows the fleet, not the row count
- Status: ACCEPTED
- Date: 2026-08-11
- Author: ShopDB maintainers
- Relates to: ADR-010 (frontend plugin hooks), ADR-013 / ADR-014 (lean per-site builds), ADR-006 (collector contract), ADR-012 (GE-Enforce manifest ownership)
The problem
The dashboard reports totals: assets, machines, PCs, network devices, printers, measuring tools. Those numbers are true every day and actionable on none of them. Nobody opens the page to learn there are 417 assets.
Meanwhile the system already knows things worth acting on and shows them nowhere:
- a bay returned 500 to every collector report for a day and a half, and the only evidence was a log file on the PC
- eleven part markers' backups were overwriting each other for weeks
- a PC can stop reporting entirely and nothing says so
- GE-Enforce records enforcement failures, stale manifests and repeated self-heals, and none of it surfaces outside a report modal
Every one of those was found by someone going to look. The dashboard should be where they find you.
What already exists
Two discoveries shaped this proposal.
The plugin mechanism is built and dead. BasePlugin.get_dashboard_widgets
exists, GET /api/dashboard/widgets aggregates across enabled plugins, skips
disabled ones, isolates a broken plugin in production and sorts by position.
Five plugins - notifications, network, machines, computers, printers - already
declare widgets.
Nothing consumes it. The frontend never calls the endpoint, and not one of
the declared components (PrinterStatusWidget, ComputerStatusWidget,
MachineStatusWidget, NotificationsWidget, NetworkStatusWidget) exists.
The declarations point at components that were never written.
So this is less "build a dashboard" than "finish one", plus a contract fix.
The data is already collected. Nothing here needs a new collector field:
| Signal | Source |
|---|---|
| PC reporting / silent | computers.lastreporteddate |
| Machine has a controlling PC | controls links, collector:machine |
| Backed up, stale, never | backuprevisions per asset and kind |
| Enforcement failed | manifestenforcementreports.status, failedcount |
| Which entry failed, and why | manifestenforcementresults.action, exitcode, message |
| Stale manifest | report appliedversion versus the scope's published version |
| Drift that will not stick | repeated selfhealed results for one entry |
| Enforcer version spread | manifestenforcementreports.enforcerversion |
| Installed software and versions | computerinstalledapps |
| Toner critical / low | printer supplies, Zabbix-fed |
| Warranty expiring | warranty plugin |
| Mis-numbered bays | the check-shared-machines query |
Proposed change to the widget contract
The existing contract names a component per widget. That does not scale and does not survive a lean build: every widget needs a bespoke Vue component, and a plugin-provided component has to be staged into the frontend bundle to exist at all.
ADR-010 already solved this for asset panels: a plugin declares render: 'list'
or 'keyvalue' or 'tabs' plus a map of fields, and a GENERIC core component
renders it. Do the same here. A plugin declares data and shape; core owns the
rendering.
{
'id': 'geenforce-failures',
'title': 'Enforcement failures',
'endpoint': '/api/geenforce/dashboard/failures',
'render': 'exceptions', # generic renderer
'severity': 'critical', # critical | warning | info
'permission': 'geenforce.view',
'position': 10,
'empty': 'hide', # hide | line
'map': {
'title': 'hostname',
'detail': 'entryname',
'meta': [{'key': 'message'}, {'key': 'exitcode'}],
'link': '/pcs/{computerid}',
},
}
Three renderers cover everything listed above:
exceptions- a list of things that are wrong, each linking to the thingmetric- a single number with a trend or threshold, for the cases where the count IS the story (toner critical: 3)list- recent items, for notifications and KB adds
Principles
An exception board, not a stat board. The default view is what needs a person today. A count appears only where the count is the story.
Empty cards must shrink. A card that says "nothing wrong" every day trains
people to stop reading the page. That is exactly how ntlars-backup.log reached
3,234 lines with 17 that mattered. empty: 'hide' is the default; 'line' for
the few where absence is itself news.
Every row links to the thing. A dashboard that says three printers are low without linking to them is a worse version of a report.
Cards respect RBAC. A card declares a permission; a user without it never
sees the card or its endpoint. Toner levels are not sensitive, but "which PCs
expose VNC" is, and the dashboard must not become a way around role gating.
Thresholds are settings with neutral defaults (ADR-015): quiet window, toner percentage, warranty horizon. Every site will disagree with the numbers.
One endpoint per card, lazily loaded, failing independently. A hung Zabbix call must not blank the page.
Wave one
Cards whose data is already reliable, ordered by how actionable they are:
- Enforcement failures - current reports with
status = failed, showing the failing entry and exit code. - PCs not reporting -
lastreporteddatebeyond the quiet window, and PCs with no GE-Enforce report at all, which is a different and worse case. - Backups missing or stale - machines with no revision of a kind their PC type should produce, and revisions older than the interval.
- Toner critical, then low - links to the printer, then to its admin page.
- Warranties expiring - within the configured horizon.
- Mis-numbered bays -
check-shared-machines, promoted from a CLI command nobody will remember to run.
Then, lower and quieter: stale manifest versions, repeated self-heals, enforcer version spread, active notifications, recent application and KB additions.
Wave two: desired versus observed
The highest-value card and the most work. The manifest declares what a PC type
should have; computerinstalledapps records what it does; filters.py already
decides which entries apply to a given PC. Diffing those answers "which bays are
missing something they should have" - which nothing in the system answers today,
and which is the thing GE-Enforce exists to guarantee.
Deferred to wave two because it needs the resolver wired into a query path, and because wave one needs nothing new.
Risks
Aggregate queries on the most-visited page. These are fleet-wide scans on every load. Cache 30-60 seconds, and log slow cards - a lazily-loaded card can be slow for months before anyone mentions it.
Cards become the new noise. Six cards that are always empty are as useless as one number that never changes. If a card is empty for a month, delete it.
Plugin gating must be real. A lean site without printers must render no
toner card. The existing endpoint already skips disabled plugins; the frontend
must not hardcode a card list alongside it.
Non-goals
- Per-user dashboard customisation. Later, if asked for.
- Historical charting. This is a "what needs doing now" board; trends belong in reports.
- Replacing the shopfloor TV dashboard, which is a different audience with different needs.