refactor: extract SecAgent support into native plugin

SecRandom.PluginSdk/IExternalStudentDrawService.cs

@@ -0,0 +1,34 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using SecRandom.Shared.Models.Profile;
+
+namespace SecRandom.PluginSdk;
+
+/// <summary>
+/// Host-neutral student draw boundary for plugins and other external integrations.
+/// The transport and authentication policy belong to the integration that consumes it.
+/// </summary>
+public sealed record ExternalStudentDrawRequest
+{
+    public string Mode { get; init; } = "result_only";
+    public int Count { get; init; } = 1;
+    public string Gender { get; init; } = string.Empty;
+    public IReadOnlyList<string> IncludeTags { get; init; } = [];
+    public IReadOnlyList<string> ExcludeTags { get; init; } = [];
+    public IReadOnlyList<string> IncludeIds { get; init; } = [];
+    public IReadOnlyList<string> IncludeNames { get; init; } = [];
+}
+
+public sealed record ExternalStudentDrawResult(
+    string Mode,
+    string Status,
+    string Profile,
+    IReadOnlyList<Student> Students);
+
+public interface IExternalStudentDrawService
+{
+    Task<ExternalStudentDrawResult> DrawAsync(
+        ExternalStudentDrawRequest request,
+        CancellationToken cancellationToken = default);
+}

SecRandom.PluginSdk/README.md

@@ -32,6 +32,12 @@ Published plugins reference the SDK package and exclude its runtime assets so th
 
 The repository template defaults `UseLocalPluginSdk=true` so solution builds work before the SDK is published; set `UseLocalPluginSdk=false` with a NuGet source that contains `SecRandom.PluginSdk` to exercise the release packaging path.
 
+## Host integration APIs
+
+`IExternalStudentDrawService` lets a transport plugin request a host-managed student draw
+without depending on desktop application's internal service types. The host owns drawing,
+temporary records, history, security, and notifications; the plugin owns its transport.
+
 ## Building a plugin package
 
 Set `<CreateSrpx>true</CreateSrpx>` to produce `srpx/<ProjectName>.srpx` after every build. The package is a ZIP whose root contains `manifest.yml`, the entrance assembly, and any external package dependencies. Place it in `data/cache/plugin-packages` and restart the desktop application to install.

SecRandom/App.axaml.cs

@@ -59,7 +59,6 @@
 using SecRandom.Services.Music;
 using SecRandom.Services.Settings;
 using SecRandom.Services.Security;
-using SecRandom.Services.SecAgent;
 using SecRandom.Services.Telemetry;
 using SecRandom.Services.Verification;
 using SecRandom.Services.Voice;
@@ -844,9 +843,7 @@ private void BuildHost(IPlatformServiceRoot platform)
                 services.AddSingleton<IVoiceAnnouncementService>(serviceProvider =>
                     serviceProvider.GetRequiredService<VoiceAnnouncementService>());
                 services.AddSingleton<NotificationService>();
