docs(templates): derive-on-compose phase status + resume plan
Companion to the design doc — captures current state, the four
decisions already made, what's done (phase 1, commit 5615f3d),
and a full play-by-play for phases 2 through 9 with exact files,
methods, and tests to touch. Written so a future session after
context compaction can pick up cleanly.
This commit is contained in:
Joseph Doherty
270
docs/plans/2026-05-12-derive-on-compose-status.md
Normal file
270
docs/plans/2026-05-12-derive-on-compose-status.md
Normal file
@@ -0,0 +1,270 @@
|
||||
# Derive-on-compose: implementation status + remaining plan
|
||||
|
||||
> **For Claude resuming after compaction:** This is the single starting point.
|
||||
> Read it in full. Then read the companion design doc
|
||||
> `2026-05-12-derive-on-compose-design.md` for the architectural rationale.
|
||||
> Do NOT make code changes until you've also confirmed which phase the user
|
||||
> wants next.
|
||||
|
||||
## Where we are
|
||||
|
||||
**Branch**: `feature/templates-folder-hierarchy`. Already pushed.
|
||||
|
||||
**Last commit on this feature**: `5615f3d` — *Phase 1 complete, additive
|
||||
schema only*.
|
||||
|
||||
**All test suites currently green**:
|
||||
- `tests/ScadaLink.CentralUI.Tests` — 159 passing
|
||||
- `tests/ScadaLink.SiteRuntime.Tests` — 129 passing
|
||||
- `tests/ScadaLink.TemplateEngine.Tests` — 199 passing
|
||||
|
||||
## Design decisions already made (from the brainstorm)
|
||||
|
||||
User picked the **full Aveva model** with all four customization scopes:
|
||||
|
||||
- **Naming**: dot-separated → `Pump.TempSensor`
|
||||
- **Delete base with derivatives**: block with a list of the dependents
|
||||
- **Migration of existing compositions**: auto-migrate all on the EF Core
|
||||
migration step in Phase 3
|
||||
- **Tree UX**: derived templates hidden by default; toggle to reveal
|
||||
- **Customization scope**: override attribute values, override script bodies,
|
||||
add new attrs/scripts per slot, lock fields against override
|
||||
|
||||
## Done — Phase 1: Additive schema
|
||||
|
||||
Commits: `6854843` (design doc) + `a968cef` (decisions recorded) + `5615f3d`.
|
||||
|
||||
Files touched in `5615f3d`:
|
||||
|
||||
- `src/ScadaLink.Commons/Entities/Templates/Template.cs`
|
||||
- Added `IsDerived: bool`
|
||||
- Added `OwnerCompositionId: int?` (plain int — not an EF nav prop)
|
||||
- `src/ScadaLink.Commons/Entities/Templates/TemplateAttribute.cs`
|
||||
- Added `IsInherited: bool`
|
||||
- Added `LockedInDerived: bool`
|
||||
- `src/ScadaLink.Commons/Entities/Templates/TemplateScript.cs`
|
||||
- Same two fields
|
||||
- `src/ScadaLink.ConfigurationDatabase/Migrations/20260512121446_AddDerivedTemplateFields.cs`
|
||||
- EF Core migration. Six new columns, all NOT NULL DEFAULT 0 (or nullable
|
||||
int). No data transform — existing rows get defaults.
|
||||
- `ScadaLinkDbContextModelSnapshot.cs` regenerated.
|
||||
|
||||
**No behavior changes**. New fields are never read or written yet.
|
||||
|
||||
## Remaining — phases 2 through 9
|
||||
|
||||
Each phase ships independently. The cumulative behavior change fully lands at
|
||||
phase 3.
|
||||
|
||||
### Phase 2: Compose flow change
|
||||
|
||||
`TemplateService.AddCompositionAsync` currently creates a `TemplateComposition`
|
||||
that references a base template directly. Change it so NEW compositions:
|
||||
|
||||
1. Create a new `Template` entity:
|
||||
- `Name = $"{parentTemplate.Name}.{instanceName}"`
|
||||
- `ParentTemplateId = composedTemplateId` (the base)
|
||||
- `IsDerived = true`
|
||||
- `FolderId = null` (or inherit from parent? — pick null; derived
|
||||
templates aren't visible in the tree)
|
||||
2. Copy the base's `Attributes` into the new template marked
|
||||
`IsInherited = true`. Same for `Scripts` and `Alarms`.
|
||||
3. Create the `TemplateComposition` with `ComposedTemplateId = newTemplate.Id`
|
||||
(the derived, not the base).
|
||||
4. Set the derived template's `OwnerCompositionId = composition.Id` (back-ref).
|
||||
|
||||
Files to touch:
|
||||
|
||||
- `src/ScadaLink.TemplateEngine/TemplateService.cs` — extend
|
||||
`AddCompositionAsync` (currently around line 290+).
|
||||
- `src/ScadaLink.TemplateEngine/TemplateService.cs` — also extend
|
||||
`DeleteCompositionAsync` to cascade-delete the derived template.
|
||||
- `src/ScadaLink.TemplateEngine/TemplateService.cs` — extend `DeleteTemplateAsync`
|
||||
to block when the template is composed (already happens) AND when
|
||||
derivatives exist; reword the error.
|
||||
- Validation: derived template names must remain unique (the base existing
|
||||
uniqueness index on `Template.Name` covers this — but if `Pump.TempSensor`
|
||||
collides with a user-created template of that name, the add fails. Add a
|
||||
guard with a clear error message.)
|
||||
|
||||
Tests to add (`tests/ScadaLink.TemplateEngine.Tests/`):
|
||||
|
||||
- AddCompositionAsync creates a derived template.
|
||||
- The derived template inherits attributes / scripts with `IsInherited = true`.
|
||||
- DeleteCompositionAsync cascades to remove the derived template.
|
||||
- Deleting a base with derivatives is blocked with a message that lists them.
|
||||
|
||||
### Phase 3: Migration of existing compositions
|
||||
|
||||
EF Core data migration that runs on next startup. Two paths:
|
||||
|
||||
**Option A (simpler) — write the migration as a custom SQL/code step**
|
||||
|
||||
In `src/ScadaLink.ConfigurationDatabase/Migrations/`, generate a new migration
|
||||
called e.g. `MigrateCompositionsToDerived`. In its `Up` method, use raw
|
||||
`migrationBuilder.Sql(...)` or a delegate to:
|
||||
|
||||
```
|
||||
FOREACH composition IN TemplateComposition WHERE ComposedTemplate.IsDerived = false:
|
||||
derived := INSERT INTO Templates (
|
||||
Name = parent.Name || '.' || composition.InstanceName,
|
||||
ParentTemplateId = composition.ComposedTemplateId,
|
||||
IsDerived = true,
|
||||
OwnerCompositionId = composition.Id)
|
||||
INSERT INTO TemplateAttributes (Name, Value, DataType, IsLocked, Description,
|
||||
DataSourceReference, IsInherited=true,
|
||||
LockedInDerived=false, TemplateId=derived.Id)
|
||||
FROM TemplateAttributes WHERE TemplateId = composition.ComposedTemplateId
|
||||
same for TemplateScripts and TemplateAlarms
|
||||
UPDATE TemplateComposition SET ComposedTemplateId = derived.Id WHERE Id = composition.Id
|
||||
```
|
||||
|
||||
Run as raw SQL to keep the migration deterministic across providers (SQL
|
||||
Server vs SQLite if used in dev).
|
||||
|
||||
**Option B — service-layer one-time migration**
|
||||
|
||||
Add a startup hook that runs once (controlled by a flag column) and uses
|
||||
`TemplateService` directly. Cleaner for complex logic but more code.
|
||||
|
||||
**Pick Option A** unless the logic doesn't fit comfortably in SQL.
|
||||
|
||||
Validation post-migration: every `TemplateComposition.ComposedTemplateId`
|
||||
should now reference a template with `IsDerived = true`.
|
||||
|
||||
Tests: integration test that seeds pre-migration data, runs the migration,
|
||||
asserts the new shape.
|
||||
|
||||
### Phase 4: Inherit/override resolution in flattening
|
||||
|
||||
`src/ScadaLink.TemplateEngine/Flattening/FlatteningService.cs`:
|
||||
|
||||
- The service currently walks `Template.ParentTemplateId` chains in
|
||||
`ResolveInheritedScripts`. That same chain now naturally includes the
|
||||
base→derived link. No special handling needed for the chain itself.
|
||||
- BUT when a derived template's attribute is `IsInherited = true`, the
|
||||
effective value comes from the base (resolved through the chain). If
|
||||
`IsInherited = false`, the derived's own value is the override and wins.
|
||||
- Treat `LockedInDerived` as an enforcement check: if a derived row has
|
||||
`IsInherited = false` (override) AND the base row has `LockedInDerived =
|
||||
true`, emit a flattening validation error.
|
||||
|
||||
Tests: round-trip flattening with overridden + inherited combinations.
|
||||
|
||||
### Phase 5: Lock semantics enforcement
|
||||
|
||||
In `TemplateService.UpdateAttributeAsync` and `UpdateScriptAsync`:
|
||||
|
||||
- If the target template has `IsDerived = true`, look up the base via
|
||||
`ParentTemplateId`.
|
||||
- If the same-named attribute on the base has `LockedInDerived = true`,
|
||||
reject the update with a clear error: *"This attribute is locked by the
|
||||
base template '$Sensor' and cannot be overridden."*
|
||||
- If the update is being applied on a base template AND there are
|
||||
derivatives that have `IsInherited = false` for this field (overrides), the
|
||||
caller may want to know — surface a warning result. Out of scope for now;
|
||||
flag as TODO.
|
||||
|
||||
Tests: lock-blocked updates fail with the expected message.
|
||||
|
||||
### Phase 6: Template tree UI — hide derived
|
||||
|
||||
`src/ScadaLink.CentralUI/Components/Pages/Design/Templates.razor`:
|
||||
|
||||
- Filter `_templates` to exclude `t.IsDerived` by default.
|
||||
- Add a "Show derived templates" checkbox at the top.
|
||||
- When shown, render derived templates indented under their base
|
||||
(`t.ParentTemplateId == base.Id && t.IsDerived`).
|
||||
- Compositions tab on `TemplateEdit` should link each composition row to the
|
||||
derived template's edit page (the existing link likely points to the base
|
||||
— needs to follow `composition.ComposedTemplateId` which after phase 3 is
|
||||
the derived).
|
||||
|
||||
### Phase 7: Derived TemplateEdit UI
|
||||
|
||||
`src/ScadaLink.CentralUI/Components/Pages/Design/TemplateEdit.razor`:
|
||||
|
||||
- Top banner when `_selectedTemplate.IsDerived`:
|
||||
*"Derived from `[base.Name]` — composed inside `[parent.Name]` as
|
||||
`[composition.InstanceName]`."*
|
||||
- Attributes table: new column showing **Inherited** or **Overridden** badge.
|
||||
- Locked-from-base attributes (base has `LockedInDerived = true`) render
|
||||
readonly with a 🔒 icon and tooltip *"Locked by base — cannot override."*
|
||||
- Editing an inherited row flips it to override (`IsInherited = false`).
|
||||
- "Revert to base" button per row when `IsInherited = false` — clears the
|
||||
override; row reverts to the base value (`IsInherited = true`, value
|
||||
cleared).
|
||||
- Adding a new attribute/script: creates a row with `IsInherited = false`
|
||||
(it's not from the base).
|
||||
- Removing an inherited row should be blocked (the row exists because it's
|
||||
on the base; can't remove it on the derived). Removing an own-added row
|
||||
deletes normally.
|
||||
|
||||
### Phase 8: Base TemplateEdit UI — lock toggle
|
||||
|
||||
Same `TemplateEdit.razor`, when editing a base template:
|
||||
|
||||
- New column on Attributes table: a 🔒 toggle representing `LockedInDerived`.
|
||||
- Same on Scripts table.
|
||||
- Tooltip on the toggle: *"Lock this against per-slot override in derived
|
||||
templates."*
|
||||
|
||||
When a base template is open and the user toggles `LockedInDerived = true`
|
||||
while derived templates exist with overrides, surface a warning toast:
|
||||
*"N derived templates currently override this. Existing overrides won't be
|
||||
silently reverted but deploy validation will flag them."*
|
||||
|
||||
### Phase 9: Editor metadata simplification
|
||||
|
||||
Now that derived templates have a single owner, `BuildParentContextsAsync`
|
||||
in `TemplateEdit.razor` simplifies:
|
||||
|
||||
- **If the open template `IsDerived`**: parent = the single template that
|
||||
owns the `OwnerCompositionId`. Always one — no picker.
|
||||
- **If the open template is a base** (`!IsDerived`): suppress `Parent.*`
|
||||
assistance entirely. Add a SCADA008 hint diagnostic on `Parent.*` use:
|
||||
*"Parent access on a base template is ambiguous — override this script in
|
||||
a derived template instead."*
|
||||
|
||||
Remove the multi-parent `select` dropdown that was added in commit `0139c9c`
|
||||
(or keep it but guard with a check that should never fire after phase 3).
|
||||
|
||||
`GetTemplatesComposingAsync` (added in `0139c9c`) is still useful elsewhere —
|
||||
keep it.
|
||||
|
||||
## How to resume
|
||||
|
||||
After compaction, the future session should:
|
||||
|
||||
1. Read this file. Read the design doc
|
||||
`2026-05-12-derive-on-compose-design.md` for context.
|
||||
2. Run `git log --oneline -15` to confirm the branch is at `5615f3d` or
|
||||
later.
|
||||
3. Check test status: `dotnet test` across the three suites named above.
|
||||
4. Ask the user which phase to tackle next (or proceed from phase 2 if the
|
||||
user has explicitly said "continue").
|
||||
5. Each phase is its own commit. Prefer phase 2 + phase 3 together because
|
||||
phase 2 alone leaves new and existing compositions in different shapes
|
||||
until phase 3's migration runs.
|
||||
|
||||
## Pre-existing capability worth knowing
|
||||
|
||||
The script-scope editor work (commits `3ed05f0` → `0139c9c`) is already in
|
||||
place. Scripts on derived templates will automatically benefit from the
|
||||
single-parent context simplification in phase 9. The runtime accessors
|
||||
(`Attributes` / `Children` / `Parent` / `Scope`) defined there continue to
|
||||
work unchanged — the canonical-name paths they resolve are stable across
|
||||
the derivation change.
|
||||
|
||||
The multi-parent picker introduced in `0139c9c` becomes mostly dormant
|
||||
after phase 3 (no template should be composed by multiple parents anymore
|
||||
through the new flow). Plan to remove it in phase 9.
|
||||
|
||||
## Quick sanity script (run before phase 2)
|
||||
|
||||
```bash
|
||||
git status --short # should be clean
|
||||
git log --oneline -5 # top should include 5615f3d
|
||||
dotnet build # 0 errors, 0 warnings
|
||||
dotnet test tests/ScadaLink.TemplateEngine.Tests/ScadaLink.TemplateEngine.Tests.csproj
|
||||
```
|
||||
Reference in New Issue
Block a user