802256f929
Execute WIKI-UPDATE-PLAN.md (14 items): - NEW docs/PRINTER-INSTALLER.md: install-list / pc-default / install-batch contract + public installer map page. - NEW-shape docs/API-REFERENCE.md: index + pointer to the live generated docs (/api/docs Redoc, openapi.json, llms.txt, MCP), replacing a stale full dump. - geenforce cutover + GE-ENFORCE-DISPLAY/CLIENT/DEPLOY: server-first display dispatcher (display-role by FQDN, display-type.txt fallback), dashboarddefaults FQDN keying, legacy kiosk autostart self-heal (Wow6432Node), per-PC-type cutover status. - PLUGINS: printers/slides rows + plugin-permissions note (slides.manage). - IMPORT-API: dashboarddefaults FQDN-first keying. - CONFIG: word-wise search, site_timezone setting. - PILOT-DEPLOY: servers-to-network reclassify step. IMPORT-ADOPTION: fixup note. - CLAUDE.md: test count 1077->1159, HTTPS-cutover state. CHANGELOG: timezone + kiosk-autostart fixes, site_timezone setting.
117 lines
8.1 KiB
Markdown
117 lines
8.1 KiB
Markdown
# 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 |
|
|
|--------|--------|-------|
|
|
| `machines` | Manufacturing machinery: 5-axis mills, lathes, broachers, heat treatment ovens | Manually entered. See [ADR-005](adr/ADR-005-equipment-vs-measuringtools.md). 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](adr/ADR-006-collector-contract.md). |
|
|
| `printers` | Network and shop-floor printers | Public installer map page + fleet install contract (`/api/printers/install-list`, `/pc-default`, `/install-batch`; see [PRINTER-INSTALLER.md](PRINTER-INSTALLER.md)). 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](adr/ADR-005-equipment-vs-measuringtools.md). Calibration lifecycle with derived status. First plugin built on the matured scaffold; its walkthrough is [PLUGIN-GUIDE.md](PLUGIN-GUIDE.md). Ships `default_enabled: false`. |
|
|
| `employees` | Read-only employee directory lookup | Backed by a separate HR database. Ships `default_enabled: false`. |
|
|
| `geenforce` | GE-Enforce manifest store: imaging PC-type scopes and their install manifests (apps, scripts, files, registry, version gates) | Per [ADR-012](adr/ADR-012-geenforce-manifest-ownership.md). Served to the GE-Enforce client as JSON. Requires GE-Enforce lib >= 2.6 on target PCs. Ships `default_enabled: false`. |
|
|
| `knowledgebase` | Knowledge Base articles linking to external resources | Lightweight article store. |
|
|
| `printedparts` | 3D-printed parts inventory | Kiosk checkout / check-in. Ships `default_enabled: false`. |
|
|
| `slides` | Slides for the lobby display and shop-floor screensaver | Upload / reorder / delete per surface. Management gated on the `slides.manage` permission, grantable to non-admin curators; display routes are public. |
|
|
| `warranty` | Asset warranty tracking | Manual entry now, Dell / Lenovo / HP provider lookups later. Derived coverage status with report buckets. |
|
|
|
|
## Plugin permissions
|
|
|
|
Plugins may register their own permissions (for example `slides.manage`). Admins
|
|
implicitly hold them; grant them to specific roles or users to delegate curation
|
|
without admin. Each plugin's registered permissions appear in its `plugin.py`
|
|
`get_permissions()`.
|
|
|
|
## Building your own
|
|
|
|
Guides:
|
|
|
|
- [PLUGIN-QUICKSTART.md](PLUGIN-QUICKSTART.md) - generate, customize, install, and test a plugin in 30 minutes using `flask plugin new`.
|
|
- [PLUGIN-GUIDE.md](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).
|
|
- [PLUGIN-EXTERNAL-REPO.md](PLUGIN-EXTERNAL-REPO.md) - developing a plugin in its own repo per ADR-003: repo layout, symlink dev workflow, `core_version` pinning, and a runnable CI harness (`scripts/test-external-plugin.sh`) that tests the plugin against a pinned framework ref.
|
|
- [CONTRACT-STABILITY.md](CONTRACT-STABILITY.md) - path to contract 1.0: what is settled vs still churning, the bump rules, and how much a sister site can safely build on today.
|
|
|
|
The contract is locked in [ADR-001](adr/ADR-001-asset-as-platform-contract.md) and versioned per [ADR-002](adr/ADR-002-plugin-versioning.md).
|
|
|
|
Quick path:
|
|
|
|
```bash
|
|
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](adr/ADR-008-plugin-migration-ownership.md)):
|
|
|
|
- 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](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](adr/ADR-003-plugin-distribution.md)):
|
|
|
|
- Plugin lives in its own git repo: `<git-host>/<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
|
|
|
|
## Lean per-site builds
|
|
|
|
A site ships only the plugins it chose; a site that never wants printedparts /
|
|
usb / network never carries that code (see
|
|
[ADR-013](adr/ADR-013-plugin-catalog-and-lean-builds.md) and
|
|
[ADR-014](adr/ADR-014-schema-lean-per-site.md)). Three layers make a build lean:
|
|
|
|
- **Backend code** - `scripts/build-site.sh <profile>` stages `shopdb/core` plus
|
|
only the chosen plugins' directories (and their hard-dependency closure). A
|
|
plugin a site did not choose is absent from the backend tree.
|
|
- **Frontend code** - `SITE_PLUGINS=machines,printers npm run build` (via
|
|
`scripts/stage-frontend.mjs`) stages only those plugins' `frontend/` dirs and
|
|
codegens the route table. **Exception:** a `plugins/<name>/frontend/` dir with
|
|
**no `manifest.json`** is a CORE feature (e.g. `applications`), not a per-site
|
|
plugin, and is ALWAYS staged regardless of `SITE_PLUGINS` - otherwise a lean
|
|
build would lose a core page.
|
|
- **Database** - the shared core Alembic baseline creates every plugin's tables,
|
|
so a lean site provisions them and then drops the ones it does not use with
|
|
`flask plugin prune-schema` (ADR-014). Run it once at provisioning, after
|
|
`flask db upgrade` and `flask plugin upgrade-all`; see
|
|
[DEPLOY.md](DEPLOY.md).
|
|
|
|
**Menus follow the build, not a plugin flag.** The sidebar nav, the settings
|
|
rail, and the Displays links all gate on whether the target route was actually
|
|
staged into this build (the router's own route table), not on a registry
|
|
"enabled" flag. So a lean site never shows a menu entry that dead-ends on a
|
|
blank page - an omitted plugin's nav item, settings cards, and kiosk links all
|
|
disappear together. Shopfloor Dashboard is a core view but is gated on the
|
|
notifications plugin (its only data source), so it drops when notifications is
|
|
not in the build.
|
|
|
|
## Naming policy
|
|
|
|
Plugin names follow the framework's naming convention (lowercase concatenated, no underscores or dashes; full words preferred over acronyms). See [CONTRIBUTING.md](../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.
|