feat(spot-card-exchange): /spot_card_exchange/{top,exchange} + SpotPoints currency

Final shop family. Schema additions:
- ViewerCurrency.SpotPoints (ulong) — new currency column on Viewers.
- SpotCardExchangeEntry — catalog (distinct from the pre-existing
  SpotCardEntry, which is the /load/index rental-cost concept).
- ViewerSpotCardExchange — standalone composite-PK table tracking
  (viewer, card, exchanged_at, is_pre_release_snapshot). Standalone
  avoids cartesian-explode on viewer-graph reads.

RewardGrantService gains a SpotCardPoint=12 currency case mirroring
the RedEther/Crystal pattern. Doc comment refreshed; SpotCard=11 and
SpotCardOnlyLatestCardPack=13 remain unimplemented with explanatory
NotSupportedException — captures show emitters always use Card=5 with
the spot-card-specific id.

Controller:
- /top: emits exactly 9 clan buckets [{"1": [cards]}, ...] matching
  prod's arbitrary single-key shape. exchange_status per-card (0=
  available, 1=already-exchanged, 2=LimitOver after pre-release cap).
  pre_relase_info WIRE TYPO PRESERVED ("relase" not "release").
- /exchange: server-authoritative price (client-supplied
  exchange_point ignored); debits SpotPoints with post-state-total
  reward_list entry; grants card via RewardGrantService.ApplyAsync
  (cosmetic cascade included); persists ViewerSpotCardExchange row.
  Insufficient points / already-exchanged / pre-release-limit all
  return 400 without partial state.

LoadController now populates /load/index spot_point from
viewer.Currency.SpotPoints (was always 0).

PreReleaseLimit hardcoded to 2 matching capture; promote to GameConfig
when captures show variance.

504 tests pass (was 496; +8 spot-card-exchange tests).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

SVSim.Database/Migrations/20260528030221_AddSpotCardExchange.cs

@@ -0,0 +1,74 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace SVSim.Database.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddSpotCardExchange : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<decimal>(
+                name: "Currency_SpotPoints",
+                table: "Viewers",
+                type: "numeric(20,0)",
+                nullable: false,
+                defaultValue: 0m);
+
+            migrationBuilder.CreateTable(
+                name: "SpotCardExchangeCatalog",
+                columns: table => new
+                {
+                    Id = table.Column<long>(type: "bigint", nullable: false),
+                    CardId = table.Column<long>(type: "bigint", nullable: false),
+                    ClassId = table.Column<int>(type: "integer", nullable: false),
+                    ExchangePoint = table.Column<int>(type: "integer", nullable: false),
+                    TsRotationId = table.Column<long>(type: "bigint", nullable: false),
+                    IsPreRelease = table.Column<bool>(type: "boolean", nullable: false),
+                    IsEnabled = table.Column<bool>(type: "boolean", nullable: false),
+                    DateCreated = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
+                    DateUpdated = table.Column<DateTime>(type: "timestamp with time zone", nullable: true)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_SpotCardExchangeCatalog", x => x.Id);
+                });
+
+            migrationBuilder.CreateTable(
+                name: "ViewerSpotCardExchanges",
+                columns: table => new
+                {
+                    ViewerId = table.Column<long>(type: "bigint", nullable: false),
+                    CardId = table.Column<long>(type: "bigint", nullable: false),
+                    IsPreRelease = table.Column<bool>(type: "boolean", nullable: false),
+                    ExchangedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_ViewerSpotCardExchanges", x => new { x.ViewerId, x.CardId });
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_ViewerSpotCardExchanges_ViewerId",
+                table: "ViewerSpotCardExchanges",
+                column: "ViewerId");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "SpotCardExchangeCatalog");
+
+            migrationBuilder.DropTable(
+                name: "ViewerSpotCardExchanges");
+
+            migrationBuilder.DropColumn(
+                name: "Currency_SpotPoints",
+                table: "Viewers");
+        }
+    }
+}

SVSim.Database/Migrations/SVSimDbContextModelSnapshot.cs

@@ -2206,6 +2206,40 @@ namespace SVSim.Database.Migrations
                     b.ToTable("SpotCards");
                 });
 
