feat(draw/music): 添加附加音乐设置与公平抽取保护

新增每条记录的附加音乐模型 DrawMusicAttachedSettings 及解析器，并在 GlobalConstants 注册设置 ID；增强 MusicLibraryService 行为（删除时拒绝外部兼容路径并清除被引用的托管曲目，支持通过配置刷新并保存 profile 引用）。

重构并增强 DrawEngine：引入 ApplyAverageGapProtection、FilterPreparedStudents 等，改进公平抽取的平均差保护逻辑、候选池扩展与权重计算（支持课程范围统计与历史缓存过滤），并在验证/抽取路径上用特定异常映射到可理解的 DrawStatus；同时在 verification 审计负载中加入 fairness 与候选计数元数据以提升可审计性。

改进 ProfileRecordIdentity：支持紧凑（N 格式）记录 ID 的迁移与合并，保留历史并删除 legacy 键以避免别名冲突。

增加/更新大量单元测试覆盖新行为（音乐库、验证导出、抽取算法/配置、记录迁移等），并同步更新若干 AGENTS.md 文档以说明托管音乐、课程联动与附加设置约定。

Author: lzy98276

AGENTS.md

@@ -109,6 +109,9 @@ Keep this map short and stable. When code moves, AI agents should re-read the mo
 - Built-in main navigation entries may use `PageLocation.Bottom` for bottom-pinned sidebar items; roll-call (`main.rollCall`) and lottery (`main.lottery`) are bottom-pinned and full-width/title-hidden. Quick draw is not a main navigation page and opens from the floating window.
 - Page IDs: `main.xxx`, `settings.xxx`, `settings.group.xxx`.
 - Picking animation style is unified: settings expose it as `AnimationStyle` / “动画样式”, and RollCall, QuickDraw, and Lottery use the same style for both rolling preview/process animation and final result reveal. Do not split process/result animation style settings.
+- Managed draw music is app-layer only: `settings.personalized.music` imports/deletes/previews MP3/WAV/FLAC files in `data/audio/music`, while the four draw-settings pages select process/result tracks through managed IDs, no-music, or random-play options. Student/prize attached settings may override only animation and result track IDs; the first drawn record supplies both overrides for a multi-record result. Deleting a managed track clears global and per-record references. `DrawAudioService` keeps SoundFlow private, loops process music only when `MoreSettings.BackgroundMusicLoop` is enabled, stops it on cancellation, and plays result music once.
+- Course linkage uses fixed v2 data-source values: `0=Off`, `1=CSES`, `2=ClassIsland`. CSES schedules live at `data/CSES/cses_schedule.yml`; ClassIsland is accessed only through the app-layer official IPC adapter. Only a confirmed course break restricts local draw/reset or hides the floating window. Missing/invalid CSES data, ClassIsland connection loss, or an unknown state must permit normal operation.
+- `LinkageSettings.VerificationRequired` governs the course-time bypass prompt and is distinct from `SecuritySettings.ProtectLinkage`, which continues to protect only external SecRandom URL/IPC mutations. Student course history uses `HistoryItem.CourseName` with `RecordId` identity; empty legacy course values remain global history.
 - Plugin pages are runtime-registered through `AddPluginMainPage` / `AddPluginSettingsPage`; their IDs must start with `plugin.<plugin-id>.` and must not occupy built-in `main.*` or `settings.*` IDs.
 - Plugin contracts live under `SecRandom.Core/Plugins`; plugin runtime/loading state lives under `SecRandom/Services/Plugins` and is registered from `BuildHost()`.
 - Plugin logs must use the original logging pipeline. Plugin categories use `SecRandom.Plugin[<plugin-id>].*`; plugin detail views may only filter their own category prefix.

SecRandom.Core.Tests/DrawProofExportServiceTests.cs

