feat(esg): --timeout-seconds on external-system create/update (management command + CLI, additive contract)

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/ExternalSystemCommands.cs

@@ -49,6 +49,7 @@ public static class ExternalSystemCommands
         var endpointUrlOption = new Option<string>("--endpoint-url") { Description = "Endpoint URL", Required = true };
         var authTypeOption = new Option<string>("--auth-type") { Description = "Auth type", Required = true };
         var authConfigOption = new Option<string?>("--auth-config") { Description = "Auth configuration JSON" };
+        var timeoutOption = new Option<int?>("--timeout-seconds") { Description = "Per-system HTTP timeout in seconds (0 = use gateway default); omit to preserve" };
 
         var cmd = new Command("update") { Description = "Update an external system" };
         cmd.Add(idOption);
@@ -56,6 +57,7 @@ public static class ExternalSystemCommands
         cmd.Add(endpointUrlOption);
         cmd.Add(authTypeOption);
         cmd.Add(authConfigOption);
+        cmd.Add(timeoutOption);
         cmd.SetAction(async (ParseResult result) =>
         {
             var id = result.GetValue(idOption);
@@ -63,9 +65,10 @@ public static class ExternalSystemCommands
             var endpointUrl = result.GetValue(endpointUrlOption)!;
             var authType = result.GetValue(authTypeOption)!;
             var authConfig = result.GetValue(authConfigOption);
+            var timeoutSeconds = result.GetValue(timeoutOption);
             return await CommandHelpers.ExecuteCommandAsync(
                 result, urlOption, formatOption, usernameOption, passwordOption,
-                new UpdateExternalSystemCommand(id, name, endpointUrl, authType, authConfig));
+                new UpdateExternalSystemCommand(id, name, endpointUrl, authType, authConfig, timeoutSeconds));
         });
         return cmd;
     }
@@ -87,21 +90,24 @@ public static class ExternalSystemCommands
         var endpointUrlOption = new Option<string>("--endpoint-url") { Description = "Endpoint URL", Required = true };
         var authTypeOption = new Option<string>("--auth-type") { Description = "Auth type (ApiKey, BasicAuth)", Required = true };
         var authConfigOption = new Option<string?>("--auth-config") { Description = "Auth configuration JSON" };
+        var timeoutOption = new Option<int?>("--timeout-seconds") { Description = "Per-system HTTP timeout in seconds (0 = use gateway default)" };
 
         var cmd = new Command("create") { Description = "Create an external system" };
         cmd.Add(nameOption);
         cmd.Add(endpointUrlOption);
         cmd.Add(authTypeOption);
         cmd.Add(authConfigOption);
+        cmd.Add(timeoutOption);
         cmd.SetAction(async (ParseResult result) =>
         {
             var name = result.GetValue(nameOption)!;
             var endpointUrl = result.GetValue(endpointUrlOption)!;
             var authType = result.GetValue(authTypeOption)!;
             var authConfig = result.GetValue(authConfigOption);
+            var timeoutSeconds = result.GetValue(timeoutOption);
             return await CommandHelpers.ExecuteCommandAsync(
                 result, urlOption, formatOption, usernameOption, passwordOption,
-                new CreateExternalSystemCommand(name, endpointUrl, authType, authConfig));
+                new CreateExternalSystemCommand(name, endpointUrl, authType, authConfig, timeoutSeconds));
         });
         return cmd;
     }

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/ExternalSystemCommands.cs

@@ -2,8 +2,8 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
 
 public record ListExternalSystemsCommand;
 public record GetExternalSystemCommand(int ExternalSystemId);
-public record CreateExternalSystemCommand(string Name, string EndpointUrl, string AuthType, string? AuthConfiguration);
-public record UpdateExternalSystemCommand(int ExternalSystemId, string Name, string EndpointUrl, string AuthType, string? AuthConfiguration);
+public record CreateExternalSystemCommand(string Name, string EndpointUrl, string AuthType, string? AuthConfiguration, int? TimeoutSeconds = null);
+public record UpdateExternalSystemCommand(int ExternalSystemId, string Name, string EndpointUrl, string AuthType, string? AuthConfiguration, int? TimeoutSeconds = null);
 public record DeleteExternalSystemCommand(int ExternalSystemId);
 
 // External System Methods

src/ZB.MOM.WW.ScadaBridge.ManagementService/ManagementActor.cs

@@ -1622,7 +1622,8 @@ public class ManagementActor : ReceiveActor
         var repo = sp.GetRequiredService<IExternalSystemRepository>();
         var def = new ExternalSystemDefinition(cmd.Name, cmd.EndpointUrl, cmd.AuthType)
         {
-            AuthConfiguration = cmd.AuthConfiguration
+            AuthConfiguration = cmd.AuthConfiguration,
+            TimeoutSeconds = cmd.TimeoutSeconds ?? 0
         };
         await repo.AddExternalSystemAsync(def);
         await repo.SaveChangesAsync();
@@ -1639,6 +1640,7 @@ public class ManagementActor : ReceiveActor
         def.EndpointUrl = cmd.EndpointUrl;
         def.AuthType = cmd.AuthType;
         def.AuthConfiguration = cmd.AuthConfiguration;
+        if (cmd.TimeoutSeconds is { } ts) def.TimeoutSeconds = ts;
         await repo.UpdateExternalSystemAsync(def);
         await repo.SaveChangesAsync();
         await AuditAsync(sp, user, "Update", "ExternalSystem", def.Id.ToString(), def.Name, def);

tests/ZB.MOM.WW.ScadaBridge.CLI.Tests/Commands/ExternalSystemTimeoutOptionTests.cs

