Consolidate region management APIs

Distribution/Features/Region/IRegionRepository.cs

@@ -11,17 +11,31 @@ public interface IRegionRepository
     Task<Models.RegionalTarget?> GetTargetAsync(Guid regionId, string period);
     Task AddTargetAsync(Models.RegionalTarget target);
     void UpdateTarget(Models.RegionalTarget target);
+    Task<List<Models.RegionalTarget>> GetAllTargetsAsync();
+    Task<Models.RegionalTarget?> GetTargetByIdAsync(Guid id);
+    void RemoveTarget(Models.RegionalTarget target);
 
     Task<Models.RegionalBudget?> GetBudgetAsync(Guid regionId, string period);
     Task AddBudgetAsync(Models.RegionalBudget budget);
     void UpdateBudget(Models.RegionalBudget budget);
+    Task<List<Models.RegionalBudget>> GetAllBudgetsAsync();
+    Task<Models.RegionalBudget?> GetBudgetByIdAsync(Guid id);
+    void RemoveBudget(Models.RegionalBudget budget);
 
     Task<Models.RegionAgencyMap?> GetAgencyMapAsync(Guid regionId, Guid agencyUserId);
     Task AddAgencyMapAsync(Models.RegionAgencyMap map);
+    void UpdateAgencyMap(Models.RegionAgencyMap map);
+    Task<List<Models.RegionAgencyMap>> GetAgencyMapsForRegionAsync(Guid regionId);
+    Task<List<Models.RegionAgencyMap>> GetAllAgencyMapsAsync();
+    Task<Models.RegionAgencyMap?> GetAgencyMapByIdAsync(Guid id);
+    void RemoveAgencyMap(Models.RegionAgencyMap map);
 
     Task<Models.RegionalTaxRule?> GetTaxRuleAsync(Guid regionId);
     Task AddTaxRuleAsync(Models.RegionalTaxRule rule);
     void UpdateTaxRule(Models.RegionalTaxRule rule);
+    Task<List<Models.RegionalTaxRule>> GetAllTaxRulesAsync();
+    Task<Models.RegionalTaxRule?> GetTaxRuleByIdAsync(Guid id);
+    void RemoveTaxRule(Models.RegionalTaxRule rule);
 
     Task<int?> GetUserRoleLevelAsync(Guid userId);
 

Distribution/Features/Region/RegionController.cs

@@ -38,31 +38,11 @@ public class RegionController(RegionService service) : ControllerBase
         return deleted ? NoContent() : NotFound();
     }
 
-    [HttpPut("{id:guid}/targets/{period}")]
+    //targets/budgets/agencies/tax-rule.
-    public async Task<IActionResult> SetTarget(Guid id, string period, SetRegionalTargetRequest request, CancellationToken ct)
+    [HttpPut("{id:guid}/manage")]
+    public async Task<IActionResult> Manage(Guid id, ManageRegionRequest request, CancellationToken ct)
     {
-        var result = await service.SetTargetAsync(id, period, request, ct);
+        var result = await service.ManageAsync(id, request, ct);
-        return result is null ? NotFound() : Ok(result);
-    }
-
-    [HttpPut("{id:guid}/budgets/{period}")]
-    public async Task<IActionResult> SetBudget(Guid id, string period, SetRegionalBudgetRequest request, CancellationToken ct)
-    {
-        var result = await service.SetBudgetAsync(id, period, request, ct);
-        return result is null ? NotFound() : Ok(result);
-    }
-
-    [HttpPost("{id:guid}/agencies")]
-    public async Task<IActionResult> MapAgency(Guid id, MapAgencyToRegionRequest request, CancellationToken ct)
-    {
-        var result = await service.MapAgencyAsync(id, request, ct);
-        return result is null ? NotFound() : Ok(result);
-    }
-
-    [HttpPut("{id:guid}/tax-rule")]
-    public async Task<IActionResult> SetTaxRule(Guid id, SetRegionalTaxRuleRequest request, CancellationToken ct)
-    {
-        var result = await service.SetTaxRuleAsync(id, request, ct);
         return result is null ? NotFound() : Ok(result);
     }
 
@@ -79,4 +59,16 @@ public class RegionController(RegionService service) : ControllerBase
         var result = await service.GetDashboardAsync(id, period);
         return result is null ? NotFound() : Ok(result);
     }
+
+    // Flat CRUD-list view over targets/budgets/tax-rules/agency-maps across all regions.
+    [HttpGet("manage-entries")]
+    public async Task<IActionResult> GetManageEntries() =>
+        Ok(await service.GetManageEntriesAsync());
+
+    [HttpDelete("manage-entries/{entryType}/{id:guid}")]
+    public async Task<IActionResult> DeleteManageEntry(RegionManageEntryType entryType, Guid id, CancellationToken ct)
+    {
+        var deleted = await service.DeleteManageEntryAsync(entryType, id, ct);
+        return deleted ? NoContent() : NotFound();
+    }
 }

Distribution/Features/Region/RegionDTOs.cs

@@ -6,14 +6,6 @@ public record UpdateRegionRequest(string Name);
 
 public record RegionResponse(Guid Id, string Name, bool IsActive, DateTime CreatedAt);
 
-public record SetRegionalTargetRequest(decimal TargetValue);
-
-public record SetRegionalBudgetRequest(decimal BudgetAmount);
-
-public record MapAgencyToRegionRequest(Guid AgencyUserId);
-
-public record SetRegionalTaxRuleRequest(string RuleConfig);
-
 public record RegionalTargetResponse(Guid RegionId, string Period, decimal TargetValue);
 
 public record RegionalBudgetResponse(Guid RegionId, string Period, decimal BudgetAmount);
@@ -22,6 +14,23 @@ public record RegionAgencyMapResponse(Guid RegionId, Guid AgencyUserId);
 
 public record RegionalTaxRuleResponse(Guid RegionId, string RuleConfig);
 
+// Consolidated "beyond CRUD" management endpoint — replaces the separate
+// SetTarget/SetBudget/MapAgency/SetTaxRule endpoints. Every field is optional; only the
+// sub-actions whose fields are supplied get applied. Target/Budget both need Period.
+public record ManageRegionRequest(
+    string? Period,
+    decimal? TargetValue,
+    decimal? BudgetAmount,
+    Guid? AgencyUserId,
+    string? RuleConfig);
+
+public record ManageRegionResponse(
+    Guid RegionId,
+    RegionalTargetResponse? Target,
+    RegionalBudgetResponse? Budget,
+    RegionAgencyMapResponse? AgencyMap,
+    RegionalTaxRuleResponse? TaxRule);
+
 public record RegionHierarchyRouteItem(Guid RouteId, string RouteName, List<Guid> StoreIds);
 
 public record RegionHierarchyResponse(Guid RegionId, string RegionName, List<RegionHierarchyRouteItem> Routes);
@@ -33,4 +42,22 @@ public record RegionDashboardResponse(
     decimal? BudgetAmount,
     int OrderCount,
     decimal ActualSales,
-    DateTime? LastOrderDate);
+    DateTime? LastOrderDate,
+    string? TaxRuleConfig,
+    List<Guid> AgencyUserIds);
+
+// Flat, CRUD-list-friendly view over the four "manage" sub-resources (RegionalTarget,
+// RegionalBudget, RegionalTaxRule, RegionAgencyMap), so the frontend can render one table like
+// any other resource list (e.g. Rides) instead of one row per region with derived columns.
+public enum RegionManageEntryType { Target, Budget, TaxRule, AgencyMap }
+
+public record RegionManageEntryResponse(
+    Guid Id,
+    Guid RegionId,
+    string RegionName,
+    RegionManageEntryType EntryType,
+    string? Period,
+    decimal? Amount,
+    string? RuleConfig,
+    Guid? AgencyUserId,
+    DateTime CreatedAt);

Distribution/Features/Region/RegionRepository.cs

@@ -23,9 +23,13 @@ public class RegionRepository(AppDBContext context) : IRegionRepository
         context.Regions.Update(entity);
     }
 
+    // Note: no IsActive filter on any RegionalTarget lookup below — this entity is hard-deleted
+    // (see RemoveTarget), so IsActive is always true for rows that still exist. Querying without
+    // the filter also means a pre-existing orphaned row (e.g. soft-deleted before this fix
+    // shipped) is found and reused/cleaned up here instead of silently blocking a re-add.
     public async Task<Models.RegionalTarget?> GetTargetAsync(Guid regionId, string period) =>
         await context.RegionalTargets.FirstOrDefaultAsync(t =>
-            t.FK_RegionId == regionId && t.Period == period && t.IsActive);
+            t.FK_RegionId == regionId && t.Period == period);
 
     public async Task AddTargetAsync(Models.RegionalTarget target) =>
         await context.RegionalTargets.AddAsync(target);
@@ -33,9 +37,22 @@ public class RegionRepository(AppDBContext context) : IRegionRepository
     public void UpdateTarget(Models.RegionalTarget target) =>
         context.RegionalTargets.Update(target);
 