@@ -0,0 +1,50 @@
+using SecRandom.Services.Verification;
+using SecRandom.Shared.Models.Verification;
+
+namespace SecRandom.Core.Tests;
+
+public sealed class DrawProofExportServiceTests
+{
+    [Fact]
+    public void CreateFileName_UsesChinaStandardTimeListAndFilters()
+    {
+        DrawProof proof = new()
+        {
+            ProofId = Guid.Parse("12345678-1234-1234-1234-123456789abc"),
+            CreatedAtUtc = new DateTimeOffset(2026, 7, 14, 0, 30, 12, 345, TimeSpan.Zero)
+        };
+
+        var fileName = DrawProofExportService.CreateFileName(
+            proof,
+            DrawProofExportContext.ForStudents("高一:一班", "A/组", "女"));
+
+        Assert.Equal("20260714_083012_345_高一_一班_组别=A_组、性别=女_12345678.srproof.json", fileName);
+    }
+
+    [Fact]
+    public void CreateFileName_UsesAllScopeWhenNoStudentFilterIsSelected()
+    {
+        DrawProof proof = new()
+        {
+            ProofId = Guid.Parse("abcdef12-1234-1234-1234-123456789abc"),
+            CreatedAtUtc = new DateTimeOffset(2026, 7, 14, 0, 0, 0, TimeSpan.Zero)
+        };
+
+        var fileName = DrawProofExportService.CreateFileName(proof, DrawProofExportContext.ForStudents("默认名单"));
+
+        Assert.Contains("默认名单_范围=全部_abcdef12", fileName);
+    }
+
+    [Fact]
+    public void CreateFileName_KeepsTheFileNameWithinWindowsLimits()
+    {
+        DrawProof proof = new();
+        var context = new DrawProofExportContext(
+            new string('名', 100),
+            [new string('组', 100), new string('性', 100), new string('课', 100)]);
+
+        var fileName = DrawProofExportService.CreateFileName(proof, context);
+
+        Assert.True(fileName.Length <= 240);
+    }
+}

SecRandom.Core.Tests/FairDrawAlgorithmTests.cs

