From 0307a498ed60e836fbf56f20b02ae0fe44938629 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 17 Apr 2026 13:12:41 -0400 Subject: [PATCH] =?UTF-8?q?Resolve=20enterprise=20shortname=20=3D=20`zb`?= =?UTF-8?q?=20(decision=20#140,=20closes=20corrections-doc=20D4)=20?= =?UTF-8?q?=E2=80=94=20matches=20the=20existing=20`ZB.MOM.WW.*`=20namespac?= =?UTF-8?q?e=20prefix=20used=20throughout=20the=20codebase,=20short=20by?= =?UTF-8?q?=20design=20since=20this=20segment=20appears=20in=20every=20equ?= =?UTF-8?q?ipment=20path=20(`zb/warsaw-west/bldg-3/line-2/cnc-mill-05/RunS?= =?UTF-8?q?tate`),=20operators=20already=20say=20"ZB"=20colloquially.=20Up?= =?UTF-8?q?dated=20plan.md=20UNS=20browse-path=20example,=20plan.md=20Name?= =?UTF-8?q?space=20schema=20sketch=20NamespaceUri=20example,=20plan.md=20S?= =?UTF-8?q?erverCluster=20schema=20sketch=20Enterprise=20comment,=20admin-?= =?UTF-8?q?ui.md=20cluster-create=20workflow=20form=20(Enterprise=20field?= =?UTF-8?q?=20default-prefilled=20`zb`),=20config-db-schema.md=20ServerClu?= =?UTF-8?q?ster.Enterprise=20column=20comment.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/v2/admin-ui.md | 2 +- docs/v2/config-db-schema.md | 2 +- docs/v2/plan.md | 7 ++++--- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/v2/admin-ui.md b/docs/v2/admin-ui.md index f088495..388f436 100644 --- a/docs/v2/admin-ui.md +++ b/docs/v2/admin-ui.md @@ -389,7 +389,7 @@ The generic JSON editor uses the per-driver JSON schema from `DriverTypeRegistry ### Add a new cluster 1. FleetAdmin: `/clusters` → "New cluster" -2. Form: Name, **Enterprise** (UNS level 1, e.g. `ent`, validated `^[a-z0-9-]{1,32}$`), **Site** (UNS level 2, e.g. `warsaw-west`, same validation), NodeCount (1 or 2), RedundancyMode (auto-set based on NodeCount) +2. Form: Name, **Enterprise** (UNS level 1; default-prefilled `zb` per the org-wide canonical value, validated `^[a-z0-9-]{1,32}$`), **Site** (UNS level 2, e.g. `warsaw-west`, same validation), NodeCount (1 or 2), RedundancyMode (auto-set based on NodeCount) 3. Save → cluster row created (`Enabled = 1`, no generations yet) 4. **Open initial draft** containing default namespaces: - Equipment-kind namespace (`NamespaceId = {ClusterName}-equipment`, `NamespaceUri = urn:{Enterprise}:{Site}:equipment`). Operator can edit URI in the draft before publish. diff --git a/docs/v2/config-db-schema.md b/docs/v2/config-db-schema.md index ae4697a..cd145be 100644 --- a/docs/v2/config-db-schema.md +++ b/docs/v2/config-db-schema.md @@ -80,7 +80,7 @@ All `Json` columns use `nvarchar(max)` with a `CHECK (ISJSON(col) = 1)` constrai CREATE TABLE dbo.ServerCluster ( ClusterId nvarchar(64) NOT NULL PRIMARY KEY, Name nvarchar(128) NOT NULL, - Enterprise nvarchar(32) NOT NULL, -- UNS level 1, e.g. "ent" + Enterprise nvarchar(32) NOT NULL, -- UNS level 1, canonical org value: "zb" Site nvarchar(32) NOT NULL, -- UNS level 2, e.g. "warsaw-west" NodeCount tinyint NOT NULL CHECK (NodeCount IN (1, 2)), RedundancyMode nvarchar(16) NOT NULL CHECK (RedundancyMode IN ('None', 'Warm', 'Hot')), diff --git a/docs/v2/plan.md b/docs/v2/plan.md index 4d46463..1f0f42e 100644 --- a/docs/v2/plan.md +++ b/docs/v2/plan.md @@ -270,7 +270,7 @@ Per the 3-year-plan handoff §12, the Equipment namespace browse paths must conf | 5 | Equipment | `Equipment.Name` | `cnc-mill-05` | | 6 | Signal | `Tag.Name` | `RunState`, `ActualFeedRate` | -OPC UA browse path: `ent/warsaw-west/bldg-3/line-2/cnc-mill-05/RunState`. +OPC UA browse path: `zb/warsaw-west/bldg-3/line-2/cnc-mill-05/RunState`. **`UnsArea` and `UnsLine` are first-class generation-versioned entities** so the UNS structure is manageable on its own — operators can rename `bldg-3` → `bldg-3a` and every equipment under it picks up the new path automatically; bulk-move 5 lines from one building to another with a single edit; etc. Equipment references `UnsLineId` (FK), not denormalized Area/Line strings. @@ -349,7 +349,7 @@ All five are exposed as **OPC UA properties** on the equipment node. External sy ServerCluster ← top-level deployment unit (1 or 2 nodes) - ClusterId (PK) - Name ← human-readable e.g. "LINE3-OPCUA" - - Enterprise ← UNS level 1, e.g. "ent" (validated [a-z0-9-]{1,32}) + - Enterprise ← UNS level 1, canonical org value: "zb" (validated [a-z0-9-]{1,32}) - Site ← UNS level 2, e.g. "warsaw-west" (validated [a-z0-9-]{1,32}) - NodeCount (1 | 2) - RedundancyMode (None | Warm | Hot) ← None when NodeCount=1 @@ -364,7 +364,7 @@ Namespace ← generation-versioned (revised after adversar - NamespaceId ← stable logical ID across generations, e.g. "LINE3-OPCUA-equipment" - ClusterId (FK) - Kind (Equipment | SystemPlatform | Simulated) ← UNIQUE (GenerationId, ClusterId, Kind) - - NamespaceUri ← e.g. "urn:ent:warsaw-west:equipment". + - NamespaceUri ← e.g. "urn:zb:warsaw-west:equipment". UNIQUE per generation; cross-generation invariant: once a (NamespaceId, ClusterId) pair publishes a NamespaceUri, it cannot change in any future generation @@ -904,6 +904,7 @@ Each step leaves the system runnable. The generic extraction is effectively free | 137 | Dev env credentials documented openly in `dev-environment.md`; production uses Integrated Security / gMSA per decision #46 | Dev defaults are not secrets — they're convenience. Production never uses these values; documented separation prevents leakage | 2026-04-17 | | 138 | Every equipment-class template extends a shared `_base` class providing universal cross-machine metadata (identity, state, alarm summary, optional production context) | References OPC UA Companion Spec OPC 40010 (Machinery) for the Identification component + MachineryOperationMode enum, OPC UA Part 9 for alarm summary fields, ISO 22400 for KPI inputs (TotalRunSeconds, TotalCycles), 3-year-plan handoff §"Canonical Model Integration" for the canonical state vocabulary. Inheritance via `extends` field on the equipment-class JSON Schema. Avoids per-class drift in identity / state / alarm field naming and ensures every machine in the estate exposes the same baseline metadata regardless of vendor or protocol. `_base` lives in `3yearplan/schemas/classes/_base.json` (temporary location until the dedicated `schemas` repo is created) | 2026-04-17 | | 139 | Equipment table extended with OPC 40010 identity columns (Manufacturer, Model, SerialNumber, HardwareRevision, SoftwareRevision, YearOfConstruction, AssetLocation, ManufacturerUri, DeviceManualUri) all nullable so equipment can be added before identity is fully captured | First-class columns rather than a JSON blob because these fields are universal (every machine has them) and need to be queryable / searchable in the Admin UI. Manufacturer and Model are declared `isRequired: true` in `_base.json` and the Admin UI flags equipment that lacks them; the rest are optional. Drivers that can read these dynamically (FANUC, Beckhoff, etc.) override the static value at runtime; static value is the fallback. Exposed on the OPC UA node under the OPC 40010-standard `Identification` sub-folder | 2026-04-17 | +| 140 | Enterprise shortname = `zb` (UNS level-1 segment) | Closes corrections-doc D4. Matches the existing `ZB.MOM.WW.*` namespace prefix used throughout the codebase; short by design since this segment appears in every equipment path (`zb/warsaw-west/bldg-3/line-2/cnc-mill-05/RunState`); operators already say "ZB" colloquially. Admin UI cluster-create form default-prefills `zb` for the Enterprise field. Production deployments use it directly from cluster-create | 2026-04-17 | ## Reference Documents