DC-153 - Implement “Request replacement card” flow in self-service portal

src/SEBT.Portal.Api/Controllers/Household/HouseholdController.cs

@@ -83,4 +83,34 @@ public async Task<IActionResult> UpdateAddress(
         var result = await commandHandler.Handle(command, cancellationToken);
         return result.ToActionResult();
     }
+
+    /// <summary>
+    /// Requests replacement cards for the authenticated user's household.
+    /// </summary>
+    /// <param name="request">The application numbers to request replacements for.</param>
+    /// <param name="commandHandler">The use case handler for requesting card replacements.</param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>No content on success; otherwise, BadRequest or Unauthorized.</returns>
+    /// <response code="204">Card replacement request recorded successfully.</response>
+    /// <response code="400">Validation failed (no applications selected or cooldown active).</response>
+    /// <response code="403">User is not authorized or no household identifier could be resolved from token.</response>
+    [HttpPost("cards/replace")]
+    [Authorize]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    [ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status403Forbidden)]
+    public async Task<IActionResult> RequestCardReplacement(
+        [FromBody] RequestCardReplacementRequest request,
+        [FromServices] ICommandHandler<RequestCardReplacementCommand> commandHandler,
+        CancellationToken cancellationToken = default)
+    {
+        var command = new RequestCardReplacementCommand
+        {
+            User = User,
+            ApplicationNumbers = request.ApplicationNumbers
+        };
+
+        var result = await commandHandler.Handle(command, cancellationToken);
+        return result.ToActionResult();
+    }
 }

src/SEBT.Portal.Api/Models/Household/RequestCardReplacementRequest.cs

@@ -0,0 +1,14 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace SEBT.Portal.Api.Models.Household;
+
+/// <summary>
+/// Request model for requesting replacement cards for one or more applications.
+/// </summary>
+public record RequestCardReplacementRequest
+{
+    /// <summary>Application numbers identifying which cards to replace.</summary>
+    [Required(ErrorMessage = "At least one application number is required.")]
+    [MinLength(1, ErrorMessage = "At least one application number is required.")]
+    public required List<string> ApplicationNumbers { get; init; }
+}

src/SEBT.Portal.Infrastructure/Dependencies.cs

@@ -96,7 +96,7 @@ public static IServiceCollection AddPortalInfrastructureRepositories(
                 "UseMockHouseholdData is false but no household plugin (ISummerEbtCaseService) is loaded. " +
                 "Either set UseMockHouseholdData to true in configuration or ensure a state plugin is loaded (e.g. PluginAssemblyPaths and the plugin DLL).");
         });
-        services.AddTransient<MockHouseholdRepository>();
+        services.AddSingleton<MockHouseholdRepository>();
         services.AddTransient<HouseholdRepository>();
 
         services.AddMemoryCache();

src/SEBT.Portal.Infrastructure/Repositories/MockHouseholdRepository.cs

@@ -64,7 +64,7 @@
 
         if (household == null)
         {
             _logger.LogInformation("Mock household not found for identifier {Type}={Value}", identifier.Type, normalizedEmail);
             return Task.FromResult<HouseholdData?>(null);
         }
 
@@ -72,7 +72,7 @@
         _logger.LogDebug(
             "Returning mock household data for identifier {Type}={Value}, PII visibility: Address={IncludeAddress}, Email={IncludeEmail}, Phone={IncludePhone}",
             identifier.Type,
             normalizedEmail,
             piiVisibility.IncludeAddress,
             piiVisibility.IncludeEmail,
             piiVisibility.IncludePhone);
