feat(pack): gacha-point catalog read (legendaries + leader cards)

SVSim.EmulatedEntrypoint/Services/IGachaPointService.cs

@@ -0,0 +1,37 @@
+using SVSim.Database.Models;
+using SVSim.EmulatedEntrypoint.Models.Dtos;
+
+namespace SVSim.EmulatedEntrypoint.Services;
+
+public interface IGachaPointService
+{
+    /// <summary>
+    /// Build the gacha-point exchange catalog for one pack, with per-viewer is_received
+    /// resolved. Returns an empty list if the pack has no gacha-point config or no eligible
+    /// cards in its pool — callers should treat the empty result as a valid response, not
+    /// an error. Order: standard legendaries first (class_id ASC, card_id ASC), then leader
+    /// cards (class_id ASC, card_id ASC).
+    /// </summary>
+    Task<IReadOnlyList<GachaPointRewardDto>> GetRewardsAsync(int packId, long viewerId);
+
+    /// <summary>
+    /// Increment the viewer's balance for <paramref name="pack"/> by
+    /// <c>child.OverrideIncreaseGachaPoint ?? pack.GachaPointConfig.IncreaseGachaPoint</c>
+    /// times <paramref name="packNumber"/>. No-op when the pack lacks a GachaPointConfig.
+    /// Caller is responsible for SaveChangesAsync.
+    /// </summary>
+    void Accrue(Viewer viewer, PackConfigEntry pack, PackChildGachaEntry child, int packNumber);
+
+    /// <summary>
+    /// Validate + execute an exchange. Returns the grant outcome on success (reward_list
+    /// entries the controller will return in <see cref="Dtos.Responses.Pack.ExchangeGachaPointResponse"/>),
+    /// or a failure result describing why. Mutates the in-memory graph; caller saves.
+    /// </summary>
+    Task<ExchangeOutcome> TryExchangeAsync(Viewer viewer, int packId, long cardId);
+}
+
+public sealed record ExchangeOutcome(bool Success, string? Error, IReadOnlyList<RewardListEntry> RewardList)
+{
+    public static ExchangeOutcome Fail(string error) => new(false, error, Array.Empty<RewardListEntry>());
+    public static ExchangeOutcome Ok(IReadOnlyList<RewardListEntry> rewards) => new(true, null, rewards);
+}