Address pr feedback

src/Core/Entities/PlayData.cs

@@ -4,6 +4,11 @@ using Bit.Core.Utilities;
 
 namespace Bit.Core.Entities;
 
+/// <summary>
+/// PlayData is a join table tracking entities created during automated testing.
+/// A `PlayId` is supplied by the clients in the `x-play-id` header to inform the server
+/// that any data created should be associated with the play, and therefore cleaned up with it.
+/// </summary>
 public class PlayData : ITableObject<Guid>
 {
     public Guid Id { get; set; }
@@ -12,14 +17,22 @@ public class PlayData : ITableObject<Guid>
     public Guid? UserId { get; init; }
     public Guid? OrganizationId { get; init; }
     public DateTime CreationDate { get; init; }
-
     protected PlayData() { }
 
+    /// <summary>
+    /// Generates and sets a new COMB GUID for the Id property.
+    /// </summary>
     public void SetNewId()
     {
         Id = CoreHelpers.GenerateComb();
     }
 
+    /// <summary>
+    /// Creates a new PlayData record associated with a User.
+    /// </summary>
+    /// <param name="user">The user entity created during the play.</param>
+    /// <param name="playId">The play identifier from the x-play-id header.</param>
+    /// <returns>A new PlayData instance tracking the user.</returns>
     public static PlayData Create(User user, string playId)
     {
         return new PlayData
@@ -30,6 +43,12 @@ public class PlayData : ITableObject<Guid>
         };
     }
 
+    /// <summary>
+    /// Creates a new PlayData record associated with an Organization.
+    /// </summary>
+    /// <param name="organization">The organization entity created during the play.</param>
+    /// <param name="playId">The play identifier from the x-play-id header.</param>
+    /// <returns>A new PlayData instance tracking the organization.</returns>
     public static PlayData Create(Organization organization, string playId)
     {
         return new PlayData

src/Core/Services/IPlayDataService.cs

@@ -0,0 +1,24 @@
+using Bit.Core.AdminConsole.Entities;
+using Bit.Core.Entities;
+
+namespace Bit.Core.Services;
+
+public interface IPlayDataService
+{
+    /// <summary>
+    /// Records a PlayData entry for the given User created during a Play session.
+    /// 
+    /// Does nothing if no Play Id is set for this http scope.
+    /// </summary>
+    /// <param name="user"></param>
+    /// <returns></returns>
+    Task Record(User user);
+    /// <summary>
+    /// Records a PlayData entry for the given Organization created during a Play session.
+    /// 
+    /// Does nothing if no Play Id is set for this http scope.
+    /// </summary>
+    /// <param name="organization"></param>
+    /// <returns></returns>
+    Task Record(Organization organization);
+}

src/Core/Services/IPlayIdService.cs

@@ -1,7 +1,23 @@
 namespace Bit.Core.Services;
 
+/// <summary>
+/// Service for managing Play identifiers in automated testing infrastructure.
+/// A "Play" is a test session that groups entities created during testing to enable cleanup.
+/// The PlayId flows from client request (x-play-id header) through PlayIdMiddleware to this service,
+/// which repositories query to create PlayData tracking records via IPlayDataService. The SeederAPI uses these records
+/// to bulk delete all entities associated with a PlayId. Only active in Development environments.
+/// </summary>
 public interface IPlayIdService
 {
+    /// <summary>
+    /// Gets or sets the current Play identifier from the x-play-id request header.
+    /// </summary>
     string? PlayId { get; set; }
+
+    /// <summary>
+    /// Checks whether the current request is part of an active Play session.
+    /// </summary>
+    /// <param name="playId">The Play identifier if active, otherwise empty string.</param>
+    /// <returns>True if in a Play session (has PlayId and in Development environment), otherwise false.</returns>
     bool InPlay(out string playId);
 }

src/Core/Services/Implementations/PlayDataService.cs

@@ -0,0 +1,26 @@
+using Bit.Core.AdminConsole.Entities;
+using Bit.Core.Entities;
+using Bit.Core.Repositories;
+using Microsoft.Extensions.Logging;
+
+namespace Bit.Core.Services;
+
+public class PlayDataService(IPlayIdService playIdService, IPlayDataRepository playDataRepository, ILogger<PlayDataService> logger) : IPlayDataService
+{
+    public async Task Record(User user)
+    {
+        if (playIdService.InPlay(out var playId))
+        {
+            logger.LogInformation("Associating user {UserId} with Play ID {PlayId}", user.Id, playId);
+            await playDataRepository.CreateAsync(PlayData.Create(user, playId));
+        }
+    }
+    public async Task Record(Organization organization)
+    {
+        if (playIdService.InPlay(out var playId))
+        {
+            logger.LogInformation("Associating organization {OrganizationId} with Play ID {PlayId}", organization.Id, playId);
+            await playDataRepository.CreateAsync(PlayData.Create(organization, playId));
+        }
+    }
+}