refactor(catalogs): apply comprehensive code review suggestions

API Improvements:
- Change all update/delete/activate/deactivate endpoints to return 204 NoContent
- Change ValidateServicesAsync parameter from Guid[] to IReadOnlyCollection<Guid>
- Remove unused IServiceProvider from CatalogsModuleApi constructor

Test Quality:
- Tighten invalid-name test assertion to verify error message contains 'name'
- Call base.OnModuleInitializeAsync to preserve future base setup in integration tests
- Future-proof test infrastructure initialization

Performance & Documentation:
- Optimize ValidateServicesAsync to deduplicate input IDs (avoid duplicate processing)
- Add performance note to GetServiceCategoriesWithCountQueryHandler about N+1 pattern
- Add unit-of-work pattern note to ServiceRepository write methods
- Improve DeleteServiceCommandHandler TODO with detailed cross-module check guidance

Code Maintainability:
- Extract validation constants to ServiceCategoryValidation and ServiceValidation classes
- Add XML summary comments to all service commands for better discoverability
- Centralize max length values to avoid duplication and drift

All 94 unit tests and 30 integration tests passing.

src/Modules/Catalogs/API/Endpoints/ServiceCategoryEndpoints.cs

@@ -112,7 +112,7 @@ public static void Map(IEndpointRouteBuilder app)
         => app.MapPut("/{id:guid}", UpdateAsync)
             .WithName("UpdateServiceCategory")
             .WithSummary("Atualizar categoria de serviço")