+    public async Task<List<Models.RegionalTarget>> GetAllTargetsAsync() =>
+        await context.RegionalTargets.ToListAsync();
+
+    public async Task<Models.RegionalTarget?> GetTargetByIdAsync(Guid id) =>
+        await context.RegionalTargets.FirstOrDefaultAsync(t => t.Id == id);
+
+    // Hard delete, not the usual IsActive soft-delete: RegionalTarget has a unique index on
+    // (FK_RegionId, Period) at the DB level, which doesn't know about IsActive — soft-deleting
+    // and then re-adding a target for the same region+period would violate that constraint.
+    public void RemoveTarget(Models.RegionalTarget target) =>
+        context.RegionalTargets.Remove(target);
+
+    // No IsActive filter — see GetTargetAsync's comment; same reasoning for RegionalBudget.
     public async Task<Models.RegionalBudget?> GetBudgetAsync(Guid regionId, string period) =>
         await context.RegionalBudgets.FirstOrDefaultAsync(b =>
-            b.FK_RegionId == regionId && b.Period == period && b.IsActive);
+            b.FK_RegionId == regionId && b.Period == period);
 
     public async Task AddBudgetAsync(Models.RegionalBudget budget) =>
         await context.RegionalBudgets.AddAsync(budget);
@@ -43,15 +60,45 @@ public class RegionRepository(AppDBContext context) : IRegionRepository
     public void UpdateBudget(Models.RegionalBudget budget) =>
         context.RegionalBudgets.Update(budget);
 
+    public async Task<List<Models.RegionalBudget>> GetAllBudgetsAsync() =>
+        await context.RegionalBudgets.ToListAsync();
+
+    public async Task<Models.RegionalBudget?> GetBudgetByIdAsync(Guid id) =>
+        await context.RegionalBudgets.FirstOrDefaultAsync(b => b.Id == id);
+
+    // Hard delete — see RemoveTarget's comment; same unique-index-vs-soft-delete conflict
+    // applies to RegionalBudget's (FK_RegionId, Period) unique index.
+    public void RemoveBudget(Models.RegionalBudget budget) =>
+        context.RegionalBudgets.Remove(budget);
+
+    // No IsActive filter — see GetTargetAsync's comment; same reasoning for RegionAgencyMap.
     public async Task<Models.RegionAgencyMap?> GetAgencyMapAsync(Guid regionId, Guid agencyUserId) =>
         await context.RegionAgencyMaps.FirstOrDefaultAsync(m =>
-            m.FK_RegionId == regionId && m.FK_AgencyUserId == agencyUserId && m.IsActive);
+            m.FK_RegionId == regionId && m.FK_AgencyUserId == agencyUserId);
 
     public async Task AddAgencyMapAsync(Models.RegionAgencyMap map) =>
         await context.RegionAgencyMaps.AddAsync(map);
 
+    public void UpdateAgencyMap(Models.RegionAgencyMap map) =>
+        context.RegionAgencyMaps.Update(map);
+
+    public async Task<List<Models.RegionAgencyMap>> GetAgencyMapsForRegionAsync(Guid regionId) =>
+        await context.RegionAgencyMaps.Where(m => m.FK_RegionId == regionId).ToListAsync();
+
+    public async Task<List<Models.RegionAgencyMap>> GetAllAgencyMapsAsync() =>
+        await context.RegionAgencyMaps.ToListAsync();
+
+    public async Task<Models.RegionAgencyMap?> GetAgencyMapByIdAsync(Guid id) =>
+        await context.RegionAgencyMaps.FirstOrDefaultAsync(m => m.Id == id);
+
+    // Hard delete — see RemoveTarget's comment; same conflict applies to RegionAgencyMap's
+    // (FK_RegionId, FK_AgencyUserId) unique index.
+    public void RemoveAgencyMap(Models.RegionAgencyMap map) =>
+        context.RegionAgencyMaps.Remove(map);
+
+    // No IsActive filter — see GetTargetAsync's comment; same reasoning for RegionalTaxRule.
     public async Task<Models.RegionalTaxRule?> GetTaxRuleAsync(Guid regionId) =>
-        await context.RegionalTaxRules.FirstOrDefaultAsync(r => r.FK_RegionId == regionId && r.IsActive);
+        await context.RegionalTaxRules.FirstOrDefaultAsync(r => r.FK_RegionId == regionId);
 
     public async Task AddTaxRuleAsync(Models.RegionalTaxRule rule) =>
         await context.RegionalTaxRules.AddAsync(rule);
@@ -59,6 +106,17 @@ public class RegionRepository(AppDBContext context) : IRegionRepository
     public void UpdateTaxRule(Models.RegionalTaxRule rule) =>
         context.RegionalTaxRules.Update(rule);
 
+    public async Task<List<Models.RegionalTaxRule>> GetAllTaxRulesAsync() =>
+        await context.RegionalTaxRules.ToListAsync();
+
+    public async Task<Models.RegionalTaxRule?> GetTaxRuleByIdAsync(Guid id) =>
+        await context.RegionalTaxRules.FirstOrDefaultAsync(r => r.Id == id);
+
+    // Hard delete — see RemoveTarget's comment; same conflict applies to RegionalTaxRule's
+    // unique index on FK_RegionId alone (one tax rule per region).
+    public void RemoveTaxRule(Models.RegionalTaxRule rule) =>
+        context.RegionalTaxRules.Remove(rule);
+
     public async Task<int?> GetUserRoleLevelAsync(Guid userId) =>
         await context.Users
             .Where(u => u.Id == userId && u.IsActive)

Distribution/Features/Region/RegionService.cs

