feat(transport): site/connection/instance bundle DTOs (M8 A2)

src/ZB.MOM.WW.ScadaBridge.Transport/Serialization/EntityDtos.cs

@@ -1,7 +1,9 @@
 using ZB.MOM.WW.ScadaBridge.Commons.Entities.ExternalSystems;
 using ZB.MOM.WW.ScadaBridge.Commons.Entities.InboundApi;
+using ZB.MOM.WW.ScadaBridge.Commons.Entities.Instances;
 using ZB.MOM.WW.ScadaBridge.Commons.Entities.Notifications;
 using ZB.MOM.WW.ScadaBridge.Commons.Entities.Scripts;
+using ZB.MOM.WW.ScadaBridge.Commons.Entities.Sites;
 using ZB.MOM.WW.ScadaBridge.Commons.Entities.Templates;
 using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
 
@@ -24,7 +26,15 @@ public sealed record EntityAggregate(
     IReadOnlyList<DatabaseConnectionDefinition> DatabaseConnections,
     IReadOnlyList<NotificationList> NotificationLists,
     IReadOnlyList<SmtpConfiguration> SmtpConfigurations,
-    IReadOnlyList<ApiMethod> ApiMethods);
+    IReadOnlyList<ApiMethod> ApiMethods)
+{
+    // M8: site/instance-scoped entities. Init-only with empty-array defaults so
+    // existing positional `new EntityAggregate(...)` callers keep compiling and
+    // never see a null collection; new callers opt in via object-initializer.
+    public IReadOnlyList<Site> Sites { get; init; } = Array.Empty<Site>();
+    public IReadOnlyList<DataConnection> DataConnections { get; init; } = Array.Empty<DataConnection>();
+    public IReadOnlyList<Instance> Instances { get; init; } = Array.Empty<Instance>();
+}
 
 /// <summary>
 /// Top-level serializable bundle payload. Lists are sequenced in dependency
@@ -50,7 +60,24 @@ public sealed record BundleContentDto(
     IReadOnlyList<NotificationListDto> NotificationLists,
     IReadOnlyList<SmtpConfigDto> SmtpConfigs,
     IReadOnlyList<ApiMethodDto> ApiMethods,
-    IReadOnlyList<ApiKeyDto>? ApiKeys = null);
+    IReadOnlyList<ApiKeyDto>? ApiKeys = null)
+{
+    // M8: site/instance-scoped payloads. Modeled as init-only properties with
+    // empty-array defaults (rather than additional positional ctor params) for
+    // two reasons:
+    //   1. Forward-compat: deserializing an OLDER bundle whose content blob has
+    //      no sites/dataConnections/instances fields leaves each property at its
+    //      Array.Empty<>() initializer — so consumers always see an empty list,
+    //      never null. (Contrast ApiKeys, which is a nullable legacy field.)
+    //   2. Source-compat: every existing `new BundleContentDto(...)` positional
+    //      caller keeps compiling unchanged; new producers opt in via an
+    //      object-initializer (`new BundleContentDto(...) { Sites = ... }`).
+    // These are written by the serializer (WhenWritingNull does not apply — they
+    // are non-null), so new bundles always carry the three arrays explicitly.
+    public IReadOnlyList<SiteDto> Sites { get; init; } = Array.Empty<SiteDto>();
+    public IReadOnlyList<DataConnectionDto> DataConnections { get; init; } = Array.Empty<DataConnectionDto>();
+    public IReadOnlyList<InstanceDto> Instances { get; init; } = Array.Empty<InstanceDto>();
+}
 
 /// <summary>
 /// Carved-off secret values for an entity. The outer DTO carries all non-
@@ -175,3 +202,71 @@ public sealed record ApiMethodDto(
     string? ParameterDefinitions,
     string? ReturnDefinition,
     int TimeoutSeconds);
+
+// --- M8: site/instance-scoped transport DTOs --------------------------------
+// These travel alongside the original central-config DTOs above. Sites and
+// instances are referenced by their stable string identities (SiteIdentifier,
+// UniqueName, TemplateName) rather than database ids so a bundle resolves
+// correctly against the *target* environment's own surrogate keys.
+
+/// <summary>
+/// A site definition. Addresses are carried verbatim; the importer decides
+/// whether to keep or rewrite them for the target environment.
+/// </summary>
+public sealed record SiteDto(
+    string SiteIdentifier,
+    string Name,
+    string? Description,
+    string? NodeAAddress,
+    string? NodeBAddress,
+    string? GrpcNodeAAddress,
+    string? GrpcNodeBAddress);
+
+/// <summary>
+/// A site-scoped protocol connection (the <c>Sites.DataConnection</c> entity —
+/// NOT the External-System <see cref="DatabaseConnectionDto"/>). The protocol-
+/// specific Primary/Backup configuration JSON rides inside <see cref="Secrets"/>
+/// so a "share without secrets" export can drop it as a unit.
+/// </summary>
+public sealed record DataConnectionDto(
+    string SiteIdentifier,
+    string Name,
+    string Protocol,
+    int FailoverRetryCount,
+    SecretsBlock? Secrets);
+
+public sealed record InstanceAttributeOverrideDto(
+    string AttributeName,
+    string? OverrideValue,
+    DataType? ElementDataType);
+
+public sealed record InstanceAlarmOverrideDto(
+    string AlarmCanonicalName,
+    string? TriggerConfigurationOverride,
+    int? PriorityLevelOverride);
+
+public sealed record InstanceNativeAlarmSourceOverrideDto(
+    string SourceCanonicalName,
+    string? ConnectionNameOverride,
+    string? SourceReferenceOverride,
+    string? ConditionFilterOverride);
+
+public sealed record InstanceConnectionBindingDto(
+    string AttributeName,
+    string ConnectionName,
+    string? DataSourceReferenceOverride);
+
+/// <summary>
+/// A deployable instance with all of its per-instance overrides and bindings.
+/// References its template and site by name/identifier (not id).
+/// </summary>
+public sealed record InstanceDto(
+    string UniqueName,
+    string TemplateName,
+    string SiteIdentifier,
+    string? AreaName,
+    InstanceState State,
+    IReadOnlyList<InstanceAttributeOverrideDto> AttributeOverrides,
+    IReadOnlyList<InstanceAlarmOverrideDto> AlarmOverrides,
+    IReadOnlyList<InstanceNativeAlarmSourceOverrideDto> NativeAlarmSourceOverrides,
+    IReadOnlyList<InstanceConnectionBindingDto> ConnectionBindings);