-            .Produces<Response<Unit>>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status204NoContent)
             .RequireAdmin();
 
     private static async Task<IResult> UpdateAsync(
@@ -123,7 +123,7 @@ private static async Task<IResult> UpdateAsync(
     {
         var command = new UpdateServiceCategoryCommand(id, request.Name, request.Description, request.DisplayOrder);
         var result = await commandDispatcher.SendAsync<UpdateServiceCategoryCommand, Result>(command, cancellationToken);
-        return Handle(result);
+        return HandleNoContent(result);
     }
 }
 
@@ -137,7 +137,7 @@ public static void Map(IEndpointRouteBuilder app)
         => app.MapDelete("/{id:guid}", DeleteAsync)
             .WithName("DeleteServiceCategory")
             .WithSummary("Deletar categoria de serviço")
-            .Produces<Response<Unit>>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status204NoContent)
             .RequireAdmin();
 
     private static async Task<IResult> DeleteAsync(
@@ -147,7 +147,7 @@ private static async Task<IResult> DeleteAsync(
     {
         var command = new DeleteServiceCategoryCommand(id);
         var result = await commandDispatcher.SendAsync<DeleteServiceCategoryCommand, Result>(command, cancellationToken);
-        return Handle(result);
+        return HandleNoContent(result);
     }
 }
 
@@ -161,7 +161,7 @@ public static void Map(IEndpointRouteBuilder app)
         => app.MapPost("/{id:guid}/activate", ActivateAsync)
             .WithName("ActivateServiceCategory")
             .WithSummary("Ativar categoria de serviço")
-            .Produces<Response<Unit>>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status204NoContent)
             .RequireAdmin();
 
     private static async Task<IResult> ActivateAsync(
@@ -171,7 +171,7 @@ private static async Task<IResult> ActivateAsync(
     {
         var command = new ActivateServiceCategoryCommand(id);
         var result = await commandDispatcher.SendAsync<ActivateServiceCategoryCommand, Result>(command, cancellationToken);
-        return Handle(result);
+        return HandleNoContent(result);
     }
 }
 
@@ -181,7 +181,7 @@ public static void Map(IEndpointRouteBuilder app)
         => app.MapPost("/{id:guid}/deactivate", DeactivateAsync)
             .WithName("DeactivateServiceCategory")
             .WithSummary("Desativar categoria de serviço")
-            .Produces<Response<Unit>>(StatusCodes.Status200OK)
+            .Produces(StatusCodes.Status204NoContent)
             .RequireAdmin();
 
     private static async Task<IResult> DeactivateAsync(
@@ -191,6 +191,6 @@ private static async Task<IResult> DeactivateAsync(
     {
         var command = new DeactivateServiceCategoryCommand(id);
         var result = await commandDispatcher.SendAsync<DeactivateServiceCategoryCommand, Result>(command, cancellationToken);
-        return Handle(result);
+        return HandleNoContent(result);
     }
 }

src/Modules/Catalogs/Application/CommandHandlers.cs

@@ -236,7 +236,11 @@ public async Task<Result> HandleAsync(DeleteServiceCommand request, Cancellation
             return Result.Failure($"Service with ID '{request.Id}' not found.");
 
         // TODO: Check if any provider offers this service before deleting
-        // This requires integration with Providers module
+        // This requires integration with Providers module via IProvidersModuleApi
+        // Consider implementing:
+        // 1. Call IProvidersModuleApi.HasProvidersOfferingServiceAsync(serviceId)
+        // 2. Return failure if providers exist: "Cannot delete service: X providers offer this service"
+        // 3. Or implement soft-delete pattern to preserve historical data
 
         await serviceRepository.DeleteAsync(serviceId, cancellationToken);
 

src/Modules/Catalogs/Application/Commands.cs

@@ -31,26 +31,45 @@ public sealed record DeactivateServiceCategoryCommand(Guid Id) : Command<Result>
 // SERVICE COMMANDS
 // ============================================================================
 
+/// <summary>
+/// Command to create a new service in a specific category.
+/// </summary>
 public sealed record CreateServiceCommand(
     Guid CategoryId,
     string Name,
     string? Description,
     int DisplayOrder = 0
 ) : Command<Result<ServiceDto>>;
 
+/// <summary>
+/// Command to update an existing service's details.
+/// </summary>
 public sealed record UpdateServiceCommand(
     Guid Id,
     string Name,
     string? Description,
     int DisplayOrder
 ) : Command<Result>;
 
+/// <summary>
+/// Command to delete a service from the catalog.
+/// Note: Currently does not check for provider references (see handler TODO).
+/// </summary>
 public sealed record DeleteServiceCommand(Guid Id) : Command<Result>;
 
+/// <summary>
+/// Command to activate a service, making it available for use.
+/// </summary>
 public sealed record ActivateServiceCommand(Guid Id) : Command<Result>;
 
+/// <summary>
+/// Command to deactivate a service, removing it from active use.
+/// </summary>
 public sealed record DeactivateServiceCommand(Guid Id) : Command<Result>;
 
+/// <summary>
+/// Command to move a service to a different category.
+/// </summary>
 public sealed record ChangeServiceCategoryCommand(
     Guid ServiceId,
     Guid NewCategoryId

src/Modules/Catalogs/Application/ModuleApi/CatalogsModuleApi.cs

@@ -19,7 +19,6 @@ namespace MeAjudaAi.Modules.Catalogs.Application.ModuleApi;
 public sealed class CatalogsModuleApi(
     IServiceCategoryRepository categoryRepository,
     IServiceRepository serviceRepository,
-    IServiceProvider serviceProvider,
     ILogger<CatalogsModuleApi> logger) : ICatalogsModuleApi
 {
     public string ModuleName => "Catalogs";
@@ -209,15 +208,16 @@ public async Task<Result<bool>> IsServiceActiveAsync(
     }
 
     public async Task<Result<ModuleServiceValidationResultDto>> ValidateServicesAsync(
-        Guid[] serviceIds,
+        IReadOnlyCollection<Guid> serviceIds,
         CancellationToken cancellationToken = default)
     {
         try
         {
             var invalidIds = new List<Guid>();
             var inactiveIds = new List<Guid>();
 
-            foreach (var serviceId in serviceIds)
+            // Deduplicate input IDs to avoid processing the same ID multiple times
+            foreach (var serviceId in serviceIds.Distinct())
             {
                 var serviceIdValue = ServiceId.From(serviceId);
                 var service = await serviceRepository.GetByIdAsync(serviceIdValue, cancellationToken);

src/Modules/Catalogs/Application/QueryHandlers.cs

@@ -153,6 +153,9 @@ public async Task<Result<IReadOnlyList<ServiceCategoryWithCountDto>>> HandleAsyn
 
         var dtos = new List<ServiceCategoryWithCountDto>();
 
+        // NOTE: This performs 2 * N count queries (one for total, one for active per category).
+        // For small-to-medium catalogs this is acceptable. If this becomes a performance bottleneck
+        // with many categories, consider optimizing with a batched query or grouping in the repository.
         foreach (var category in categories)
         {
             var totalCount = await serviceRepository.CountByCategoryAsync(

src/Modules/Catalogs/Domain/Entities/Service.cs

@@ -5,6 +5,15 @@
 
 namespace MeAjudaAi.Modules.Catalogs.Domain.Entities;
 
+/// <summary>
+/// Validation constants for Service entity.
+/// </summary>
+public static class ServiceValidation
+{
+    public const int MaxNameLength = 150;
+    public const int MaxDescriptionLength = 1000;
+}
+
 /// <summary>
 /// Represents a specific service that providers can offer (e.g., "Limpeza de Apartamento", "Conserto de Torneira").
 /// Services belong to a category and can be activated/deactivated by administrators.
@@ -137,13 +146,13 @@ private static void ValidateName(string name)
         if (string.IsNullOrWhiteSpace(name))
             throw new CatalogDomainException("Service name is required.");
 
-        if (name.Trim().Length > 150)
-            throw new CatalogDomainException("Service name cannot exceed 150 characters.");
+        if (name.Trim().Length > ServiceValidation.MaxNameLength)
+            throw new CatalogDomainException($"Service name cannot exceed {ServiceValidation.MaxNameLength} characters.");
     }
 
     private static void ValidateDescription(string? description)
     {
-        if (description is not null && description.Trim().Length > 1000)
-            throw new CatalogDomainException("Service description cannot exceed 1000 characters.");
+        if (description is not null && description.Trim().Length > ServiceValidation.MaxDescriptionLength)
+            throw new CatalogDomainException($"Service description cannot exceed {ServiceValidation.MaxDescriptionLength} characters.");
     }
 }

src/Modules/Catalogs/Domain/Entities/ServiceCategory.cs

@@ -5,6 +5,15 @@
 
 namespace MeAjudaAi.Modules.Catalogs.Domain.Entities;
 
+/// <summary>
+/// Validation constants for ServiceCategory entity.
+/// </summary>
+public static class ServiceCategoryValidation
+{
+    public const int MaxNameLength = 100;
+    public const int MaxDescriptionLength = 500;
+}
+
 /// <summary>
 /// Represents a service category in the catalog (e.g., "Limpeza", "Reparos").
 /// Categories organize services into logical groups for easier discovery.
@@ -106,13 +115,13 @@ private static void ValidateName(string name)
         if (string.IsNullOrWhiteSpace(name))
             throw new CatalogDomainException("Category name is required.");
 
-        if (name.Trim().Length > 100)
-            throw new CatalogDomainException("Category name cannot exceed 100 characters.");
+        if (name.Trim().Length > ServiceCategoryValidation.MaxNameLength)
+            throw new CatalogDomainException($"Category name cannot exceed {ServiceCategoryValidation.MaxNameLength} characters.");
     }
 
     private static void ValidateDescription(string? description)
     {
-        if (description is not null && description.Trim().Length > 500)
-            throw new CatalogDomainException("Category description cannot exceed 500 characters.");
+        if (description is not null && description.Trim().Length > ServiceCategoryValidation.MaxDescriptionLength)
+            throw new CatalogDomainException($"Category description cannot exceed {ServiceCategoryValidation.MaxDescriptionLength} characters.");
     }
 }

src/Modules/Catalogs/Infrastructure/Persistence/Repositories/ServiceRepository.cs

@@ -71,6 +71,10 @@ public async Task<int> CountByCategoryAsync(ServiceCategoryId categoryId, bool a
         return await query.CountAsync(cancellationToken);
     }
 
+    // NOTE: Write methods call SaveChangesAsync directly, treating each operation as a unit of work.
+    // This is appropriate for single-aggregate commands. If multi-aggregate transactions are needed
+    // in the future, consider introducing a shared unit-of-work abstraction.
+
     public async Task AddAsync(Service service, CancellationToken cancellationToken = default)
     {
         await context.Services.AddAsync(service, cancellationToken);
@@ -85,11 +89,13 @@ public async Task UpdateAsync(Service service, CancellationToken cancellationTok
 
     public async Task DeleteAsync(ServiceId id, CancellationToken cancellationToken = default)
     {
+        // Reuse GetByIdAsync but note it's a tracked query for delete scenarios
         var service = await GetByIdAsync(id, cancellationToken);
         if (service is not null)
         {
             context.Services.Remove(service);
             await context.SaveChangesAsync(cancellationToken);
         }
+        // Delete is idempotent - no-op if service doesn't exist
     }
 }

src/Modules/Catalogs/Tests/Integration/CatalogsModuleApiIntegrationTests.cs

@@ -9,10 +9,10 @@ public class CatalogsModuleApiIntegrationTests : CatalogsIntegrationTestBase
 {
     private ICatalogsModuleApi _moduleApi = null!;
 
-    protected override Task OnModuleInitializeAsync(IServiceProvider serviceProvider)
+    protected override async Task OnModuleInitializeAsync(IServiceProvider serviceProvider)
     {
+        await base.OnModuleInitializeAsync(serviceProvider);
         _moduleApi = GetService<ICatalogsModuleApi>();
-        return Task.CompletedTask;
     }
 
     [Fact]

src/Modules/Catalogs/Tests/Integration/ServiceCategoryRepositoryIntegrationTests.cs

@@ -9,10 +9,10 @@ public class ServiceCategoryRepositoryIntegrationTests : CatalogsIntegrationTest
 {
     private IServiceCategoryRepository _repository = null!;
 
-    protected override Task OnModuleInitializeAsync(IServiceProvider serviceProvider)
+    protected override async Task OnModuleInitializeAsync(IServiceProvider serviceProvider)
     {
+        await base.OnModuleInitializeAsync(serviceProvider);
         _repository = GetService<IServiceCategoryRepository>();
-        return Task.CompletedTask;
     }
 
     [Fact]

src/Modules/Catalogs/Tests/Unit/Application/Handlers/Commands/CreateServiceCategoryCommandHandlerTests.cs

@@ -84,5 +84,6 @@ public async Task Handle_WithInvalidName_ShouldReturnFailure(string? invalidName
         // Assert
         result.IsSuccess.Should().BeFalse();
         result.Error.Should().NotBeNull();
+        result.Error!.Message.Should().Contain("name", "validation error should mention the problematic field");
     }
 }

src/Shared/Contracts/Modules/Catalogs/ICatalogsModuleApi.cs

@@ -65,6 +65,6 @@ Task<Result<bool>> IsServiceActiveAsync(
     /// </summary>
     /// <returns>Result containing validation outcome and list of invalid service IDs</returns>
     Task<Result<ModuleServiceValidationResultDto>> ValidateServicesAsync(
-        Guid[] serviceIds,
+        IReadOnlyCollection<Guid> serviceIds,
         CancellationToken cancellationToken = default);
 }