scadalink-design/docs/plans/phase-5-authoring-ui.md

# Phase 5: Design-Time UI & Authoring Workflows

**Date**: 2026-03-16
**Status**: Plan complete
**Goal**: Design users can author templates, scripts, and system definitions through the UI.

---

## Scope

**Components**: Central UI (design workflows)

**Features**:
- Template authoring CRUD with tree visualization
- Composition management with collision feedback
- Attribute/alarm/script editing with lock indicators
- Inherited vs. local vs. overridden visual indicators
- On-demand validation
- Shared script management
- External system definition management (metadata only)
- Database connection definition management (metadata only)
- Notification list management (metadata only)
- Inbound API method definition management (metadata only)
- Instance creation from template
- Instance per-attribute data connection binding with bulk assignment
- Instance attribute override editing

**Note**: This phase authors metadata/definitions only for External System Gateway, Database Connections, Notification Service, and Inbound API. Runtime execution is Phase 7. UI for these definitions does not depend on Phase 7 runtime.

---

## Prerequisites

| Phase | What must be complete |
|-------|-----------------------|
| Phase 1 | Central UI Blazor Server shell, login, route protection, role-based navigation, Security & Auth, Configuration Database, IAuditService |
| Phase 2 | Template Engine (full): CRUD, inheritance, composition, flattening, diff, validation, instance/area/site/data connection models |
| Phase 4 | Operator/Admin UI: Site management, data connection management, area management, health dashboard, instance list, deployment status view |

---

## Requirements Checklist

### Section 3.1 — Template Structure (UI)
- [ ] `[3.1-1]` Machines are modeled as instances of templates — UI allows creating templates
- [ ] `[3.1-2]` Templates define a set of attributes — UI allows defining attributes on templates
- [ ] `[3.1-3]` Each attribute has a lock flag — UI exposes lock flag toggle

### Section 3.2 — Attribute Definition (UI)
- [ ] `[3.2-1]` Attribute Name — editable in UI
- [ ] `[3.2-2]` Attribute Value — editable in UI (may be empty)
- [ ] `[3.2-3]` Attribute Data Type (Boolean, Integer, Float, String) — selectable in UI
- [ ] `[3.2-4]` Attribute Lock Flag — toggleable in UI
- [ ] `[3.2-5]` Attribute Description — editable in UI
- [ ] `[3.2-6]` Attribute Data Source Reference (optional relative path) — editable in UI
- [ ] `[3.2-7]` Template defines *what* to read, not *where* — UI does not allow connection selection on template attributes

### Section 3.3 — Data Connections (UI portion)
- [ ] `[3.3-1]` Binding is per-attribute at instance level — UI supports per-attribute binding
- [ ] `[3.3-2]` Bulk assignment — UI supports selecting multiple attributes and assigning a data connection to all at once
- [ ] `[3.3-3]` Templates do not specify a default connection — UI does not offer default connection on templates

### Section 3.4 — Alarm Definitions (UI)
- [ ] `[3.4-1]` Alarms are first-class template members — UI shows alarms alongside attributes and scripts
- [ ] `[3.4-2]` Alarm Name — editable in UI
- [ ] `[3.4-3]` Alarm Description — editable in UI
- [ ] `[3.4-4]` Alarm Priority Level (0–1000) — editable with validation in UI
- [ ] `[3.4-5]` Alarm Lock Flag — toggleable in UI
- [ ] `[3.4-6]` Trigger Definition types (Value Match, Range Violation, Rate of Change) — selectable in UI with appropriate fields per type
- [ ] `[3.4-7]` Optional On-Trigger Script reference — selectable in UI
- [ ] `[3.4-8]` Alarms follow same inheritance, override, and lock rules as attributes — UI reflects this