+            modelBuilder.Entity("SVSim.Database.Models.SpotCardExchangeEntry", b =>
+                {
+                    b.Property<long>("Id")
+                        .HasColumnType("bigint");
+
+                    b.Property<long>("CardId")
+                        .HasColumnType("bigint");
+
+                    b.Property<int>("ClassId")
+                        .HasColumnType("integer");
+
+                    b.Property<DateTime>("DateCreated")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<DateTime?>("DateUpdated")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<int>("ExchangePoint")
+                        .HasColumnType("integer");
+
+                    b.Property<bool>("IsEnabled")
+                        .HasColumnType("boolean");
+
+                    b.Property<bool>("IsPreRelease")
+                        .HasColumnType("boolean");
+
+                    b.Property<long>("TsRotationId")
+                        .HasColumnType("bigint");
+
+                    b.HasKey("Id");
+
+                    b.ToTable("SpotCardExchangeCatalog");
+                });
+
             modelBuilder.Entity("SVSim.Database.Models.UnlimitedRestrictionEntry", b =>
                 {
                     b.Property<long>("Id")
@@ -2473,6 +2507,27 @@ namespace SVSim.Database.Migrations
                     b.ToTable("ViewerPuzzleClears");
                 });
 
+            modelBuilder.Entity("SVSim.Database.Models.ViewerSpotCardExchange", b =>
+                {
+                    b.Property<long>("ViewerId")
+                        .HasColumnType("bigint");
+
+                    b.Property<long>("CardId")
+                        .HasColumnType("bigint");
+
+                    b.Property<DateTime>("ExchangedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<bool>("IsPreRelease")
+                        .HasColumnType("boolean");
+
+                    b.HasKey("ViewerId", "CardId");
+
+                    b.HasIndex("ViewerId");
+
+                    b.ToTable("ViewerSpotCardExchanges");
+                });
+
             modelBuilder.Entity("SleeveEntryViewer", b =>
                 {
                     b.Property<int>("SleevesId")
@@ -3390,6 +3445,9 @@ namespace SVSim.Database.Migrations
                             b1.Property<decimal>("Rupees")
                                 .HasColumnType("numeric(20,0)");
 
+                            b1.Property<decimal>("SpotPoints")
+                                .HasColumnType("numeric(20,0)");
+
                             b1.Property<decimal>("SteamCrystals")
                                 .HasColumnType("numeric(20,0)");
 

SVSim.Database/Models/SpotCardExchangeEntry.cs

@@ -0,0 +1,30 @@
+using SVSim.Database.Common;
+
+namespace SVSim.Database.Models;
+
+/// <summary>
+/// One catalog entry of the /spot_card_exchange/top shop — a card the viewer can buy with
+/// spot points. PK = wire card_id. Distinct from <see cref="SpotCardEntry"/> (which is the
+/// /load/index data.spot_cards rental-cost list — a different concept).
+/// <para>
+/// <see cref="TsRotationId"/> matches the card_set_id; cards cycle out of the exchange when
+/// their set rotates. <see cref="IsPreRelease"/> distinguishes the pre-release-pool subset
+/// gated by <c>pre_release_spot_card_exchange_limit</c>.
+/// </para>
+/// </summary>
+public class SpotCardExchangeEntry : BaseEntity<long>
+{
+    public long CardId { get => Id; set => Id = value; }
+
+    /// <summary>Wire <c>class</c> field — clan id (0=Neutral, 1=Forestcraft, ..., 8).</summary>
+    public int ClassId { get; set; }
+
+    public int ExchangePoint { get; set; }
+
+    /// <summary>Wire <c>ts_rotation_id</c> — card_set_id this card belongs to.</summary>
+    public long TsRotationId { get; set; }
+
+    public bool IsPreRelease { get; set; }
+
+    public bool IsEnabled { get; set; }
+}

SVSim.Database/Models/ViewerCurrency.cs

@@ -14,4 +14,11 @@ public class ViewerCurrency
     public ulong LifeTotalCrystals { get; set; }
     public ulong RedEther { get; set; }
     public ulong Rupees { get; set; }
+
+    /// <summary>
+    /// Spot card points — currency earned from battles/missions, spent at /spot_card_exchange/exchange.
+    /// Wire field <c>spot_point</c> in /load/index and /spot_card_exchange/top; reward_type 12
+    /// (<see cref="Enums.UserGoodsType.SpotCardPoint"/>) in reward_list entries.
+    /// </summary>
+    public ulong SpotPoints { get; set; }
 }

SVSim.Database/Models/ViewerSpotCardExchange.cs

@@ -0,0 +1,16 @@
+namespace SVSim.Database.Models;
+
+/// <summary>
+/// One row per (viewer, exchanged card). Composite PK (ViewerId, CardId). Standalone table
+/// (not a Viewer owned collection) to avoid cartesian-explode on viewer-graph reads.
+/// <see cref="IsPreRelease"/> snapshot at exchange time so the pre-release counter can be
+/// computed without joining back to <see cref="SpotCardExchangeEntry"/> (and to survive
+/// catalog edits that re-classify a card).
+/// </summary>
+public class ViewerSpotCardExchange
+{
+    public long ViewerId { get; set; }
+    public long CardId { get; set; }
+    public bool IsPreRelease { get; set; }
+    public DateTime ExchangedAt { get; set; }
+}

SVSim.Database/SVSimDbContext.cs

@@ -76,6 +76,8 @@ public class SVSimDbContext : DbContext
     public DbSet<LeaderSkinShopSeriesEntry> LeaderSkinShopSeries => Set<LeaderSkinShopSeriesEntry>();
     public DbSet<LeaderSkinShopProductEntry> LeaderSkinShopProducts => Set<LeaderSkinShopProductEntry>();
     public DbSet<ViewerLeaderSkinSetClaim> ViewerLeaderSkinSetClaims => Set<ViewerLeaderSkinSetClaim>();
+    public DbSet<SpotCardExchangeEntry> SpotCardExchangeCatalog => Set<SpotCardExchangeEntry>();
+    public DbSet<ViewerSpotCardExchange> ViewerSpotCardExchanges => Set<ViewerSpotCardExchange>();
     public DbSet<MaintenanceCardEntry> MaintenanceCards => Set<MaintenanceCardEntry>();
     public DbSet<FeatureMaintenanceEntry> FeatureMaintenances => Set<FeatureMaintenanceEntry>();
     public DbSet<PreReleaseInfo> PreReleaseInfos => Set<PreReleaseInfo>();
@@ -209,6 +211,12 @@ public class SVSimDbContext : DbContext
             b.HasIndex(c => c.ViewerId);
         });
 
