feat(ums): implement consistent state-change and deletion dependency guard policy

Adds a cross-cutting policy that blocks state-change and deletion operations
when active dependencies exist, preventing orphaned records and inconsistencies.

Domain layer:
- BlockingDependency.cs: new record type and BlockedOperationError encoder/decoder
  for structured error propagation from application to presentation layer
- DomainErrors: new guard error codes (TENANT_HAS_ACTIVE_USERS, USER_HAS_ACTIVE_PROFILES,
  ROLE_HAS_ACTIVE_PROFILES, ROLE_HAS_ACTIVE_CHILD_ROLES, TEMPLATE_HAS_ACTIVE_PROFILES,
  DOMAIN_RESOURCE_HAS_TEMPLATE_ITEMS, MODULE_HAS_ACTIVE_MENUS)

Repository contracts:
- IUserAccountRepository: CountActiveByTenantAsync
- IProfileRepository: CountActiveByRoleAsync, CountActiveByTemplateAsync, CountActiveByUserAsync
- IRoleRepository: CountActiveChildRolesAsync
- IPermissionTemplateRepository: CountPublishedByRoleAsync, CountItemsByTargetAsync
- Implemented in both SqlServer and InMemory repositories

Application guards (pre-condition checks before state changes):
- SuspendTenantCommandHandler: blocks if tenant has active users
- BlockUserAccountCommandHandler: blocks if user has active profiles
- DeleteUserAccountCommandHandler: blocks if user has active profiles
- SetRoleStatusCommandHandler: blocks deactivation if role has active profiles or child roles
- DeprecatePermissionTemplateCommandHandler: blocks if template has active profiles
- RemoveDomainResourceCommandHandler: blocks if domain resource is referenced in template items

Presentation layer:
- BlockedOperationResponse: structured 409 Conflict response with errorCode,
  message, brokenRule, and blockingDependencies array
- BlockedOperationMessages: user-facing messages and rules per error code
- ResultExtensions.ToNoContent: routes through ToBlockedOrProblem for structured 409 vs generic 4xx

Tests: 549 passing (+10 new guard tests in RoleCommandHandlerTests and SuspendTenantCommandHandlerTests)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: beyondnetPeru

src/apps/ums.api/Ums.Application.Test/Authorization/Role/RoleCommandHandlerTests.cs

@@ -4,13 +4,15 @@ namespace Ums.Application.Test.Authorization.Role;
 using Ums.Application.Common.Interfaces;
 using Ums.Domain.Authorization;
 using Ums.Domain.Authorization.SystemSuite;
+using Ums.Domain.Kernel;
 using RoleAggregate = Ums.Domain.Authorization.Role.Role;
 using Moq;
 using Xunit;
 
 public sealed class RoleCommandHandlerTests
 {
     private readonly Mock<IRoleRepository> _roles = new();
+    private readonly Mock<IProfileRepository> _profiles = new();
     private readonly Mock<ISystemSuiteRepository> _suites = new();
     private readonly Mock<IUnitOfWork> _unitOfWork = new();
     private readonly Mock<IUserContext> _userContext = new();
@@ -23,8 +25,17 @@ public RoleCommandHandlerTests()
         _userContext.Setup(x => x.UserId).Returns("user-001");
         _scopePolicy.Setup(x => x.EnsureManagementOwnerScopeAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()))
             .ReturnsAsync(Result.Success());