-                // Local-only REST endpoint for the SecAgent connector. It intentionally has no UI/settings registration.
-                services.AddHostedService<SecAgentHttpHostedService>();
-                services.AddHostedService<SecAgentPluginBootstrapHostedService>();
+                services.AddSingleton<IExternalStudentDrawService, ExternalStudentDrawService>();
                 services.AddSingleton(serviceProvider => new MusicLibraryService(
                     serviceProvider.GetRequiredService<MainConfigHandler>(),
                     serviceProvider.GetRequiredService<ILogger<MusicLibraryService>>(),

SecRandom/Services/Draw/ExternalStudentDrawService.cs

@@ -0,0 +1,148 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using SecRandom.Core.Abstraction.Services;
+using SecRandom.Core.Enums;
+using SecRandom.Core.Enums.Configs;
+using SecRandom.Core.Models.Draw;
+using SecRandom.Core.Services.Config;
+using SecRandom.Core.Services.Draw;
+using SecRandom.PluginSdk;
+using SecRandom.Services.Linkage;
+using SecRandom.Services.Notification;
+using SecRandom.Shared.Extensions;
+using SecRandom.Shared.Models.Profile;
+
+namespace SecRandom.Services.Draw;
+
+/// <summary>
+/// Implements the host-neutral external student draw boundary.
+/// Transport-specific integrations, such as the SecAgent plugin, call this service.
+/// </summary>
+public sealed class ExternalStudentDrawService(
+    IProfileService profileService,
+    MainConfigHandler configHandler,
+    IDrawTemporaryRecordService temporaryRecordService,
+    DrawEngine drawEngine,
+    LinkageDrawCoordinator linkageDrawCoordinator,
+    NotificationService notificationService) : IExternalStudentDrawService
+{
+    public async Task<ExternalStudentDrawResult> DrawAsync(
+        ExternalStudentDrawRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        if (request.Mode is not ("flash" or "result_only"))
+            throw new ArgumentException("mode must be flash or result_only.", nameof(request));
+
+        var requestedCount = Math.Clamp(request.Count, 1, 100);
+        if (request.Mode == "flash")
+            requestedCount = 1;
+
+        var gender = request.Gender?.Trim() ?? string.Empty;
+        var listName = profileService.CurrentStudentList?.Name ?? string.Empty;
+        var temporaryCounts = temporaryRecordService.GetStudentCounts(listName, gender, string.Empty);
+        var hasMatchingStudents = (profileService.CurrentStudentList?.Students ?? [])
+            .Any(student => student.IsCandidate && Matches(student, gender, request));
+        var mayResetExhaustedRound = configHandler.Data.QuickDrawSettings.DrawMode != DrawMode.Repeat
+                                     && hasMatchingStudents;
+
+        var result = await InvokeAuthorizedAsync(
+            SecurityOperation.QuickDrawStart,
+            async () =>
+            {
+                DrawResult<Student> DrawFromRemainingStudents()
+                    => drawEngine.DrawStudent(
+                        requestedCount,
+                        student => Matches(student, gender, request)
+                                      && !HasReachedTemporaryLimit(student, temporaryCounts),
+                        DrawSettingsType.QuickDraw,
+                        linkageDrawCoordinator.GetCourseName());
+
+                var draw = DrawFromRemainingStudents();
+                if (!draw.IsSuccess
+                    && mayResetExhaustedRound
+                    && draw.Status == DrawStatus.RepeatLimitExhausted)
+                {
+                    profileService.ClearCurrentStudentHistory();
+                    temporaryRecordService.ResetStudentList(listName);
+                    temporaryCounts = temporaryRecordService.GetStudentCounts(listName, gender, string.Empty);
+                    draw = DrawFromRemainingStudents();
+                }
+
+                if (!draw.IsSuccess || draw.Result.Count == 0)
+                    return draw;
+
+                profileService.RecordStudentHistory(
+                    draw.Result,
+                    DateTime.Now,
+                    requestedCount,
+                    drawMethod: (int)configHandler.Data.QuickDrawSettings.DrawType,
+                    courseName: linkageDrawCoordinator.GetCourseName());
+                temporaryRecordService.RecordStudents(listName, gender, string.Empty, draw.Result);
+                if (request.Mode == "flash")
+                    notificationService.QueueStudents(
+                        NotificationSettingsType.QuickDraw,
+                        linkageDrawCoordinator.GetCourseName(),
+                        draw.Result);
+                return draw;
+            },
+            cancellationToken).ConfigureAwait(false);
+
+        return new ExternalStudentDrawResult(
+            request.Mode,
+            result.Status.ToString(),
+            listName,
+            result.Result);
+    }
+
+    private async Task<DrawResult<Student>> InvokeAuthorizedAsync(
+        SecurityOperation operation,
+        Func<Task<DrawResult<Student>>> action,
+        CancellationToken cancellationToken)
+    {
+        DrawResult<Student>? result = null;
+        var authorized = await linkageDrawCoordinator.AuthorizeAsync(
+            operation,
+            async () => result = await action().ConfigureAwait(false),
+            cancellationToken).ConfigureAwait(false);
+        return authorized && result is not null
+            ? result
+            : new DrawResult<Student> { Status = DrawStatus.Failure };
+    }
+
+    private bool HasReachedTemporaryLimit(
+        Student student,
+        IReadOnlyDictionary<string, int> temporaryCounts)
+    {
+        var settings = configHandler.Data.QuickDrawSettings;
+        var threshold = settings.DrawMode switch
+        {
+            DrawMode.Repeat => 0,
+            DrawMode.NoRepeat => 1,
+            DrawMode.HalfRepeat => Math.Max(1, settings.HalfRepeat),
+            _ => 1
+        };
+        return threshold > 0
+               && temporaryCounts.GetValueOrDefault(ProfileRecordIdentity.EnsureRecordId(student)) >= threshold;
+    }
+
+    private static bool Matches(
+        Student student,
+        string gender,
+        ExternalStudentDrawRequest request)
+    {
+        var tags = student.Tags.Split(
+            [',', ';', ' '],
+            StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        return (string.IsNullOrWhiteSpace(gender)
+                || string.Equals(student.Gender, gender, StringComparison.OrdinalIgnoreCase))
+               && request.IncludeTags.All(tag => tags.Contains(tag, StringComparer.OrdinalIgnoreCase))
+               && request.ExcludeTags.All(tag => !tags.Contains(tag, StringComparer.OrdinalIgnoreCase))
+               && (request.IncludeIds.Count == 0
+                   || request.IncludeIds.Contains(student.Id, StringComparer.OrdinalIgnoreCase))
+               && (request.IncludeNames.Count == 0
+                   || request.IncludeNames.Contains(student.Name, StringComparer.OrdinalIgnoreCase));
+    }
+}