diff --git a/docs/adr/ADR-011-machines-rename.md b/docs/adr/ADR-011-machines-rename.md new file mode 100644 index 0000000..dbea125 --- /dev/null +++ b/docs/adr/ADR-011-machines-rename.md @@ -0,0 +1,67 @@ +# ADR-011: Rename the equipment domain to machines; retype the models catalog with modeltypes + +- **Status:** ACCEPTED +- **Date:** 2026-07-11 +- **Deciders:** cproudlock +- **Relates to:** ADR-005 (equipment vs measuringtools scope), ADR-008 (plugin migration ownership) + +## Context + +ADR-005 split the old "equipment" concept: gage-lab instruments moved to the +measuringtools plugin, leaving the equipment plugin holding exactly one thing - +shop-floor machines (lathes, mills, CMMs, grinders, furnaces). The UI, the +routes (`/machines`), the frontend view folder (`views/machines/`), and even +the data vocabulary (asset numbers headed "MACHINE #") already said machines. +Only the code identity still said equipment: the plugin name, the API prefix, +the `equipment`/`equipmenttypes` tables, and the `assettype='equipment'` data +value. Every future contributor would pay a small permanent translation tax. + +A display-label-only swap was shipped first (2026-07-11) and immediately showed +the dissonance: UI Machines over code equipment forever. + +Separately, the legacy `machinetypes` table survived the Machine-model +retirement for one real reason: it types the vendor **models catalog** +(`models.machinetypeid`, 95 of 127 models) with fine-grained, cross-category +types (Lathe, Switch, Laser Printer). Its name was a misnomer - it never typed +machines specifically - and it squatted on the name the machines plugin's +subtype table wants. + +The economics favor doing this now and never again: the plugin contract is +pre-1.0 (breaking changes are cheap per ADR-002), no sister site has adopted +yet, there is no production instance, and the test suite plus CI give the +strongest safety net the project has had. + +## Decision + +Rename the domain in one coordinated pass: + +| Current | New | Rationale | +|---|---|---| +| `plugins/equipment/`, `/api/equipment`, `equipment.*` perms | `plugins/machines/`, `/api/machines`, `machines.*` | plugin identity matches the domain | +| `equipment` table, `equipmentid` | `machines`, `machineid` | main entity | +| `equipmenttypes`, `equipmenttypeid`, `equipmenttype` | `machinetypes`, `machinetypeid`, `machinetype` | subtypes take the freed name | +| legacy `machinetypes`, `models.machinetypeid` | `modeltypes`, `models.modeltypeid` | role-accurate: it types the models catalog, losslessly (no collapse to the 4 asset types) | +| `assettypes.assettype = 'equipment'` (data) | `'machine'` | the string compare sites flip with it | + +Migration placement follows ADR-008: the modeltypes rename and the data flips +land in the core chain (core tables, core data); the plugin table renames land +in the machines plugin's own chain, idempotently guarded so fresh installs +(whose core chain still creates the old names at `7c04`) rename on first +`flask plugin upgrade-all`. The `alembic_version_equipment` version table is +renamed to `alembic_version_machines` by the core migration so the plugin chain +resumes seamlessly on existing installs. The plugin registry auto-migrates an +`equipment` key to `machines` on load. + +Historical migrations and accepted ADRs are not rewritten; old ids and ADR-005 +wording remain as history. + +## Consequences + +- Upgrading instances run `flask db upgrade` then `flask plugin upgrade-all`, + same as every deploy; both migrations are idempotent. +- `/api/equipment` and `equipmentApi` cease to exist - a breaking change made + while there is nobody to break. After contract 1.0 this class of rename + would be a major-version event; this is the last cheap moment. +- The "Machine Types" settings card becomes "Model Types" and finally says + what it does; the machines plugin's subtype card owns the machine-types name. +- Contributors stop translating between UI vocabulary and code vocabulary. diff --git a/docs/adr/README.md b/docs/adr/README.md index f690596..610d41f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -23,6 +23,7 @@ Each ADR captures a single architectural decision: the context, the decision its | [008](ADR-008-plugin-migration-ownership.md) | Plugin migration ownership (per-plugin chains) | ACCEPTED | | [009](ADR-009-frontend-plugin-gating.md) | Frontend plugin route gating | ACCEPTED | | [010](ADR-010-frontend-plugin-hooks.md) | Frontend plugin hook contract | PROPOSED | +| [011](ADR-011-machines-rename.md) | Machines rename + modeltypes retyping | ACCEPTED | ## Authoring