Implement billing functionality and enhance role management

- Introduced billing capabilities, allowing users to request payments for subscription periods (3/6/12 months) with admin approval via Telegram.
- Updated role management to include a `BillingEnabled` property, preventing billing for admin roles.
- Enhanced the `CreateRoleCommand` and `UpdateRoleCommand` to accept billing parameters, ensuring proper handling during role creation and updates.
- Added new endpoints for billing management and integrated billing checks into VPN config creation to enforce payment requirements.
- Updated related services, models, and tests to support the new billing features, ensuring comprehensive coverage and functionality.
- Enhanced documentation to reflect the new billing processes and role management changes.

backend/tests/PnvPanel.Domain.Tests/Billing/PaymentRequestTests.cs

@@ -0,0 +1,101 @@
+using PnvPanel.Domain.Billing;
+using PnvPanel.Domain.Exceptions;
+using Xunit;
+
+namespace PnvPanel.Domain.Tests.Billing;
+
+public class PaymentRequestTests
+{
+    [Fact]
+    public void Create_StartsInAwaitingPayment()
+    {
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.Quarter, 1500);
+
+        Assert.Equal(PaymentRequestStatus.AwaitingPayment, request.Status);
+        Assert.Equal(1500, request.AmountSnapshot);
+    }
+
+    [Fact]
+    public void MarkPaymentSent_FromAwaitingPayment_MovesToAwaitingConfirmation()
+    {
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.Quarter, 1500);
+
+        request.MarkPaymentSent();
+
+        Assert.Equal(PaymentRequestStatus.AwaitingConfirmation, request.Status);
+    }
+
+    [Fact]
+    public void MarkPaymentSent_WhenAlreadySent_Throws()
+    {
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.Quarter, 1500);
+        request.MarkPaymentSent();
+
+        Assert.Throws<DomainException>(() => request.MarkPaymentSent());
+    }
+
+    [Fact]
+    public void Cancel_FromAwaitingPayment_MovesToCancelled()
+    {
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.Quarter, 1500);
+
+        request.Cancel();
+
+        Assert.Equal(PaymentRequestStatus.Cancelled, request.Status);
+    }
+
+    [Fact]
+    public void Cancel_AfterMarkPaymentSent_Throws()
+    {
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.Quarter, 1500);
+        request.MarkPaymentSent();
+
+        Assert.Throws<DomainException>(() => request.Cancel());
+    }
+
+    [Fact]
+    public void Confirm_FromAwaitingConfirmation_Succeeds()
+    {
+        var adminId = Guid.NewGuid();
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.Year, 5000);
+        request.MarkPaymentSent();
+
+        request.Confirm(adminId);
+
+        Assert.Equal(PaymentRequestStatus.Confirmed, request.Status);
+        Assert.Equal(adminId, request.DecidedBy);
+        Assert.NotNull(request.DecidedAt);
+    }
+
+    [Fact]
+    public void Confirm_FromAwaitingPayment_Succeeds()
+    {
+        // Админ мог увидеть оплату раньше, чем пользователь нажал "Я оплатил".
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.Year, 5000);
+
+        request.Confirm(Guid.NewGuid());
+
+        Assert.Equal(PaymentRequestStatus.Confirmed, request.Status);
+    }
+
+    [Fact]
+    public void Reject_FromAwaitingConfirmation_SetsReason()
+    {
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.HalfYear, 3000);
+        request.MarkPaymentSent();
+
+        request.Reject(Guid.NewGuid(), "Платёж не найден");
+
+        Assert.Equal(PaymentRequestStatus.Rejected, request.Status);
+        Assert.Equal("Платёж не найден", request.RejectionReason);
+    }
+
+    [Fact]
+    public void Confirm_WhenAlreadyDecided_Throws()
+    {
+        var request = PaymentRequest.Create(Guid.NewGuid(), PaymentPeriod.Quarter, 1500);
+        request.Cancel();
+
+        Assert.Throws<DomainException>(() => request.Confirm(Guid.NewGuid()));
+    }
+}

backend/tests/PnvPanel.Domain.Tests/Configs/VpnConfigTests.cs

@@ -137,6 +137,62 @@ public class VpnConfigTests
         Assert.Equal(ConfigStatus.Revoked, config.Status);
     }
 
+    [Fact]
+    public void Suspend_WhenActive_SetsExpired()
+    {
+        var config = VpnConfig.Create(Guid.NewGuid(), Guid.NewGuid(), VpnProtocol.Vless, null);
+
+        config.Suspend();
+
+        Assert.Equal(ConfigStatus.Expired, config.Status);
+    }
+
+    [Fact]
+    public void Suspend_WhenDisabledByAdmin_DoesNotOverrideBlock()
+    {
+        // Suspend (биллинг) не должен путать своё состояние с Disable (блокировка админом) — иначе
+        // Resume() ошибочно вернёт в Active конфиг, погашенный не за неуплату.
+        var config = VpnConfig.Create(Guid.NewGuid(), Guid.NewGuid(), VpnProtocol.Vless, null);
+        config.Disable();
+
+        config.Suspend();
+
+        Assert.Equal(ConfigStatus.Disabled, config.Status);
+    }
+
+    [Fact]
+    public void Resume_WhenExpired_ReturnsToActive()
+    {
+        var config = VpnConfig.Create(Guid.NewGuid(), Guid.NewGuid(), VpnProtocol.Vless, null);
+        config.Suspend();
+
+        config.Resume();
+
+        Assert.Equal(ConfigStatus.Active, config.Status);
+    }
+
+    [Fact]
+    public void Resume_WhenDisabledByAdmin_DoesNotResurrect()
+    {
+        var config = VpnConfig.Create(Guid.NewGuid(), Guid.NewGuid(), VpnProtocol.Vless, null);
+        config.Disable();
+
+        config.Resume();
+
+        Assert.Equal(ConfigStatus.Disabled, config.Status);
+    }
+
+    [Fact]
+    public void SetBillingExpiry_SetsExpiresAt()
+    {
+        var config = VpnConfig.Create(Guid.NewGuid(), Guid.NewGuid(), VpnProtocol.Vless, null);
+        var expiresAt = DateTimeOffset.UtcNow.AddMonths(3);
+
+        config.SetBillingExpiry(expiresAt);
+
+        Assert.Equal(expiresAt, config.ExpiresAt);
+    }
+
     [Fact]
     public void UpdateTraffic_SetsBytesAndLastSyncAt()
     {