@@ -0,0 +1,154 @@
+using System.Collections.ObjectModel;
+using System.Text.Json;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using SecRandom.Core.Abstraction;
+using SecRandom.Core.Abstraction.Services;
+using SecRandom.Core.Enums;
+using SecRandom.Core.Enums.Configs;
+using SecRandom.Core.Models;
+using SecRandom.Core.Models.SubConfigs.Picking;
+using SecRandom.Core.Services.Config;
+using SecRandom.Core.Services.Draw;
+using SecRandom.Shared.Abstraction;
+using SecRandom.Shared.Models.Profile;
+
+namespace SecRandom.Core.Tests;
+
+public sealed class FairDrawAlgorithmTests
+{
+    [Fact]
+    public void FairDraw_ExcludesAboveAverageCandidatesWhenLowerCandidatesCanSatisfyDraw()
+    {
+        var low = new Student { Name = "Low", RecordId = Guid.NewGuid() };
+        var average = new Student { Name = "Average", RecordId = Guid.NewGuid() };
+        var high = new Student { Name = "High", RecordId = Guid.NewGuid() };
+        var history = new StudentHistory
+        {
+            Students =
+            {
+                [low.RecordId.ToString("D")] = new History { TotalCount = 0 },
+                [average.RecordId.ToString("D")] = new History { TotalCount = 2 },
+                [high.RecordId.ToString("D")] = new History { TotalCount = 4 }
+            }
+        };
+        var config = CreateConfig(new FairDrawSettingsConfig
+        {
+            FairDraw = true,
+            FairDrawGroup = false,
+            FairDrawGender = false,
+            FairDrawTime = false,
+            ColdStartEnabled = false,
+            EnableAvgGapProtection = true,
+            GapThreshold = 10,
+            MinWeight = 0,
+            MaxWeight = 10
+        });
+        var students = new StudentList { Students = [low, average, high] };
+
+        using var host = CreateHost(config, new TestProfileService(history, students));
+        IAppHost.Host = host;
+        var engine = new DrawEngine();
+
+        var localResult = engine.DrawPreparedStudents(1, [low, average, high], DrawSettingsType.RollCall);
+        var verificationInput = engine.CreateStudentVerificationInput(1, [low, average, high], DrawSettingsType.RollCall);
+
+        Assert.True(localResult.IsSuccess);
+        Assert.DoesNotContain(high, localResult.Result);
+        Assert.DoesNotContain(verificationInput.Candidates, candidate => candidate.RecordId == high.RecordId);
+        using var audit = JsonDocument.Parse(verificationInput.AuditPayload);
+        Assert.True(audit.RootElement.GetProperty("fairness").GetProperty("averageGapProtectionApplied").GetBoolean());
+        Assert.Equal(3, audit.RootElement.GetProperty("fairness").GetProperty("candidateCountBeforeAverageGapProtection").GetInt32());
+        Assert.Equal(2, audit.RootElement.GetProperty("fairness").GetProperty("candidateCountAfterAverageGapProtection").GetInt32());
+    }
+
+    [Fact]
+    public void CreateStudentVerificationInput_UsesCourseScopedBalanceWeights()
+    {
+        var groupA = new Student { Name = "A", Group = "A", RecordId = Guid.NewGuid() };
+        var groupB = new Student { Name = "B", Group = "B", RecordId = Guid.NewGuid() };
+        var history = new StudentHistory();
+        history.GroupStats["A"] = 100;
+        history.Students["legacy"] = new History
+        {
+            Histories = new ObservableCollection<HistoryItem>(
+                Enumerable.Range(0, 10)
+                    .Select(_ => new HistoryItem { CourseName = "数学", RecordGroup = "B" }))
+        };
+        var config = CreateConfig(new FairDrawSettingsConfig
+        {
+            FairDraw = true,
+            FairDrawGroup = true,
+            FairDrawGender = false,
+            FairDrawTime = false,
+            ColdStartEnabled = false,
+            EnableAvgGapProtection = false,
+            FrequencyWeight = 0,
+            BaseWeight = 0,
+            GroupWeight = 1,
+            MinWeight = 0,
+            MaxWeight = 10
+        });
+        var students = new StudentList { Students = [groupA, groupB] };
+
+        using var host = CreateHost(config, new TestProfileService(history, students));
+        IAppHost.Host = host;
+
+        var input = new DrawEngine().CreateStudentVerificationInput(1, [groupA, groupB], DrawSettingsType.RollCall, "数学");
+
+        Assert.True(input.Candidates.Single(candidate => candidate.RecordId == groupA.RecordId).WeightMicros
+                    > input.Candidates.Single(candidate => candidate.RecordId == groupB.RecordId).WeightMicros);
+    }
+
+    private static MainConfigModel CreateConfig(FairDrawSettingsConfig fairSettings)
+    {
+        return new MainConfigModel
+        {
+            FairDrawSettings = fairSettings,
+            RollCallSettings = new RollCallSettingsConfig(),
+            LotterySettings = new LotterySettingsConfig(),
+            DefaultDrawSettings = new DefaultDrawSettingsConfig()
+        };
+    }
+
+    private static IHost CreateHost(MainConfigModel config, IProfileService profile)
+    {
+        return Host.CreateDefaultBuilder()
+            .ConfigureServices(services =>
+            {
+                services.AddLogging(builder => builder.SetMinimumLevel(LogLevel.None));
+                services.AddSingleton<IProfileService>(profile);
+                services.AddSingleton<ConfigServiceBase>(new TestConfigService(config));
+                services.AddSingleton<MainConfigHandler>();
+            })
+            .Build();
+    }
+
+    private sealed class TestConfigService(MainConfigModel config) : ConfigServiceBase
+    {
+        public override bool IsConfigExists<T>(T fallback) => true;
+        public override T LoadConfig<T>(T fallback) => config is T typed ? typed : fallback;
+        public override void SaveConfig<T>(T config) { }
+        public override void DeleteConfig<T>(T config) { }
+    }
+
+    private sealed class TestProfileService(StudentHistory history, StudentList students) : IProfileService
+    {
+        public StudentList? CurrentStudentList { get; } = students;
+        public StudentHistory? CurrentStudentHistory { get; } = history;
+        public PrizeList? CurrentPrizeList { get; } = new();
+        public PrizeHistory? CurrentPrizeHistory { get; } = new();
+        public StudentListConfig? StudentListConfig => null;
+        public StudentHistoryConfig? StudentHistoryConfig => null;
+        public PrizeListConfig? PrizeListConfig => null;
+        public PrizeHistoryConfig? PrizeHistoryConfig => null;
+        public void LoadStudentProfile(string name, bool saveCurrent = true) { }
+        public void LoadPrizeProfile(string name, bool saveCurrent = true) { }
+        public void RecordStudentHistory(IReadOnlyList<Student> students, DateTime now, int requestedCount, string drawGroup = "", string drawGender = "", int drawMethod = 0, IReadOnlyDictionary<Student, double>? weights = null, string courseName = "") { }
+        public void RecordPrizeHistory(IReadOnlyList<Prize> prizes, DateTime now, int requestedCount) { }
+        public void ClearCurrentStudentHistory() { }
+        public void ClearCurrentPrizeHistory() { }
+        public void SaveProfile() { }
+    }
+}

