4995456136
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.
150 lines
7.0 KiB
Markdown
150 lines
7.0 KiB
Markdown
# 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)
|