@@ -131,9 +131,11 @@
             var app = h.Applications.FirstOrDefault();
             if (app != null)
             {
+                app.IssuanceType = IssuanceType.SnapEbtCard;
                 app.BenefitIssueDate = now.AddDays(-20);
                 app.BenefitExpirationDate = now.AddDays(70);
                 app.Last4DigitsOfCard = "0000";
+                app.CardRequestedAt = now.AddDays(-60);
                 // Set specific children names for test
                 app.Children = new List<Child>
                 {
@@ -162,6 +164,9 @@
             var app = h.Applications.FirstOrDefault();
             if (app != null)
             {
+                app.ApplicationNumber = "APP-2025-01-100001";
+                app.CaseNumber = "CASE-100001";
+                app.IssuanceType = IssuanceType.SummerEbt;
                 app.BenefitIssueDate = now.AddDays(-30);
                 app.BenefitExpirationDate = now.AddDays(60);
                 app.Last4DigitsOfCard = "1234"; // Specific value for test
@@ -322,8 +327,11 @@
             var app = h.Applications.FirstOrDefault();
             if (app != null)
             {
+                app.IssuanceType = IssuanceType.SummerEbt;
                 app.BenefitIssueDate = now.AddDays(-15);
                 app.BenefitExpirationDate = now.AddDays(75);
+                app.Last4DigitsOfCard = "4321";
+                app.CardRequestedAt = now.AddDays(-45);
                 // Use Bogus to generate child name
                 var childFaker = new Faker<Child>()
                     .RuleFor(c => c.FirstName, f => f.Name.FirstName())
@@ -343,8 +351,11 @@
             var app = h.Applications.FirstOrDefault();
             if (app != null)
             {
+                app.IssuanceType = IssuanceType.TanfEbtCard;
                 app.BenefitIssueDate = now.AddDays(-45);
                 app.BenefitExpirationDate = now.AddDays(45);
+                app.Last4DigitsOfCard = "8765";
+                app.CardRequestedAt = now.AddDays(-30);
                 // Set specific children names for test
                 app.Children = new List<Child>
                 {
@@ -385,6 +396,8 @@
             {
                 app.BenefitIssueDate = now.AddDays(-120);
                 app.BenefitExpirationDate = now.AddDays(-10); // Expired
+                app.Last4DigitsOfCard = "9012";
+                app.CardRequestedAt = now.AddDays(-90);
                 // Use Bogus to generate child name
                 var childFaker = new Faker<Child>()
                     .RuleFor(c => c.FirstName, f => f.Name.FirstName())
@@ -416,12 +429,13 @@
         var multipleApps = HouseholdFactory.CreateHouseholdDataWithStatus(ApplicationStatus.Approved, h =>
         {
             h.BenefitIssuanceType = BenefitIssuanceType.SnapEbtCard;
-            var faker = new Faker();
+            var faker = new Faker { Random = new Randomizer(42) };
             var approvedApp = new Application
             {
                 ApplicationNumber = $"APP-{now.AddDays(-30):yyyy-MM}-{faker.Random.Number(100000, 999999)}",
                 CaseNumber = $"CASE-{faker.Random.Number(100000, 999999)}",
                 ApplicationStatus = ApplicationStatus.Approved,
+                IssuanceType = IssuanceType.SummerEbt,
                 BenefitIssueDate = now.AddDays(-30),
                 BenefitExpirationDate = now.AddDays(60),
                 Last4DigitsOfCard = "5678",

src/SEBT.Portal.TestUtilities/Helpers/HouseholdFactory.cs

@@ -119,7 +119,7 @@ private static Application CreateApplicationWithStatus(ApplicationStatus status,
 
         if (status == ApplicationStatus.Approved)
         {
-            application.ApplicationNumber = $"APP-{faker.Date.Recent(365):yyyy-MM}-{faker.Random.Number(100000, 999999)}";
+            application.ApplicationNumber = $"APP-{faker.Random.Number(2024, 2026)}-{faker.Random.Number(1, 12):D2}-{faker.Random.Number(100000, 999999)}";
             application.CaseNumber = $"CASE-{faker.Random.Number(100000, 999999)}";
             application.BenefitIssueDate = faker.Date.Recent(120);
             application.BenefitExpirationDate = application.BenefitIssueDate.Value.AddDays(faker.Random.Int(30, 365));
@@ -134,7 +134,7 @@ private static Application CreateApplicationWithStatus(ApplicationStatus status,
         }
         else if (status == ApplicationStatus.Denied)
         {
-            application.ApplicationNumber = $"APP-{faker.Date.Recent(365):yyyy-MM}-{faker.Random.Number(100000, 999999)}";
+            application.ApplicationNumber = $"APP-{faker.Random.Number(2024, 2026)}-{faker.Random.Number(1, 12):D2}-{faker.Random.Number(100000, 999999)}";
             application.CaseNumber = $"CASE-{faker.Random.Number(100000, 999999)}";
             if (faker.Random.Bool(0.5f))
             {
@@ -163,7 +163,7 @@ private static Application CreateApplicationWithStatus(ApplicationStatus status,
         else
         {
             // For other statuses (Pending, UnderReview, Cancelled)
-            application.ApplicationNumber = $"APP-{faker.Date.Recent(365):yyyy-MM}-{faker.Random.Number(100000, 999999)}";
+            application.ApplicationNumber = $"APP-{faker.Random.Number(2024, 2026)}-{faker.Random.Number(1, 12):D2}-{faker.Random.Number(100000, 999999)}";
             if (faker.Random.Bool(0.5f))
             {
                 application.CardStatus = CardStatus.Requested;

src/SEBT.Portal.UseCases/Dependencies.cs

@@ -20,6 +20,7 @@ public static IServiceCollection AddUseCases(this IServiceCollection services)
         services.RegisterQueryHandler<GetVerificationStatusQuery, VerificationStatusResponse, GetVerificationStatusQueryHandler>();
         services.RegisterCommandHandler<ProcessWebhookCommand, ProcessWebhookCommandHandler>();
         services.RegisterCommandHandler<UpdateAddressCommand, UpdateAddressCommandHandler>();
+        services.RegisterCommandHandler<RequestCardReplacementCommand, RequestCardReplacementCommandHandler>();
 
         return services;
     }

src/SEBT.Portal.UseCases/Household/RequestCardReplacement/RequestCardReplacementCommand.cs

@@ -0,0 +1,25 @@
+using System.ComponentModel.DataAnnotations;
+using System.Security.Claims;
+using SEBT.Portal.Kernel;
+
+namespace SEBT.Portal.UseCases.Household;
+
+/// <summary>
+/// Command to request replacement cards for one or more applications.
+/// </summary>
+public class RequestCardReplacementCommand : ICommand
+{
+    /// <summary>
+    /// The authenticated user's claims principal, used to resolve household identity.
+    /// </summary>
+    [Required]
+    public required ClaimsPrincipal User { get; init; }
+
+    /// <summary>
+    /// Application numbers identifying which cards to replace.
+    /// All children on a selected application share the same card.
+    /// </summary>
+    [Required(ErrorMessage = "At least one application number is required.")]
+    [MinLength(1, ErrorMessage = "At least one application number is required.")]
+    public required List<string> ApplicationNumbers { get; init; }
+}

src/SEBT.Portal.UseCases/Household/RequestCardReplacement/RequestCardReplacementCommandHandler.cs

@@ -0,0 +1,107 @@
+using Microsoft.Extensions.Logging;
+using SEBT.Portal.Core.Models;
+using SEBT.Portal.Core.Models.Auth;
+using SEBT.Portal.Core.Repositories;
+using SEBT.Portal.Core.Services;
+using SEBT.Portal.Kernel;
+using SEBT.Portal.Kernel.Results;
+
+namespace SEBT.Portal.UseCases.Household;
+
+/// <summary>
+/// Handles card replacement requests for an authenticated user's household.
+/// Validates input, resolves household identity, enforces 2-week cooldown, and returns success.
+/// State connector call is stubbed — actual card replacement is a future integration.
+/// </summary>
+public class RequestCardReplacementCommandHandler(
+    IValidator<RequestCardReplacementCommand> validator,
+    IHouseholdIdentifierResolver resolver,
+    IHouseholdRepository repository,
+    ILogger<RequestCardReplacementCommandHandler> logger)
+    : ICommandHandler<RequestCardReplacementCommand>
+{
+    private static readonly TimeSpan CooldownPeriod = TimeSpan.FromDays(14);
+
+    public async Task<Result> Handle(
+        RequestCardReplacementCommand command,
+        CancellationToken cancellationToken = default)
+    {
+        var validationResult = await validator.Validate(command, cancellationToken);
+        if (validationResult is ValidationFailedResult validationFailed)
+        {
+            logger.LogWarning("Card replacement validation failed");
+            return Result.ValidationFailed(validationFailed.Errors);
+        }
+
+        var identifier = await resolver.ResolveAsync(command.User, cancellationToken);
+        if (identifier == null)
+        {
+            logger.LogWarning(
+                "Card replacement attempted but no household identifier could be resolved from claims");
+            return Result.Unauthorized("Unable to identify user from token.");
+        }
+
+        var household = await repository.GetHouseholdByIdentifierAsync(
+            identifier,
+            new PiiVisibility(IncludeAddress: false, IncludeEmail: false, IncludePhone: false),
+            UserIalLevel.None,
+            cancellationToken);
+
+        if (household == null)
+        {
+            logger.LogWarning("Card replacement attempted but household data not found");
+            return Result.PreconditionFailed(PreconditionFailedReason.NotFound, "Household data not found.");
+        }
+
+        var cooldownErrors = CheckCooldown(command.ApplicationNumbers, household);
+        if (cooldownErrors.Count > 0)
+        {
+            logger.LogInformation(
+                "Card replacement rejected: {Count} application(s) within cooldown period",
+                cooldownErrors.Count);
+            return Result.ValidationFailed(cooldownErrors);
+        }
+
+        var identifierKind = identifier.Type.ToString();
+        logger.LogInformation(
+            "Card replacement request received for household identifier kind {Kind}, {Count} application(s)",
+            identifierKind,
+            command.ApplicationNumbers.Count);
+
+        // TODO: Call state connector to process card replacement.
+        // Stubbed — returns success without calling the state system.
+
+        logger.LogInformation(
+            "Card replacement completed for household identifier kind {Kind}",
+            identifierKind);
+
+        return Result.Success();
+    }
+
+    private static List<ValidationError> CheckCooldown(
+        List<string> requestedApplicationNumbers,
+        Core.Models.Household.HouseholdData household)
+    {
+        var errors = new List<ValidationError>();
+        var now = DateTime.UtcNow;
+
+        foreach (var appNumber in requestedApplicationNumbers)
+        {
+            var application = household.Applications
+                .FirstOrDefault(a => a.ApplicationNumber == appNumber);
+
+            if (application?.CardRequestedAt == null)
+                continue;
+
+            var elapsed = now - application.CardRequestedAt.Value;
+            if (elapsed < CooldownPeriod)
+            {
+                errors.Add(new ValidationError(
+                    "ApplicationNumbers",
+                    $"Application {appNumber} was requested within the last 14 days."));
+            }
+        }
+
+        return errors;
+    }
+}

src/SEBT.Portal.UseCases/Household/RequestCardReplacement/RequestCardReplacementCommandValidator.cs

@@ -0,0 +1,17 @@
+using SEBT.Portal.Kernel;
+using SEBT.Portal.Kernel.Results;
+
+namespace SEBT.Portal.UseCases.Household;
+
+/// <summary>
+/// Validates <see cref="RequestCardReplacementCommand"/> using data annotations.
+/// </summary>
+public class RequestCardReplacementCommandValidator(
+    IValidator<RequestCardReplacementCommand> validator)
+    : IValidator<RequestCardReplacementCommand>
+{
+    public Task<ValidationResult> Validate(
+        RequestCardReplacementCommand command,
+        CancellationToken cancellationToken = default)
+        => validator.Validate(command, cancellationToken);
+}