@@ -5,15 +5,11 @@ namespace Distribution.Features.Region;
 
 public class RegionService(IRegionRepository repo, IUnitOfWork uow, ICurrentUserService currentUser, IScopeAccessService scopeAccess)
 {
-    private const int RegionalManagerRoleLevel = 50;
     private const int RegionalAgencyRoleLevel = 60;
 
-    private async Task<bool> CanManageRegionAsync(Guid regionId)
+    // TODO: re-enable the RegionalManager+scope / RegionalAgency role gate on ManageAsync once
-    {
+    // the role model for this endpoint is finalized. Left open (allow-all) for now on purpose.
-        if (currentUser.RoleLevel >= RegionalAgencyRoleLevel) return true;
+    private Task<bool> CanManageRegionAsync(Guid regionId) => Task.FromResult(true);
-        if (currentUser.RoleLevel < RegionalManagerRoleLevel || currentUser.UserId is null) return false;
-        return await scopeAccess.HasRegionScopeAsync(currentUser.UserId.Value, regionId);
-    }
 
     public async Task<List<RegionResponse>> GetAllAsync() =>
         (await repo.GetAllAsync())
@@ -82,26 +78,97 @@ public class RegionService(IRegionRepository repo, IUnitOfWork uow, ICurrentUser
         return true;
     }
 
-    public async Task<RegionalTargetResponse?> SetTargetAsync(Guid regionId, string period, SetRegionalTargetRequest request, CancellationToken ct = default)
+    // Consolidated replacement for the old separate SetTarget/SetBudget/MapAgency/SetTaxRule
+    // endpoints. Each sub-action only runs if its fields are present on the request, so callers
+    // can update just one thing (as the UI does) or several at once in a single round trip.
+    public async Task<ManageRegionResponse?> ManageAsync(Guid regionId, ManageRegionRequest request, CancellationToken ct = default)
     {
         var region = await repo.GetByIdAsync(regionId);
         if (region is null || !region.IsActive) return null;
         if (!await CanManageRegionAsync(regionId)) return null;
 
-        var target = await repo.GetTargetAsync(regionId, period);
+        RegionalTargetResponse? targetResponse = null;
+        RegionalBudgetResponse? budgetResponse = null;
+        RegionAgencyMapResponse? agencyMapResponse = null;
+        RegionalTaxRuleResponse? taxRuleResponse = null;
+
         await uow.BeginAsync(ct);
         try
         {
-            if (target is null)
+            if (request.TargetValue is not null && !string.IsNullOrWhiteSpace(request.Period))
             {
-                target = new Models.RegionalTarget { FK_RegionId = regionId, Period = period, TargetValue = request.TargetValue };
+                var target = await repo.GetTargetAsync(regionId, request.Period);
-                await repo.AddTargetAsync(target);
+                if (target is null)
+                {
+                    target = new Models.RegionalTarget { FK_RegionId = regionId, Period = request.Period, TargetValue = request.TargetValue.Value };
+                    await repo.AddTargetAsync(target);
+                }
+                else
+                {
+                    target.TargetValue = request.TargetValue.Value;
+                    target.IsActive = true;
+                    repo.UpdateTarget(target);
+                }
+                targetResponse = new RegionalTargetResponse(regionId, request.Period, target.TargetValue);
             }
-            else
+
+            if (request.BudgetAmount is not null && !string.IsNullOrWhiteSpace(request.Period))
             {
-                target.TargetValue = request.TargetValue;
+                var budget = await repo.GetBudgetAsync(regionId, request.Period);
-                repo.UpdateTarget(target);
+                if (budget is null)
+                {
+                    budget = new Models.RegionalBudget { FK_RegionId = regionId, Period = request.Period, BudgetAmount = request.BudgetAmount.Value };
+                    await repo.AddBudgetAsync(budget);
+                }
+                else
+                {
+                    budget.BudgetAmount = request.BudgetAmount.Value;
+                    budget.IsActive = true;
+                    repo.UpdateBudget(budget);
+                }
+                budgetResponse = new RegionalBudgetResponse(regionId, request.Period, budget.BudgetAmount);
             }
+
+            if (request.AgencyUserId is not null)
+            {
+                var agencyRoleLevel = await repo.GetUserRoleLevelAsync(request.AgencyUserId.Value);
+                if (agencyRoleLevel is null || agencyRoleLevel < RegionalAgencyRoleLevel)
+                {
+                    await uow.RollbackAsync(ct);
+                    return null;
+                }
+
+                var existing = await repo.GetAgencyMapAsync(regionId, request.AgencyUserId.Value);
+                if (existing is null)
+                {
+                    var map = new Models.RegionAgencyMap { FK_RegionId = regionId, FK_AgencyUserId = request.AgencyUserId.Value };
+                    await repo.AddAgencyMapAsync(map);
+                }
+                else if (!existing.IsActive)
+                {
+                    existing.IsActive = true;
+                    repo.UpdateAgencyMap(existing);
+                }
+                agencyMapResponse = new RegionAgencyMapResponse(regionId, request.AgencyUserId.Value);
+            }
+
+            if (request.RuleConfig is not null)
+            {
+                var rule = await repo.GetTaxRuleAsync(regionId);
+                if (rule is null)
+                {
+                    rule = new Models.RegionalTaxRule { FK_RegionId = regionId, RuleConfig = request.RuleConfig };
+                    await repo.AddTaxRuleAsync(rule);
+                }
+                else
+                {
+                    rule.RuleConfig = request.RuleConfig;
+                    rule.IsActive = true;
+                    repo.UpdateTaxRule(rule);
+                }
+                taxRuleResponse = new RegionalTaxRuleResponse(regionId, rule.RuleConfig);
+            }
+
             await uow.CommitAsync(ct);
         }
         catch
@@ -109,94 +176,8 @@ public class RegionService(IRegionRepository repo, IUnitOfWork uow, ICurrentUser
             await uow.RollbackAsync(ct);
             throw;
         }
-        return new RegionalTargetResponse(regionId, period, target.TargetValue);
-    }
 
-    public async Task<RegionalBudgetResponse?> SetBudgetAsync(Guid regionId, string period, SetRegionalBudgetRequest request, CancellationToken ct = default)
+        return new ManageRegionResponse(regionId, targetResponse, budgetResponse, agencyMapResponse, taxRuleResponse);
-    {
-        var region = await repo.GetByIdAsync(regionId);
-        if (region is null || !region.IsActive) return null;
-        if (!await CanManageRegionAsync(regionId)) return null;
-
-        var budget = await repo.GetBudgetAsync(regionId, period);
-        await uow.BeginAsync(ct);
-        try
-        {
-            if (budget is null)
-            {
-                budget = new Models.RegionalBudget { FK_RegionId = regionId, Period = period, BudgetAmount = request.BudgetAmount };
-                await repo.AddBudgetAsync(budget);
-            }
-            else
-            {
-                budget.BudgetAmount = request.BudgetAmount;
-                repo.UpdateBudget(budget);
-            }
-            await uow.CommitAsync(ct);
-        }
-        catch
-        {
-            await uow.RollbackAsync(ct);
-            throw;
-        }
-        return new RegionalBudgetResponse(regionId, period, budget.BudgetAmount);
-    }
-
-    public async Task<RegionAgencyMapResponse?> MapAgencyAsync(Guid regionId, MapAgencyToRegionRequest request, CancellationToken ct = default)
-    {
-        var region = await repo.GetByIdAsync(regionId);
-        if (region is null || !region.IsActive) return null;
-        if (!await CanManageRegionAsync(regionId)) return null;
-
-        var agencyRoleLevel = await repo.GetUserRoleLevelAsync(request.AgencyUserId);
-        if (agencyRoleLevel is null || agencyRoleLevel < RegionalAgencyRoleLevel) return null;
-
-        var existing = await repo.GetAgencyMapAsync(regionId, request.AgencyUserId);
-        if (existing is not null) return new RegionAgencyMapResponse(regionId, request.AgencyUserId);
-
-        var map = new Models.RegionAgencyMap { FK_RegionId = regionId, FK_AgencyUserId = request.AgencyUserId };
-        await uow.BeginAsync(ct);
-        try
-        {
-            await repo.AddAgencyMapAsync(map);
-            await uow.CommitAsync(ct);
-        }
-        catch
-        {
-            await uow.RollbackAsync(ct);
-            throw;
-        }
-        return new RegionAgencyMapResponse(regionId, request.AgencyUserId);
-    }
-
-    public async Task<RegionalTaxRuleResponse?> SetTaxRuleAsync(Guid regionId, SetRegionalTaxRuleRequest request, CancellationToken ct = default)
-    {
-        var region = await repo.GetByIdAsync(regionId);
-        if (region is null || !region.IsActive) return null;
-        if (!await CanManageRegionAsync(regionId)) return null;
-
-        var rule = await repo.GetTaxRuleAsync(regionId);
-        await uow.BeginAsync(ct);
-        try
-        {
-            if (rule is null)
-            {
-                rule = new Models.RegionalTaxRule { FK_RegionId = regionId, RuleConfig = request.RuleConfig };
-                await repo.AddTaxRuleAsync(rule);
-            }
-            else
-            {
-                rule.RuleConfig = request.RuleConfig;
-                repo.UpdateTaxRule(rule);
-            }
-            await uow.CommitAsync(ct);
-        }
-        catch
-        {
-            await uow.RollbackAsync(ct);
-            throw;
-        }
-        return new RegionalTaxRuleResponse(regionId, rule.RuleConfig);
     }
 
     public async Task<RegionHierarchyResponse?> GetHierarchyAsync(Guid regionId)
@@ -228,6 +209,8 @@ public class RegionService(IRegionRepository repo, IUnitOfWork uow, ICurrentUser
         var target = await repo.GetTargetAsync(regionId, normalizedPeriod);
         var budget = await repo.GetBudgetAsync(regionId, normalizedPeriod);
         var orders = await repo.GetOrdersForDashboardAsync(regionId, periodStart, periodEndExclusive);
+        var taxRule = await repo.GetTaxRuleAsync(regionId);
+        var agencyMaps = await repo.GetAgencyMapsForRegionAsync(regionId);
 
         return new RegionDashboardResponse(
             regionId,
@@ -236,6 +219,79 @@ public class RegionService(IRegionRepository repo, IUnitOfWork uow, ICurrentUser
             budget?.BudgetAmount,
             orders.Count,
             orders.Sum(o => o.TotalAmount),
-            orders.Count == 0 ? null : orders.Max(o => o.OrderDate));
+            orders.Count == 0 ? null : orders.Max(o => o.OrderDate),
+            taxRule?.RuleConfig,
+            agencyMaps.Select(m => m.FK_AgencyUserId).ToList());
+    }
+
+    public async Task<List<RegionManageEntryResponse>> GetManageEntriesAsync()
+    {
+        var regionNames = (await repo.GetAllAsync()).ToDictionary(r => r.Id, r => r.Name);
+        string RegionName(Guid id) => regionNames.TryGetValue(id, out var name) ? name : "Unknown";
+
+        var entries = new List<RegionManageEntryResponse>();
+
+        entries.AddRange((await repo.GetAllTargetsAsync()).Select(t =>
+            new RegionManageEntryResponse(t.Id, t.FK_RegionId, RegionName(t.FK_RegionId), RegionManageEntryType.Target, t.Period, t.TargetValue, null, null, t.CreatedAt)));
+
+        entries.AddRange((await repo.GetAllBudgetsAsync()).Select(b =>
+            new RegionManageEntryResponse(b.Id, b.FK_RegionId, RegionName(b.FK_RegionId), RegionManageEntryType.Budget, b.Period, b.BudgetAmount, null, null, b.CreatedAt)));
+
+        entries.AddRange((await repo.GetAllTaxRulesAsync()).Select(r =>
+            new RegionManageEntryResponse(r.Id, r.FK_RegionId, RegionName(r.FK_RegionId), RegionManageEntryType.TaxRule, null, null, r.RuleConfig, null, r.CreatedAt)));
+
+        entries.AddRange((await repo.GetAllAgencyMapsAsync()).Select(m =>
+            new RegionManageEntryResponse(m.Id, m.FK_RegionId, RegionName(m.FK_RegionId), RegionManageEntryType.AgencyMap, null, null, null, m.FK_AgencyUserId, m.CreatedAt)));
+
+        return entries.OrderByDescending(e => e.CreatedAt).ToList();
+    }
+
+    public async Task<bool> DeleteManageEntryAsync(RegionManageEntryType entryType, Guid id, CancellationToken ct = default)
+    {
+        await uow.BeginAsync(ct);
+        try
+        {
+            bool found;
+            switch (entryType)
+            {
+                case RegionManageEntryType.Target:
+                    var target = await repo.GetTargetByIdAsync(id);
+                    found = target is not null;
+                    if (target is not null) repo.RemoveTarget(target);
+                    break;
+                case RegionManageEntryType.Budget:
+                    var budget = await repo.GetBudgetByIdAsync(id);
+                    found = budget is not null;
+                    if (budget is not null) repo.RemoveBudget(budget);
+                    break;
+                case RegionManageEntryType.TaxRule:
+                    var rule = await repo.GetTaxRuleByIdAsync(id);
+                    found = rule is not null;
+                    if (rule is not null) repo.RemoveTaxRule(rule);
+                    break;
+                case RegionManageEntryType.AgencyMap:
+                    var map = await repo.GetAgencyMapByIdAsync(id);
+                    found = map is not null;
+                    if (map is not null) repo.RemoveAgencyMap(map);
+                    break;
+                default:
+                    found = false;
+                    break;
+            }
+
+            if (!found)
+            {
+                await uow.RollbackAsync(ct);
+                return false;
+            }
+
+            await uow.CommitAsync(ct);
+            return true;
+        }
+        catch
+        {
+            await uow.RollbackAsync(ct);
+            throw;
+        }
     }
 }