+
+        // Default: no active profiles or child roles → guard passes
+        _profiles.Setup(x => x.CountActiveByRoleAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(0);
+        _roles.Setup(x => x.CountActiveChildRolesAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(0);
     }
 
+    private SetRoleStatusCommandHandler MakeSetStatusHandler()
+        => new(_roles.Object, _profiles.Object, _userContext.Object);
+
     private static SystemSuite MakeSuite() => SystemSuite.Create(
         TenantId.Load(Guid.NewGuid()),
         Code.Create("WMS"),
@@ -99,7 +110,7 @@ public async Task SetStatus_Deactivate_UpdatesRole()
             suite.TenantId, suite.GetId(), Code.Create("OPERATOR"), Name.Create("Operator"),
             Description.Create(""), null, 0, 0, ActorId.Create("user-001")).Value;
         _roles.Setup(x => x.GetByIdAsync(role.GetId().GetValue(), It.IsAny<CancellationToken>())).ReturnsAsync(role);
-        var handler = new SetRoleStatusCommandHandler(_roles.Object, _userContext.Object);
+        var handler = MakeSetStatusHandler();
 
         var result = await handler.Handle(new SetRoleStatusCommand(role.GetId().GetValue(), false), CancellationToken.None);
 
@@ -108,6 +119,69 @@ public async Task SetStatus_Deactivate_UpdatesRole()
         _roles.Verify(x => x.UpdateAsync(role, It.IsAny<CancellationToken>()), Times.Once);
     }
 
