Feature Overrides

public class TenantFeatureOverride : AuditableEntity
{
    public Guid TenantId { get; set; }
    
    public Guid FeatureId { get; set; }
    public Feature Feature { get; set; } = null!;
    
    public string Value { get; set; } = string.Empty;
    // Must match Feature.ValueType:
    //   Boolean → "true" / "false"
    //   Numeric → integer string (e.g. "500")
    //   String  → arbitrary string
    
    public string? Reason { get; set; }                // Audit trail
    public DateTime? ExpiresAt { get; set; }           // null = permanent
    public bool IsActive { get; set; } = true;
    public Guid AppliedBy { get; set; }                // Who set it
}

{
  "featureId": "550e8400-e29b-41d4-a716-446655440000",
  "value": "500",
  "reason": "Enterprise deal — 500 admins for annual contract",
  "expiresAt": null
}

// Response 200:
{
  "id": "770e8400-e29b-41d4-a716-446655440099",
  "tenantId": "660e8400-e29b-41d4-a716-446655440001",
  "featureId": "550e8400-e29b-41d4-a716-446655440000",
  "featureName": "MaxAdmins",
  "value": "500",
  "previousValue": "50",
  "source": "Override",
  "reason": "Enterprise deal — 500 admins for annual contract",
  "expiresAt": null,
  "isActive": true,
  "appliedBy": "admin-user-id",
  "createdAt": "2026-03-02T10:00:00Z"
}

{
  "tenantId": "660e8400-e29b-41d4-a716-446655440001",
  "editionName": "Pro",
  "resolvedFeatures": [
    {
      "featureId": "...",
      "name": "Chat.Enabled",
      "displayName": "Chat",
      "valueType": "Boolean",
      "value": "true",
      "source": "Edition",
      "editionDefault": "true",
      "overrideValue": null,
      "featureDefault": "false"
    },
    {
      "featureId": "...",
      "name": "MaxAdmins",
      "displayName": "Maximum Administrators",
      "valueType": "Numeric",
      "value": "500",
      "source": "Override",
      "editionDefault": "50",
      "overrideValue": "500",
      "featureDefault": "5",
      "currentUsage": 12,
      "overrideReason": "Enterprise deal",
      "overrideExpiresAt": null
    },
    {
      "featureId": "...",
      "name": "SSO.Enabled",
      "displayName": "Single Sign-On",
      "valueType": "Boolean",
      "value": "false",
      "source": "Default",
      "editionDefault": null,
      "overrideValue": null,
      "featureDefault": "false"
    }
  ]
}

{
  "featureId": "...")
  "value": "true",
  "reason": "30-day trial of Advanced Reporting feature",
  "expiresAt": "2026-04-02T00:00:00Z"
}

// After expiry:
// - Override is automatically marked isActive = false
// - Feature falls back to edition value (or default)
// - No manual intervention needed

// Inside SubscriptionRepository.cs:
// Active subscriptions are ordered by type priority:
return await _db.Subscriptions
    .Where(s => s.TenantId == tenantId && s.Status == SubscriptionStatus.Active)
    .OrderBy(s => s.Type) // Lifetime (0) → Monthly (1) → Yearly (2) → Trial (3) → AddOn (4) → Free (5)
    .ToListAsync(ct);

// Inside SubscriptionChangedEventHandler.cs:
public async Task Handle(SubscriptionChangedEvent notification, CancellationToken ct)
{
    var tenantId = notification.TenantId;
    
    if (notification.IsRevocation) // Canceled, Expired, Suspended, or PendingPayment
    {
        // Revoke all permissions and lock super admin role
        await _tenantPermissionManager.SyncPermissionsForModulesAsync(tenantId, [], ct);
        await _permissionCache.InvalidateAll();
        return;
    }

    // Active/Trialing: Extract modules from enabled features (e.g. "Communication.Enabled" -> "Communication")
    var enabledModules = notification.Features
        .Where(f => f.Name.EndsWith(".Enabled") && f.Value == "true")
        .Select(f => f.Name.Split('.')[0])
        .ToList();

    // Sync tenant permission pool
    await _tenantPermissionManager.SyncPermissionsForModulesAsync(tenantId, enabledModules, ct);

    // Sync super admin role permissions
    await _roleManager.SyncSuperAdminRolePermissionsAsync(tenantId, ct);
    
    // Invalidate cached permissions
    await _permissionCache.InvalidateAll();
}