Distribution/docs/10_region_management.md

@@ -50,29 +50,39 @@ it's stored for a future pricing-rule integration.
 | Function reference | Endpoint | Status |
 |---|---|---|
 | `assignAreaToRegion(areaId, regionId)` | — | Blocked — no `Area` entity exists (see [00_existing_gaps.md](./00_existing_gaps.md#9-no-area-entity-between-region-and-route)). Stand-in: `PUT /api/routes/{id}/region` assigns/reassigns an existing route directly to a region (see [11_route_sales_management.md](./11_route_sales_management.md)). |
-| `setRegionalTarget(regionId, period, targetValue)` | `PUT /api/regions/{id}/targets/{period}` | Implemented |
+| `setRegionalTarget(regionId, period, targetValue)` | `PUT /api/regions/{id}/manage` (consolidated, see below) | Implemented |
-| `setRegionalBudget(regionId, period, budgetAmount)` | `PUT /api/regions/{id}/budgets/{period}` | Implemented |
+| `setRegionalBudget(regionId, period, budgetAmount)` | `PUT /api/regions/{id}/manage` (consolidated, see below) | Implemented |
-| `mapAgencyToRegion(agencyId, regionId)` | `POST /api/regions/{id}/agencies` | Implemented |
+| `mapAgencyToRegion(agencyId, regionId)` | `PUT /api/regions/{id}/manage` (consolidated, see below) | Implemented |
-| `setRegionalTaxRule(regionId, ruleConfig)` | `PUT /api/regions/{id}/tax-rule` | Implemented |
+| `setRegionalTaxRule(regionId, ruleConfig)` | `PUT /api/regions/{id}/manage` (consolidated, see below) | Implemented |
 | `getRegionHierarchy(regionId)` | `GET /api/regions/{id}/hierarchy` | Implemented (region → routes → store ids; no `Area` level) |
 | `getRegionDashboard(regionId, period)` | `GET /api/regions/{id}/dashboard?period=...` | Implemented (real-time aggregation; see Open Questions, resolved) |
 
 All request/response DTOs live in `Features/Region/RegionDTOs.cs`; routing and access checks are
 in `RegionController.cs` and `RegionService.cs`.
 
+The four `set*`/`mapAgencyToRegion` actions above were later consolidated into a single
+`PUT /api/regions/{id}/manage` endpoint (`RegionService.ManageAsync`) — every field on the request
+is optional, and only the sub-action(s) whose fields are present get applied, so one call can
+update just one thing (as the frontend's `region-manage-sheet.tsx` does, one button per field) or
+several at once. See [BACKEND_API_REFERENCE.md §6.5](../../sharedDocs/BACKEND_API_REFERENCE.md#65-regions)
+for the exact request/response shape.
+
 ---
 
 ## Business Rules
 
-- Only `RegionalManager` and above (per role level in `Data/Seed/RoleAndPermissionSeed.cs`) can
+- ⚠️ **Temporarily disabled**: `RegionService.CanManageRegionAsync` (the gate on `ManageAsync`) was
-  set targets/budgets/tax-rule for their own region; only `RegionalAgency` can set them across
+  stubbed to always return `true` — role-based restriction is deliberately deferred pending a
-  regions. Implemented via `RegionService.CanManageRegionAsync`: role level ≥ 60 (`RegionalAgency`)
+  decision on the role model for this endpoint (tracked as a `TODO` in `RegionService.cs`). The
-  is allowed unconditionally, role level ≥ 50 (`RegionalManager`) requires a matching
+  design below is what it enforced before being stubbed out, and what it should return to:
-  `UserRegionScope` row for that region, anything lower is rejected. The same gate is applied to
+  - Only `RegionalManager` and above (per role level in `Data/Seed/RoleAndPermissionSeed.cs`) can
-  `mapAgencyToRegion`.
+    set targets/budgets/tax-rule for their own region; only `RegionalAgency` can set them across
-- `mapAgencyToRegion` additionally rejects the target user if their role level is below the
+    regions. Role level ≥ 60 (`RegionalAgency`) allowed unconditionally, role level ≥ 50
-  `RegionalAgency` threshold (60) — you can only map a user who actually holds (or outranks) that
+    (`RegionalManager`) requires a matching `UserRegionScope` row for that region, anything lower
-  role.
+    rejected.
+- `agencyUserId` (when supplied to `manage`) still rejects the target user if their role level is
+  below the `RegionalAgency` threshold (60) — you can only map a user who actually holds (or
+  outranks) that role. This check was not part of the disabled gate and remains active.
 
 ---
 

Distribution/docs/mainPlan.md

@@ -117,10 +117,10 @@ here — see `SRS_User_Management_Module.pdf`.
 |---|---|---|
 | `createRegion(name, boundaries)` | Creates a new region record. | Partially implemented — `RegionController` supports create with `Name` only, no `boundaries` field. |
 | `assignAreaToRegion(areaId, regionId)` | Links an existing area under a region. | Not implemented — no `Area` entity exists in the schema (see [00_existing_gaps.md](./00_existing_gaps.md#9-no-area-entity-between-region-and-route)). As a stand-in, a route (the next tier down) can be assigned/reassigned to a region directly via `PUT /api/routes/{id}/region`. |
-| `setRegionalTarget(regionId, period, targetValue)` | Sets the sales target for a region for a given period. | Implemented — `PUT /api/regions/{id}/targets/{period}`, backed by the `RegionalTarget` entity. Restricted to `RegionalManager`+ with region scope, or `RegionalAgency` across any region. |
+| `setRegionalTarget(regionId, period, targetValue)` | Sets the sales target for a region for a given period. | Implemented — `PUT /api/regions/{id}/manage` (consolidated with the three rows below), backed by the `RegionalTarget` entity. Role-level restriction (`RegionalManager`+ with region scope, or `RegionalAgency` across any region) is temporarily disabled — see `10_region_management.md`. |
-| `setRegionalBudget(regionId, period, budgetAmount)` | Allocates budget at the regional level. | Implemented — `PUT /api/regions/{id}/budgets/{period}`, backed by the `RegionalBudget` entity. Same access rule as `setRegionalTarget`. |
+| `setRegionalBudget(regionId, period, budgetAmount)` | Allocates budget at the regional level. | Implemented — `PUT /api/regions/{id}/manage` (consolidated), backed by the `RegionalBudget` entity. Same endpoint/access note as `setRegionalTarget`. |
-| `mapAgencyToRegion(agencyId, regionId)` | Assigns a Regional Agency's contract scope to a region. | Implemented — `POST /api/regions/{id}/agencies`, backed by the `RegionAgencyMap` entity. `RegionalAgency` is still a `Role`, not a distinct agency entity — `agencyId` is the `Guid` of an existing `User` holding that role (consistent with `Claim.FK_AgencyUserId`, §18); the endpoint rejects a user who doesn't hold the role. |
+| `mapAgencyToRegion(agencyId, regionId)` | Assigns a Regional Agency's contract scope to a region. | Implemented — `PUT /api/regions/{id}/manage` (consolidated), backed by the `RegionAgencyMap` entity. `RegionalAgency` is still a `Role`, not a distinct agency entity — `agencyId` is the `Guid` of an existing `User` holding that role (consistent with `Claim.FK_AgencyUserId`, §18); the endpoint rejects a user who doesn't hold the role (this check remains active even with the role gate disabled). |
-| `setRegionalTaxRule(regionId, ruleConfig)` | Overrides tax/pricing rules for a specific region. | Implemented — `PUT /api/regions/{id}/tax-rule`, backed by the `RegionalTaxRule` entity (`RuleConfig` stored as a raw JSON string, not yet consumed by pricing/tax logic elsewhere). |
+| `setRegionalTaxRule(regionId, ruleConfig)` | Overrides tax/pricing rules for a specific region. | Implemented — `PUT /api/regions/{id}/manage` (consolidated), backed by the `RegionalTaxRule` entity (`RuleConfig` stored as a raw JSON string, not yet consumed by pricing/tax logic elsewhere). |
 | `getRegionHierarchy(regionId)` | Returns all areas/territories nested under a region. | Partially implemented — `GET /api/regions/{id}/hierarchy` returns the region's routes and each route's store ids; no `Area` level since that entity doesn't exist yet. |
 | `getRegionDashboard(regionId, period)` | Aggregated KPIs: sales, fill rate, agency performance for the region. | Partially implemented — `GET /api/regions/{id}/dashboard?period=...` returns real-time order count, actual sales, target, and budget for the period; no fill-rate or agency-performance metrics yet. |
 

distribution_fe/app/(dashboard)/network/region-manage/_components/region-manage-entry-sheet.tsx

@@ -0,0 +1,265 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useForm, zodResolver, z } from '@/lib/form'
+import { FormField } from '@/components/shared/form-field'
+import { Input } from '@/components/ui/input'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import { Button } from '@/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+} from '@/components/ui/dialog'
+import { FieldGroup } from '@/components/ui/field'
+import { Separator } from '@/components/ui/separator'
+import { toast } from '@/components/ui/toast'
+import { regions as regionsApi, users as usersApi, getApiError, getPaginatedItems } from '@/lib/api/index'
+import type { RegionResponse, UserResponse } from '@/types/api'
+
+function currentPeriod() {
+  const now = new Date()
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`
+}
+
+const schema = z.object({
+  regionId: z.string().min(1, 'Region is required'),
+  period: z.string(),
+  targetValue: z.string(),
+  budgetAmount: z.string(),
+  ruleConfig: z.string(),
+  agencyUserId: z.string(),
+})
+
+type FormValues = z.infer<typeof schema>
+
+export interface RegionManageInitialValues {
+  regionId: string
+  period?: string
+  targetValue?: number
+  budgetAmount?: number
+  ruleConfig?: string
+  agencyUserId?: string
+}
+
+interface RegionManageEntrySheetProps {
+  open: boolean
+  onClose: () => void
+  onSuccess: () => void
+  initial?: RegionManageInitialValues | null
+}
+
+export function RegionManageEntrySheet({ open, onClose, onSuccess, initial }: RegionManageEntrySheetProps) {
+  const [regionsList, setRegionsList] = useState<RegionResponse[]>([])
+  const [agencyUsers, setAgencyUsers] = useState<UserResponse[]>([])
+  const isEdit = !!initial
+
+  const form = useForm<FormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: {
+      regionId: '',
+      period: currentPeriod(),
+      targetValue: '',
+      budgetAmount: '',
+      ruleConfig: '',
+      agencyUserId: '',
+    },
+  })
+
+  useEffect(() => {
+    if (!open) return
+
+    form.reset({
+      regionId: initial?.regionId ?? '',
+      period: initial?.period ?? currentPeriod(),
+      targetValue: initial?.targetValue != null ? String(initial.targetValue) : '',
+      budgetAmount: initial?.budgetAmount != null ? String(initial.budgetAmount) : '',
+      ruleConfig: initial?.ruleConfig ?? '',
+      agencyUserId: initial?.agencyUserId ?? '',
+    })
+
+    Promise.all([
+      regionsApi.list({ page: 1, pageSize: 200 }),
+      usersApi.list({ page: 1, pageSize: 200 }),
+    ])
+      .then(([r, u]) => {
+        setRegionsList(getPaginatedItems(r).filter((x) => x.isActive))
+        setAgencyUsers(getPaginatedItems(u).filter((x) => x.roleName === 'RegionalAgency'))
+      })
+      .catch((err) => toast.add({ title: 'Failed to load reference data', description: getApiError(err), type: 'error' }))
+  }, [open, initial])
+
+  async function onSubmit(values: FormValues) {
+    const body: {
+      period?: string
+      targetValue?: number
+      budgetAmount?: number
+      agencyUserId?: string
+      ruleConfig?: string
+    } = {}
+
+    const target = values.targetValue.trim() ? parseFloat(values.targetValue) : NaN
+    const budget = values.budgetAmount.trim() ? parseFloat(values.budgetAmount) : NaN
+    if (!Number.isNaN(target)) {
+      body.period = values.period
+      body.targetValue = target
+    }
+    if (!Number.isNaN(budget)) {
+      body.period = values.period
+      body.budgetAmount = budget
+    }
+    if (values.ruleConfig.trim()) body.ruleConfig = values.ruleConfig
+    if (values.agencyUserId) body.agencyUserId = values.agencyUserId
+
+    if (Object.keys(body).length === 0) {
+      toast.add({ title: 'Nothing to save', description: 'Fill in at least one field.', type: 'error' })
+      return
+    }
+
+    try {
+      await regionsApi.manage(values.regionId, body)
+      toast.add({ title: isEdit ? 'Region settings updated' : 'Entry saved', type: 'success' })
+      onSuccess()
+      onClose()
+    } catch (err) {
+      toast.add({ title: 'Failed to save entry', description: getApiError(err), type: 'error' })
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={(v) => !v && onClose()}>
+      <DialogContent className="overflow-y-auto sm:max-w-lg">
+        <DialogHeader>
+          <DialogTitle>{isEdit ? 'Edit Manage Entry' : 'Add Manage Entry'}</DialogTitle>
+        </DialogHeader>
+
+        <form onSubmit={form.handleSubmit(onSubmit)} className="flex flex-col gap-6">
+          <FieldGroup>
+            <FormField
+              control={form.control}
+              name="regionId"
+              label="Region"
+              required
+              render={({ field, invalid }) => (
+                <Select value={field.value as string} onValueChange={field.onChange} disabled={isEdit}>
+                  <SelectTrigger aria-invalid={invalid}>
+                    <SelectValue placeholder="Select a region">
+                      {regionsList.find((r) => r.id === field.value)?.name}
+                    </SelectValue>
+                  </SelectTrigger>
+                  <SelectContent>
+                    {regionsList.map((r) => (
+                      <SelectItem key={r.id} value={r.id}>{r.name}</SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              )}
+            />
+
+            <FormField
+              control={form.control}
+              name="period"
+              label="Period"
+              render={({ field }) => (
+                <Input
+                  type="month"
+                  value={field.value as string}
+                  onChange={field.onChange}
+                  className="w-40"
+                />
+              )}
+            />
+
+            <Separator />
+
+            <FormField
+              control={form.control}
+              name="targetValue"
+              label="Regional Target"
+              render={({ field }) => (
+                <Input
+                  type="number"
+                  value={field.value as string}
+                  onChange={field.onChange}
+                  placeholder="e.g. 500000"
+                />
+              )}
+            />
+
+            <FormField
+              control={form.control}
+              name="budgetAmount"
+              label="Regional Budget"
+              render={({ field }) => (
+                <Input
+                  type="number"
+                  value={field.value as string}
+                  onChange={field.onChange}
+                  placeholder="e.g. 200000"
+                />
+              )}
+            />
+
+            <Separator />
+
+            <FormField
+              control={form.control}
+              name="ruleConfig"
+              label="Regional Rule Config"
+              render={({ field }) => (
+                <Input
+                  value={field.value as string}
+                  onChange={field.onChange}
+                  placeholder='0.15'
+                />
+              )}
+            />
+
+            <Separator />
+
+            <FormField
+              control={form.control}
+              name="agencyUserId"
+              label="Map Regional Agency"
+              render={({ field }) => (
+                <Select value={field.value as string} onValueChange={field.onChange}>
+                  <SelectTrigger>
+                    <SelectValue placeholder="Select an agency user">
+                      {agencyUsers.find((u) => u.id === field.value)?.fullName}
+                    </SelectValue>
+                  </SelectTrigger>
+                  <SelectContent>
+                    {agencyUsers.map((u) => (
+                      <SelectItem key={u.id} value={u.id}>{u.fullName}</SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              )}
+            />
+            {agencyUsers.length === 0 && (
+              <p className="text-xs text-muted-foreground">No users with the RegionalAgency role found.</p>
+            )}
+          </FieldGroup>
+
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={onClose}>
+              Cancel
+            </Button>
+            <Button type="submit" disabled={form.formState.isSubmitting}>
+              {form.formState.isSubmitting ? 'Saving…' : 'Save'}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  )
+}

distribution_fe/app/(dashboard)/network/region-manage/_components/region-manage-list-client.tsx

@@ -0,0 +1,218 @@
+'use client'
+
+import { useState, useEffect, useCallback, useMemo } from 'react'
+import { HugeiconsIcon } from '@hugeicons/react'
+import { Add01Icon } from '@hugeicons/core-free-icons'
+
+import { DataTable } from '@/components/shared/data-table'
+import type { TableConfig } from '@/components/shared/data-table'
+import { Button } from '@/components/ui/button'
+import { toast } from '@/components/ui/toast'
+import { regions as regionsApi, users as usersApi, getApiError, getPaginatedItems } from '@/lib/api/index'
+import type { RegionManageEntryResponse, UserResponse } from '@/types/api'
+
+import { RegionManageEntrySheet, type RegionManageInitialValues } from './region-manage-entry-sheet'
+
+interface RegionManageRow {
+  regionId: string
+  regionName: string
+  period: string | null
+  targetValue: number | null
+  budgetAmount: number | null
+  ruleConfig: string | null
+  agencyUserIds: string[]
+  entries: RegionManageEntryResponse[]
+}
+
+function groupByRegion(entries: RegionManageEntryResponse[]): RegionManageRow[] {
+  const byRegion = new Map<string, RegionManageEntryResponse[]>()
+  for (const e of entries) {
+    const list = byRegion.get(e.regionId) ?? []
+    list.push(e)
+    byRegion.set(e.regionId, list)
+  }
+
+  const latestOf = (list: RegionManageEntryResponse[], type: RegionManageEntryResponse['entryType']) =>
+    list
+      .filter((e) => e.entryType === type)
+      .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())[0]
+
+  return Array.from(byRegion.entries()).map(([regionId, list]) => {
+    const target = latestOf(list, 'Target')
+    const budget = latestOf(list, 'Budget')
+    const taxRule = latestOf(list, 'TaxRule')
+    const agencyMaps = list.filter((e) => e.entryType === 'AgencyMap')
+
+    return {
+      regionId,
+      regionName: list[0].regionName,
+      period: target?.period ?? budget?.period ?? null,
+      targetValue: target?.amount ?? null,
+      budgetAmount: budget?.amount ?? null,
+      ruleConfig: taxRule?.ruleConfig ?? null,
+      agencyUserIds: agencyMaps.map((m) => m.agencyUserId).filter((id): id is string => !!id),
+      entries: list,
+    }
+  })
+}
+
+export function RegionManageListClient() {
+  const [entries, setEntries] = useState<RegionManageEntryResponse[]>([])
+  const [loading, setLoading] = useState(true)
+  const [agencyUsers, setAgencyUsers] = useState<UserResponse[]>([])
+
+  const [sheetOpen, setSheetOpen] = useState(false)
+  const [editingInitial, setEditingInitial] = useState<RegionManageInitialValues | null>(null)
+
+  const fetchData = useCallback(async () => {
+    setLoading(true)
+    try {
+      const res = await regionsApi.manageEntries()
+      setEntries(res)
+    } catch (err) {
+      toast.add({ title: 'Failed to load manage entries', description: getApiError(err), type: 'error' })
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    fetchData()
+  }, [fetchData])
+
+  useEffect(() => {
+    usersApi.list({ page: 1, pageSize: 200 })
+      .then((res) => setAgencyUsers(getPaginatedItems(res)))
+      .catch(() => toast.add({ title: 'Failed to load users', type: 'error' }))
+  }, [])
+
+  const rows = useMemo(() => groupByRegion(entries), [entries])
+
+  function openAdd() {
+    setEditingInitial(null)
+    setSheetOpen(true)
+  }
+
+  function openEdit(row: RegionManageRow) {
+    setEditingInitial({
+      regionId: row.regionId,
+      period: row.period ?? undefined,
+      targetValue: row.targetValue ?? undefined,
+      budgetAmount: row.budgetAmount ?? undefined,
+      ruleConfig: row.ruleConfig ?? undefined,
+      agencyUserId: row.agencyUserIds[0] ?? undefined,
+    })
+    setSheetOpen(true)
+  }
+
+  async function handleClear(row: RegionManageRow) {
+    try {
+      await Promise.all(
+        row.entries.map((e) => regionsApi.removeManageEntry(e.entryType, e.id))
+      )
+      toast.add({ title: 'Region settings cleared', type: 'success' })
+      fetchData()
+    } catch (err) {
+      toast.add({ title: 'Failed to clear settings', description: getApiError(err), type: 'error' })
+    }
+  }
+
+  const tableConfig = useMemo<TableConfig<RegionManageRow>>(() => ({
+    rowKey: 'regionId',
+    stickyHeader: true,
+    emptyMessage: 'No manage entries yet. Add one to get started.',
+    pagination: { enabled: true, pageSize: 20, pageSizeOptions: [10, 20, 50] },
+    columns: [
+      {
+        key: 'regionName',
+        title: 'Region',
+        fields: [{ key: 'regionName', primary: true }],
+        minWidth: 160,
+      },
+      {
+        key: 'period',
+        title: 'Period',
+        fields: ['period'],
+        width: 100,
+        cellRender: (row) => row.period ?? '—',
+      },
+      {
+        key: 'targetValue',
+        title: 'Regional Target',
+        fields: ['targetValue'],
+        width: 140,
+        cellRender: (row) => row.targetValue ?? '—',
+      },
+      {
+        key: 'budgetAmount',
+        title: 'Regional Budget',
+        fields: ['budgetAmount'],
+        width: 140,
+        cellRender: (row) => row.budgetAmount ?? '—',
+      },
+      {
+        key: 'ruleConfig',
+        title: 'Regional Rule Config',
+        fields: ['ruleConfig'],
+        minWidth: 180,
+        cellRender: (row) => row.ruleConfig ?? '—',
+      },
+      {
+        key: 'agencyUserIds',
+        title: 'Map Regional Agency',
+        fields: ['agencyUserIds'],
+        minWidth: 180,
+        cellRender: (row) => {
+          if (row.agencyUserIds.length === 0) return '—'
+          return row.agencyUserIds
+            .map((id) => agencyUsers.find((u) => u.id === id)?.fullName ?? id)
+            .join(', ')
+        },
+      },
+    ],
+    rowActions: {
+      actions: () => [
+        {
+          action: 'edit',
+          label: 'Edit region settings',
+          onClick: openEdit,
+        },
+        {
+          action: 'deactivate',
+          label: 'Clear region settings',
+          onClick: handleClear,
+        },
+      ],
+    },
+  }), [agencyUsers])
+
+  return (
+    <>
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-2xl font-semibold text-foreground">Region Manage</h1>
+          <p className="text-sm text-muted-foreground mt-0.5">
+            Targets, budgets, tax rules, and agency mappings across regions
+          </p>
+        </div>
+        <Button onClick={openAdd}>
+          <HugeiconsIcon icon={Add01Icon} size={16} />
+          Add Entry
+        </Button>
+      </div>
+
+      <DataTable
+        config={tableConfig}
+        data={rows}
+        loading={loading}
+      />
+
+      <RegionManageEntrySheet
+        open={sheetOpen}
+        onClose={() => setSheetOpen(false)}
+        onSuccess={fetchData}
+        initial={editingInitial}
+      />
+    </>
+  )
+}

distribution_fe/app/(dashboard)/network/region-manage/page.tsx

@@ -0,0 +1,5 @@
+import { RegionManageListClient } from './_components/region-manage-list-client'
+
+export default function RegionManagePage() {
+  return <RegionManageListClient />
+}

distribution_fe/app/(dashboard)/network/regions/_components/region-manage-sheet.tsx

@@ -1,276 +0,0 @@
-'use client'
-
-import { useEffect, useState } from 'react'
-
-import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
-import { Label } from '@/components/ui/label'
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select'
-import {
-  Dialog,
-  DialogContent,
-  DialogHeader,
-  DialogTitle,
-  DialogDescription,
-} from '@/components/ui/dialog'
-import { Separator } from '@/components/ui/separator'
-import { toast } from '@/components/ui/toast'
-import { regions as regionsApi, users as usersApi, getApiError, getPaginatedItems } from '@/lib/api/index'
-import type {
-  RegionResponse,
-  UserResponse,
-  RegionDashboardResponse,
-  RegionHierarchyResponse,
-} from '@/types/api'
-
-interface RegionManageSheetProps {
-  open: boolean
-  onClose: () => void
-  region: RegionResponse | null
-}
-
-function currentPeriod() {
-  const now = new Date()
-  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`
-}
-
-export function RegionManageSheet({ open, onClose, region }: RegionManageSheetProps) {
-  const [period, setPeriod] = useState(currentPeriod())
-  const [targetValue, setTargetValue] = useState('')
-  const [budgetAmount, setBudgetAmount] = useState('')
-  const [ruleConfig, setRuleConfig] = useState('')
-  const [agencyUserId, setAgencyUserId] = useState('')
-  const [agencyUsers, setAgencyUsers] = useState<UserResponse[]>([])
-  const [dashboard, setDashboard] = useState<RegionDashboardResponse | null>(null)
-  const [hierarchy, setHierarchy] = useState<RegionHierarchyResponse | null>(null)
-  const [saving, setSaving] = useState<string | null>(null)
-
-  useEffect(() => {
-    if (!open || !region) return
-
-    setPeriod(currentPeriod())
-    setTargetValue('')
-    setBudgetAmount('')
-    setRuleConfig('')
-    setAgencyUserId('')
-
-    usersApi.list({ page: 1, pageSize: 200 })
-      .then((res) => setAgencyUsers(getPaginatedItems(res).filter((u) => u.roleName === 'RegionalAgency')))
-      .catch(() => toast.add({ title: 'Failed to load agency users', type: 'error' }))
-
-    regionsApi.hierarchy(region.id)
-      .then(setHierarchy)
-      .catch(() => toast.add({ title: 'Failed to load hierarchy', type: 'error' }))
-  }, [open, region])
-
-  useEffect(() => {
-    if (!open || !region) return
-    regionsApi.dashboard(region.id, period)
-      .then(setDashboard)
-      .catch(() => toast.add({ title: 'Failed to load dashboard', type: 'error' }))
-  }, [open, region, period])
-
-  if (!region) return null
-
-  async function handleSetTarget() {
-    const value = parseFloat(targetValue)
-    if (Number.isNaN(value)) return
-    setSaving('target')
-    try {
-      await regionsApi.setTarget(region!.id, period, value)
-      toast.add({ title: 'Target updated', type: 'success' })
-      regionsApi.dashboard(region!.id, period).then(setDashboard)
-    } catch (err) {
-      toast.add({ title: 'Failed to set target', description: getApiError(err), type: 'error' })
-    } finally {
-      setSaving(null)
-    }
-  }
-
-  async function handleSetBudget() {
-    const value = parseFloat(budgetAmount)
-    if (Number.isNaN(value)) return
-    setSaving('budget')
-    try {
-      await regionsApi.setBudget(region!.id, period, value)
-      toast.add({ title: 'Budget updated', type: 'success' })
-      regionsApi.dashboard(region!.id, period).then(setDashboard)
-    } catch (err) {
-      toast.add({ title: 'Failed to set budget', description: getApiError(err), type: 'error' })
-    } finally {
-      setSaving(null)
-    }
-  }
-
-  async function handleSetTaxRule() {
-    if (!ruleConfig.trim()) return
-    setSaving('tax-rule')
-    try {
-      await regionsApi.setTaxRule(region!.id, ruleConfig)
-      toast.add({ title: 'Tax rule updated', type: 'success' })
-    } catch (err) {
-      toast.add({ title: 'Failed to set tax rule', description: getApiError(err), type: 'error' })
-    } finally {
-      setSaving(null)
-    }
-  }
-
-  async function handleMapAgency() {
-    if (!agencyUserId) return
-    setSaving('agency')
-    try {
-      await regionsApi.mapAgency(region!.id, agencyUserId)
-      toast.add({ title: 'Agency mapped to region', type: 'success' })
-      setAgencyUserId('')
-    } catch (err) {
-      toast.add({ title: 'Failed to map agency', description: getApiError(err), type: 'error' })
-    } finally {
-      setSaving(null)
-    }
-  }
-
-  return (
-    <Dialog open={open} onOpenChange={(v) => !v && onClose()}>
-      <DialogContent className="overflow-y-auto sm:max-w-xl">
-        <DialogHeader>
-          <DialogTitle>Manage {region.name}</DialogTitle>
-          <DialogDescription>
-            Targets, budgets, tax rules, agency mapping, and dashboard for this region.
-          </DialogDescription>
-        </DialogHeader>
-
-        <div className="flex flex-col gap-6">
-          <div className="flex flex-col gap-2">
-            <Label htmlFor="period">Period</Label>
-            <Input
-              id="period"
-              type="month"
-              value={period}
-              onChange={(e) => setPeriod(e.target.value)}
-              className="w-40"
-            />
-          </div>
-
-          <Separator />
-
-          <div className="flex flex-col gap-2">
-            <Label>Regional Target</Label>
-            <div className="flex gap-2">
-              <Input
-                type="number"
-                placeholder="e.g. 500000"
-                value={targetValue}
-                onChange={(e) => setTargetValue(e.target.value)}
-              />
-              <Button type="button" onClick={handleSetTarget} disabled={saving === 'target'}>
-                {saving === 'target' ? 'Saving…' : 'Set Target'}
-              </Button>
-            </div>
-            {dashboard?.targetValue != null && (
-              <p className="text-xs text-muted-foreground">Current: {dashboard.targetValue}</p>
-            )}
-          </div>
-
-          <div className="flex flex-col gap-2">
-            <Label>Regional Budget</Label>
-            <div className="flex gap-2">
-              <Input
-                type="number"
-                placeholder="e.g. 200000"
-                value={budgetAmount}
-                onChange={(e) => setBudgetAmount(e.target.value)}
-              />
-              <Button type="button" onClick={handleSetBudget} disabled={saving === 'budget'}>
-                {saving === 'budget' ? 'Saving…' : 'Set Budget'}
-              </Button>
-            </div>
-            {dashboard?.budgetAmount != null && (
-              <p className="text-xs text-muted-foreground">Current: {dashboard.budgetAmount}</p>
-            )}
-          </div>
-
-          <Separator />
-
-          <div className="flex flex-col gap-2">
-            <Label>Tax Rule Config (JSON)</Label>
-            <div className="flex gap-2">
-              <Input
-                placeholder='e.g. {"rate": 0.15}'
-                value={ruleConfig}
-                onChange={(e) => setRuleConfig(e.target.value)}
-              />
-              <Button type="button" onClick={handleSetTaxRule} disabled={saving === 'tax-rule'}>
-                {saving === 'tax-rule' ? 'Saving…' : 'Save'}
-              </Button>
-            </div>
-          </div>
-
-          <Separator />
-
-          <div className="flex flex-col gap-2">
-            <Label>Map Regional Agency</Label>
-            <div className="flex gap-2">
-              <Select value={agencyUserId} onValueChange={(v) => setAgencyUserId(v ?? '')}>
-                <SelectTrigger>
-                  <SelectValue placeholder="Select an agency user">
-                    {agencyUsers.find((u) => u.id === agencyUserId)?.fullName}
-                  </SelectValue>
-                </SelectTrigger>
-                <SelectContent>
-                  {agencyUsers.map((u) => (
-                    <SelectItem key={u.id} value={u.id}>{u.fullName}</SelectItem>
-                  ))}
-                </SelectContent>
-              </Select>
-              <Button type="button" onClick={handleMapAgency} disabled={saving === 'agency'}>
-                {saving === 'agency' ? 'Saving…' : 'Map'}
-              </Button>
-            </div>
-            {agencyUsers.length === 0 && (
-              <p className="text-xs text-muted-foreground">No users with the RegionalAgency role found.</p>
-            )}
-          </div>
-
-          <Separator />
-
-          <div className="flex flex-col gap-2">
-            <Label>Hierarchy</Label>
-            {hierarchy && hierarchy.routes.length > 0 ? (
-              <ul className="text-sm space-y-1">
-                {hierarchy.routes.map((r) => (
-                  <li key={r.routeId}>
-                    {r.routeName} — {r.storeIds.length} store{r.storeIds.length === 1 ? '' : 's'}
-                  </li>
-                ))}
-              </ul>
-            ) : (
-              <p className="text-xs text-muted-foreground">No routes under this region yet.</p>
-            )}
-          </div>
-
-          <Separator />
-
-          <div className="flex flex-col gap-2">
-            <Label>Dashboard ({period})</Label>
-            {dashboard ? (
-              <div className="grid grid-cols-2 gap-2 text-sm">
-                <div>Orders: {dashboard.orderCount}</div>
-                <div>Actual Sales: {dashboard.actualSales}</div>
-                <div>Target: {dashboard.targetValue ?? '—'}</div>
-                <div>Budget: {dashboard.budgetAmount ?? '—'}</div>
-              </div>
-            ) : (
-              <p className="text-xs text-muted-foreground">Loading dashboard…</p>
-            )}
-          </div>
-        </div>
-      </DialogContent>
-    </Dialog>
-  )
-}

distribution_fe/app/(dashboard)/network/regions/_components/regions-client.tsx

@@ -13,7 +13,6 @@ import { regions as regionsApi, getApiError, getPaginatedItems } from '@/lib/api
 import type { RegionResponse } from '@/types/api'
 
 import { RegionSheet } from './region-sheet'
-import { RegionManageSheet } from './region-manage-sheet'
 
 export function RegionsClient() {
   const [data, setData] = useState<RegionResponse[]>([])
@@ -25,9 +24,6 @@ export function RegionsClient() {
   const [sheetOpen, setSheetOpen] = useState(false)
   const [editing, setEditing] = useState<RegionResponse | null>(null)
 
-  const [manageOpen, setManageOpen] = useState(false)
-  const [managing, setManaging] = useState<RegionResponse | null>(null)
-
   const fetchData = useCallback(async (p: number, ps: number) => {
     setLoading(true)
     try {
@@ -55,11 +51,6 @@ export function RegionsClient() {
     setSheetOpen(true)
   }
 
-  function openManage(region: RegionResponse) {
-    setManaging(region)
-    setManageOpen(true)
-  }
-
   async function toggleActive(region: RegionResponse) {
     try {
       await regionsApi.update(region.id, { isActive: !region.isActive })
@@ -112,11 +103,6 @@ export function RegionsClient() {
     ],
     rowActions: {
       actions: () => [
-        {
-          action: 'confirm',
-          label: 'Manage targets, budgets & agencies',
-          onClick: openManage,
-        },
         {
           action: 'edit',
           label: 'Edit region',
@@ -136,7 +122,7 @@ export function RegionsClient() {
         },
       ],
     },
-  }), [pageSize, openEdit, openManage, toggleActive])
+  }), [pageSize, openEdit, toggleActive])
 
   return (
     <>
@@ -170,12 +156,6 @@ export function RegionsClient() {
         region={editing}
         onSuccess={() => fetchData(page, pageSize)}
       />
-
-      <RegionManageSheet
-        open={manageOpen}
-        onClose={() => setManageOpen(false)}
-        region={managing}
-      />
     </>
   )
 }

distribution_fe/config/nav.ts

@@ -138,6 +138,7 @@ export const NAV_GROUPS: NavGroup[] = [
     icon: Building02Icon,
     items: [
       { title: 'Regions', href: '/network/regions', icon: Location01Icon, description: 'Geographic territories the distribution network operates in', permission: 'regions.view' },
+      { title: 'Region Manage', href: '/network/region-manage', icon: ClipboardListIcon, description: 'Targets, budgets, tax rules, and agency mapping per region', permission: 'regions.view' },
       { title: 'Routes', href: '/network/routes', icon: Route01Icon, description: 'Delivery paths within a region that rides are assigned to', permission: 'routes.view' },
       { title: 'Vehicles', href: '/network/vehicles', icon: Car01Icon, description: 'Fleet vehicles available for delivery rides', permission: 'vehicles.view' },
       { title: 'Warehouses', href: '/network/warehouses', icon: Building02Icon, description: 'Storage locations where stock is held and loaded from', permission: 'warehouses.view' },

distribution_fe/lib/api/master.ts

@@ -2,12 +2,11 @@ import { api } from '@/lib/api'
 import type {
   PaginatedResponse,
   RegionResponse,
-  RegionalTargetResponse,
+  ManageRegionResponse,
-  RegionalBudgetResponse,
-  RegionAgencyMapResponse,
-  RegionalTaxRuleResponse,
   RegionHierarchyResponse,
   RegionDashboardResponse,
+  RegionManageEntryResponse,
+  RegionManageEntryType,
   RouteResponse,
   RouteVisitResponse,
   VehicleResponse,
@@ -104,17 +103,18 @@ export const regions = {
   remove: (id: string) =>
     api.delete(`/regions/${id}`),
 
-  setTarget: (id: string, period: string, targetValue: number) =>
+  // Consolidated replacement for the old separate setTarget/setBudget/mapAgency/setTaxRule
-    api.put<RegionalTargetResponse>(`/regions/${id}/targets/${period}`, { targetValue }).then(r => r.data),
+  // calls — pass only the fields you want to change (Period is required alongside targetValue
+  // and/or budgetAmount).
+  manage: (id: string, body: { period?: string; targetValue?: number; budgetAmount?: number; agencyUserId?: string; ruleConfig?: string }) =>
+    api.put<ManageRegionResponse>(`/regions/${id}/manage`, body).then(r => r.data),
 
-  setBudget: (id: string, period: string, budgetAmount: number) =>
+  // Flat CRUD-list view over targets/budgets/tax-rules/agency-maps across all regions.
-    api.put<RegionalBudgetResponse>(`/regions/${id}/budgets/${period}`, { budgetAmount }).then(r => r.data),
+  manageEntries: () =>
+    api.get<RegionManageEntryResponse[]>('/regions/manage-entries').then(r => r.data),
 
-  mapAgency: (id: string, agencyUserId: string) =>
+  removeManageEntry: (entryType: RegionManageEntryType, id: string) =>
-    api.post<RegionAgencyMapResponse>(`/regions/${id}/agencies`, { agencyUserId }).then(r => r.data),
+    api.delete(`/regions/manage-entries/${entryType}/${id}`),
-
-  setTaxRule: (id: string, ruleConfig: string) =>
-    api.put<RegionalTaxRuleResponse>(`/regions/${id}/tax-rule`, { ruleConfig }).then(r => r.data),
 
   hierarchy: (id: string) =>
     api.get<RegionHierarchyResponse>(`/regions/${id}/hierarchy`).then(r => r.data),

distribution_fe/types/api.ts

@@ -125,6 +125,14 @@ export interface RegionalTaxRuleResponse {
   ruleConfig: string
 }
 
+export interface ManageRegionResponse {
+  regionId: string
+  target: RegionalTargetResponse | null
+  budget: RegionalBudgetResponse | null
+  agencyMap: RegionAgencyMapResponse | null
+  taxRule: RegionalTaxRuleResponse | null
+}
+
 export interface RegionHierarchyRouteItem {
   routeId: string
   routeName: string
@@ -145,6 +153,22 @@ export interface RegionDashboardResponse {
   orderCount: number
   actualSales: number
   lastOrderDate: string | null
+  taxRuleConfig: string | null
+  agencyUserIds: string[]
+}
+
+export type RegionManageEntryType = 'Target' | 'Budget' | 'TaxRule' | 'AgencyMap'
+
+export interface RegionManageEntryResponse {
+  id: string
+  regionId: string
+  regionName: string
+  entryType: RegionManageEntryType
+  period: string | null
+  amount: number | null
+  ruleConfig: string | null
+  agencyUserId: string | null
+  createdAt: string
 }
 
 // ─── Vehicles / Warehouses ───────────────────────────────────────────────────

sharedDocs/BACKEND_API_REFERENCE.md

@@ -506,54 +506,44 @@ Array of:
 }
 ```
 
-**Beyond CRUD** — targets, budgets, agency mapping, tax rules, hierarchy, and dashboard. These are
+**Beyond CRUD** — manage (targets/budgets/agency mapping/tax rules, consolidated), hierarchy, and
-not gated by the `regions.*` permission codes above; access is checked by role level in
+dashboard. Not gated by the `regions.*` permission codes above.
-`RegionService`: `RegionalManager` (level 50) can act only on a region they have scope over (via
+
-`UserRegionScope`), `RegionalAgency` (level 60) can act on any region.
+> ⚠️ **Authorization temporarily disabled**: `ManageAsync` currently allows any authenticated
+> caller — the previous role-level gate (`RegionalManager`, level 50, scoped via
+> `UserRegionScope`; `RegionalAgency`, level 60, any region) was deliberately stubbed out
+> (`CanManageRegionAsync` always returns `true`) pending a decision on the role model for this
+> endpoint. Re-enabling it is tracked as a TODO in `RegionService.cs`.
 
 | Method | Path | Description |
 |---|---|---|
-| `PUT` | `/api/regions/{id}/targets/{period}` | Set the sales target for a region for a period (`period` = `yyyy-MM`) |
+| `PUT` | `/api/regions/{id}/manage` | Set target/budget/agency-map/tax-rule in one call — replaces the old separate targets/budgets/agencies/tax-rule endpoints |
-| `PUT` | `/api/regions/{id}/budgets/{period}` | Set the budget for a region for a period |
-| `POST` | `/api/regions/{id}/agencies` | Map an existing user (holding the `RegionalAgency` role) to this region |
-| `PUT` | `/api/regions/{id}/tax-rule` | Set/replace the region's tax rule config |
 | `GET` | `/api/regions/{id}/hierarchy` | Region's routes and each route's store ids |
 | `GET` | `/api/regions/{id}/dashboard?period=yyyy-MM` | Real-time order count/sales/target/budget for the period |
 
-**Set target request / response:**
+**Manage request** — every field is optional; only the sub-actions whose fields are present get
+applied, so a caller can update just one thing or several in a single request. `period` is
+required alongside `targetValue` and/or `budgetAmount` (both are silently skipped without it):
 ```json
-// PUT /api/regions/{id}/targets/{period}
+// PUT /api/regions/{id}/manage
-{ "targetValue": 500000 }
+{
-```
+  "period": "2026-08",             // required for targetValue/budgetAmount
-```json
+  "targetValue": 500000,           // optional
-{ "regionId": "guid", "period": "2026-08", "targetValue": 500000 }
+  "budgetAmount": 200000,          // optional
+  "agencyUserId": "guid",          // optional — must be a User with the RegionalAgency role
+  "ruleConfig": "{\"rate\": 0.15}" // optional — arbitrary JSON stored as a string, not yet consumed by pricing
+}
 ```
 
-**Set budget request / response:**
+**Manage response** — each field is `null` if that sub-action wasn't requested:
 ```json
-// PUT /api/regions/{id}/budgets/{period}
+{
-{ "budgetAmount": 200000 }
+  "regionId": "guid",
-```
+  "target": { "regionId": "guid", "period": "2026-08", "targetValue": 500000 } | null,
-```json
+  "budget": { "regionId": "guid", "period": "2026-08", "budgetAmount": 200000 } | null,
-{ "regionId": "guid", "period": "2026-08", "budgetAmount": 200000 }
+  "agencyMap": { "regionId": "guid", "agencyUserId": "guid" } | null,
-```
+  "taxRule": { "regionId": "guid", "ruleConfig": "{\"rate\": 0.15}" } | null
-
+}
-**Map agency request / response:**
-```json
-// POST /api/regions/{id}/agencies
-{ "agencyUserId": "guid" }   // must be a User with the RegionalAgency role
-```
-```json
-{ "regionId": "guid", "agencyUserId": "guid" }
-```
-
-**Set tax rule request / response:**
-```json
-// PUT /api/regions/{id}/tax-rule
-{ "ruleConfig": "{\"rate\": 0.15}" }   // arbitrary JSON stored as a string; not yet consumed by pricing
-```
-```json
-{ "regionId": "guid", "ruleConfig": "{\"rate\": 0.15}" }
 ```
 
 **Hierarchy response:**
@@ -576,13 +566,20 @@ not gated by the `regions.*` permission codes above; access is checked by role l
   "budgetAmount": 200000,      // null if no budget set for the period
   "orderCount": 42,
   "actualSales": 187500.00,
-  "lastOrderDate": "datetime | null"
+  "lastOrderDate": "datetime | null",
+  "taxRuleConfig": "{\"rate\": 0.15}" | null,   // current tax rule, independent of period
+  "agencyUserIds": ["guid", "..."]              // all agency users currently mapped to this region
 }
 ```
+`taxRuleConfig` and `agencyUserIds` are not period-scoped — they reflect current state regardless
+of the `period` query param, added so the frontend's region-manage dialog has something to render
+after calling `manage` (previously the dashboard only echoed back target/budget, leaving tax-rule
+and agency-mapping changes invisible in the UI after saving).
 
-All four of these endpoints return `404` if the region doesn't exist, the caller lacks the
+All three of these endpoints return `404` if the region doesn't exist, or (for `manage`, when
-required region scope, or (for agency mapping) the target user doesn't hold the `RegionalAgency`
+`agencyUserId` is supplied) the target user doesn't hold the `RegionalAgency` role — the response
-role — the response body carries no distinction between "not found" and "forbidden".
+body carries no distinction between "not found" and "invalid agency user". (The former
+"forbidden due to region scope" case doesn't currently apply — see the authorization note above.)
 
 ---