docs(plans): design for contained names on composition-derived templates
This commit is contained in:
Joseph Doherty
130
docs/plans/2026-05-18-contained-template-names-design.md
Normal file
130
docs/plans/2026-05-18-contained-template-names-design.md
Normal file
@@ -0,0 +1,130 @@
|
|||||||
|
# Contained Names for Composition-Derived Templates — Design
|
||||||
|
|
||||||
|
**Date:** 2026-05-18
|
||||||
|
**Status:** Approved (brainstorming) — implementation to follow
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
When a template composes another template, the `MigrateCompositionsToDerived`
|
||||||
|
migration materializes the composition slot as its own *derived* `Template`
|
||||||
|
row. Each derived template was named `OwnerTemplate.Name + "." + Composition.
|
||||||
|
InstanceName` — e.g. the `Pump` slot inside `Motor Controller` became a
|
||||||
|
template literally named **`Motor Controller.Pump`**.
|
||||||
|
|
||||||
|
The dotted name exists only to satisfy the global `UNIQUE` index on
|
||||||
|
`Template.Name`: there is already a standalone `Pump` template, so the derived
|
||||||
|
one could not also be called `Pump`.
|
||||||
|
|
||||||
|
This is the opposite of how AVEVA System Platform models containment — there,
|
||||||
|
an object has a **contained name** (`Pump`, unique only within its container)
|
||||||
|
and a **hierarchical name** (`MotorController.Pump`) that is *derived*, not
|
||||||
|
stored. This design moves ScadaLink to that model.
|
||||||
|
|
||||||
|
### Decisions taken during brainstorming
|
||||||
|
|
||||||
|
- **Adopt the contained-name model.** A derived template's stored `Name` is its
|
||||||
|
contained name (the composition's `InstanceName`); the qualified path is
|
||||||
|
computed, not stored.
|
||||||
|
- **Keep derived templates materialized.** The `MigrateCompositionsToDerived`
|
||||||
|
design is not revisited — the contained-name fix works with derived
|
||||||
|
templates as-is.
|
||||||
|
- **`QualifiedName` is computed**, not a denormalized column — a stored column
|
||||||
|
would need cascade maintenance on every rename up the chain. Composition
|
||||||
|
chains are 1–3 deep, so walking them on read is cheap.
|
||||||
|
|
||||||
|
### Audit findings (read-only, completed before this design)
|
||||||
|
|
||||||
|
- No code resolves a template *by name*: there is no `GetTemplateByNameAsync`;
|
||||||
|
the Management API and CLI are entirely ID-based.
|
||||||
|
- The template tree already hides derived templates (`Where(t => !t.IsDerived)`).
|
||||||
|
- Flattening, member canonical names, and collision detection use
|
||||||
|
`composition.InstanceName` — never `Template.Name`.
|
||||||
|
- The flattened/deployed artifact carries no template name; deployment keys on
|
||||||
|
ID + revision hash. The dotted name never reaches sites.
|
||||||
|
- `TemplateComposition` already has a DB `UNIQUE (TemplateId, InstanceName)`
|
||||||
|
index — the contained-name uniqueness backstop already exists.
|
||||||
|
- Every other `Template.Name` use is either dotted-name construction
|
||||||
|
(`TemplateService` + the old migration), a dotted-name uniqueness pre-check,
|
||||||
|
or reading `.Name` for display after an ID lookup.
|
||||||
|
|
||||||
|
## Design
|
||||||
|
|
||||||
|
### 1. Schema
|
||||||
|
|
||||||
|
- The `UNIQUE` index on `Template.Name` becomes a **filtered** unique index:
|
||||||
|
`UNIQUE ... WHERE [IsDerived] = 0`. User-authored (base) templates stay
|
||||||
|
globally unique; derived templates do not need to be.
|
||||||
|
- Derived templates' uniqueness is enforced entirely by the existing
|
||||||
|
`UNIQUE (TemplateId, InstanceName)` index on `TemplateComposition` — a slot
|
||||||
|
name is unique within its owner.
|
||||||
|
- A new EF Core migration:
|
||||||
|
- Rewrites every derived row: `Name = OwnerComposition.InstanceName`.
|
||||||
|
- Replaces the `Template.Name` index with the filtered version.
|
||||||
|
- `TemplateConfiguration`: `HasIndex(t => t.Name).IsUnique()` gains
|
||||||
|
`.HasFilter("[IsDerived] = 0")`.
|
||||||
|
|
||||||
|
### 2. Qualified name
|
||||||
|
|
||||||
|
A new pure helper resolves the hierarchical name on demand:
|
||||||
|
|
||||||
|
```
|
||||||
|
QualifiedName(template, byId, compById):
|
||||||
|
if not template.IsDerived: return template.Name
|
||||||
|
comp = compById[template.OwnerCompositionId]
|
||||||
|
owner = byId[comp.TemplateId]
|
||||||
|
return QualifiedName(owner, …) + "." + comp.InstanceName
|
||||||
|
```
|
||||||
|
|
||||||
|
It lives in a small static class in `ScadaLink.TemplateEngine` (e.g.
|
||||||
|
`TemplateNaming`), takes lookups the callers already have, and is null-safe
|
||||||
|
(a missing link falls back to the stored `Name`).
|
||||||
|
|
||||||
|
### 3. TemplateService
|
||||||
|
|
||||||
|
The composition create / rename / cascade paths currently build
|
||||||
|
`$"{owner.Name}.{instanceName}"` for the derived `Template.Name`. They change
|
||||||
|
to store the **contained name** (`instanceName`) directly:
|
||||||
|
|
||||||
|
- `CreateCascadedCompositionAsync` — derived `Name = instanceName`.
|
||||||
|
- Nested cascade (`EnumerateCascadeNames`, cascade-rename) — each level stores
|
||||||
|
its own `InstanceName`, not the accumulated path.
|
||||||
|
- The dotted-name global collision pre-check (`allTemplates.Any(t => t.Name ==
|
||||||
|
newName)`) is removed — uniqueness is the in-owner `InstanceName` check that
|
||||||
|
already runs (and the DB index behind it).
|
||||||
|
|
||||||
|
### 4. UI
|
||||||
|
|
||||||
|
- `TemplateEdit`: the page title shows the contained `Name`; the qualified
|
||||||
|
path is shown as a breadcrumb / subtitle (the existing "— composed inside X
|
||||||
|
as Y" line already carries this information and becomes the canonical
|
||||||
|
presentation).
|
||||||
|
- "inherits X", cycle-detection messages, and deletion-blocked messages use
|
||||||
|
`QualifiedName` when the referenced template is derived, so a bare `TempSensor`
|
||||||
|
is never ambiguous in a message.
|
||||||
|
|
||||||
|
### 5. Out of scope
|
||||||
|
|
||||||
|
- Un-materializing derived templates (treating a composition purely as a slot).
|
||||||
|
- Any change to member/attribute canonical names — they already use
|
||||||
|
`InstanceName`.
|
||||||
|
|
||||||
|
## Testing & verification
|
||||||
|
|
||||||
|
- **`TemplateNaming` unit tests** — qualified name for a base template, a
|
||||||
|
one-level derived template, and a nested derived template; null-safe
|
||||||
|
fallback.
|
||||||
|
- **`TemplateService` tests** — composition create and rename store the
|
||||||
|
contained name; two derived templates with the same contained name under
|
||||||
|
different owners are allowed; a duplicate slot name on one owner is rejected.
|
||||||
|
- **Migration** — applied to the dev cluster; existing derived rows
|
||||||
|
(`Motor Controller.Pump`, `Tank Monitor.DrivePump.TempSensor`, …) collapse to
|
||||||
|
contained names; verified in the browser.
|
||||||
|
|
||||||
|
## Affected files
|
||||||
|
|
||||||
|
- `src/ScadaLink.ConfigurationDatabase/Configurations/TemplateConfiguration.cs`
|
||||||
|
- `src/ScadaLink.ConfigurationDatabase/Migrations/*` (new migration)
|
||||||
|
- `src/ScadaLink.TemplateEngine/TemplateService.cs`
|
||||||
|
- `src/ScadaLink.TemplateEngine/TemplateNaming.cs` (new)
|
||||||
|
- `src/ScadaLink.CentralUI/Components/Pages/Design/TemplateEdit.razor`
|
||||||
|
- Docs: `docs/requirements/Component-TemplateEngine.md`
|
||||||
Reference in New Issue
Block a user