### Section 3.5 — Template Relationships (UI)
- [ ] `[3.5-1]` Inheritance (is-a) — UI allows setting a parent template
- [ ] `[3.5-2]` Child inherits all attributes, alarms, scripts, and composed modules from parent — UI shows inherited members
- [ ] `[3.5-3]` Child can override non-locked inherited values — UI allows overriding
- [ ] `[3.5-4]` Child can add new attributes, alarms, scripts — UI supports adding
- [ ] `[3.5-5]` Child cannot remove parent-defined members — UI prevents removal of inherited members
- [ ] `[3.5-6]` Composition (has-a) — UI allows adding feature module instances
- [ ] `[3.5-7]` Recursive composition — UI supports nested module visualization
- [ ] `[3.5-8]` Naming collisions are design-time errors — UI reports collisions and blocks save

### Section 3.6 — Locking (UI)
- [ ] `[3.6-1]` Locking applies to attributes, alarms, and scripts uniformly — UI shows lock state on all three
- [ ] `[3.6-2]` Locked member cannot be overridden downstream — UI disables editing of locked members
- [ ] `[3.6-3]` Unlocked member can be overridden — UI enables editing of unlocked members
- [ ] `[3.6-4]` Intermediate locking — UI allows locking an unlocked member at any level
- [ ] `[3.6-5]` Downstream cannot unlock what is locked above — UI prevents unlocking of upstream-locked members

### Section 3.6 (second) — Attribute Resolution Order (UI)
- [ ] `[3.6-res-1]` Resolution order: Instance → Child → Parent → Composing → Composed — UI visually indicates which level a value comes from

### Section 3.7 — Override Scope (UI)
- [ ] `[3.7-1]` Child templates can override non-locked attributes from parent — UI allows this
- [ ] `[3.7-2]` Composing template can override non-locked attributes in composed modules — UI allows this
- [ ] `[3.7-3]` Overrides can pierce into composed modules — UI supports editing module members from child templates

### Section 3.8 — Instance Rules (UI)
- [ ] `[3.8-1]` Instance can override non-locked attribute values — UI allows this
- [ ] `[3.8-2]` Instance cannot add new attributes — UI does not offer "add attribute" on instances
- [ ] `[3.8-3]` Instance cannot remove attributes — UI does not offer "remove" on instance attributes
- [ ] `[3.8-4]` Instance structure defined by template — UI shows read-only structure
- [ ] `[3.8-5]` Each instance assigned to an area — UI requires area assignment

### Section 3.9 — Template Deployment & Change Propagation (UI portion)
- [ ] `[3.9-6]` Concurrent editing uses last-write-wins — UI does not implement conflict detection

### Section 3.10 — Areas (UI portion — Phase 5 owns instance-area assignment)
- [ ] `[3.10-1]` Instance is assigned to an area within its site — UI supports area selection on instance creation

### Section 3.11 — Pre-Deployment Validation (UI)
- [ ] `[3.11-7]` On-demand validation available in Central UI for Design users during template authoring — UI provides "Validate" action
- [ ] `[3.11-8]` Shared script validation: C# syntax and structural correctness — UI provides compile-check action

### Section 4.1 — Script Definitions (UI portion)
- [ ] `[4.1-1]` Scripts are C# defined at template level as first-class members — UI supports script editing
- [ ] `[4.1-2]` Scripts follow inheritance, override, and lock rules — UI reflects this
- [ ] `[4.1-3]` Scripts can define input parameters (name and data type) — UI supports parameter definition editing
- [ ] `[4.1-4]` Scripts can define return value definition (field names and data types, objects, lists) — UI supports return definition editing
- [ ] `[4.1-5]` Scripts can define trigger configuration — UI supports trigger type selection and configuration

### Section 4.5 — Shared Scripts (UI portion)
- [ ] `[4.5-1]` Shared scripts are not associated with any template — UI manages them as a separate section
- [ ] `[4.5-2]` Shared scripts can define input parameters and return value definitions — UI supports editing these
- [ ] `[4.5-3]` Managed by users with Design role — UI enforces Design role access