SecRandom.Core.Tests/FairDrawSettingsConfigTests.cs

@@ -4,6 +4,7 @@
 using Microsoft.Extensions.Logging;
 using SecRandom.Core.Abstraction;
 using SecRandom.Core.Abstraction.Services;
+using SecRandom.Core.Enums;
 using SecRandom.Core.Enums.Configs;
 using SecRandom.Core.Models;
 using SecRandom.Core.Models.SubConfigs.Picking;
@@ -198,6 +199,45 @@ public void CalculateStudentWeight_CourseScopeUsesOnlyCourseGroupAndGenderHistor
                     > weights.Single(item => item.Candidate == groupA).Weight);
     }
 
+    [Fact]
+    public void CreateStudentVerificationInput_AppliesAverageGapProtection()
+    {
+        var first = new Student { Name = "A", RecordId = Guid.NewGuid() };
+        var second = new Student { Name = "B", RecordId = Guid.NewGuid() };
+        var overdrawn = new Student { Name = "C", RecordId = Guid.NewGuid() };
+        var history = new StudentHistory
+        {
+            Students =
+            {
+                [first.RecordId.ToString("D")] = new History { TotalCount = 0 },
+                [second.RecordId.ToString("D")] = new History { TotalCount = 0 },
+                [overdrawn.RecordId.ToString("D")] = new History { TotalCount = 3 }
+            }
+        };
+        var config = BuildConfig(new FairDrawSettingsConfig
+        {
+            FairDraw = true,
+            EnableAvgGapProtection = true,
+            GapThreshold = 1,
+            FairDrawGroup = false,
+            FairDrawGender = false,
+            FairDrawTime = false,
+            ColdStartEnabled = false
+        });
+        config.RollCallSettings.DrawType = DrawType.Fair;
+
+        using var host = BuildHost(config, new TestProfileService(history));
+        IAppHost.Host = host;
+
+        var input = new DrawEngine().CreateStudentVerificationInput(
+            1,
+            [first, second, overdrawn],
+            DrawSettingsType.RollCall);
+
+        Assert.Equal(2, input.Candidates.Count);
+        Assert.DoesNotContain(input.Candidates, candidate => candidate.RecordId == overdrawn.RecordId);
+    }
+
     private static MainConfigModel BuildConfig(FairDrawSettingsConfig fairSettings)
     {
         return new MainConfigModel

SecRandom.Core.Tests/MusicLibraryServiceTests.cs

@@ -1,9 +1,13 @@
 using Microsoft.Extensions.Logging.Abstractions;
 using SecRandom.Core.Abstraction;
+using SecRandom.Core.Abstraction.Services;
+using SecRandom.Core.Models.AttachedSettings;
 using SecRandom.Core.Models;
 using SecRandom.Core.Models.SubConfigs.Picking;
 using SecRandom.Core.Services.Config;
+using SecRandom.Shared.Extensions;
 using SecRandom.Services.Music;
+using SecRandom.Shared.Models.Profile;
 
 namespace SecRandom.Core.Tests;
 
@@ -40,6 +44,18 @@ public void ResolvePath_RejectsUnsupportedAndTraversalSelections()
         Assert.Null(service.ResolvePath("track.ogg"));
     }
 
