Refactor client update handling to support nullable parameters for name and expiration

- Updated the `UpdateClientAsync` method in `IXuiPanelGateway` to accept nullable parameters for `name` and `expiresAt`, allowing for more flexible client management without unintended modifications. - Adjusted the `BlockUserCommandHandler`, `UnblockUserCommandHandler`, and other related command handlers to utilize the new nullable parameters, ensuring that client names remain unchanged during block/unblock operations and that expiration dates are managed correctly. - Enhanced the billing and configuration handling to reflect the new logic for managing client states based on expiration rather than enabling/disabling, improving reliability in client status management. - Updated tests to cover the new behavior and ensure proper functionality across the application.
2026-07-19 18:58:36 +03:00
parent 5ff5224935
commit 979eddf72e
20 changed files with 282 additions and 29 deletions
@@ -42,13 +42,17 @@ public sealed class BlockUserCommandHandler(

            if (inbound is not null && node is not null)
            {
+                // name: null — не трогаем текущее имя клиента в панели, это не переименование.
+                // expiresAt: null — блокировка админом отдельная ось от биллинга (см.
+                // IXuiPanelGateway.UpdateClientAsync), срок оплаты не трогаем.
                var updateResult = await gateway.UpdateClientAsync(
                    node,
                    inbound.RemoteInboundId,
                    config.ClientExternalId,
                    config.Protocol,
-                    config.Label ?? config.ClientEmail,
+                    name: null,
                    enable: false,
+                    expiresAt: null,
                    cancellationToken
                );

@@ -47,13 +47,17 @@ public sealed class UnblockUserCommandHandler(

            if (inbound is not null && node is not null)
            {
+                // name: null — не трогаем текущее имя клиента в панели, это не переименование.
+                // expiresAt: null — блокировка админом отдельная ось от биллинга (см.
+                // IXuiPanelGateway.UpdateClientAsync), срок оплаты не трогаем.
                var updateResult = await gateway.UpdateClientAsync(
                    node,
                    inbound.RemoteInboundId,
                    config.ClientExternalId,
                    config.Protocol,
-                    config.Label ?? config.ClientEmail,
+                    name: null,
                    enable: true,
+                    expiresAt: null,
                    cancellationToken
                );

@@ -47,13 +47,18 @@ internal static class BillingConfigResumer

                if (inbound is not null && node is not null)
                {
+                    // Возвращаем через expiryTime = новый newPaidUntil, а не enable:true — тот же
+                    // механизм приостановки, что и у BillingService (см. IXuiPanelGateway.UpdateClientAsync):
+                    // переписываем просроченную дату на настоящую, панель/Xray сами перестают считать
+                    // клиента истёкшим. name: null — не переименовываем клиента.
                    var updateResult = await gateway.UpdateClientAsync(
                        node,
                        inbound.RemoteInboundId,
                        config.ClientExternalId,
                        config.Protocol,
-                        config.Label ?? config.ClientEmail,
-                        enable: true,
+                        name: null,
+                        enable: null,
+                        expiresAt: newPaidUntil,
                        cancellationToken
                    );

@@ -36,6 +36,8 @@ public interface IXuiPanelGateway
    /// Возвращает ClientExternalId, присвоенный панелью (UUID для VLESS/VMess, пароль для Trojan/Shadowsocks).
    /// <paramref name="limitIp"/> — лимит одновременных IP клиента (квота роли, см. AppRole.MaxIpLimit);
    /// -1 (RoleQuota.Unlimited) означает без лимита — гейтвей сам переводит его в нативное значение 3x-ui.
+    /// <paramref name="expiresAt"/> — дата, до которой клиент активен в самой панели (billing-роли —
+    /// AppUser.BillingPaidUntil на момент создания); <c>null</c> — без ограничения по сроку.
    /// </summary>
    Task<Result<string>> AddClientAsync(
        Node node,
@@ -44,6 +46,7 @@ public interface IXuiPanelGateway
        string clientEmail,
        string clientName,
        int limitIp,
+        DateTimeOffset? expiresAt,
        CancellationToken cancellationToken
    );

@@ -55,13 +58,35 @@ public interface IXuiPanelGateway
        CancellationToken cancellationToken
    );

+    /// <summary>
+    /// Все параметры, кроме обязательных идентификаторов, — "не трогать, если null" (см. ThreeXui.Net
+    /// UpdateClientRequest: "All fields optional — null means leave as is").
+    /// <para>
+    /// <paramref name="name"/> — НЕ отдельная косметическая метка: у клиента 3x-ui нет своего поля
+    /// remark/comment, поэтому ThreeXui.Net пишет её в то же поле <c>settings.clients[].email</c>,
+    /// которое AddClientAsync изначально заполняет стабильным ClientEmail. Передавайте <c>null</c>
+    /// для любого вызова, не являющегося намеренным переименованием — иначе затрёте панельный
+    /// identity-идентификатор клиента (и сломаете сопоставление по email в GetClientTrafficAsync).
+    /// Единственный легитимный вызывающий с непустым name — EditVpnConfigCommandHandler.
+    /// </para>
+    /// <para>
+    /// <paramref name="expiresAt"/> — используется для приостановки/возврата за неуплату
+    /// (BillingService/BillingConfigResumer): дата в прошлом делает клиента просроченным для самой
+    /// панели/Xray независимо от <paramref name="enable"/> (по факту тестирования — переключение
+    /// enable ненадёжно останавливает уже установленные соединения, а expiryTime — надёжно), дата в
+    /// будущем (новый AppUser.BillingPaidUntil) снимает приостановку. Блокировка/разблокировка
+    /// админом (BlockUserCommandHandler/UnblockUserCommandHandler) — отдельная ось, передаёт
+    /// <c>expiresAt: null</c> и управляет только <paramref name="enable"/>.
+    /// </para>
+    /// </summary>
    Task<Result> UpdateClientAsync(
        Node node,
        string inboundRemoteId,
        string clientExternalId,
        VpnProtocol protocol,
-        string name,
-        bool enable,
+        string? name,
+        bool? enable,
+        DateTimeOffset? expiresAt,
        CancellationToken cancellationToken
    );

@@ -73,6 +73,8 @@ public sealed class CreateVpnConfigCommandHandler(
            config.ClientEmail,
            config.Label ?? config.ClientEmail,
            profile.MaxIpLimit,
+            // BillingRequired-проверка выше гарантирует, что при BillingEnabled PaidUntil уже в будущем.
+            expiresAt: profile.BillingEnabled ? profile.BillingPaidUntil : null,
            cancellationToken
        );

@@ -42,13 +42,17 @@ public sealed class EditVpnConfigCommandHandler(
                .FirstOrDefaultAsync(n => n.Id == inbound.NodeId, cancellationToken);
            if (node is not null)
            {
+                // enable/expiresAt: null — переименование не должно снимать приостановку/блокировку
+                // клиента (раньше здесь стояло enable:true и молча реактивировало погашенный за
+                // неуплату/блокировку конфиг просто оттого, что пользователь его переименовал).
                var updateResult = await gateway.UpdateClientAsync(
                    node,
                    inbound.RemoteInboundId,
                    config.ClientExternalId,
                    config.Protocol,
                    command.Label,
-                    enable: true,
+                    enable: null,
+                    expiresAt: null,
                    cancellationToken
                );

@@ -56,6 +56,9 @@ public sealed class RotateVpnConfigCommandHandler(
            newClientEmail,
            config.Label ?? newClientEmail,
            profile.MaxIpLimit,
+            // Переносим уже действующий срок (billing paidUntil) на нового клиента — ротация не должна
+            // ни продлевать, ни сбрасывать оплаченный период.
+            expiresAt: config.ExpiresAt,
            cancellationToken
        );

@@ -139,13 +139,18 @@ public sealed class BillingService(

            if (inbound is not null && node is not null)
            {
+                // Приостанавливаем через expiryTime в прошлом, а не enable:false — переключение enable
+                // ненадёжно останавливает уже установленные соединения на стороне Xray/панели (см.
+                // IXuiPanelGateway.UpdateClientAsync), просроченный expiryTime — надёжно и независимо
+                // от enable. name: null — не переименовываем клиента.
                var updateResult = await gateway.UpdateClientAsync(
                    node,
                    inbound.RemoteInboundId,
                    config.ClientExternalId,
                    config.Protocol,
-                    config.Label ?? config.ClientEmail,
-                    enable: false,
+                    name: null,
+                    enable: null,
+                    expiresAt: DateTimeOffset.UtcNow.AddDays(-1),
                    cancellationToken
                );

@@ -92,6 +92,7 @@ internal sealed class XuiPanelGateway(
        string clientEmail,
        string clientName,
        int limitIp,
+        DateTimeOffset? expiresAt,
        CancellationToken cancellationToken
    )
    {
@@ -105,7 +106,7 @@ internal sealed class XuiPanelGateway(
                clientEmail,
                ToRemoteProtocol(protocol),
                limitIp == RoleQuota.Unlimited ? 0 : limitIp,
-                null
+                expiresAt
            );
            var result = await client.AddClientAsync(inboundRemoteId, request, cancellationToken);
            return Result.Success(result.ExternalClientId);
@@ -150,16 +151,17 @@ internal sealed class XuiPanelGateway(
        string inboundRemoteId,
        string clientExternalId,
        VpnProtocol protocol,
-        string name,
-        bool enable,
+        string? name,
+        bool? enable,
+        DateTimeOffset? expiresAt,
        CancellationToken cancellationToken
    )
    {
        try
        {
            var client = GetClient(node);
-            // deviceLimit: null — не трогаем то, что уже стоит на клиенте в панели (см. AddClientAsync).
-            var request = new UpdateClientRequest(null, null, enable, name);
+            // limitIp: null — не трогаем то, что уже стоит на клиенте в панели (см. AddClientAsync).
+            var request = new UpdateClientRequest(null, expiresAt, enable, name);
            await client.UpdateClientAsync(
                inboundRemoteId,
                clientExternalId,
@@ -167,7 +167,8 @@ public class ConfirmPaymentRequestCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<VpnProtocol>(),
                Arg.Any<string>(),
-                enable: true,
+                Arg.Any<bool?>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            )
            .Returns(Result.Success());
@@ -192,6 +193,8 @@ public class ConfirmPaymentRequestCommandHandlerTests
        Assert.NotNull(expiredConfig.ExpiresAt);
        Assert.NotNull(activeConfig.ExpiresAt);
        Assert.Equal(expiredConfig.ExpiresAt, activeConfig.ExpiresAt);
+        // enable: null — возврат из приостановки теперь идёт через expiresAt (новый newPaidUntil),
+        // а не через переключение enable (см. IXuiPanelGateway.UpdateClientAsync).
        await _gateway
            .Received(1)
            .UpdateClientAsync(
@@ -200,7 +203,8 @@ public class ConfirmPaymentRequestCommandHandlerTests
                "ext-1",
                VpnProtocol.Vless,
                Arg.Any<string>(),
-                enable: true,
+                null,
+                Arg.Is<DateTimeOffset?>(d => d == expiredConfig.ExpiresAt),
                Arg.Any<CancellationToken>()
            );
    }
@@ -128,7 +128,8 @@ public class ApproveExtensionRequestCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<VpnProtocol>(),
                Arg.Any<string>(),
-                enable: true,
+                Arg.Any<bool?>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            )
            .Returns(Result.Success());
@@ -54,7 +54,8 @@ public class BlockUserCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<VpnProtocol>(),
                Arg.Any<string>(),
-                Arg.Any<bool>(),
+                Arg.Any<bool?>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            );
    }
@@ -91,7 +92,8 @@ public class BlockUserCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<VpnProtocol>(),
                Arg.Any<string>(),
-                Arg.Any<bool>(),
+                Arg.Any<bool?>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            )
            .Returns(Result.Success());
@@ -111,6 +113,8 @@ public class BlockUserCommandHandlerTests
        Assert.True(result.IsSuccess);
        Assert.Equal(ConfigStatus.Disabled, config.Status);

+        // name: null — блокировка не переименовывает клиента; expiresAt: null — блокировка не трогает
+        // срок оплаты (см. IXuiPanelGateway.UpdateClientAsync).
        await _gateway
            .Received(1)
            .UpdateClientAsync(
@@ -118,8 +122,9 @@ public class BlockUserCommandHandlerTests
                inbound.RemoteInboundId,
                config.ClientExternalId,
                config.Protocol,
-                "my-config",
+                null,
                enable: false,
+                expiresAt: null,
                Arg.Any<CancellationToken>()
            );
        await _notifier
@@ -168,7 +173,8 @@ public class BlockUserCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<VpnProtocol>(),
                Arg.Any<string>(),
-                Arg.Any<bool>(),
+                Arg.Any<bool?>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            );
    }
@@ -205,7 +211,8 @@ public class BlockUserCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<VpnProtocol>(),
                Arg.Any<string>(),
-                Arg.Any<bool>(),
+                Arg.Any<bool?>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            )
            .Returns(Result.Failure(Error.Failure("Xui.UpdateClientFailed", "Нода недоступна.")));
@@ -54,7 +54,8 @@ public class UnblockUserCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<VpnProtocol>(),
                Arg.Any<string>(),
-                Arg.Any<bool>(),
+                Arg.Any<bool?>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            )
            .Returns(Result.Success());
@@ -81,6 +82,7 @@ public class UnblockUserCommandHandlerTests
                config.Protocol,
                Arg.Any<string>(),
                true,
+                null,
                Arg.Any<CancellationToken>()
            );
        await _notifier
@@ -155,7 +157,8 @@ public class UnblockUserCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<VpnProtocol>(),
                Arg.Any<string>(),
-                Arg.Any<bool>(),
+                Arg.Any<bool?>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            )
            .Returns(Result.Failure(Error.Failure("Xui.UpdateClientFailed", "Нода недоступна.")));