@@ -0,0 +1,79 @@
+using System.CommandLine;
+using ZB.MOM.WW.ScadaBridge.CLI.Commands;
+
+namespace ZB.MOM.WW.ScadaBridge.CLI.Tests.Commands;
+
+/// <summary>
+/// PLAN-06 Task 11: <c>external-system create</c> and <c>external-system update</c>
+/// must expose an optional <c>--timeout-seconds</c> (<see cref="int"/>?) flag that
+/// carries the per-system ESG HTTP timeout. Omitting it preserves the existing value
+/// (update) / uses the gateway default (create).
+/// </summary>
+public class ExternalSystemTimeoutOptionTests
+{
+    private static readonly Option<string> Url = new("--url") { Recursive = true };
+    private static readonly Option<string> Format = new("--format") { Recursive = true };
+    private static readonly Option<string> Username = new("--username") { Recursive = true };
+    private static readonly Option<string> Password = new("--password") { Recursive = true };
+
+    private static Command Group() => ExternalSystemCommands.Build(Url, Format, Username, Password);
+
+    private static Option? FindOption(Command command, string name)
+        => command.Options.SingleOrDefault(o => o.Name == name);
+
+    [Fact]
+    public void Create_HasOptionalTimeoutSecondsOption()
+    {
+        var create = Group().Subcommands.Single(c => c.Name == "create");
+        var option = FindOption(create, "--timeout-seconds");
+        Assert.NotNull(option);
+        Assert.False(option!.Required);
+    }
+
+    [Fact]
+    public void Update_HasOptionalTimeoutSecondsOption()
+    {
+        var update = Group().Subcommands.Single(c => c.Name == "update");
+        var option = FindOption(update, "--timeout-seconds");
+        Assert.NotNull(option);
+        Assert.False(option!.Required);
+    }
+
+    [Fact]
+    public void Create_ParsesTimeoutSecondsValue()
+    {
+        var parse = Group().Parse(new[]
+        {
+            "create", "--name", "Sys", "--endpoint-url", "http://x",
+            "--auth-type", "none", "--timeout-seconds", "15",
+        });
+
+        Assert.Empty(parse.Errors);
+        Assert.Equal(15, parse.GetValue<int?>("--timeout-seconds"));
+    }
+
+    [Fact]
+    public void Update_ParsesTimeoutSecondsValue()
+    {
+        var parse = Group().Parse(new[]
+        {
+            "update", "--id", "7", "--name", "Sys", "--endpoint-url", "http://x",
+            "--auth-type", "none", "--timeout-seconds", "20",
+        });
+
+        Assert.Empty(parse.Errors);
+        Assert.Equal(20, parse.GetValue<int?>("--timeout-seconds"));
+    }
+
+    [Fact]
+    public void Create_OmittedTimeoutSeconds_ParsesWithoutError()
+    {
+        var parse = Group().Parse(new[]
+        {
+            "create", "--name", "Sys", "--endpoint-url", "http://x", "--auth-type", "none",
+        });
+
+        Assert.Empty(parse.Errors);
+        Assert.Null(parse.GetValue<int?>("--timeout-seconds"));
+    }
+}

tests/ZB.MOM.WW.ScadaBridge.ManagementService.Tests/ManagementActorTests.cs

@@ -2923,4 +2923,56 @@ public class ManagementActorTests : TestKit, IDisposable
         Assert.Contains("MissingSharedSchema", msg.JsonData, StringComparison.Ordinal);
         Assert.Contains("\"category\":15", msg.JsonData, StringComparison.Ordinal);
     }
+
+    // ========================================================================
+    // PLAN-06 Task 11: per-system ESG TimeoutSeconds management commands
+    // ========================================================================
+
+    [Fact]
+    public void CreateExternalSystem_PersistsTimeoutSeconds()
+    {
+        var extRepo = Substitute.For<IExternalSystemRepository>();
+        _services.AddScoped(_ => extRepo);
+
+        var actor = CreateActor();
+        var envelope = Envelope(
+            new CreateExternalSystemCommand("Sys", "http://x", "none", null, TimeoutSeconds: 15),
+            "Designer");
+
+        actor.Tell(envelope);
+
+        var response = ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(5));
+        Assert.Equal(envelope.CorrelationId, response.CorrelationId);
+        extRepo.Received(1).AddExternalSystemAsync(
+            Arg.Is<Commons.Entities.ExternalSystems.ExternalSystemDefinition>(d => d.TimeoutSeconds == 15),
+            Arg.Any<CancellationToken>());
+    }
+
+    [Fact]
+    public void UpdateExternalSystem_NullTimeout_PreservesExisting()
+    {
+        var existing = new Commons.Entities.ExternalSystems.ExternalSystemDefinition("Sys", "http://x", "none")
+        {
+            Id = 7,
+            TimeoutSeconds = 42
+        };
+        var extRepo = Substitute.For<IExternalSystemRepository>();
+        extRepo.GetExternalSystemByIdAsync(7, Arg.Any<CancellationToken>()).Returns(existing);
+        _services.AddScoped(_ => extRepo);
+
+        var actor = CreateActor();
+        // TimeoutSeconds omitted (null) => existing 42 must be preserved.
+        var envelope = Envelope(
+            new UpdateExternalSystemCommand(7, "Sys", "http://x", "none", null),
+            "Designer");
+
+        actor.Tell(envelope);
+
+        var response = ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(5));
+        Assert.Equal(envelope.CorrelationId, response.CorrelationId);
+        Assert.Equal(42, existing.TimeoutSeconds);
+        extRepo.Received(1).UpdateExternalSystemAsync(
+            Arg.Is<Commons.Entities.ExternalSystems.ExternalSystemDefinition>(d => d.TimeoutSeconds == 42),
+            Arg.Any<CancellationToken>());
+    }
 }