From da654944dc86fd3da34e9d70da0a08e8b175514a Mon Sep 17 00:00:00 2001 From: cproudlock Date: Fri, 8 May 2026 18:02:11 -0400 Subject: [PATCH] Phase 6: simplify-pass policy, plugins listing, roadmap to 1.0 End-of-pipeline cleanup. No structural changes; documents what is done, what is left, and the discipline for future cleanup commits. Skill: - simplifying-python: end-of-session cleanup discipline. Inspired by Anthropic's open-sourced code-simplifier. Targets duplication, dead code, voodoo constants, stale comments, misnamed identifiers, unnecessary abstraction. Anti-targets: architecture, public API surface, schema, sweeping rewrites. Behavior preservation enforced by running pytest before and after. Simplify pass on shopdb/utils/responses.py: - error_response docstring claimed the error info lives at top level `error`. Implementation puts it under `data.error` (consistent with the success envelope). Implementation is correct; docstring updated. - paginated_response docstring used snake_case keys (`per_page`, `total_pages`, etc). Implementation uses lowercase concatenated per CONTRIBUTING.md. Docstring updated to match. Documentation: - docs/PLUGINS.md: bundled plugins (six, with what they track and caveats per ADR), planned plugins (measuringtools as the scaffold canary per ADR-005), distribution conventions for sister-site plugins per ADR-003, naming policy. - docs/ROADMAP.md: phase status table (0-5 done, 6 in progress), must-have work for 1.0 (Asset.mapx/mapy, equipment migration, printers retirement, frontend hook contract, per-plugin Alembic chains), nice-to-have (measuringtools plugin, frontend scaffolding, marketplace listing, surface-diff tooling), deferred (multi-tenancy, pip-installable plugins, event bus). Defines what 1.0.0 means as a contract. Test count unchanged: 101 passing. Naming/style check green. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/PLUGINS.md | 47 +++++++++++++++++++++++++++++ docs/ROADMAP.md | 62 +++++++++++++++++++++++++++++++++++++++ shopdb/utils/responses.py | 28 ++++++++++-------- 3 files changed, 125 insertions(+), 12 deletions(-) create mode 100644 docs/PLUGINS.md create mode 100644 docs/ROADMAP.md diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md new file mode 100644 index 0000000..fe9c51f --- /dev/null +++ b/docs/PLUGINS.md @@ -0,0 +1,47 @@ +# 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 `/plugins//` at install time. + +## Bundled (ship with the framework) + +These six plugins are in `plugins/` in this repo. Enable per site with `flask plugin install `. + +| Plugin | Tracks | Notes | +|--------|--------|-------| +| `equipment` | 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 | 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`. | + +## Planned (in the roadmap, not yet built) + +| Plugin | Tracks | Status | +|--------|--------|--------| +| `measuringtools` | Metrology and inspection: CMMs, Keyence vision, surface profilometers, GenSpec | Per [ADR-005](adr/ADR-005-equipment-vs-measuringtools.md). First plugin to be built using `flask plugin new` as the canary for the scaffold. | + +## Building your own + +See [PLUGIN-QUICKSTART.md](PLUGIN-QUICKSTART.md) for the 30-minute walkthrough. 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 +``` + +## Distribution conventions + +For sister-site plugins (per [ADR-003](adr/ADR-003-plugin-distribution.md)): + +- Plugin lives in its own git repo: `gitea.proudtech.net//` +- Adopting site clones or symlinks into their `/plugins//` +- 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](../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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..3acf201 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,62 @@ +# Roadmap + +shopdb-flask is at `__contract_version__ = '0.2.0'` (pre-1.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 + +| Phase | Status | Commit | +|-------|--------|--------| +| 0 - Lock platform contract, naming, style enforcement | DONE | `d6725c0` | +| 1 - pytest baseline, production hardening, pinned requirements | DONE | `2d1bb83` | +| 2 - Plugin contract surface and compliance tests | DONE | `5fefb53` | +| 3 - Manifest-first loader, shopdb.api namespace, auto-register blueprints | DONE | `6f085a1` | +| 4 - Plugin scaffolding (`flask plugin new`) | DONE | `8eb9362` | +| 5 - Alembic baseline, per-site deploy, ADRs to docs/adr | DONE | `d4e3ac9` | +| 6 - Polish (this phase) | IN PROGRESS | this commit | + +## What's left before tagging 1.0.0 + +### Must-have + +- **Asset model fully wired**. `Asset.mapx, Asset.mapy` columns, `AssetRelationship.inheritsposition`, `AssetRelationship.propagatesthroughid` columns. Models match the locked ADR-001 surface that `resolve_asset_position` already targets. +- **Equipment data migration script** for facilities migrating from legacy ASP shopdb. One-shot script under `scripts/migration/`. See [migrating-asset-schema](../../.claude/skills/migrating-asset-schema.md) for the policy. Per ADR-001, only `category='Equipment' AND machinenumber IS NOT NULL` migrates. +- **Printers retirement**. Legacy `PrinterData` model, `printers_bp` legacy blueprint, and the frontend `PrinterForm.vue` references to `printer.printerdata.*` get removed in lockstep. Coordinated with the equipment migration. +- **Frontend hook contract**. Vue side equivalents for the backend hook system: how plugins expose asset-detail components, map markers, search-result renderers. Requires its own design ADR. +- **Per-plugin Alembic migrations**. The framework supports them via `shopdb/plugins/migrations.py`; bundled plugins still rely on `db.create_all()`. Move each bundled plugin onto its own version chain before sister sites adopt. + +### Nice-to-have + +- `measuringtools` plugin built using the scaffold (validates the scaffold under realistic conditions). +- Frontend scaffolding skill (the backend has `flask plugin new`; the frontend stub is currently manual copy-paste). +- Marketplace listing site (PLUGINS.md is a one-pager; a proper listing with links to sister-site plugins becomes useful when there are more than three external plugins). +- Plugin contract surface diff tooling. Today version bumps are manual judgment; a CI check that diffs the contract surface against the previous tag would catch missed bumps. See ADR-002. +- Calibration cycles, maintenance windows, downtime tracking (domain extensions; would likely live in the `equipment` and `measuringtools` plugins). + +### Deferred (out of scope for 1.0) + +- Multi-tenancy (rejected by ADR-004; revisit only if more than five sites adopt and operational overhead becomes painful). +- Pip-installable plugins (deferred per ADR-003 v2). Filesystem distribution stays the v1 model. +- Event bus on `BasePlugin` (removed per ADR-001; add via new ADR if a real use case appears). +- Frontend rebuild beyond Vue 3 + Pinia + Vite (the existing stack is fine). + +## What 1.0.0 means + +Tagging `1.0.0` is a commitment that the contract surface is stable for at least the next minor version cycle. Plugin authors at sister sites can pin `core_version: ">=1.0.0,<2.0.0"` and trust their plugin will not break on framework patches. + +Concretely, 1.0.0 ships when: + +1. ADR-001's full contract surface is implemented in code, not just documented (`Asset.mapx`, `RelationshipType.propagatesthroughid`, etc.) +2. The contract test suite covers every documented hook with both happy-path and a "broken plugin" failure-isolation test +3. At least one external plugin (likely `measuringtools` from the scaffold canary) has been built end-to-end with no contract changes required mid-build +4. The deploy runbook (DEPLOY.md) has been validated by an actual fresh-host deploy + +## Decision log pointers + +When a roadmap item gets prioritized, document the why in a new ADR and link from this file. The ADRs are the canonical source for design decisions; this file is the prioritized backlog. + +- [ADR-001](adr/ADR-001-asset-as-platform-contract.md) - Asset as platform contract +- [ADR-002](adr/ADR-002-plugin-versioning.md) - Plugin contract versioning +- [ADR-003](adr/ADR-003-plugin-distribution.md) - Plugin distribution model +- [ADR-004](adr/ADR-004-deployment-topology.md) - Deployment topology (per-site) +- [ADR-005](adr/ADR-005-equipment-vs-measuringtools.md) - Equipment vs measuringtools +- [ADR-006](adr/ADR-006-collector-contract.md) - Collector contract pattern diff --git a/shopdb/utils/responses.py b/shopdb/utils/responses.py index ed3c960..fd3dcf6 100644 --- a/shopdb/utils/responses.py +++ b/shopdb/utils/responses.py @@ -80,16 +80,21 @@ def error_response( details: Dict = None, http_code: int = 400 ): - """ - Error response helper. + """Error response helper. Response format: { "status": "error", - "error": { - "code": "VALIDATION_ERROR", - "message": "Human-readable message", - "details": {...} + "data": { + "error": { + "code": "VALIDATION_ERROR", + "message": "Human-readable message", + "details": {...} + } + }, + "meta": { + "timestamp": "...", + "requestid": "..." } } """ @@ -132,8 +137,7 @@ def paginated_response( total: int, schema=None ): - """ - Paginated list response. + """Paginated list response. Response format: { @@ -142,11 +146,11 @@ def paginated_response( "meta": { "pagination": { "page": 1, - "per_page": 20, + "perpage": 20, "total": 150, - "total_pages": 8, - "has_next": true, - "has_prev": false + "totalpages": 8, + "hasnext": true, + "hasprev": false } } }