@@ -0,0 +1,128 @@
+using NSubstitute;
+using PnvPanel.Application.Common.Interfaces;
+using PnvPanel.Application.Common.Models;
+using PnvPanel.Application.Configs;
+using PnvPanel.Application.Configs.Create;
+using PnvPanel.Application.Tests.TestSupport;
+using PnvPanel.Domain.Inbounds;
+using PnvPanel.Infrastructure.Persistence;
+using Xunit;
+
+namespace PnvPanel.Application.Tests.Configs.Create;
+
+/// <summary>
+/// Только ветки ДО ReserveQuotaSlotAsync (billing-guard) — дальше хендлер уходит в
+/// pg_advisory_xact_lock, который InMemory-провайдер не поддерживает (см. CLAUDE.md/
+/// ConfigQuotaTests в IntegrationTests для позитивного пути и гонок).
+/// </summary>
+public class CreateVpnConfigCommandHandlerTests
+{
+    private readonly IIdentityService _identityService = Substitute.For<IIdentityService>();
+    private readonly IXuiPanelGateway _gateway = Substitute.For<IXuiPanelGateway>();
+
+    private static CurrentUserProfile Profile(
+        Guid userId,
+        Guid roleId,
+        bool billingEnabled,
+        DateTimeOffset? billingPaidUntil
+    ) =>
+        new(
+            userId,
+            "alice",
+            roleId,
+            "premium",
+            IsActivated: true,
+            IsBlocked: false,
+            MaxConfigs: 5,
+            MaxIpLimit: 3,
+            SubscriptionToken: "sub-token",
+            BillingEnabled: billingEnabled,
+            BillingPaidUntil: billingPaidUntil,
+            BillingSuspended: false
+        );
+
+    private async Task<(Inbound inbound, Guid roleId)> SeedAllowedInboundAsync(AppDbContext dbContext)
+    {
+        var roleId = Guid.NewGuid();
+        var node = Domain.Nodes.Node.Register(
+            "node-1",
+            new Uri("https://node1.example.com"),
+            new Domain.Nodes.NodeCredentials("admin", "protected"),
+            null
+        );
+        var inbound = Inbound.FromRemote(node.Id, "1", VpnProtocol.Vless, "remark", 443);
+        inbound.Publish(null, [roleId]);
+
+        dbContext.Nodes.Add(node);
+        dbContext.Inbounds.Add(inbound);
+        await dbContext.SaveChangesAsync(CancellationToken.None);
+
+        return (inbound, roleId);
+    }
+
+    [Fact]
+    public async Task Handle_WhenBillingEnabledAndPaidUntilExpired_ReturnsBillingRequired()
+    {
+        using var dbContext = InMemoryDbContextFactory.Create();
+        var userId = Guid.NewGuid();
+        var (inbound, roleId) = await SeedAllowedInboundAsync(dbContext);
+
+        _identityService
+            .GetProfileAsync(userId, Arg.Any<CancellationToken>())
+            .Returns(Profile(userId, roleId, billingEnabled: true, billingPaidUntil: DateTimeOffset.UtcNow.AddDays(-1)));
+
+        var handler = new CreateVpnConfigCommandHandler(
+            dbContext,
+            _identityService,
+            _gateway,
+            FakeCurrentUser.Authenticated(userId)
+        );
+
+        var result = await handler.Handle(
+            new CreateVpnConfigCommand(inbound.Id, null),
+            CancellationToken.None
+        );
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(ConfigErrors.BillingRequired, result.Error);
+        await _gateway
+            .DidNotReceive()
+            .AddClientAsync(
+                Arg.Any<Domain.Nodes.Node>(),
+                Arg.Any<string>(),
+                Arg.Any<VpnProtocol>(),
+                Arg.Any<string>(),
+                Arg.Any<string>(),
+                Arg.Any<int>(),
+                Arg.Any<DateTimeOffset?>(),
+                Arg.Any<CancellationToken>()
+            );
+    }
+
+    [Fact]
+    public async Task Handle_WhenBillingEnabledAndPaidUntilNull_ReturnsBillingRequired()
+    {
+        using var dbContext = InMemoryDbContextFactory.Create();
+        var userId = Guid.NewGuid();
+        var (inbound, roleId) = await SeedAllowedInboundAsync(dbContext);
+
+        _identityService
+            .GetProfileAsync(userId, Arg.Any<CancellationToken>())
+            .Returns(Profile(userId, roleId, billingEnabled: true, billingPaidUntil: null));
+
+        var handler = new CreateVpnConfigCommandHandler(
+            dbContext,
+            _identityService,
+            _gateway,
+            FakeCurrentUser.Authenticated(userId)
+        );
+
+        var result = await handler.Handle(
+            new CreateVpnConfigCommand(inbound.Id, null),
+            CancellationToken.None
+        );
+
+        Assert.False(result.IsSuccess);
+        Assert.Equal(ConfigErrors.BillingRequired, result.Error);
+    }
+}
@@ -65,6 +65,7 @@ public class RotateVpnConfigCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<string>(),
                Arg.Any<int>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            )
            .Returns(Result.Success("new-external-id"));
@@ -209,6 +210,7 @@ public class RotateVpnConfigCommandHandlerTests
                Arg.Any<string>(),
                Arg.Any<string>(),
                Arg.Any<int>(),
+                Arg.Any<DateTimeOffset?>(),
                Arg.Any<CancellationToken>()
            )
            .Returns(Result.Failure<string>(gatewayError));
@@ -38,6 +38,7 @@ public sealed class FakeXuiPanelGateway : IXuiPanelGateway
        string clientEmail,
        string clientName,
        int limitIp,
+        DateTimeOffset? expiresAt,
        CancellationToken cancellationToken
    ) => Task.FromResult(Result.Success(Guid.NewGuid().ToString()));

@@ -54,8 +55,9 @@ public sealed class FakeXuiPanelGateway : IXuiPanelGateway
        string inboundRemoteId,
        string clientExternalId,
        VpnProtocol protocol,
-        string name,
-        bool enable,
+        string? name,
+        bool? enable,
+        DateTimeOffset? expiresAt,
        CancellationToken cancellationToken
    ) => Task.FromResult(Result.Success());