### Section 5.1 — External System Definitions (UI portion)
- [ ] `[5.1-1]` External systems are predefined contracts created by Design role — UI provides CRUD for definitions
- [ ] `[5.1-2]` Connection details: endpoint URL, authentication, protocol — UI supports editing these fields
- [ ] `[5.1-3]` Method definitions: parameters and return types — UI supports method definition editing
- [ ] `[5.1-4]` Definitions deployed uniformly to all sites — UI shows deployment scope indicator
- [ ] `[5.1-5]` Deployment requires explicit Deployment role action — UI separates definition editing (Design) from deployment trigger (Deployment)

### Section 5.5 — Database Connections (UI portion)
- [ ] `[5.5-1]` Database connections are predefined named resources by Design role — UI provides CRUD
- [ ] `[5.5-2]` Connection details: server, database, credentials — UI supports editing these fields
- [ ] `[5.5-3]` Retry settings: max retry count, fixed time between retries — UI supports editing these
- [ ] `[5.5-4]` Deployed uniformly to all sites — UI shows deployment scope indicator
- [ ] `[5.5-5]` Deployment requires explicit Deployment role action — UI separates editing from deployment

### Section 6.1 — Notification Lists (UI portion)
- [ ] `[6.1-1]` Notification lists are system-wide, managed by Design role — UI provides CRUD
- [ ] `[6.1-2]` Each list has a name and one or more recipients — UI supports list name and recipients editing
- [ ] `[6.1-3]` Each recipient has a name and email address — UI supports recipient fields
- [ ] `[6.1-4]` Deployed to all sites — UI shows deployment scope indicator
- [ ] `[6.1-5]` Deployment requires explicit Deployment role action — UI separates editing from deployment

