ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
62c5454f00eba0d724f94dea8bf18b39beb689af
shopdb-flask/docs/adr/ADR-005-equipment-vs-measuringtools.md
cproudlock 4995456136 docs: take one site's name, hosts and paths off the public wiki 
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.
2026-08-14 15:38:27 -04:00

7.0 KiB
Raw Blame History

ADR-005: Equipment plugin scope vs measuringtools plugin

  • Status: ACCEPTED
  • Date: 2026-05-08
  • Deciders: ShopDB maintainers
  • 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/machines/ (equipment plugin, renamed per ADR-011)
  • plugins/computers/ (existing example of plugin pattern)
Reference in New Issue View Git Blame Copy Permalink