Refactor payment request handling to support role change top-ups

- Updated the `PaymentRequest` model to include a new `Kind` property, distinguishing between `Subscription` and `RoleChangeTopUp` requests.
- Modified the `TelegramNotifier` to accommodate the new request type, ensuring accurate notifications for role change top-ups.
- Enhanced the `ConfirmPaymentRequestCommandHandler` to handle role change top-ups without extending the billing period, reflecting the new payment logic.
- Updated various application components and tests to support the new payment request structure and ensure proper functionality.
- Revised API documentation to clarify the behavior of role change top-ups and their impact on billing.

backend/tests/PnvPanel.Application.Tests/Admin/Billing/ConfirmPaymentRequestCommandHandlerTests.cs

@@ -205,6 +205,48 @@ public class ConfirmPaymentRequestCommandHandlerTests
             );
     }
 
+    [Fact]
+    public async Task Handle_WhenRoleChangeTopUp_ConfirmsWithoutExtendingPaidUntil()
+    {
+        using var dbContext = InMemoryDbContextFactory.Create();
+        var adminId = Guid.NewGuid();
+        var userId = Guid.NewGuid();
+        var existingPaidUntil = DateTimeOffset.UtcNow.AddDays(20);
+        var request = PaymentRequest.CreateRoleChangeTopUp(userId, 1200);
+        request.MarkPaymentSent();
+        dbContext.PaymentRequests.Add(request);
+        await dbContext.SaveChangesAsync(CancellationToken.None);
+
+        _identityService
+            .GetProfileAsync(userId, Arg.Any<CancellationToken>())
+            .Returns(Profile(userId, paidUntil: existingPaidUntil));
+
+        var handler = new ConfirmPaymentRequestCommandHandler(
+            dbContext,
+            _identityService,
+            _gateway,
+            _notifier,
+            _telegramNotifier,
+            FakeCurrentUser.Authenticated(adminId, "admin"),
+            _logger
+        );
+
+        var result = await handler.Handle(
+            new ConfirmPaymentRequestCommand(request.Id),
+            CancellationToken.None
+        );
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal(PaymentRequestStatus.Confirmed, request.Status);
+        await _identityService
+            .DidNotReceive()
+            .ExtendBillingPaidUntilAsync(
+                Arg.Any<Guid>(),
+                Arg.Any<DateTimeOffset>(),
+                Arg.Any<CancellationToken>()
+            );
+    }
+
     [Fact]
     public async Task Handle_WhenRequestAlreadyDecided_ReturnsNotDecidable()
     {

backend/tests/PnvPanel.Application.Tests/Admin/Support/ApproveRoleRequestCommandHandlerTests.cs

@@ -2,9 +2,11 @@ using NSubstitute;
 using PnvPanel.Application.Admin.Roles;
 using PnvPanel.Application.Admin.Support;
 using PnvPanel.Application.Common.Interfaces;
+using PnvPanel.Application.Common.Messaging;
 using PnvPanel.Application.Common.Models;
 using PnvPanel.Application.Support;
 using PnvPanel.Application.Tests.TestSupport;
+using PnvPanel.Domain.Billing;
 using PnvPanel.Domain.Support;
 using Xunit;
 
@@ -13,9 +15,33 @@ namespace PnvPanel.Application.Tests.Admin.Support;
 public class ApproveRoleRequestCommandHandlerTests
 {
     private readonly IRoleService _roleService = Substitute.For<IRoleService>();
+    private readonly IIdentityService _identityService = Substitute.For<IIdentityService>();
     private readonly IRealtimeNotifier _notifier = Substitute.For<IRealtimeNotifier>();
     private readonly ITelegramNotifier _telegramNotifier = Substitute.For<ITelegramNotifier>();
 
+    private ApproveRoleRequestCommandHandler CreateHandler(IAppDbContext dbContext, ICurrentUser currentUser) =>
+        new(dbContext, _roleService, _identityService, _notifier, _telegramNotifier, currentUser);
+
+    private static CurrentUserProfile Profile(
+        Guid userId,
+        int maxConfigs,
+        DateTimeOffset? billingPaidUntil = null
+    ) =>
+        new(
+            userId,
+            "alice",
+            Guid.NewGuid(),
+            "old-role",
+            IsActivated: true,
+            IsBlocked: false,
+            MaxConfigs: maxConfigs,
+            MaxIpLimit: 3,
+            SubscriptionToken: "sub-token",
+            BillingEnabled: billingPaidUntil != null,
+            BillingPaidUntil: billingPaidUntil,
+            BillingSuspended: false
+        );
+
     [Fact]
     public async Task Handle_ForNewRoleRequest_CreatesRoleAssignsAndResolves()
     {
@@ -34,13 +60,7 @@ public class ApproveRoleRequestCommandHandlerTests
             .Returns(Result.Success());
 
         var currentUser = FakeCurrentUser.Authenticated(Guid.NewGuid(), "admin");
-        var handler = new ApproveRoleRequestCommandHandler(
-            dbContext,
-            _roleService,
-            _notifier,
-            _telegramNotifier,
-            currentUser
-        );
+        var handler = CreateHandler(dbContext, currentUser);
 
         var result = await handler.Handle(
             new ApproveRoleRequestCommand(ticket.Id),
@@ -75,18 +95,15 @@ public class ApproveRoleRequestCommandHandlerTests
         dbContext.SupportTickets.Add(ticket);
         await dbContext.SaveChangesAsync(CancellationToken.None);
 
+        _roleService
+            .ListRolesAsync(Arg.Any<CancellationToken>())
+            .Returns(new List<RoleDto> { new(roleId, "premium", 10, 5, false, false) });
         _roleService
             .ChangeUserRoleAsync(userId, roleId, Arg.Any<CancellationToken>())
             .Returns(Result.Success());
 
         var currentUser = FakeCurrentUser.Authenticated(Guid.NewGuid());
-        var handler = new ApproveRoleRequestCommandHandler(
-            dbContext,
-            _roleService,
-            _notifier,
-            _telegramNotifier,
-            currentUser
-        );
+        var handler = CreateHandler(dbContext, currentUser);
 
         var result = await handler.Handle(
             new ApproveRoleRequestCommand(ticket.Id),
@@ -114,13 +131,7 @@ public class ApproveRoleRequestCommandHandlerTests
         await dbContext.SaveChangesAsync(CancellationToken.None);
 
         var currentUser = FakeCurrentUser.Authenticated(Guid.NewGuid());
-        var handler = new ApproveRoleRequestCommandHandler(
-            dbContext,
-            _roleService,
-            _notifier,
-            _telegramNotifier,
-            currentUser
-        );
+        var handler = CreateHandler(dbContext, currentUser);
 
         var result = await handler.Handle(
             new ApproveRoleRequestCommand(ticket.Id),
@@ -143,18 +154,15 @@ public class ApproveRoleRequestCommandHandlerTests
         dbContext.SupportTickets.Add(ticket);
         await dbContext.SaveChangesAsync(CancellationToken.None);
 
+        _roleService
+            .ListRolesAsync(Arg.Any<CancellationToken>())
+            .Returns(new List<RoleDto> { new(roleId, "premium", 10, 5, false, false) });
         _roleService
             .ChangeUserRoleAsync(adminId, roleId, Arg.Any<CancellationToken>())
             .Returns(Result.Success());
 
         var currentUser = FakeCurrentUser.Authenticated(adminId, "admin");
-        var handler = new ApproveRoleRequestCommandHandler(
-            dbContext,
-            _roleService,
-            _notifier,
-            _telegramNotifier,
-            currentUser
-        );
+        var handler = CreateHandler(dbContext, currentUser);
 
         var result = await handler.Handle(
             new ApproveRoleRequestCommand(ticket.Id),
@@ -175,18 +183,15 @@ public class ApproveRoleRequestCommandHandlerTests
         dbContext.SupportTickets.Add(ticket);
         await dbContext.SaveChangesAsync(CancellationToken.None);
 
+        _roleService
+            .ListRolesAsync(Arg.Any<CancellationToken>())
+            .Returns(new List<RoleDto> { new(roleId, "premium", 10, 5, false, false) });
         _roleService
             .ChangeUserRoleAsync(adminId, roleId, Arg.Any<CancellationToken>())
             .Returns(Result.Failure(RoleErrors.CannotRemoveLastAdmin));
 
         var currentUser = FakeCurrentUser.Authenticated(adminId, "admin");
-        var handler = new ApproveRoleRequestCommandHandler(
-            dbContext,
-            _roleService,
-            _notifier,
-            _telegramNotifier,
-            currentUser
-        );
+        var handler = CreateHandler(dbContext, currentUser);
 
         var result = await handler.Handle(
             new ApproveRoleRequestCommand(ticket.Id),
@@ -198,4 +203,63 @@ public class ApproveRoleRequestCommandHandlerTests
         // Тикет остаётся Open — можно повторить попытку после назначения второго админа.
         Assert.Equal(TicketStatus.Open, ticket.Status);
     }
+
+    [Fact]
+    public async Task Handle_WhenNewRoleMoreExpensiveWithActivePaidPeriod_CreatesRoleChangeTopUp()
+    {
+        using var dbContext = InMemoryDbContextFactory.Create();
+        var userId = Guid.NewGuid();
+        var roleId = Guid.NewGuid();
+        var ticket = SupportTicket.CreateRoleRequestForExistingRole(userId, roleId);
+        dbContext.SupportTickets.Add(ticket);
+
+        var pricing = PnvPanel.Domain.Pricing.PricingSettings.CreateDefault();
+        pricing.Update(500, 450, 400);
+        dbContext.PricingSettings.Add(pricing);
+        await dbContext.SaveChangesAsync(CancellationToken.None);
+
+        _roleService
+            .ListRolesAsync(Arg.Any<CancellationToken>())
+            .Returns(new List<RoleDto> { new(roleId, "premium", MaxConfigs: 10, 5, false, BillingEnabled: true) });
+        _roleService.ChangeUserRoleAsync(userId, roleId, Arg.Any<CancellationToken>()).Returns(Result.Success());
+        _identityService
+            .GetProfileAsync(userId, Arg.Any<CancellationToken>())
+            .Returns(Profile(userId, maxConfigs: 3, billingPaidUntil: DateTimeOffset.UtcNow.AddDays(30)));
+
+        var handler = CreateHandler(dbContext, FakeCurrentUser.Authenticated(Guid.NewGuid(), "admin"));
+
+        var result = await handler.Handle(new ApproveRoleRequestCommand(ticket.Id), CancellationToken.None);
+
+        Assert.True(result.IsSuccess);
+        var topUp = Assert.Single(dbContext.PaymentRequests.Local);
+        Assert.Equal(PaymentRequestKind.RoleChangeTopUp, topUp.Kind);
+        Assert.Null(topUp.Period);
+        Assert.True(topUp.AmountSnapshot > 0);
+    }
+
+    [Fact]
+    public async Task Handle_WhenNoActivePaidPeriod_DoesNotCreateTopUp()
+    {
+        using var dbContext = InMemoryDbContextFactory.Create();
+        var userId = Guid.NewGuid();
+        var roleId = Guid.NewGuid();
+        var ticket = SupportTicket.CreateRoleRequestForExistingRole(userId, roleId);
+        dbContext.SupportTickets.Add(ticket);
+        await dbContext.SaveChangesAsync(CancellationToken.None);
+
+        _roleService
+            .ListRolesAsync(Arg.Any<CancellationToken>())
+            .Returns(new List<RoleDto> { new(roleId, "premium", MaxConfigs: 10, 5, false, BillingEnabled: true) });
+        _roleService.ChangeUserRoleAsync(userId, roleId, Arg.Any<CancellationToken>()).Returns(Result.Success());
+        _identityService
+            .GetProfileAsync(userId, Arg.Any<CancellationToken>())
+            .Returns(Profile(userId, maxConfigs: 3, billingPaidUntil: null));
+
+        var handler = CreateHandler(dbContext, FakeCurrentUser.Authenticated(Guid.NewGuid(), "admin"));
+
+        var result = await handler.Handle(new ApproveRoleRequestCommand(ticket.Id), CancellationToken.None);
+
+        Assert.True(result.IsSuccess);
+        Assert.Empty(dbContext.PaymentRequests.Local);
+    }
 }