feat(m9/T32c): schema-library CRUD commands + handlers + Central UI page + read-accessor

2026-06-18 12:32:31 -04:00
parent 71d5722692
commit 71a2bca4df
13 changed files with 1363 additions and 0 deletions
@@ -0,0 +1,36 @@
+namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;
+
+/// <summary>
+/// CentralUI read-accessor over the named JSON-Schema library (M9-T32c) for surfaces
+/// that need to RESOLVE <c>{"$ref":"lib:Name"}</c> pointers — chiefly the schema-driven
+/// value-entry forms (T30). It exposes the library as a name → schema-JSON map (and the
+/// equivalent single-name lookup) so the value form can plug the resolved schema text
+/// into <c>InboundApiSchema.Parse(json, name =&gt; query.Resolve(name))</c> exactly the
+/// way the deploy-time / runtime resolvers do.
+/// </summary>
+/// <remarks>
+/// This is the READ counterpart of <see cref="ISchemaLibraryService"/> (the authoring /
+/// mutation facade). Reads do not need the guard-running ManagementActor path, so this
+/// accessor is backed by <c>ISharedSchemaRepository</c> over a fresh DI scope (mirroring
+/// the AuditLog / KPI query services), keeping it off the circuit-scoped DbContext.
+/// </remarks>
+public interface ISchemaLibraryQueryService
+{
+    /// <summary>
+    /// Returns the whole library as a name → schema-JSON map (name-keyed, ordinal
+    /// comparison — the same key the <c>lib:Name</c> resolver matches on).
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task resolving to the name → schema-JSON map (empty when the library is empty).</returns>
+    Task<IReadOnlyDictionary<string, string>> GetSchemaMapAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Returns the schema JSON for a single named library entry, or <c>null</c> when no
+    /// entry by that name exists. Suitable directly as the <c>resolveRef</c> seam's
+    /// per-name lookup.
+    /// </summary>
+    /// <param name="name">The library entry name (the part after the <c>lib:</c> scheme prefix).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task resolving to the entry's schema JSON, or <c>null</c> if not found.</returns>
+    Task<string?> ResolveAsync(string name, CancellationToken cancellationToken = default);
+}
@@ -0,0 +1,83 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Entities.Schemas;
+
+namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;
+
+/// <summary>
+/// Outcome of a single schema-library mutation dispatch (create / update / delete).
+/// Wraps either success or a human-readable server error (a duplicate-name guard, an
+/// invalid-JSON validation failure, or a not-found) so the schema-library page can
+/// render an inline result rather than reasoning about transport exceptions or the
+/// three management response shapes. Mirrors <see cref="DataConnectionMoveResult"/>.
+/// </summary>
+/// <param name="Success">Whether the mutation succeeded.</param>
+/// <param name="Error">A human-readable error message when <paramref name="Success"/> is <c>false</c>; otherwise <c>null</c>.</param>
+public record SchemaLibraryActionResult(bool Success, string? Error)
+{
+    /// <summary>Creates a successful result.</summary>
+    /// <returns>A successful <see cref="SchemaLibraryActionResult"/>.</returns>
+    public static SchemaLibraryActionResult Ok() => new(true, null);
+
+    /// <summary>Creates a failed result carrying <paramref name="error"/>.</summary>
+    /// <param name="error">The human-readable failure (typically a server guard / validation message).</param>
+    /// <returns>A failed <see cref="SchemaLibraryActionResult"/>.</returns>
+    public static SchemaLibraryActionResult Fail(string error) => new(false, error);
+}
+
+/// <summary>
+/// CentralUI facade over the schema-library CRUD management commands (M9-T32c). Every
+/// mutation (<c>CreateSharedSchemaCommand</c> / <c>UpdateSharedSchemaCommand</c> /
+/// <c>DeleteSharedSchemaCommand</c>) and the list query is dispatched to the central
+/// <c>ManagementActor</c> through the in-process <c>ManagementActorHolder</c> seam — the
+/// SAME Ask path the HTTP <c>/management</c> endpoint uses — so the server remains the
+/// single enforcer of the Designer role gate, the unique-name guard, and JSON-Schema
+/// validation. The page re-implements none of that: it lists, authors via
+/// <c>SchemaBuilder</c>, and SUBMITS commands; any guard / validation failure comes back
+/// as a classified <see cref="SchemaLibraryActionResult"/>.
+/// </summary>
+/// <remarks>
+/// The current Blazor principal is projected to an <c>AuthenticatedUser</c> so the
+/// server's role gate runs against the real identity. Mirrors
+/// <c>IDataConnectionMoveService</c> / <c>ISecuredWriteService</c>.
+/// </remarks>
+public interface ISchemaLibraryService
+{
+    /// <summary>
+    /// Lists every library schema (name-ordered) via the read-gated
+    /// <c>ListSharedSchemasCommand</c>. A read failure yields an empty list (logged) so
+    /// the page renders gracefully.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task resolving to the library entries, or an empty list on failure.</returns>
+    Task<IReadOnlyList<SharedSchema>> ListAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Creates a library schema via the Designer-gated <c>CreateSharedSchemaCommand</c>.
+    /// </summary>
+    /// <param name="name">The unique schema name.</param>
+    /// <param name="scope">An optional scope discriminator (<c>null</c> = global).</param>
+    /// <param name="schemaJson">The JSON Schema document text.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task resolving to a classified create outcome.</returns>
+    Task<SchemaLibraryActionResult> CreateAsync(
+        string name, string? scope, string schemaJson, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Updates a library schema via the Designer-gated <c>UpdateSharedSchemaCommand</c>.
+    /// </summary>
+    /// <param name="id">Primary key of the schema to update.</param>
+    /// <param name="name">The (possibly renamed) unique schema name.</param>
+    /// <param name="scope">An optional scope discriminator (<c>null</c> = global).</param>
+    /// <param name="schemaJson">The JSON Schema document text.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task resolving to a classified update outcome.</returns>
+    Task<SchemaLibraryActionResult> UpdateAsync(
+        int id, string name, string? scope, string schemaJson, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Deletes a library schema via the Designer-gated <c>DeleteSharedSchemaCommand</c>.
+    /// </summary>
+    /// <param name="id">Primary key of the schema to delete.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task resolving to a classified delete outcome.</returns>
+    Task<SchemaLibraryActionResult> DeleteAsync(int id, CancellationToken cancellationToken = default);
+}
@@ -0,0 +1,58 @@
+using Microsoft.Extensions.DependencyInjection;
+using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
+
+namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;
+
+/// <summary>
+/// Default <see cref="ISchemaLibraryQueryService"/> implementation (M9-T32c). Reads the
+/// named JSON-Schema library directly from <see cref="ISharedSchemaRepository"/> over a
+/// fresh DI scope per query — mirroring <c>AuditLogQueryService</c> /
+/// <c>KpiHistoryQueryService</c> so a value form's auto-load never races other reads on
+/// the shared circuit-scoped DbContext. Read-only; no mutation goes through here.
+/// </summary>
+public sealed class SchemaLibraryQueryService : ISchemaLibraryQueryService
+{
+    private readonly IServiceScopeFactory _scopeFactory;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SchemaLibraryQueryService"/>.
+    /// </summary>
+    /// <param name="scopeFactory">Factory used to open a fresh DI scope (and DbContext) per query.</param>
+    public SchemaLibraryQueryService(IServiceScopeFactory scopeFactory)
+    {
+        _scopeFactory = scopeFactory ?? throw new ArgumentNullException(nameof(scopeFactory));
+    }
+
+    /// <inheritdoc/>
+    public async Task<IReadOnlyDictionary<string, string>> GetSchemaMapAsync(
+        CancellationToken cancellationToken = default)
+    {
+        await using var scope = _scopeFactory.CreateAsyncScope();
+        var repo = scope.ServiceProvider.GetRequiredService<ISharedSchemaRepository>();
+        var all = await repo.ListAsync(cancellationToken);
+
+        // Ordinal-keyed to match the lib:Name resolver's exact-name lookup. Last-wins on
+        // the (DB-unique) name guards against a transient duplicate read.
+        var map = new Dictionary<string, string>(StringComparer.Ordinal);
+        foreach (var schema in all)
+        {
+            map[schema.Name] = schema.SchemaJson;
+        }
+
+        return map;
+    }
+
+    /// <inheritdoc/>
+    public async Task<string?> ResolveAsync(string name, CancellationToken cancellationToken = default)
+    {
+        if (string.IsNullOrEmpty(name))
+        {
+            return null;
+        }
+
+        await using var scope = _scopeFactory.CreateAsyncScope();
+        var repo = scope.ServiceProvider.GetRequiredService<ISharedSchemaRepository>();
+        var schema = await repo.GetByNameAsync(name, cancellationToken);
+        return schema?.SchemaJson;
+    }
+}
@@ -0,0 +1,165 @@
+using System.Security.Claims;
+using System.Text.Json;
+using Akka.Actor;
+using Microsoft.AspNetCore.Components.Authorization;
+using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.ScadaBridge.Commons.Entities.Schemas;
+using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
+using ZB.MOM.WW.ScadaBridge.ManagementService;
+using ZB.MOM.WW.ScadaBridge.Security;
+
+namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;
+
+/// <summary>
+/// Default <see cref="ISchemaLibraryService"/> implementation — a thin facade that
+/// dispatches the schema-library CRUD commands to the central <c>ManagementActor</c>
+/// through the in-process <see cref="ManagementActorHolder"/> (the same Ask seam the
+/// HTTP <c>/management</c> endpoint uses). The actor authorizes the command against the
+/// supplied <see cref="AuthenticatedUser"/> (Designer-gated mutations), enforces the
+/// unique-name guard, validates the JSON Schema, and writes the audit row — none of
+/// that is re-implemented here. Mirrors <see cref="SecuredWriteService"/> /
+/// <see cref="DataConnectionMoveService"/>.
+/// </summary>
+public sealed class SchemaLibraryService : ISchemaLibraryService
+{
+    /// <summary>
+    /// camelCase + case-insensitive, matching <c>ManagementActor.SerializeResult</c>'s
+    /// options. <see cref="ManagementSuccess.JsonData"/> is produced with those settings,
+    /// so the deserializer must mirror them to bind every property.
+    /// </summary>
+    private static readonly JsonSerializerOptions ResultDeserializerOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+    };
+
+    private static readonly TimeSpan AskTimeout = TimeSpan.FromSeconds(30);
+
+    private readonly ManagementActorHolder _holder;
+    private readonly AuthenticationStateProvider _auth;
+    private readonly ILogger<SchemaLibraryService> _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SchemaLibraryService"/>.
+    /// </summary>
+    /// <param name="holder">Holder for the central <c>ManagementActor</c> reference.</param>
+    /// <param name="auth">Authentication state provider used to project the current principal.</param>
+    /// <param name="logger">Logger instance.</param>
+    public SchemaLibraryService(
+        ManagementActorHolder holder,
+        AuthenticationStateProvider auth,
+        ILogger<SchemaLibraryService> logger)
+    {
+        _holder = holder ?? throw new ArgumentNullException(nameof(holder));
+        _auth = auth ?? throw new ArgumentNullException(nameof(auth));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    /// <inheritdoc/>
+    public async Task<IReadOnlyList<SharedSchema>> ListAsync(CancellationToken cancellationToken = default)
+    {
+        var response = await SendAsync(new ListSharedSchemasCommand(), cancellationToken);
+        if (response is ManagementSuccess success)
+        {
+            var items = JsonSerializer.Deserialize<List<SharedSchema>>(
+                success.JsonData, ResultDeserializerOptions);
+            return items ?? new List<SharedSchema>();
+        }
+
+        // Read path: log + return empty so the list table renders gracefully.
+        _logger.LogWarning("ListSharedSchemas failed: {Response}", DescribeFailure(response));
+        return Array.Empty<SharedSchema>();
+    }
+
+    /// <inheritdoc/>
+    public Task<SchemaLibraryActionResult> CreateAsync(
+        string name, string? scope, string schemaJson, CancellationToken cancellationToken = default)
+        => DispatchAsync(new CreateSharedSchemaCommand(name, scope, schemaJson), cancellationToken);
+
+    /// <inheritdoc/>
+    public Task<SchemaLibraryActionResult> UpdateAsync(
+        int id, string name, string? scope, string schemaJson, CancellationToken cancellationToken = default)
+        => DispatchAsync(new UpdateSharedSchemaCommand(id, name, scope, schemaJson), cancellationToken);
+
+    /// <inheritdoc/>
+    public Task<SchemaLibraryActionResult> DeleteAsync(int id, CancellationToken cancellationToken = default)
+        => DispatchAsync(new DeleteSharedSchemaCommand(id), cancellationToken);
+
+    /// <summary>
+    /// Dispatches a single mutating command and maps the response (or any fault) to a
+    /// typed <see cref="SchemaLibraryActionResult"/>.
+    /// </summary>
+    private async Task<SchemaLibraryActionResult> DispatchAsync(
+        object command, CancellationToken cancellationToken)
+    {
+        var response = await SendAsync(command, cancellationToken);
+        return response switch
+        {
+            ManagementSuccess => SchemaLibraryActionResult.Ok(),
+            ManagementUnauthorized unauthorized => SchemaLibraryActionResult.Fail(unauthorized.Message),
+            ManagementError error => SchemaLibraryActionResult.Fail(error.Error),
+            _ => SchemaLibraryActionResult.Fail(DescribeFailure(response)),
+        };
+    }
+
+    /// <summary>
+    /// Wraps <paramref name="command"/> in a <see cref="ManagementEnvelope"/> for the
+    /// current principal and Asks the <c>ManagementActor</c>. Transport faults (timeout,
+    /// actor not yet started, cancellation→propagated) become a synthetic
+    /// <see cref="ManagementError"/> so callers handle one response shape.
+    /// </summary>
+    private async Task<object> SendAsync(object command, CancellationToken cancellationToken)
+    {
+        var actor = _holder.ActorRef;
+        if (actor is null)
+        {
+            return new ManagementError(
+                string.Empty, "Management service is not ready.", "SERVICE_UNAVAILABLE");
+        }
+
+        var user = await BuildAuthenticatedUserAsync();
+        var envelope = new ManagementEnvelope(user, command, Guid.NewGuid().ToString("N"));
+
+        try
+        {
+            return await actor.Ask<object>(envelope, AskTimeout, cancellationToken);
+        }
+        catch (OperationCanceledException)
+        {
+            // Caller-initiated cancel (e.g. circuit teardown) — propagate cleanly.
+            throw;
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "ManagementActor Ask failed for {Command}", command.GetType().Name);
+            return new ManagementError(string.Empty, ex.Message, "TRANSPORT_ERROR");
+        }
+    }
+
+    /// <summary>
+    /// Projects the current Blazor <see cref="ClaimsPrincipal"/> to the
+    /// <see cref="AuthenticatedUser"/> the actor authorizes against — username,
+    /// display name, role claims, and the permitted-site scope claims (mirrors the
+    /// claim set the HTTP endpoint constructs).
+    /// </summary>
+    private async Task<AuthenticatedUser> BuildAuthenticatedUserAsync()
+    {
+        var state = await _auth.GetAuthenticationStateAsync();
+        var principal = state.User;
+
+        var username = principal.FindFirst(JwtTokenService.UsernameClaimType)?.Value ?? "unknown";
+        var displayName = principal.FindFirst(JwtTokenService.DisplayNameClaimType)?.Value ?? username;
+        var roles = principal.FindAll(JwtTokenService.RoleClaimType).Select(c => c.Value).ToArray();
+        var permittedSiteIds = principal.FindAll(JwtTokenService.SiteIdClaimType).Select(c => c.Value).ToArray();
+
+        return new AuthenticatedUser(username, displayName, roles, permittedSiteIds);
+    }
+
+    /// <summary>Renders a fallback description for an unexpected/failure response.</summary>
+    private static string DescribeFailure(object response) => response switch
+    {
+        ManagementUnauthorized unauthorized => unauthorized.Message,
+        ManagementError error => error.Error,
+        _ => "Unexpected response from the management service.",
+    };
+}