feat(tutorial): add /tutorial/gift_top with hardcoded starter present list

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SVSim.Database/Migrations/20260528160031_AddViewerClaimedTutorialGift.cs

@@ -0,0 +1,41 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace SVSim.Database.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddViewerClaimedTutorialGift : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.CreateTable(
+                name: "ViewerClaimedTutorialGifts",
+                columns: table => new
+                {
+                    ViewerId = table.Column<long>(type: "bigint", nullable: false),
+                    PresentId = table.Column<string>(type: "character varying(64)", maxLength: 64, nullable: false),
+                    ClaimedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_ViewerClaimedTutorialGifts", x => new { x.ViewerId, x.PresentId });
+                    table.ForeignKey(
+                        name: "FK_ViewerClaimedTutorialGifts_Viewers_ViewerId",
+                        column: x => x.ViewerId,
+                        principalTable: "Viewers",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                });
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "ViewerClaimedTutorialGifts");
+        }
+    }
+}

SVSim.Database/Migrations/SVSimDbContextModelSnapshot.cs

@@ -2407,6 +2407,23 @@ namespace SVSim.Database.Migrations
                     b.ToTable("ViewerBattlePassProgress");
                 });
 
+            modelBuilder.Entity("SVSim.Database.Models.ViewerClaimedTutorialGift", b =>
+                {
+                    b.Property<long>("ViewerId")
+                        .HasColumnType("bigint");
+
+                    b.Property<string>("PresentId")
+                        .HasMaxLength(64)
+                        .HasColumnType("character varying(64)");
+
+                    b.Property<DateTime>("ClaimedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.HasKey("ViewerId", "PresentId");
+
+                    b.ToTable("ViewerClaimedTutorialGifts");
+                });
+
             modelBuilder.Entity("SVSim.Database.Models.ViewerEventCounter", b =>
                 {
                     b.Property<long>("ViewerId")
@@ -3598,6 +3615,17 @@ namespace SVSim.Database.Migrations
                         .IsRequired();
                 });
 
+            modelBuilder.Entity("SVSim.Database.Models.ViewerClaimedTutorialGift", b =>
+                {
+                    b.HasOne("SVSim.Database.Models.Viewer", "Viewer")
+                        .WithMany()
+                        .HasForeignKey("ViewerId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.Navigation("Viewer");
+                });
+
             modelBuilder.Entity("SVSim.Database.Models.ViewerEventCounter", b =>
                 {
                     b.HasOne("SVSim.Database.Models.Viewer", null)

SVSim.Database/Models/ViewerClaimedTutorialGift.cs

@@ -0,0 +1,14 @@
+namespace SVSim.Database.Models;
+
+/// <summary>
+/// Records that a viewer has claimed a specific tutorial gift present_id. Composite key
+/// (ViewerId, PresentId) — viewer can't claim the same present twice.
+/// </summary>
+public class ViewerClaimedTutorialGift
+{
+    public long ViewerId { get; set; }
+    public string PresentId { get; set; } = string.Empty;
+    public DateTime ClaimedAt { get; set; }
+
+    public Viewer Viewer { get; set; } = null!;
+}

SVSim.Database/SVSimDbContext.cs

@@ -95,6 +95,8 @@ public class SVSimDbContext : DbContext
     public DbSet<ViewerStoryProgress> ViewerStoryProgress => Set<ViewerStoryProgress>();
     public DbSet<ViewerStoryBranchUnlock> ViewerStoryBranchUnlocks => Set<ViewerStoryBranchUnlock>();
 
+    public DbSet<ViewerClaimedTutorialGift> ViewerClaimedTutorialGifts => Set<ViewerClaimedTutorialGift>();
+
     #endregion
 
     public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
@@ -336,6 +338,13 @@ public class SVSimDbContext : DbContext
             b.HasIndex(e => new { e.ViewerId, e.Period });
         });
 
+        modelBuilder.Entity<ViewerClaimedTutorialGift>(b =>
+        {
+            b.HasKey(g => new { g.ViewerId, g.PresentId });
+            b.HasOne(g => g.Viewer).WithMany().HasForeignKey(g => g.ViewerId).OnDelete(DeleteBehavior.Cascade);
+            b.Property(g => g.PresentId).HasMaxLength(64);
+        });
+
         base.OnModelCreating(modelBuilder);
     }
 

SVSim.EmulatedEntrypoint/Controllers/GiftController.cs

@@ -0,0 +1,76 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
+using SVSim.Database;
+using SVSim.EmulatedEntrypoint.Models.Dtos.Requests.Gift;
+using SVSim.EmulatedEntrypoint.Models.Dtos.Responses.Gift;
+
+namespace SVSim.EmulatedEntrypoint.Controllers;
+
+/// <summary>
+/// Tutorial-scoped gift endpoints. We do NOT implement a generic gift system here —
+/// only the /tutorial/gift_top and /tutorial/gift_receive aliases needed for the
+/// step 31 → 41 reward flow. A full gift inbox is future work; if/when needed,
+/// add /gift/top and /gift/receive_gift aliases to this controller.
+/// </summary>
+public class GiftController : SVSimController
+{
+    /// <summary>The hardcoded tutorial gift bundle every fresh viewer sees at step 31.</summary>
+    public static readonly IReadOnlyList<PresentDto> TutorialGifts = new[]
+    {
+        new PresentDto { PresentId = "71478626", RewardType = "1", RewardDetailId = "0",     RewardCount = "400", Message = "For completing the tutorial" },
+        new PresentDto { PresentId = "71478627", RewardType = "9", RewardDetailId = "0",     RewardCount = "100", Message = "For completing the tutorial" },
+        new PresentDto { PresentId = "71478628", RewardType = "4", RewardDetailId = "1",     RewardCount = "3",   Message = "For completing the tutorial", ItemType = 1 },
+        new PresentDto { PresentId = "71478629", RewardType = "4", RewardDetailId = "80001", RewardCount = "40",  Message = "For completing the tutorial", ItemType = 2 },
+        new PresentDto { PresentId = "71478630", RewardType = "4", RewardDetailId = "90001", RewardCount = "1",   Message = "For completing the tutorial", ItemType = 2 },
+    };
+
+    private readonly SVSimDbContext _db;
+
+    public GiftController(SVSimDbContext db)
+    {
+        _db = db;
+    }
+
+    [HttpPost("/tutorial/gift_top")]
+    public async Task<ActionResult<GiftTopResponse>> TutorialGiftTop([FromBody] GiftTopRequest request)
+    {
+        if (!TryGetViewerId(out long viewerId)) return Unauthorized();
+
+        var claimedList = await _db.ViewerClaimedTutorialGifts
+            .Where(g => g.ViewerId == viewerId)
+            .Select(g => g.PresentId)
+            .ToListAsync();
+        var claimed = new HashSet<string>(claimedList);
+
+        var nowString = DateTime.UtcNow.ToString("yyyy-MM-dd HH:mm:ss");
+        var presents = TutorialGifts
+            .Where(p => !claimed.Contains(p.PresentId))
+            .Select(p => Clone(p, nowString))
+            .ToList();
+        var history = TutorialGifts
+            .Where(p => claimed.Contains(p.PresentId))
+            .Select(p => Clone(p, nowString))
+            .ToList();
+
+        return new GiftTopResponse
+        {
+            PresentList = presents,
+            PresentHistoryList = history,
+            LimitOverPresentList = new(),
+        };
+    }
+
+    private static PresentDto Clone(PresentDto p, string createTime) => new()
+    {
+        PresentId = p.PresentId,
+        RewardType = p.RewardType,
+        RewardDetailId = p.RewardDetailId,
+        RewardCount = p.RewardCount,
+        ConditionNumber = p.ConditionNumber,
+        PresentLimitType = p.PresentLimitType,
+        RewardLimitTime = p.RewardLimitTime,
+        CreateTime = createTime,
+        ItemType = p.ItemType,
+        Message = p.Message,
+    };
+}

SVSim.EmulatedEntrypoint/Models/Dtos/Requests/Gift/GiftTopRequest.cs

@@ -0,0 +1,13 @@
+using System.Text.Json.Serialization;
+using MessagePack;
+using SVSim.EmulatedEntrypoint.Models.Dtos.Requests;
+
+namespace SVSim.EmulatedEntrypoint.Models.Dtos.Requests.Gift;
+
+[MessagePackObject]
+public class GiftTopRequest : BaseRequest
+{
+    [JsonPropertyName("page")]
+    [Key("page")]
+    public int Page { get; set; }
+}

SVSim.EmulatedEntrypoint/Models/Dtos/Responses/Gift/GiftTopResponse.cs

@@ -0,0 +1,70 @@
+using System.Text.Json.Serialization;
+using MessagePack;
+
+namespace SVSim.EmulatedEntrypoint.Models.Dtos.Responses.Gift;
+
+[MessagePackObject]
+public class GiftTopResponse
+{
+    [JsonPropertyName("present_list")]
+    [Key("present_list")]
+    public List<PresentDto> PresentList { get; set; } = new();
+
+    [JsonPropertyName("present_history_list")]
+    [Key("present_history_list")]
+    public List<PresentDto> PresentHistoryList { get; set; } = new();
+
+    [JsonPropertyName("limit_over_present_list")]
+    [Key("limit_over_present_list")]
+    public List<PresentDto> LimitOverPresentList { get; set; } = new();
+}
+
+/// <summary>
+/// Prod sends most numeric-looking fields as STRINGS on this endpoint
+/// (present_id, reward_type, reward_detail_id, reward_count, condition_number,
+/// present_limit_type). item_type is an INT. We mirror the prod shape exactly.
+/// </summary>
+[MessagePackObject]
+public class PresentDto
+{
+    [JsonPropertyName("present_id")]
+    [Key("present_id")]
+    public string PresentId { get; set; } = string.Empty;
+
+    [JsonPropertyName("reward_type")]
+    [Key("reward_type")]
+    public string RewardType { get; set; } = string.Empty;
+
+    [JsonPropertyName("reward_detail_id")]
+    [Key("reward_detail_id")]
+    public string RewardDetailId { get; set; } = string.Empty;
+
+    [JsonPropertyName("reward_count")]
+    [Key("reward_count")]
+    public string RewardCount { get; set; } = string.Empty;
+
+    [JsonPropertyName("condition_number")]
+    [Key("condition_number")]
+    public string ConditionNumber { get; set; } = "0";
+
+    [JsonPropertyName("present_limit_type")]
+    [Key("present_limit_type")]
+    public string PresentLimitType { get; set; } = "0";
+
+    [JsonPropertyName("reward_limit_time")]
+    [Key("reward_limit_time")]
+    public int RewardLimitTime { get; set; }
+
+    [JsonPropertyName("create_time")]
+    [Key("create_time")]
+    public string CreateTime { get; set; } = string.Empty;
+
+    /// <summary>Only present on item/pack-ticket entries (gifts where reward_type=4); omit on currency entries.</summary>
+    [JsonPropertyName("item_type")]
+    [Key("item_type")]
+    public int? ItemType { get; set; }
+
+    [JsonPropertyName("message")]
+    [Key("message")]
+    public string Message { get; set; } = string.Empty;
+}

SVSim.UnitTests/Controllers/GiftControllerTests.cs

@@ -0,0 +1,50 @@
+using System.Net;
+using System.Text;
+using System.Text.Json;
+using NUnit.Framework;
+using SVSim.UnitTests.Infrastructure;
+
+namespace SVSim.UnitTests.Controllers;
+
+public class GiftControllerTests
+{
+    private const string BaseAuthBlock =
+        @"""viewer_id"":""0"",""steam_id"":0,""steam_session_ticket"":""""";
+
+    [Test]
+    public async Task GiftTop_returns_five_tutorial_gifts_for_unclaimed_viewer()
+    {
+        using var factory = new SVSimTestFactory();
+        long viewerId = await factory.SeedViewerAsync(tutorialState: 31);
+        using var client = factory.CreateAuthenticatedClient(viewerId);
+
+        var response = await client.PostAsync("/tutorial/gift_top",
+            new StringContent($$"""{"page":1,{{BaseAuthBlock}}}""", Encoding.UTF8, "application/json"));
+
+        Assert.That(response.StatusCode, Is.EqualTo(HttpStatusCode.OK));
+        using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+        var root = doc.RootElement;
+
+        var presents = root.GetProperty("present_list");
+        Assert.That(presents.GetArrayLength(), Is.EqualTo(5));
+
+        // Expect the legendary pack entry (present_id 71478630) to be present.
+        bool foundLegendaryGift = false;
+        foreach (var p in presents.EnumerateArray())
+        {
+            if (p.GetProperty("present_id").GetString() == "71478630")
+            {
+                foundLegendaryGift = true;
+                Assert.That(p.GetProperty("reward_type").GetString(), Is.EqualTo("4"));
+                Assert.That(p.GetProperty("reward_detail_id").GetString(), Is.EqualTo("90001"));
+                Assert.That(p.GetProperty("reward_count").GetString(), Is.EqualTo("1"));
+                Assert.That(p.GetProperty("item_type").GetInt32(), Is.EqualTo(2));
+                Assert.That(p.GetProperty("message").GetString(), Is.EqualTo("For completing the tutorial"));
+            }
+        }
+        Assert.That(foundLegendaryGift, Is.True, "Legendary starter pack gift (71478630) must be in present_list.");
+
+        Assert.That(root.GetProperty("present_history_list").GetArrayLength(), Is.EqualTo(0));
+        Assert.That(root.GetProperty("limit_over_present_list").GetArrayLength(), Is.EqualTo(0));
+    }
+}