+    [Fact]
+    public async Task SetStatus_Deactivate_WhenRoleHasActiveProfiles_ReturnsBlockedFailure()
+    {
+        var suite = MakeSuite();
+        var role = RoleAggregate.Create(
+            suite.TenantId, suite.GetId(), Code.Create("OPERATOR"), Name.Create("Operator"),
+            Description.Create(""), null, 0, 0, ActorId.Create("user-001")).Value;
+        _roles.Setup(x => x.GetByIdAsync(role.GetId().GetValue(), It.IsAny<CancellationToken>())).ReturnsAsync(role);
+        _profiles.Setup(x => x.CountActiveByRoleAsync(role.GetId().GetValue(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(5);
+        var handler = MakeSetStatusHandler();
+
+        var result = await handler.Handle(new SetRoleStatusCommand(role.GetId().GetValue(), false), CancellationToken.None);
+
+        Assert.True(result.IsFailure);
+        var decoded = BlockedOperationError.TryDecode(result.Error, out var code, out var deps);
+        Assert.True(decoded);
+        Assert.Equal(DomainErrors.Authorization.RoleHasActiveProfiles, code);
+        Assert.Single(deps);
+        Assert.Equal("Profile", deps[0].EntityType);
+        Assert.Equal(5, deps[0].Count);
+    }
+
+    [Fact]
+    public async Task SetStatus_Deactivate_WhenRoleHasActiveChildRoles_ReturnsBlockedFailure()
+    {
+        var suite = MakeSuite();
+        var role = RoleAggregate.Create(
+            suite.TenantId, suite.GetId(), Code.Create("OPERATOR"), Name.Create("Operator"),
+            Description.Create(""), null, 0, 0, ActorId.Create("user-001")).Value;
+        _roles.Setup(x => x.GetByIdAsync(role.GetId().GetValue(), It.IsAny<CancellationToken>())).ReturnsAsync(role);
+        _roles.Setup(x => x.CountActiveChildRolesAsync(role.GetId().GetValue(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(3);
+        var handler = MakeSetStatusHandler();
+
+        var result = await handler.Handle(new SetRoleStatusCommand(role.GetId().GetValue(), false), CancellationToken.None);
+
+        Assert.True(result.IsFailure);
+        var decoded = BlockedOperationError.TryDecode(result.Error, out var code, out _);
+        Assert.True(decoded);
+        Assert.Equal(DomainErrors.Authorization.RoleHasActiveChildRoles, code);
+    }
+
+    [Fact]
+    public async Task SetStatus_Activate_DoesNotCheckDependencies()
+    {
+        var suite = MakeSuite();
+        var role = RoleAggregate.Create(
+            suite.TenantId, suite.GetId(), Code.Create("OPERATOR"), Name.Create("Operator"),
+            Description.Create(""), null, 0, 0, ActorId.Create("user-001")).Value;
+        role.Deactivate(ActorId.Create("user-001"));
+        _roles.Setup(x => x.GetByIdAsync(role.GetId().GetValue(), It.IsAny<CancellationToken>())).ReturnsAsync(role);
+        // Setup unreachable: profiles have many active — should NOT be checked on activate
+        _profiles.Setup(x => x.CountActiveByRoleAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(99);
+        var handler = MakeSetStatusHandler();
+
+        var result = await handler.Handle(new SetRoleStatusCommand(role.GetId().GetValue(), true), CancellationToken.None);
+
+        Assert.True(result.IsSuccess);
+        _profiles.Verify(x => x.CountActiveByRoleAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()), Times.Never);
+    }
+
     [Fact]
     public async Task Update_WhenParentIsDescendant_RejectsCycle()
     {

src/apps/ums.api/Ums.Application.Test/Tenants/SuspendTenant/SuspendTenantCommandHandlerTests.cs

@@ -1,4 +1,4 @@
-namespace Ums.Application.Test.Tenants.SuspendTenant;
+namespace Ums.Application.Test.Tenants.SuspendTenant;
 
 using Ums.Application.Identity.Tenant.Commands;
 using Ums.Domain.Identity;
@@ -9,17 +9,28 @@
 public class SuspendTenantCommandHandlerTests
 {
     private readonly Mock<ITenantRepository> _tenantRepositoryMock;
+    private readonly Mock<IUserAccountRepository> _userAccountRepositoryMock;
     private readonly Mock<IUnitOfWork> _unitOfWorkMock;
     private readonly Mock<IUserContext> _userContextMock;
     private readonly SuspendTenantCommandHandler _handler;
 
     public SuspendTenantCommandHandlerTests()
     {
         _tenantRepositoryMock = new Mock<ITenantRepository>();
+        _userAccountRepositoryMock = new Mock<IUserAccountRepository>();
         _unitOfWorkMock = new Mock<IUnitOfWork>();
         _tenantRepositoryMock.Setup(r => r.UnitOfWork).Returns(_unitOfWorkMock.Object);
         _userContextMock = new Mock<IUserContext>();
-        _handler = new SuspendTenantCommandHandler(_tenantRepositoryMock.Object, _userContextMock.Object);
+
+        // Default: no active users → guard passes
+        _userAccountRepositoryMock
+            .Setup(r => r.CountActiveByTenantAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(0);
+
+        _handler = new SuspendTenantCommandHandler(
+            _tenantRepositoryMock.Object,
+            _userAccountRepositoryMock.Object,
+            _userContextMock.Object);
     }
 
     #region Handle - Success Scenarios
@@ -126,6 +137,86 @@ public async Task Handle_WhenTenantAlreadySuspended_ReturnsFailure()
         Assert.True(result.IsFailure);
     }
 
+    // ── Dependency guard tests ────────────────────────────────────────────────
+
+    [Fact]
+    public async Task Handle_WhenTenantHasActiveUsers_ReturnsBlockedFailure()
+    {
+        var tenantId = Guid.NewGuid();
+        _userContextMock.Setup(u => u.UserId).Returns("user-001");
+        var tenant = CreateActiveTenant();
+        _tenantRepositoryMock.Setup(r => r.GetByIdAsync(tenantId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(tenant);
+
+        _userAccountRepositoryMock
+            .Setup(r => r.CountActiveByTenantAsync(tenantId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(12);
+
+        var result = await _handler.Handle(new SuspendTenantCommand(tenantId), CancellationToken.None);
+
+        Assert.True(result.IsFailure);
+        Assert.Contains(DomainErrors.Tenant.HasActiveUsers, result.Error);
+    }
+
+    [Fact]
+    public async Task Handle_WhenTenantHasActiveUsers_DoesNotUpdateTenant()
+    {
+        var tenantId = Guid.NewGuid();
+        _userContextMock.Setup(u => u.UserId).Returns("user-001");
+        var tenant = CreateActiveTenant();
+        _tenantRepositoryMock.Setup(r => r.GetByIdAsync(tenantId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(tenant);
+
+        _userAccountRepositoryMock
+            .Setup(r => r.CountActiveByTenantAsync(tenantId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(5);
+
+        await _handler.Handle(new SuspendTenantCommand(tenantId), CancellationToken.None);
+
+        _tenantRepositoryMock.Verify(r => r.UpdateAsync(It.IsAny<Tenant>(), It.IsAny<CancellationToken>()), Times.Never);
+    }
+
+    [Fact]
+    public async Task Handle_WhenTenantHasActiveUsers_ErrorContainsBlockingDependencies()
+    {
+        var tenantId = Guid.NewGuid();
+        _userContextMock.Setup(u => u.UserId).Returns("user-001");
+        var tenant = CreateActiveTenant();
+        _tenantRepositoryMock.Setup(r => r.GetByIdAsync(tenantId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(tenant);
+
+        _userAccountRepositoryMock
+            .Setup(r => r.CountActiveByTenantAsync(tenantId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(3);
+
+        var result = await _handler.Handle(new SuspendTenantCommand(tenantId), CancellationToken.None);
+
+        var decoded = BlockedOperationError.TryDecode(result.Error, out var code, out var deps);
+        Assert.True(decoded);
+        Assert.Equal(DomainErrors.Tenant.HasActiveUsers, code);
+        Assert.Single(deps);
+        Assert.Equal("UserAccount", deps[0].EntityType);
+        Assert.Equal(3, deps[0].Count);
+    }
+
+    [Fact]
+    public async Task Handle_WhenTenantHasNoActiveUsers_AllowsSuspension()
+    {
+        var tenantId = Guid.NewGuid();
+        _userContextMock.Setup(u => u.UserId).Returns("user-001");
+        var tenant = CreateActiveTenant();
+        _tenantRepositoryMock.Setup(r => r.GetByIdAsync(tenantId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(tenant);
+
+        _userAccountRepositoryMock
+            .Setup(r => r.CountActiveByTenantAsync(tenantId, It.IsAny<CancellationToken>()))
+            .ReturnsAsync(0);
+
+        var result = await _handler.Handle(new SuspendTenantCommand(tenantId), CancellationToken.None);
+
+        Assert.True(result.IsSuccess);
+    }
+
     #endregion
 
     private static Tenant CreateActiveTenant()

src/apps/ums.api/Ums.Application/Authorization/Role/Commands/SetRoleStatusCommandHandler.cs

@@ -1,15 +1,21 @@
 using Ums.Domain.Authorization;
+using Ums.Domain.Kernel;
 
 namespace Ums.Application.Authorization.Role.Commands;
 
 public sealed class SetRoleStatusCommandHandler : ICommandHandler<SetRoleStatusCommand>
 {
     private readonly IRoleRepository _repository;
+    private readonly IProfileRepository _profileRepository;
     private readonly IUserContext _userContext;
 
-    public SetRoleStatusCommandHandler(IRoleRepository repository, IUserContext userContext)
+    public SetRoleStatusCommandHandler(
+        IRoleRepository repository,
+        IProfileRepository profileRepository,
+        IUserContext userContext)
     {
         _repository = repository;
+        _profileRepository = profileRepository;
         _userContext = userContext;
     }
 
@@ -28,6 +34,31 @@ public async Task<Result> Handle(SetRoleStatusCommand request, CancellationToken
             return Result.Failure("No se pudo cambiar el estado porque el rol no existe.");
         }
 
+        // ── Dependency guard (deactivate only) ────────────────────────────────
+        if (!request.IsActive)
+        {
+            var activeProfileCount = await _profileRepository.CountActiveByRoleAsync(
+                request.RoleId, cancellationToken);
+
+            var activeChildCount = await _repository.CountActiveChildRolesAsync(
+                request.RoleId, cancellationToken);
+
+            if (activeProfileCount > 0 || activeChildCount > 0)
+            {
+                var deps = new List<BlockingDependency>();
+                if (activeProfileCount > 0)
+                    deps.Add(new("Profile", "Active", activeProfileCount));
+                if (activeChildCount > 0)
+                    deps.Add(new("Role", "Active", activeChildCount));
+
+                var errorCode = activeProfileCount > 0
+                    ? DomainErrors.Authorization.RoleHasActiveProfiles
+                    : DomainErrors.Authorization.RoleHasActiveChildRoles;
+
+                return Result.Failure(BlockedOperationError.Encode(errorCode, deps));
+            }
+        }
+
         var actor = ActorId.Create(_userContext.UserId);
         var result = request.IsActive ? role.Activate(actor) : role.Deactivate(actor);
         if (result.IsFailure)

src/apps/ums.api/Ums.Application/Authorization/SystemSuite/Commands/RemoveDomainResourceCommandHandler.cs

@@ -8,7 +8,10 @@
 
 namespace Ums.Application.Authorization.SystemSuite.Commands;
 
-public sealed class RemoveDomainResourceCommandHandler(ISystemSuiteRepository repository, IUserContext userContext)
+public sealed class RemoveDomainResourceCommandHandler(
+    ISystemSuiteRepository repository,
+    IPermissionTemplateRepository templateRepository,
+    IUserContext userContext)
     : ICommandHandler<RemoveDomainResourceCommand>
 {
     public async Task<Result> Handle(RemoveDomainResourceCommand request, CancellationToken cancellationToken)
@@ -19,6 +22,20 @@ public async Task<Result> Handle(RemoveDomainResourceCommand request, Cancellati
             return Result.Failure(DomainErrors.Common.NotFound);
         }
 
+        // ── Dependency guard: active template items referencing this resource ──
+        var templateItemCount = await templateRepository.CountItemsByTargetAsync(
+            request.DomainResourceId, cancellationToken);
+
+        if (templateItemCount > 0)
+        {
+            var deps = new List<BlockingDependency>
+            {
+                new("PermissionTemplateItem", "Active", templateItemCount),
+            };
+            return Result.Failure(BlockedOperationError.Encode(
+                DomainErrors.Authorization.DomainResourceHasTemplateItems, deps));
+        }
+
         var result = suite.RemoveDomainResource(
             IdValueObject.Load(request.DomainResourceId),
             ActorId.Create(userContext.UserId ?? string.Empty));

src/apps/ums.api/Ums.Application/Authorization/Template/Commands/DeprecatePermissionTemplateCommandHandler.cs

@@ -1,18 +1,22 @@
 namespace Ums.Application.Authorization.Template.Commands;
 
 using Ums.Domain.Authorization;
+using Ums.Domain.Kernel;
 
 public sealed class DeprecatePermissionTemplateCommandHandler
     : ICommandHandler<DeprecatePermissionTemplateCommand>
 {
     private readonly IPermissionTemplateRepository _repository;
+    private readonly IProfileRepository _profileRepository;
     private readonly IUserContext _userContext;
 
     public DeprecatePermissionTemplateCommandHandler(
         IPermissionTemplateRepository repository,
+        IProfileRepository profileRepository,
         IUserContext userContext)
     {
         _repository = repository;
+        _profileRepository = profileRepository;
         _userContext = userContext;
     }
 
@@ -28,6 +32,20 @@ public async Task<Result> Handle(
         var template = await _repository.GetByIdAsync(request.TemplateId, cancellationToken);
         if (template is null) return Result.Failure("Template not found.");
 
+        // ── Dependency guard: active profiles using this template ──────────────
+        var activeProfileCount = await _profileRepository.CountActiveByTemplateAsync(
+            request.TemplateId, cancellationToken);
+
+        if (activeProfileCount > 0)
+        {
+            var deps = new List<BlockingDependency>
+            {
+                new("Profile", "Active", activeProfileCount),
+            };
+            return Result.Failure(BlockedOperationError.Encode(
+                DomainErrors.Authorization.TemplateHasActiveProfiles, deps));
+        }
+
         var result = template.Deprecate(ActorId.Create(_userContext.UserId));
         if (result.IsFailure) return result;