shopdb-flask/docs/adr/ADR-005-equipment-vs-measuringtools.md

# ADR-005: Equipment plugin scope vs measuringtools plugin

- **Status:** ACCEPTED
- **Date:** 2026-05-08
- **Deciders:** cproudlock
- **Supersedes:** none

## Context

ADR-001 narrowed the migration to physical manufacturing equipment with a `machinenumber`. In practice, the legacy `category='Equipment'` rows contain two distinct asset classes:

1. **Manufacturing machinery** (5-axis mills, lathes, broachers, heat treatment ovens). These produce parts.
2. **Metrology and inspection instruments** (CMMs, Keyence vision systems, wax-and-trace surface profilometers, GenSpec instruments). These measure parts.

Both share `Asset` properties (vendor, model, location, controller). They differ in domain fields (axes vs measurement accuracy, cycle time vs calibration interval, controller protocol vs measurement software).

Mixing them under one plugin pollutes the schema and confuses cross-plugin queries ("show me all measuring tools" requires an enumeration of measuring-instrument equipmenttype values, which scales badly).

## Decision

Two plugins, separate concerns, shared platform contract.

### `equipment` plugin

Tracks manufacturing machinery. Bundled, in-tree.

Schema (per ADR-001 contract):

```
equipment
- assetid                FK to assets, PK
- equipmenttypeid        FK to equipmenttypes (5-axis mill, lathe, broacher, heat treat, ...)
- vendorid               FK to vendors (platform)
- modelid                FK to models (platform)
- controllertypeid       FK to controllertypes (equipment plugin)
- controllerosid         FK to controlleros (equipment plugin)
- (other shared fields: spindle count, axes, max workpiece size, ...)

equipmenttypes (lookup, equipment plugin)
- equipmenttypeid, name (5-axis mill, lathe, broacher, heat treat, ...)

controllertypes (lookup, equipment plugin)
- controllertypeid, name (Fanuc 31i, Siemens 840D, Mitsubishi M70, Heidenhain TNC640, ...)
- vendorid (FK to vendors)

controlleros (lookup, equipment plugin - separate from PC OS)
- controllerosid, name (FAPT, VxWorks, embedded Windows, Linux RT, ...)

equipmentfocas (subtype, optional, present only when FOCAS-equipped)
- assetid                PK, FK to equipment
- focasipaddress         text
- focasport              integer
- focasversion           text
- focasmachinenumber     text

equipmentclm (subtype, optional, present only when CLM-equipped)
- assetid                PK, FK to equipment
- (CLM-specific: address, port, station ID - finalize when plugin is built)

equipmentmtconnect (subtype, optional, present only when MTConnect-equipped)
- assetid                PK, FK to equipment
- mtconnectagenturl      text
- mtconnectdevicename    text
```

The `equipment.protocol` enum field is deliberately **not** included. Presence or absence of a subtype row indicates which protocol applies. Avoids a denormalized field that can drift out of sync.

### `measuringtools` plugin

Tracks metrology and inspection instruments. Bundled, in-tree (built in Phase 3-4 of the refactor as the first new plugin built using the framework scaffold).

Schema (initial draft, refined when plugin is built):

```
measuringtools
- assetid                FK to assets, PK
- measuringtooltypeid    FK to measuringtooltypes (CMM, vision system, profilometer, surface tester, ...)
- vendorid               FK to vendors (platform)
- modelid                FK to models (platform)
- measurementaxes        integer (e.g., 3 for a 3-axis CMM)
- accuracyspec           text (e.g., "+/-0.5um")
- calibrationintervaldays  integer
- lastcalibrationdate    date
- nextcalibrationdate    date (computed)
- (other domain fields as needed)

measuringtooltypes (lookup, measuringtools plugin)
- measuringtooltypeid, name (CMM, vision system, surface profilometer, gage block, ...)
```

Future extension: subtype tables for measurement-software integrations (PC-DMIS, Keyence, GenSpec). Same pattern as equipment subtype tables.

### Subtype-table pattern (general)

Both plugins use the same pattern for protocol- or software-specific fields:

- Core plugin table carries shared, common fields
- Optional subtype tables (one per protocol or software) hold extension fields
- Each subtype table is keyed by `assetid` (PK), one-to-one with the parent
- Subtype row exists if and only if the asset uses that protocol or software
- Sister sites add new subtype tables for their own integrations without touching core

## Reclassification of legacy data

ADR-001's migration moves all legacy `category='Equipment' AND machinenumber IS NOT NULL` rows to `assets` with `assettype='Equipment'` and into the equipment plugin's `equipment` table. This includes both manufacturing machinery and measuring tools.

After the equipment migration, when the measuringtools plugin is built:

1. Build a mapping table: legacy `machinetypeid` values that are measuring tools (CMM type, Keyence type, etc.)
2. Run a reclassification script:
   - For each `assets` row where the original `machinetypeid` is in the measuring-tool mapping
   - Change `assets.assettype` to `'MeasuringTool'`
   - Move the row from `equipment` to `measuringtools`
   - Map domain fields where they differ (e.g., legacy `axes` field maps to `measurementaxes`)
3. Verify counts pre- and post-reclassification
4. Audit log entry per reclassified row

Reclassification is one-shot, run once, archived. Like the original migration script.

## Consequences

### Positive

- Manufacturing machinery and measuring tools are first-class plugins, each with appropriate domain fields
- Sister sites can install one or both depending on what they track
- Subtype-table pattern is the canonical example for protocol-specific data and extends naturally to other plugins
- Building `measuringtools` mid-refactor validates the plugin scaffold tooling against a real new plugin

### Negative

- Reclassification is a second migration step. Lower risk than the initial migration because it is data-only (no schema change beyond moving rows between two tables that share the same `assetid` link).
- Sites that adopt the framework before `measuringtools` ships need to either keep measuring tools in `equipment` (workable but suboptimal) or wait for the plugin

### Neutral

- Legacy `machinetypeid` is preserved on the equipment row during migration to enable reclassification

## Alternatives considered

1. **Single equipment plugin with sub-typed assets.** Use `equipment.equipmenttypeid` to discriminate manufacturing vs metrology. Rejected: domain fields differ enough that a single table is wide and full of NULLs.
2. **Migrate split (build mapping before initial migration).** Cleaner end state but requires the `measuringtools` plugin to exist before the migration runs, which delays Phase 5. Rejected.
3. **JSON blob for protocol data instead of subtype tables.** Considered for both plugins. Rejected: weak typing, awkward queries, no schema validation.

## References

- ADR-001 (Asset is platform contract)
- ADR-002 (versioning of the surface)
- `plugins/equipment/` (current placeholder)
- `plugins/computers/` (existing example of plugin pattern)