### Section 7.4 — API Method Definitions (UI portion)
- [ ] `[7.4-1]` API methods are predefined, managed by Design role — UI provides CRUD
- [ ] `[7.4-2]` Method name — editable in UI
- [ ] `[7.4-3]` Approved API keys list — selectable in UI
- [ ] `[7.4-4]` Parameter definitions (name, data type) — editable in UI
- [ ] `[7.4-5]` Return value definition (supports objects, lists) — editable in UI
- [ ] `[7.4-6]` Timeout per method — editable in UI
- [ ] `[7.4-7]` Implementation script (C# inline) — editable in UI with code editor
- [ ] `[7.4-8]` API scripts are standalone (no template inheritance) — UI presents them independently

### Section 8 — Central UI (Design workflows, Phase 5 owns)
- [ ] `[8-design-1]` Template Authoring: create, edit, manage templates including hierarchy and composition
- [ ] `[8-design-2]` Author and manage scripts within templates
- [ ] `[8-design-3]` Design-time validation on demand
- [ ] `[8-design-4]` Shared Script Management: create, edit, manage
- [ ] `[8-design-5]` Notification List Management: create, edit, manage lists and recipients
- [ ] `[8-design-6]` External System Management: define contracts, connection details, API method definitions
- [ ] `[8-design-7]` Database Connection Management: define named connections
- [ ] `[8-design-8]` Inbound API Management: define methods (Design role for methods)
- [ ] `[8-design-9]` Instance Management: create instances from templates, bind data connections (per-attribute with bulk assignment), set overrides, assign to areas
- [ ] `[8-design-10]` Template deletion blocked if instances or child templates reference it — UI displays references

---

## Design Constraints Checklist

| ID | Constraint | Source | Mapped WP |
|----|-----------|--------|-----------|
| KDD-ui-1 | Blazor Server (ASP.NET Core + SignalR), Bootstrap, no JS frameworks, clean corporate design | CLAUDE.md | WP-1 |
| KDD-deploy-2 | Composed member addressing uses path-qualified canonical names: [ModuleInstanceName].[MemberName] | CLAUDE.md | WP-2, WP-4 |
| KDD-deploy-3 | Override granularity defined per entity type and per field | CLAUDE.md | WP-3, WP-13 |
| KDD-deploy-4 | Template graph acyclicity enforced on save | CLAUDE.md | WP-2 |
| KDD-deploy-5 | Flattened configs include revision hash for staleness detection | CLAUDE.md | WP-5 |
| KDD-deploy-10 | Last-write-wins for concurrent template editing | CLAUDE.md | WP-1 |
| KDD-deploy-12 | Naming collisions in composed feature modules are design-time errors | CLAUDE.md | WP-2 |
| CD-CUI-1 | Template deletion blocked if instances or child templates reference — UI displays references | Component-CentralUI | WP-1 |
| CD-CUI-2 | External system definition includes retry settings (max retry count, time between retries) | Component-CentralUI | WP-7 |
| CD-CUI-3 | Database connection definition includes retry settings | Component-CentralUI | WP-8 |
| CD-CUI-4 | SMTP settings defined centrally | Component-NotificationService | WP-9 |
| CD-CUI-5 | Inbound API extended type system (Object, List) for parameters and return types | Component-InboundAPI | WP-10 |
| CD-CUI-6 | External system method definitions include HTTP method (GET/POST/PUT/DELETE) and relative path | Component-ESG | WP-7 |
| CD-CUI-7 | External system auth options: API Key (header name + value) or Basic Auth (username + password) | Component-ESG | WP-7 |
| CD-CUI-8 | External system base URL and per-system timeout | Component-ESG | WP-7 |

---

## Work Packages

### WP-1: Template Authoring CRUD & Tree Visualization (L)

**Description**: Implement the template list, create/edit/delete pages. Display the inheritance tree as a visual hierarchy. Support template deletion with referencing-check feedback.

**Acceptance Criteria**:
- Design users can create, edit, and delete templates
- Template deletion blocked when instances or child templates reference it; UI displays the blocking references (`CD-CUI-1`)
- Inheritance tree visualization shows parent-child relationships (`[3.5-1]`, `[3.5-2]`)
- Setting a parent template on create/edit (`[3.5-1]`)
- Last-write-wins editing — no conflict detection or pessimistic locks (`KDD-deploy-10`, `[3.9-6]`)
- Blazor Server + Bootstrap styling, no JS frameworks (`KDD-ui-1`)
- Graph acyclicity enforced on save (UI surfaces error from Template Engine backend) (`KDD-deploy-4`)
- `[3.1-1]`, `[8-design-1]`

**Complexity**: L
**Traces**: `[3.1-1]`, `[3.5-1]`, `[3.5-2]`, `[3.9-6]`, `[8-design-1]`, `[8-design-10]`, KDD-ui-1, KDD-deploy-4, KDD-deploy-10, CD-CUI-1

---

### WP-2: Composition Management with Collision Feedback (M)

**Description**: UI for adding/removing feature module instances within templates. Display composed modules with their canonical path-qualified names. Show collision detection feedback and block save on collision.

**Acceptance Criteria**:
- Design users can add and remove feature module instances on a template (`[3.5-6]`)
- Composed members displayed with path-qualified canonical names `[ModuleInstanceName].[MemberName]` (`KDD-deploy-2`)
- Recursive composition supported — nested modules visualized with extended paths (`[3.5-7]`)
- Naming collision feedback shown immediately when composing modules; save blocked until resolved (`[3.5-8]`, `KDD-deploy-12`)
- Graph acyclicity check surfaces errors on save (`KDD-deploy-4`)

**Complexity**: M
**Traces**: `[3.5-6]`, `[3.5-7]`, `[3.5-8]`, KDD-deploy-2, KDD-deploy-4, KDD-deploy-12

---

### WP-3: Attribute/Alarm/Script Editing with Lock Indicators (L)

**Description**: Full editing UI for attributes, alarms, and scripts on templates. Lock flag toggle, override granularity enforcement, and visual indicators for lock state.

**Acceptance Criteria**:
- Attributes: Name, Value, Data Type, Lock Flag, Description, Data Source Reference editable (`[3.1-2]`, `[3.1-3]`, `[3.2-1]`–`[3.2-6]`)
- Template does not allow connection selection — only relative path (`[3.2-7]`, `[3.3-3]`)
- Alarms: Name, Description, Priority (0–1000), Lock Flag, Trigger Definition (Value Match / Range Violation / Rate of Change), On-Trigger Script reference (`[3.4-1]`–`[3.4-8]`)
- Scripts: Name, C# source code, Trigger config (Interval / Value Change / Conditional), minimum time between runs, Lock Flag (`[4.1-1]`, `[4.1-2]`, `[4.1-5]`, `[8-design-2]`)
- Script parameter definitions (name + data type per param) editable (`[4.1-3]`)
- Script return value definitions (field names + data types, objects/lists) editable (`[4.1-4]`)
- Lock flag toggled on all three entity types (`[3.6-1]`)
- Locked members show disabled/read-only editing (`[3.6-2]`)
- Unlocked members show enabled editing (`[3.6-3]`)
- Intermediate locking supported — can lock an unlocked member at current level (`[3.6-4]`)
- Cannot unlock upstream-locked members (`[3.6-5]`)
- Override granularity per entity type and field enforced (`KDD-deploy-3`)
- Alarms shown alongside attributes and scripts as first-class members (`[3.4-1]`)

**Complexity**: L
**Traces**: `[3.1-2]`, `[3.1-3]`, `[3.2-1]`–`[3.2-7]`, `[3.3-3]`, `[3.4-1]`–`[3.4-8]`, `[3.6-1]`–`[3.6-5]`, `[4.1-1]`–`[4.1-5]`, `[8-design-2]`, KDD-deploy-3

---

### WP-4: Inherited vs. Local vs. Overridden Visual Indicators (M)

**Description**: Visual differentiation showing where each member comes from: inherited from parent, locally defined, overridden from parent, or from a composed module with canonical path.

**Acceptance Criteria**:
- Each attribute, alarm, and script shows its origin level (inherited / local / overridden) with a visual indicator (`[3.6-res-1]`)
- Composed module members displayed with path-qualified canonical names (`KDD-deploy-2`)
- Child templates show inherited members (from parent + composed modules) as read-only unless unlocked for override (`[3.5-2]`, `[3.5-3]`)
- Child can add new members — shown as "local" (`[3.5-4]`)
- Cannot remove inherited members — no delete option shown on inherited items (`[3.5-5]`)
- Override scope: child can override non-locked parent attributes including piercing into composed modules (`[3.7-1]`, `[3.7-2]`, `[3.7-3]`)

**Complexity**: M
**Traces**: `[3.5-2]`–`[3.5-5]`, `[3.6-res-1]`, `[3.7-1]`–`[3.7-3]`, KDD-deploy-2

---

### WP-5: On-Demand Validation (S)

**Description**: "Validate" button for Design users that runs the full pre-deployment validation pipeline (flattening, naming collisions, script compilation, trigger references) and displays results without triggering deployment.

**Acceptance Criteria**:
- Validate action available on template and instance views for Design users (`[3.11-7]`, `[8-design-3]`)
- Displays validation results: flattening errors, naming collisions, compilation errors, trigger reference errors, binding completeness
- Actionable error display — each error identifies the specific member and issue
- Uses revision hash from flattened output for display (`KDD-deploy-5`)

**Complexity**: S
**Traces**: `[3.11-7]`, `[3.11-8]`, `[8-design-3]`, KDD-deploy-5

---

### WP-6: Shared Script Management (S)

**Description**: CRUD for shared (global) scripts. Code editor, parameter/return definitions, compilation check.

**Acceptance Criteria**:
- Create, edit, delete shared scripts (`[4.5-1]`, `[8-design-4]`)
- Shared scripts are not associated with any template — managed in separate section (`[4.5-1]`)
- Parameter definitions and return value definitions editable (`[4.5-2]`)
- Design role required — UI enforces access control (`[4.5-3]`)
- Compilation check action for C# syntax and structural correctness (`[3.11-8]`)

**Complexity**: S
**Traces**: `[4.5-1]`–`[4.5-3]`, `[3.11-8]`, `[8-design-4]`

---

### WP-7: External System Definition Management (M)

**Description**: CRUD for external system definitions including connection details, authentication, method definitions. Metadata only — no runtime execution.

**Acceptance Criteria**:
- Create, edit, delete external system definitions (`[5.1-1]`, `[8-design-6]`)
- Connection details editable: Base URL (`CD-CUI-8`), Authentication (API Key header name + value, or Basic Auth username + password) (`CD-CUI-7`, `[5.1-2]`)
- Per-system timeout editable (`CD-CUI-8`)
- Retry settings editable: max retry count, fixed time between retries (`CD-CUI-2`)
- Method definitions editable: method name, HTTP method (GET/POST/PUT/DELETE), relative path, parameter definitions, return type definitions (`CD-CUI-6`, `[5.1-3]`)
- Extended type system (Object, List) for method parameters and return types (`CD-CUI-5`)
- UI shows deployment scope indicator (all sites) (`[5.1-4]`)
- Editing by Design role; deployment trigger by Deployment role — clear separation (`[5.1-5]`)
- All changes audit logged via IAuditService

**Complexity**: M
**Traces**: `[5.1-1]`–`[5.1-5]`, `[8-design-6]`, CD-CUI-2, CD-CUI-5, CD-CUI-6, CD-CUI-7, CD-CUI-8

---

### WP-8: Database Connection Definition Management (S)

**Description**: CRUD for database connection definitions. Metadata only.

**Acceptance Criteria**:
- Create, edit, delete database connection definitions (`[5.5-1]`, `[8-design-7]`)
- Connection details editable: server, database name, credentials (`[5.5-2]`)
- Retry settings editable: max retry count, fixed time between retries (`[5.5-3]`, `CD-CUI-3`)
- UI shows deployment scope indicator (all sites) (`[5.5-4]`)
- Editing by Design role; deployment trigger by Deployment role (`[5.5-5]`)
- All changes audit logged via IAuditService

**Complexity**: S
**Traces**: `[5.5-1]`–`[5.5-5]`, `[8-design-7]`, CD-CUI-3

---

### WP-9: Notification List Management (S)

**Description**: CRUD for notification lists and recipients. SMTP configuration editing. Metadata only.

**Acceptance Criteria**:
- Create, edit, delete notification lists (`[6.1-1]`, `[8-design-5]`)
- List name and recipients editable (`[6.1-2]`)
- Recipient fields: name and email address (`[6.1-3]`)
- SMTP configuration editing (server, port, auth mode, TLS, from address, timeout, max connections, retry settings) (`CD-CUI-4`)
- UI shows deployment scope indicator (all sites) (`[6.1-4]`)
- Editing by Design role; deployment trigger by Deployment role (`[6.1-5]`)
- All changes audit logged via IAuditService

**Complexity**: S
**Traces**: `[6.1-1]`–`[6.1-5]`, `[8-design-5]`, CD-CUI-4

---

### WP-10: Inbound API Method Definition Management (M)

**Description**: CRUD for API method definitions. Code editor for implementation scripts.

**Acceptance Criteria**:
- Create, edit, delete API method definitions (`[7.4-1]`, `[8-design-8]`)
- Method name editable — unique identifier (`[7.4-2]`)
- Approved API keys selectable from existing keys (`[7.4-3]`)
- Parameter definitions editable (name, data type) with extended type system (Object, List) (`[7.4-4]`, `CD-CUI-5`)
- Return value definition editable (objects, lists) (`[7.4-5]`, `CD-CUI-5`)
- Per-method timeout editable (`[7.4-6]`)
- Implementation script (C# inline) editable with code editor (`[7.4-7]`)
- API scripts presented as standalone — no template inheritance UI (`[7.4-8]`)
- Design role required for method management
- All changes audit logged via IAuditService

**Complexity**: M
**Traces**: `[7.4-1]`–`[7.4-8]`, `[8-design-8]`, CD-CUI-5

---

### WP-11: Instance Creation from Template (M)

**Description**: Workflow for creating a new instance from a selected template at a selected site.

**Acceptance Criteria**:
- Create instances from templates (`[8-design-9]`)
- Template selection, site selection, area assignment required (`[3.8-5]`, `[3.10-1]`)
- Instance structure (attributes, alarms, scripts) derived from template — read-only structure (`[3.8-4]`)
- Instance cannot add new attributes (`[3.8-2]`)
- Instance cannot remove attributes (`[3.8-3]`)
- Deployment role required

**Complexity**: M
**Traces**: `[3.8-1]`–`[3.8-5]`, `[3.10-1]`, `[8-design-9]`

---

### WP-12: Instance Per-Attribute Data Connection Binding with Bulk Assignment (M)

**Description**: UI for binding each attribute with a data source reference to a data connection, with bulk assignment support.

**Acceptance Criteria**:
- Per-attribute data connection binding — each attribute with a data source reference individually selects its data connection from the site's available connections (`[3.3-1]`)
- Bulk assignment: select multiple attributes and assign one data connection to all at once (`[3.3-2]`, `[8-design-9]`)
- Only connections assigned to the instance's site are available for selection
- Attributes without data source reference are not shown in binding UI

**Complexity**: M
**Traces**: `[3.3-1]`, `[3.3-2]`, `[8-design-9]`

---

### WP-13: Instance Attribute Override Editing (S)

**Description**: UI for editing instance-level attribute overrides respecting lock rules.

**Acceptance Criteria**:
- Instance can override non-locked attribute values (`[3.8-1]`)
- Override granularity enforced per entity type and field (`KDD-deploy-3`)
- Locked attributes shown as read-only — cannot be overridden (`[3.6-2]`)
- Visual indicators show which values are overridden at instance level vs. inherited from template

**Complexity**: S
**Traces**: `[3.8-1]`, `[3.6-2]`, KDD-deploy-3, `[8-design-9]`

---

## Test Strategy

### Unit Tests
- Component rendering tests for each Blazor page/component using bUnit
- Lock flag enforcement: verify locked members render as read-only
- Override granularity: verify correct fields are editable per entity type
- Collision detection feedback rendering
- Visual indicator logic (inherited / local / overridden classification)
- Bulk assignment selection logic

### Integration Tests
- Template CRUD round-trip: create → edit → validate → verify in DB
- Composition flow: add module → detect collision → resolve → save
- Instance creation: select template → assign site/area → bind connections → save
- Shared script: create → compile check → verify
- External system definition CRUD → verify audit log entry
- Notification list CRUD → verify audit log entry
- API method definition CRUD → verify audit log entry
- Database connection definition CRUD → verify audit log entry
- Role enforcement: Design user can author; non-Design user is blocked
- Template deletion with existing references → verify blocked with feedback

### Negative Tests
- Attempt to override a locked attribute → verify blocked
- Attempt to unlock an upstream-locked member → verify blocked
- Attempt to remove inherited member from child template → verify blocked
- Attempt to add attribute on instance → verify not available
- Attempt to remove attribute on instance → verify not available
- Attempt to save template with naming collision → verify blocked with error
- Attempt to create circular inheritance → verify blocked
- Attempt to create circular composition → verify blocked
- Non-Design user accessing authoring pages → verify access denied

---

## Verification Gate

Phase 5 is complete when:
1. All 13 work packages pass acceptance criteria
2. All unit and integration tests pass
3. All negative tests verify prohibited behaviors
4. A Design user can perform a full template authoring workflow: create template → add attributes/alarms/scripts → set locks → compose modules → validate → create instance → bind connections → override attributes
5. All definition management UIs (external system, DB connection, notification list, inbound API) are functional with audit logging
6. Role-based access control correctly restricts access by role

---

## Open Questions

No new questions discovered during Phase 5 plan generation.

---

## Split-Section Verification

| Section | Phase 5 Bullets | Other Phase(s) | Other Phase Bullets |
|---------|----------------|-----------------|---------------------|
| 3.1 | `[3.1-1]`–`[3.1-3]` (UI) | Phase 2 | Model, validation (all bullets) |
| 3.2 | `[3.2-1]`–`[3.2-7]` (UI) | Phase 2 | Model, storage (all bullets) |
| 3.3 | `[3.3-1]`–`[3.3-3]` (UI) | Phase 2, 3B | Model/binding, runtime |
| 3.4 | `[3.4-1]`–`[3.4-8]` (UI) | Phase 2 | Model (all bullets) |
| 3.5 | `[3.5-1]`–`[3.5-8]` (UI) | Phase 2 | Model, enforcement (all bullets) |
| 3.6 | `[3.6-1]`–`[3.6-5]`, `[3.6-res-1]` (UI) | Phase 2 | Model, enforcement |
| 3.7 | `[3.7-1]`–`[3.7-3]` (UI) | Phase 2 | Model, enforcement |
| 3.8 | `[3.8-1]`–`[3.8-5]` (UI) | Phase 2 | Model, enforcement |
| 3.9 | `[3.9-6]` (last-write-wins UI) | Phase 3C, 6 | Backend pipeline, deployment UI |
| 3.10 | `[3.10-1]` (instance-area assign) | Phase 2, 4 | Model, admin UI |
| 3.11 | `[3.11-7]`, `[3.11-8]` (on-demand UI) | Phase 2 | Backend validation |
| 4.1 | `[4.1-1]`–`[4.1-5]` (UI) | Phase 2, 3B | Model, runtime |
| 4.5 | `[4.5-1]`–`[4.5-3]` (UI) | Phase 3B | Runtime |
| 5.1 | `[5.1-1]`–`[5.1-5]` (definition UI) | Phase 7 | Runtime execution |
| 5.5 | `[5.5-1]`–`[5.5-5]` (definition UI) | Phase 7 | Runtime execution |
| 6.1 | `[6.1-1]`–`[6.1-5]` (definition UI) | Phase 7 | Runtime delivery |
| 7.4 | `[7.4-1]`–`[7.4-8]` (definition UI) | Phase 7 | Runtime execution |
| 8 | `[8-design-1]`–`[8-design-10]` | Phase 4, 6 | Admin/operator, deployment/troubleshooting |

---

## Orphan Check Result

**Forward check**: Every Requirements Checklist item and Design Constraints Checklist item maps to at least one work package with acceptance criteria that would fail if the requirement were not implemented. PASS.

**Reverse check**: Every work package traces back to at least one requirement or design constraint. No untraceable work. PASS.

**Split-section check**: All split sections verified above. Phase 5 covers UI presentation for sections shared with Phase 2 (model), Phase 3B (runtime), Phase 3C/6 (deployment pipeline/UI), Phase 4 (admin UI), and Phase 7 (runtime execution). No unassigned bullets found. PASS.

**Negative requirement check**: The following negative requirements have explicit acceptance criteria:
- `[3.2-7]` Template does not allow connection selection → verified in WP-3
- `[3.3-3]` Templates do not specify default connection → verified in WP-3
- `[3.5-5]` Cannot remove inherited members → verified in WP-4
- `[3.6-2]` Locked cannot be overridden → verified in WP-3
- `[3.6-5]` Cannot unlock upstream-locked → verified in WP-3
- `[3.8-2]` Instance cannot add attributes → verified in WP-11
- `[3.8-3]` Instance cannot remove attributes → verified in WP-11
- `[3.9-6]` No conflict detection → verified in WP-1

PASS.

**Codex MCP verification**: Skipped — external tool verification deferred.