+        modelBuilder.Entity<ViewerSpotCardExchange>(b =>
+        {
+            b.HasKey(e => new { e.ViewerId, e.CardId });
+            b.HasIndex(e => e.ViewerId);
+        });
+
         modelBuilder.Entity<CardCosmeticReward>(b =>
         {
             b.HasKey(r => new { r.CardId, r.Type, r.CosmeticId });

SVSim.Database/Services/RewardGrantService.cs

@@ -20,8 +20,9 @@ public sealed record GrantedReward(int RewardType, long RewardId, int RewardNum)
 ///
 /// <para>
 /// <b>DO NOT reimplement reward dispatch in a controller or new helper.</b> This service handles
-/// RedEther, Crystal, Item, Card (with <see cref="CardCosmeticReward"/> cascade), Sleeve, Emblem,
-/// Degree, Rupy, Skin, MyPageBG — everything except SpotCard (TODO). Endpoint code that takes a
+/// RedEther, Crystal, SpotCardPoint, Item, Card (with <see cref="CardCosmeticReward"/> cascade),
+/// Sleeve, Emblem, Degree, Rupy, Skin, MyPageBG — everything except the dead-letter SpotCard /
+/// SpotCardOnlyLatestCardPack slots (use Card=5 instead). Endpoint code that takes a
 /// list of <c>(type, id, num)</c> tuples should iterate and call <see cref="ApplyAsync"/>
 /// per tuple — never switch on type yourself, never filter to "only card-typed rewards", never
 /// build a second dispatch table. Past duplicate implementations (ICardAcquisitionService in the
@@ -87,6 +88,10 @@ public sealed class RewardGrantService
                 viewer.Currency.RedEther += (ulong)num;
                 return Single(type, detailId, checked((int)viewer.Currency.RedEther));
 
+            case UserGoodsType.SpotCardPoint:
+                viewer.Currency.SpotPoints += (ulong)num;
+                return Single(type, detailId, checked((int)viewer.Currency.SpotPoints));
+
             case UserGoodsType.Item:
             {
                 var owned = viewer.Items.FirstOrDefault(i => i.Item.Id == (int)detailId);
@@ -106,11 +111,11 @@ public sealed class RewardGrantService
 
             case UserGoodsType.SpotCard:
             case UserGoodsType.SpotCardOnlyLatestCardPack:
-                // TODO: spot cards are currently global in our seed data; the existence of these
-                // reward types suggests there's a mix of global + per-player spot cards. Revisit
-                // when per-player spot-card infrastructure lands.
+                // Spot-card-typed grants don't appear in captures — emitters always use Card=5
+                // with the spot-card-specific id. These two enum slots remain unimplemented; if a
+                // capture ever shows one in a reward_list we'll know to wire them up here.
                 throw new NotSupportedException(
-                    $"{type} rewards are not yet supported — see SpotCard TODO in RewardGrantService.");
+                    $"{type} rewards are not yet supported — emitters use Card=5 instead.");
 
             default:
                 throw new NotSupportedException($"UserGoodsType {type} not yet handled by RewardGrantService");