+    [Fact]
+    public void Delete_RejectsExternalCompatibilityPaths()
+    {
+        Directory.CreateDirectory(_directory);
+        var externalPath = Path.Combine(_directory, "external.wav");
+        File.WriteAllBytes(externalPath, [1]);
+        var service = CreateService(out _);
+
+        Assert.False(service.Delete(new MusicTrack(externalPath, "external", 1)));
+        Assert.True(File.Exists(externalPath));
+    }
+
     [Fact]
     public void NewDrawSettings_HaveUsableMusicControlDefaults()
     {
@@ -76,19 +92,43 @@ public void Delete_ClearsEveryDefaultAndOverrideReference()
         Assert.Equal(MusicLibraryService.NoMusicTrackId, config.LotterySettings.ResultMusic);
     }
 
+    [Fact]
+    public void Delete_ClearsActiveAttachedMusicReferences()
+    {
+        Directory.CreateDirectory(_directory);
+        File.WriteAllBytes(Path.Combine(_directory, "track.wav"), [1]);
+        var student = new Student();
+        student.AttachedObjects[Guid.Parse(GlobalConstants.DrawMusicAttachedSettings)] = new DrawMusicAttachedSettings
+        {
+            IsAttachSettingsEnabled = true,
+            AnimationMusic = "track.wav",
+            ResultMusic = "track.wav"
+        };
+        var profileService = new TestProfileService(student);
+        var service = CreateService(out _, profileService);
+        service.Refresh();
+
+        Assert.True(service.Delete(Assert.Single(service.Tracks)));
+        var settings = student.GetAttachedObject<DrawMusicAttachedSettings>(Guid.Parse(GlobalConstants.DrawMusicAttachedSettings));
+        Assert.NotNull(settings);
+        Assert.Equal(MusicLibraryService.NoMusicTrackId, settings.AnimationMusic);
+        Assert.Equal(MusicLibraryService.NoMusicTrackId, settings.ResultMusic);
+        Assert.Equal(1, profileService.SaveCount);
+    }
+
     public void Dispose()
     {
         if (Directory.Exists(_directory))
             Directory.Delete(_directory, recursive: true);
     }
 
-    private MusicLibraryService CreateService(out MainConfigModel config)
+    private MusicLibraryService CreateService(out MainConfigModel config, IProfileService? profileService = null)
     {
         config = new MainConfigModel();
         var handler = new MainConfigHandler(
             NullLogger<MainConfigHandler>.Instance,
             new TestConfigService(config));
-        return new MusicLibraryService(handler, NullLogger<MusicLibraryService>.Instance, _directory);
+        return new MusicLibraryService(handler, NullLogger<MusicLibraryService>.Instance, _directory, profileService);
     }
 
     private sealed class TestConfigService(MainConfigModel config) : ConfigServiceBase
@@ -98,4 +138,26 @@ private sealed class TestConfigService(MainConfigModel config) : ConfigServiceBa
         public override void SaveConfig<T>(T value) { }
         public override void DeleteConfig<T>(T value) { }
     }
+
+    private sealed class TestProfileService(Student student) : IProfileService
+    {
+        public int SaveCount { get; private set; }
+        public StudentList? CurrentStudentList { get; } = new() { Students = [student] };
+        public StudentHistory? CurrentStudentHistory => null;
+        public PrizeList? CurrentPrizeList => null;
+        public PrizeHistory? CurrentPrizeHistory => null;
+        public StudentListConfig? StudentListConfig => null;
+        public StudentHistoryConfig? StudentHistoryConfig => null;
+        public PrizeListConfig? PrizeListConfig => null;
+        public PrizeHistoryConfig? PrizeHistoryConfig => null;
+        public void LoadStudentProfile(string name, bool saveCurrent = true) { }
+        public void LoadPrizeProfile(string name, bool saveCurrent = true) { }
+        public void RecordStudentHistory(IReadOnlyList<Student> students, DateTime now, int requestedCount,
+            string drawGroup = "", string drawGender = "", int drawMethod = 0,
+            IReadOnlyDictionary<Student, double>? weights = null, string courseName = "") { }
+        public void RecordPrizeHistory(IReadOnlyList<Prize> prizes, DateTime now, int requestedCount) { }
+        public void ClearCurrentStudentHistory() { }
+        public void ClearCurrentPrizeHistory() { }
+        public void SaveProfile() => SaveCount++;
+    }
 }