md update

Implemented DeliveryTask, Payment, and Sale entities with full CRUD, business logic, and API endpoints. Updated Order/OrderItem for sale linkage and fulfillment tracking. Registered new DbSets and DI services. Revised documentation for delivery, sale, and payment workflows.

Distribution/Data/AppDBContext.cs

@@ -17,6 +17,7 @@ public class AppDBContext(DbContextOptions<AppDBContext> options) : DbContext(op
     public DbSet<UomConversion> UomConversions { get; set; }
     public DbSet<Item> Items { get; set; }
     public DbSet<SaleRoute> SaleRoutes { get; set; }
+    public DbSet<Sale> Sales { get; set; }
     public DbSet<Order> Orders { get; set; }
     public DbSet<OrderItem> OrderItems { get; set; }
     public DbSet<DeliveryRun> DeliveryRuns { get; set; }
@@ -36,6 +37,19 @@ public class AppDBContext(DbContextOptions<AppDBContext> options) : DbContext(op
     public DbSet<DriverProfile> DriverProfiles { get; set; }
     public DbSet<DriverComplianceConfig> DriverComplianceConfigs { get; set; }
     public DbSet<RideCancelRequest> RideCancelRequests { get; set; }
+    public DbSet<Scheme> Schemes { get; set; }
+    public DbSet<SchemeRedemption> SchemeRedemptions { get; set; }
+    public DbSet<SchemeBundleComponent> SchemeBundleComponents { get; set; }
+    public DbSet<LoadingSheet> LoadingSheets { get; set; }
+    public DbSet<LoadingSheetItem> LoadingSheetItems { get; set; }
+    public DbSet<Payment> Payments { get; set; }
+    public DbSet<DeliveryTask> DeliveryTasks { get; set; }
+    public DbSet<PurchaseOrder> PurchaseOrders { get; set; }
+    public DbSet<PurchaseOrderItem> PurchaseOrderItems { get; set; }
+    public DbSet<GoodsReceipt> GoodsReceipts { get; set; }
+    public DbSet<GoodsReceiptItem> GoodsReceiptItems { get; set; }
+    public DbSet<PurchaseReturn> PurchaseReturns { get; set; }
+    public DbSet<PurchaseReturnItem> PurchaseReturnItems { get; set; }
 
     protected override void OnModelCreating(ModelBuilder modelBuilder)
     {
@@ -68,15 +82,20 @@ public class AppDBContext(DbContextOptions<AppDBContext> options) : DbContext(op
             .HasIndex(pli => new { pli.FK_PriceListId, pli.FK_ItemId })
             .IsUnique();
 
+        modelBuilder.Entity<Order>()
+            .HasIndex(o => o.FK_SaleId)
+            .IsUnique();
+
         modelBuilder.Entity<DriverProfile>()
             .HasIndex(dp => dp.FK_UserId)
             .IsUnique();
 
         modelBuilder.Entity<Vehicle>()
-            .HasOne(v => v.DefaultWarehouse)
+            .HasOne<Warehouse>()
             .WithMany()
-            .HasForeignKey(v => v.FK_DefaultWarehouseId)
-            .OnDelete(DeleteBehavior.Restrict);
+            .HasForeignKey(nameof(Vehicle.DefaultWarehouseId))
+            .OnDelete(DeleteBehavior.Restrict)
+            .IsRequired(false);
 
         modelBuilder.Entity<DeliveryRun>()
             .HasOne(r => r.SourceWarehouse)
@@ -90,6 +109,179 @@ public class AppDBContext(DbContextOptions<AppDBContext> options) : DbContext(op
             .HasForeignKey(r => r.FK_DriverProfileId)
             .OnDelete(DeleteBehavior.Restrict);
 
+        modelBuilder.Entity<Sale>()
+            .HasOne(s => s.Store)
+            .WithMany()
+            .HasForeignKey(s => s.FK_StoreId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<Sale>()
+            .HasOne(s => s.CreatedByUser)
+            .WithMany()
+            .HasForeignKey(s => s.CreatedByUserId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<Sale>()
+            .HasOne(s => s.Ride)
+            .WithMany()
+            .HasForeignKey(s => s.FK_RideId)
+            .OnDelete(DeleteBehavior.Restrict)
+            .IsRequired(false);
+
+        modelBuilder.Entity<Order>()
+            .HasOne(o => o.Sale)
+            .WithMany()
+            .HasForeignKey(o => o.FK_SaleId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<SchemeRedemption>()
+            .HasOne(r => r.Scheme)
+            .WithMany(s => s.Redemptions)
+            .HasForeignKey(r => r.FK_SchemeId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<SchemeRedemption>()
+            .HasOne(r => r.Order)
+            .WithMany()
+            .HasForeignKey(r => r.FK_OrderId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<SchemeRedemption>()
+            .HasOne(r => r.FreeItem)
+            .WithMany()
+            .HasForeignKey(r => r.FK_FreeItemId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<Scheme>()
+            .HasOne(s => s.TriggerItem)
+            .WithMany()
+            .HasForeignKey(s => s.FK_TriggerItemId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<Scheme>()
+            .HasOne(s => s.FreeItem)
+            .WithMany()
+            .HasForeignKey(s => s.FK_FreeItemId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<SchemeBundleComponent>()
+            .HasOne(c => c.Scheme)
+            .WithMany(s => s.BundleComponents)
+            .HasForeignKey(c => c.FK_SchemeId)
+            .OnDelete(DeleteBehavior.Cascade);
+
+        modelBuilder.Entity<SchemeBundleComponent>()
+            .HasOne(c => c.Item)
+            .WithMany()
+            .HasForeignKey(c => c.FK_ItemId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<SchemeBundleComponent>()
+            .HasIndex(c => new { c.FK_SchemeId, c.FK_ItemId })
+            .IsUnique();
+
+        modelBuilder.Entity<LoadingSheet>()
+            .HasOne(s => s.SourceWarehouse)
+            .WithMany()
+            .HasForeignKey(s => s.FK_SourceWarehouseId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<LoadingSheet>()
+            .HasOne(s => s.Ride)
+            .WithMany()
+            .HasForeignKey(s => s.FK_RideId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<LoadingSheetItem>()
+            .HasOne(i => i.Item)
+            .WithMany()
+            .HasForeignKey(i => i.FK_ItemId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<PurchaseOrder>()
+            .HasOne(po => po.Supplier)
+            .WithMany()
+            .HasForeignKey(po => po.FK_SupplierId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<PurchaseOrderItem>()
+            .HasOne(i => i.PurchaseOrder)
+            .WithMany(po => po.Items)
+            .HasForeignKey(i => i.FK_PurchaseOrderId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<PurchaseOrderItem>()
+            .HasOne(i => i.Item)
+            .WithMany()
+            .HasForeignKey(i => i.FK_ItemId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<GoodsReceipt>()
+            .HasOne(gr => gr.PurchaseOrder)
+            .WithMany()
+            .HasForeignKey(gr => gr.FK_PurchaseOrderId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<GoodsReceipt>()
+            .HasOne(gr => gr.Warehouse)
+            .WithMany()
+            .HasForeignKey(gr => gr.FK_WarehouseId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<GoodsReceiptItem>()
+            .HasOne(i => i.GoodsReceipt)
+            .WithMany(gr => gr.Items)
+            .HasForeignKey(i => i.FK_GoodsReceiptId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<GoodsReceiptItem>()
+            .HasOne(i => i.PurchaseOrderItem)
+            .WithMany()
+            .HasForeignKey(i => i.FK_PurchaseOrderItemId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<PurchaseReturn>()
+            .HasOne(pr => pr.PurchaseOrder)
+            .WithMany()
+            .HasForeignKey(pr => pr.FK_PurchaseOrderId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<PurchaseReturnItem>()
+            .HasOne(i => i.PurchaseReturn)
+            .WithMany(pr => pr.Items)
+            .HasForeignKey(i => i.FK_PurchaseReturnId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<PurchaseReturnItem>()
+            .HasOne(i => i.Item)
+            .WithMany()
+            .HasForeignKey(i => i.FK_ItemId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<PurchaseOrderItem>()
+            .HasIndex(i => i.FK_PurchaseOrderId);
+
+        modelBuilder.Entity<GoodsReceiptItem>()
+            .HasIndex(i => i.FK_GoodsReceiptId);
+
+        modelBuilder.Entity<GoodsReceiptItem>()
+            .HasIndex(i => i.FK_PurchaseOrderItemId);
+
+        modelBuilder.Entity<PurchaseReturnItem>()
+            .HasIndex(i => i.FK_PurchaseReturnId);
+
+        modelBuilder.Entity<DeliveryTask>()
+            .HasOne(t => t.Ride)
+            .WithMany()
+            .HasForeignKey(t => t.FK_RideId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        modelBuilder.Entity<DeliveryTask>()
+            .HasOne(t => t.Order)
+            .WithMany()
+            .HasForeignKey(t => t.FK_OrderId)
+            .OnDelete(DeleteBehavior.Restrict);
+
         Seed.RoleAndPermissionSeed.Apply(modelBuilder);
     }
 }

Distribution/Data/Seed/RoleAndPermissionSeed.cs

@@ -14,78 +14,6 @@ public static class RoleAndPermissionSeed
     private static readonly Guid RegionalManagerId = new("10000000-0000-0000-0000-000000000005");
     private static readonly Guid RegionalAgencyId = new("10000000-0000-0000-0000-000000000006");
 
-    private static readonly (string Code, string Description) [] PermissionDefs =
-    [
-        ("regions.view", "View regions"),
-        ("regions.create", "Create regions"),
-        ("regions.update", "Update regions"),
-        ("regions.delete", "Delete regions"),
-
-        ("routes.view", "View routes"),
-        ("routes.create", "Create routes"),
-        ("routes.update", "Update routes"),
-        ("routes.delete", "Delete routes"),
-
-        ("vehicles.view", "View vehicles"),
-        ("vehicles.create", "Create vehicles"),
-        ("vehicles.update", "Update vehicles"),
-        ("vehicles.delete", "Delete vehicles"),
-
-        ("stores.view", "View stores"),
-        ("stores.create", "Create stores"),
-        ("stores.update", "Update stores"),
-        ("stores.delete", "Delete stores"),
-        ("stores.kyc.verify", "Verify or reject store KYC documents"),
-        ("stores.credit.update", "Update store credit limit and outstanding balance"),
-
-        ("warehouses.view", "View warehouses"),
-        ("warehouses.create", "Create warehouses"),
-        ("warehouses.update", "Update warehouses"),
-        ("warehouses.delete", "Delete warehouses"),
-
-        ("orders.view", "View orders"),
-        ("orders.create", "Create orders"),
-        ("orders.update", "Update orders"),
-        ("orders.delete", "Delete orders"),
-
-        ("users.view", "View users"),
-        ("users.create", "Create users"),
-        ("users.update", "Update users"),
-        ("users.deactivate", "Deactivate users"),
-        ("users.assign_role", "Assign a role to a user"),
-        ("users.assign_scope", "Assign region/route/store scope to a user"),
-
-        ("items.view", "View items, brands and UOMs"),
-        ("items.create", "Create items, brands and UOMs"),
-        ("items.update", "Update items, brands and UOMs"),
-        ("items.delete", "Delete items, brands and UOMs"),
-
-        ("categories.view", "View categories"),
-        ("categories.create", "Create categories and subcategories"),
-        ("categories.update", "Update categories and subcategories"),
-        ("categories.delete", "Delete categories and subcategories"),
-
-        ("driver_profiles.view", "View driver profiles"),
-        ("driver_profiles.create", "Create driver profiles"),
-        ("driver_profiles.update", "Update driver profiles"),
-        ("driver_profiles.deactivate", "Deactivate driver profiles"),
-
-        ("compliance.manage", "Manage driver compliance configuration"),
-
-        ("rides.view", "View rides"),
-        ("rides.create", "Create rides"),
-        ("rides.manage", "Manage ride lifecycle"),
-        ("rides.cancel.request", "Request ride cancellation"),
-        ("rides.cancel.approve", "Approve or reject ride cancellations"),
-    ];
-
-    private static readonly Dictionary<string, Guid> PermissionIds = PermissionDefs
-        .Select((p, i) => (p.Code, Id: DeterministicPermissionId(i)))
-        .ToDictionary(x => x.Code, x => x.Id);
-
-    private static Guid DeterministicPermissionId(int index) =>
-        new($"20000000-0000-0000-0000-{index + 1:D12}");
-
     public static void Apply(ModelBuilder modelBuilder)
     {
         modelBuilder.Entity<Role>().HasData(
@@ -96,76 +24,5 @@ public static class RoleAndPermissionSeed
             new Role { Id = RegionalManagerId, Name = "RegionalManager", Level = 50, CreatedAt = SeedDate, IsActive = true },
             new Role { Id = RegionalAgencyId, Name = "RegionalAgency", Level = 60, CreatedAt = SeedDate, IsActive = true }
         );
-
-        modelBuilder.Entity<Permission>().HasData(
-            PermissionDefs.Select(p => new Permission
-            {
-                Id = PermissionIds[p.Code],
-                Code = p.Code,
-                Description = p.Description,
-                CreatedAt = SeedDate,
-                IsActive = true
-            })
-        );
-
-        var itemViewPerms = new[] { "items.view", "categories.view" };
-        var itemManagePerms = new[] { "items.view", "items.create", "items.update", "categories.view" };
-        var itemPerms = new[] { "items.view", "items.create", "items.update", "items.delete", "categories.view", "categories.create", "categories.update", "categories.delete" };
-
-        var salesRepPerms = new[] { "orders.view", "orders.create", "orders.update", "stores.view", "routes.view" }.Concat(itemViewPerms).ToArray();
-        var supervisorPerms = salesRepPerms.Concat(["orders.delete", "stores.create", "stores.update"]).ToArray();
-        var ridePerms = new[]
-        {
-            "driver_profiles.view", "driver_profiles.create", "driver_profiles.update", "driver_profiles.deactivate",
-            "compliance.manage",
-            "rides.view", "rides.create", "rides.manage", "rides.cancel.request", "rides.cancel.approve"
-        };
-
-        var areaManagerPerms = supervisorPerms.Concat(["vehicles.view", "warehouses.view"]).Concat(itemManagePerms).Concat(ridePerms).Distinct().ToArray();
-        var areaSupervisorPerms = areaManagerPerms.Concat(["routes.create", "routes.update"]).Concat(itemPerms).Distinct().ToArray();
-
-        var regionalManagerPerms = new[]
-        {
-            "orders.view", "orders.create", "orders.update", "orders.delete",
-            "stores.view", "stores.create", "stores.update", "stores.delete", "stores.kyc.verify", "stores.credit.update",
-            "routes.view", "routes.create", "routes.update", "routes.delete",
-            "vehicles.view", "vehicles.create", "vehicles.update", "vehicles.delete",
-            "warehouses.view", "warehouses.create", "warehouses.update", "warehouses.delete",
-            "regions.view", "users.view",
-            "driver_profiles.view", "driver_profiles.create", "driver_profiles.update", "driver_profiles.deactivate",
-            "compliance.manage",
-            "rides.view", "rides.create", "rides.manage", "rides.cancel.request", "rides.cancel.approve",
-            "items.view", "items.create", "items.update", "items.delete",
-            "categories.view", "categories.create", "categories.update", "categories.delete"
-        };
-        var regionalAgencyPerms = PermissionDefs.Select(p => p.Code).ToArray();
-
-        var rolePermissionMap = new (Guid RoleId, string[] Codes)[]
-        {
-            (SalesRepId, salesRepPerms),
-            (SupervisorId, supervisorPerms),
-            (AreaManagerId, areaManagerPerms),
-            (AreaSupervisorId, areaSupervisorPerms),
-            (RegionalManagerId, regionalManagerPerms),
-            (RegionalAgencyId, regionalAgencyPerms),
-        };
-
-        modelBuilder.Entity<RolePermission>().HasData(
-            rolePermissionMap.SelectMany(rp => rp.Codes.Select(code => new RolePermission
-            {
-                Id = DeterministicRolePermissionId(rp.RoleId, PermissionIds[code]),
-                FK_RoleId = rp.RoleId,
-                FK_PermissionId = PermissionIds[code],
-                CreatedAt = SeedDate,
-                IsActive = true
-            }))
-        );
-    }
-
-    private static Guid DeterministicRolePermissionId(Guid roleId, Guid permissionId)
-    {
-        using var md5 = System.Security.Cryptography.MD5.Create();
-        var bytes = md5.ComputeHash(roleId.ToByteArray().Concat(permissionId.ToByteArray()).ToArray());
-        return new Guid(bytes);
     }
 }

Distribution/Features/DeliveryRide/DeliveryTaskController.cs

@@ -0,0 +1,72 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.DeliveryRide;
+
+[ApiController]
+[Authorize]
+[Route("api")]
+public class DeliveryTaskController(DeliveryTaskService service) : ControllerBase
+{
+    [HttpPost("rides/{rideId:guid}/tasks/generate")]
+    public async Task<IActionResult> Generate(Guid rideId, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.GenerateAsync(rideId, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpGet("rides/{rideId:guid}/tasks")]
+    public async Task<IActionResult> GetByRide(Guid rideId)
+    {
+        var result = await service.GetByRideIdAsync(rideId);
+        return Ok(result);
+    }
+
+    [HttpGet("delivery-tasks/{id:guid}")]
+    public async Task<IActionResult> GetById(Guid id)
+    {
+        var result = await service.GetByIdAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPut("delivery-tasks/{id:guid}/quantities")]
+    public async Task<IActionResult> SetQuantities(Guid id, SetQuantitiesRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.SetQuantitiesAsync(id, request, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPost("delivery-tasks/{id:guid}/confirm")]
+    public async Task<IActionResult> Confirm(Guid id, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.ConfirmAsync(id, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPost("delivery-tasks/{id:guid}/fail")]
+    public async Task<IActionResult> Fail(Guid id, FailTaskRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.FailAsync(id, request.Note, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+}

Distribution/Features/DeliveryRide/DeliveryTaskDTOs.cs

@@ -0,0 +1,24 @@
+using Distribution.Models;
+
+namespace Distribution.Features.DeliveryRide;
+
+public record DeliveryTaskItemResponse(Guid ItemId, string ItemName, int Quantity, int QuantityFulfilled, decimal UnitPrice);
+
+public record DeliveryTaskResponse(
+    Guid Id,
+    Guid FK_RideId,
+    Guid FK_OrderId,
+    Guid StoreId,
+    string StoreName,
+    int Sequence,
+    DeliveryTaskStatus Status,
+    bool CustomerConfirmed,
+    DateTime? ConfirmedAt,
+    string? Note,
+    List<DeliveryTaskItemResponse> Items,
+    DateTime CreatedAt);
+
+public record SetQuantitiesRequest(List<DeliveryTaskItemQuantity> Items);
+public record DeliveryTaskItemQuantity(Guid ItemId, int QuantityFulfilled);
+
+public record FailTaskRequest(string Note);

Distribution/Features/DeliveryRide/DeliveryTaskRepository.cs

@@ -0,0 +1,38 @@
+using Distribution.Data;
+using Distribution.Models;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.DeliveryRide;
+
+public class DeliveryTaskRepository(AppDBContext context) : IDeliveryTaskRepository
+{
+    public async Task<DeliveryTask?> GetByIdAsync(Guid id) =>
+        await context.DeliveryTasks
+            .Include(t => t.Order)
+                .ThenInclude(o => o.Store)
+            .Include(t => t.Order)
+                .ThenInclude(o => o.OrderItems)
+                    .ThenInclude(i => i.Item)
+            .FirstOrDefaultAsync(t => t.Id == id);
+
+    public async Task<List<DeliveryTask>> GetByRideIdAsync(Guid rideId) =>
+        await context.DeliveryTasks
+            .Include(t => t.Order)
+                .ThenInclude(o => o.Store)
+            .Include(t => t.Order)
+                .ThenInclude(o => o.OrderItems)
+                    .ThenInclude(i => i.Item)
+            .Where(t => t.FK_RideId == rideId)
+            .OrderBy(t => t.Sequence)
+            .ToListAsync();
+
+    public async Task<bool> ExistsForOrderAndRideAsync(Guid orderId, Guid rideId) =>
+        await context.DeliveryTasks
+            .AnyAsync(t => t.FK_OrderId == orderId && t.FK_RideId == rideId);
+
+    public async Task AddAsync(DeliveryTask task) =>
+        await context.DeliveryTasks.AddAsync(task);
+
+    public void Update(DeliveryTask task) =>
+        context.DeliveryTasks.Update(task);
+}

Distribution/Features/DeliveryRide/DeliveryTaskService.cs

@@ -0,0 +1,224 @@
+using Distribution.Features.Order;
+using Distribution.Features.Ride;
+using Distribution.Features.Sale;
+using Distribution.Features.Stock;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+
+namespace Distribution.Features.DeliveryRide;
+
+public class DeliveryTaskService(
+    IDeliveryTaskRepository repo,
+    IRideRepository rideRepo,
+    IOrderRepository orderRepo,
+    ISaleRepository saleRepo,
+    IStockRepository stockRepo,
+    IUnitOfWork uow)
+{
+    private static DeliveryTaskResponse ToResponse(DeliveryTask t) =>
+        new(t.Id,
+            t.FK_RideId,
+            t.FK_OrderId,
+            t.Order.FK_StoreId,
+            t.Order.Store?.StoreName ?? string.Empty,
+            t.Sequence,
+            t.Status,
+            t.CustomerConfirmed,
+            t.ConfirmedAt,
+            t.Note,
+            t.Order.OrderItems.Select(i => new DeliveryTaskItemResponse(
+                i.FK_ItemId,
+                i.Item?.Name ?? string.Empty,
+                i.Quantity,
+                i.QuantityFulfilled,
+                i.UnitPrice)).ToList(),
+            t.CreatedAt);
+
+    public async Task<List<DeliveryTaskResponse>> GenerateAsync(Guid rideId, CancellationToken ct = default)
+    {
+        var ride = await rideRepo.GetByIdAsync(rideId)
+            ?? throw new KeyNotFoundException("Ride not found");
+
+        if (ride.Status != RideStatus.Active)
+            throw new InvalidOperationException("Tasks can only be generated for an Active ride");
+
+        if (ride.RideType != RideType.Delivery)
+            throw new InvalidOperationException("Tasks can only be generated for a Delivery ride");
+
+        var orders = await orderRepo.GetPendingByRouteIdAsync(ride.FK_RouteId);
+
+        var created = new List<DeliveryTask>();
+        int sequence = 1;
+
+        foreach (var order in orders)
+        {
+            if (await repo.ExistsForOrderAndRideAsync(order.Id, rideId))
+                continue;
+
+            var task = new DeliveryTask
+            {
+                FK_RideId = rideId,
+                FK_OrderId = order.Id,
+                Sequence = sequence++,
+                Status = DeliveryTaskStatus.Pending
+            };
+            created.Add(task);
+        }
+
+        if (created.Count == 0)
+            return new List<DeliveryTaskResponse>();
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            foreach (var task in created)
+                await repo.AddAsync(task);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        var saved = await repo.GetByRideIdAsync(rideId);
+        return saved.Select(ToResponse).ToList();
+    }
+
+    public async Task<List<DeliveryTaskResponse>> GetByRideIdAsync(Guid rideId)
+    {
+        var tasks = await repo.GetByRideIdAsync(rideId);
+        return tasks.Select(ToResponse).ToList();
+    }
+
+    public async Task<DeliveryTaskResponse?> GetByIdAsync(Guid id)
+    {
+        var task = await repo.GetByIdAsync(id);
+        return task is null ? null : ToResponse(task);
+    }
+
+    public async Task<DeliveryTaskResponse> SetQuantitiesAsync(Guid taskId, SetQuantitiesRequest request, CancellationToken ct = default)
+    {
+        var task = await repo.GetByIdAsync(taskId)
+            ?? throw new KeyNotFoundException("Delivery task not found");
+
+        if (task.Status != DeliveryTaskStatus.Pending)
+            throw new InvalidOperationException("Quantities can only be set for a Pending task");
+
+        foreach (var input in request.Items)
+        {
+            var orderItem = task.Order.OrderItems.FirstOrDefault(i => i.FK_ItemId == input.ItemId)
+                ?? throw new InvalidOperationException($"Item {input.ItemId} is not on this order");
+
+            if (input.QuantityFulfilled < 0)
+                throw new InvalidOperationException($"QuantityFulfilled cannot be negative for item {input.ItemId}");
+
+            if (input.QuantityFulfilled > orderItem.Quantity)
+                throw new InvalidOperationException($"QuantityFulfilled exceeds ordered quantity for item {input.ItemId}");
+
+            orderItem.QuantityFulfilled = input.QuantityFulfilled;
+        }
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            repo.Update(task);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        var saved = await repo.GetByIdAsync(taskId);
+        return ToResponse(saved!);
+    }
+
+    public async Task<DeliveryTaskResponse> ConfirmAsync(Guid taskId, CancellationToken ct = default)
+    {
+        var task = await repo.GetByIdAsync(taskId)
+            ?? throw new KeyNotFoundException("Delivery task not found");
+
+        if (task.Status != DeliveryTaskStatus.Pending)
+            throw new InvalidOperationException("Only a Pending task can be confirmed");
+
+        if (!task.Order.OrderItems.Any(i => i.QuantityFulfilled > 0))
+            throw new InvalidOperationException("Set quantities before confirming — at least one item must have a fulfilled quantity greater than zero");
+
+        var ride = await rideRepo.GetByIdAsync(task.FK_RideId)
+            ?? throw new KeyNotFoundException("Ride not found");
+
+        var vehicleId = ride.FK_VehicleId;
+
+        bool fullyDelivered = task.Order.OrderItems.All(i => i.QuantityFulfilled == i.Quantity);
+
+        task.CustomerConfirmed = true;
+        task.ConfirmedAt = DateTime.Now;
+        task.Status = fullyDelivered ? DeliveryTaskStatus.Delivered : DeliveryTaskStatus.PartiallyDelivered;
+
+        var order = task.Order;
+        order.Status = fullyDelivered ? OrderStatus.Fulfilled : OrderStatus.PartiallyFulfilled;
+        if (fullyDelivered)
+            order.FulfilledAt = DateTime.Now;
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            foreach (var item in task.Order.OrderItems.Where(i => i.QuantityFulfilled > 0))
+            {
+                var vehicleBalance = await stockRepo.GetBalanceAsync(item.FK_ItemId, vehicleId)
+                    ?? throw new InvalidOperationException($"No vehicle stock found for item {item.FK_ItemId}");
+
+                if (vehicleBalance.Quantity < item.QuantityFulfilled)
+                    throw new InvalidOperationException($"Insufficient vehicle stock for item {item.FK_ItemId}");
+
+                vehicleBalance.Quantity -= item.QuantityFulfilled;
+                vehicleBalance.UpdatedAt = DateTime.Now;
+                stockRepo.UpdateBalance(vehicleBalance);
+
+                await stockRepo.AddMovementAsync(new StockMovement
+                {
+                    FK_ItemId = item.FK_ItemId,
+                    FromLocationId = vehicleId,
+                    FromLocationType = LocationType.Vehicle,
+                    Quantity = item.QuantityFulfilled,
+                    Type = MovementType.Sale,
+                    ReferenceId = task.FK_OrderId
+                });
+            }
+
+            repo.Update(task);
+            orderRepo.Update(order);
+
+            if (fullyDelivered)
+            {
+                var sale = await saleRepo.GetByIdAsync(order.FK_SaleId)
+                    ?? throw new KeyNotFoundException("Sale not found");
+                sale.Status = SaleStatus.Completed;
+                sale.CompletedAt = DateTime.Now;
+                saleRepo.Update(sale);
+            }
+
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        var saved = await repo.GetByIdAsync(taskId);
+        return ToResponse(saved!);
+    }
+
+    public async Task<DeliveryTaskResponse> FailAsync(Guid taskId, string note, CancellationToken ct = default)
+    {
+        var task = await repo.GetByIdAsync(taskId)
+            ?? throw new KeyNotFoundException("Delivery task not found");
+
+        if (task.Status != DeliveryTaskStatus.Pending)
+            throw new InvalidOperationException("Only a Pending task can be failed");
+
+        task.Status = DeliveryTaskStatus.Failed;
+        task.Note = note;
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            repo.Update(task);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return ToResponse(task);
+    }
+}

Distribution/Features/DeliveryRide/IDeliveryTaskRepository.cs

@@ -0,0 +1,12 @@
+using Distribution.Models;
+
+namespace Distribution.Features.DeliveryRide;
+
+public interface IDeliveryTaskRepository
+{
+    Task<DeliveryTask?> GetByIdAsync(Guid id);
+    Task<List<DeliveryTask>> GetByRideIdAsync(Guid rideId);
+    Task<bool> ExistsForOrderAndRideAsync(Guid orderId, Guid rideId);
+    Task AddAsync(DeliveryTask task);
+    void Update(DeliveryTask task);
+}

Distribution/Features/Grn/GrnController.cs

@@ -0,0 +1,33 @@
+using Distribution.Infra.Authorization;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.Grn;
+
+[ApiController]
+[Authorize]
+public class GrnController(GrnService service, ICurrentUserService currentUser) : ControllerBase
+{
+    [HttpGet("api/goods-receipts/{id:guid}")]
+    public async Task<IActionResult> GetById(Guid id)
+    {
+        var result = await service.GetByIdAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpGet("api/purchase-orders/{id:guid}/goods-receipts")]
+    public async Task<IActionResult> GetByPurchaseOrder(Guid id) =>
+        Ok(await service.GetByPurchaseOrderIdAsync(id));
+
+    [HttpPost("api/purchase-orders/{id:guid}/goods-receipts")]
+    public async Task<IActionResult> Create(Guid id, CreateGrnRequest request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        try
+        {
+            var result = await service.CreateAsync(id, request, userId, ct);
+            return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+}

Distribution/Features/Grn/GrnDTOs.cs

@@ -0,0 +1,24 @@
+namespace Distribution.Features.Grn;
+
+public record GrnItemRequest(Guid PurchaseOrderItemId, int AcceptedQuantity, int RejectedQuantity);
+
+public record CreateGrnRequest(Guid WarehouseId, List<GrnItemRequest> Items);
+
+public record GrnItemResponse(
+    Guid Id,
+    Guid PurchaseOrderItemId,
+    Guid ItemId,
+    string Sku,
+    string ItemName,
+    int AcceptedQuantity,
+    int RejectedQuantity);
+
+public record GrnResponse(
+    Guid Id,
+    Guid PurchaseOrderId,
+    Guid ReceivedByUserId,
+    Guid WarehouseId,
+    string WarehouseName,
+    DateTime ReceivedAt,
+    DateTime CreatedAt,
+    List<GrnItemResponse> Items);

Distribution/Features/Grn/GrnRepository.cs

@@ -0,0 +1,35 @@
+using Distribution.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.Grn;
+
+public class GrnRepository(AppDBContext context) : IGrnRepository
+{
+    public async Task<Models.GoodsReceipt?> GetByIdAsync(Guid id) =>
+        await context.GoodsReceipts
+            .Include(gr => gr.Warehouse)
+            .Include(gr => gr.Items).ThenInclude(i => i.PurchaseOrderItem).ThenInclude(poi => poi.Item)
+            .FirstOrDefaultAsync(gr => gr.Id == id);
+
+    public async Task<List<Models.GoodsReceipt>> GetByPurchaseOrderIdAsync(Guid purchaseOrderId) =>
+        await context.GoodsReceipts
+            .Include(gr => gr.Warehouse)
+            .Include(gr => gr.Items).ThenInclude(i => i.PurchaseOrderItem).ThenInclude(poi => poi.Item)
+            .Where(gr => gr.FK_PurchaseOrderId == purchaseOrderId && gr.IsActive)
+            .OrderByDescending(gr => gr.ReceivedAt)
+            .ToListAsync();
+
+    public async Task AddAsync(Models.GoodsReceipt entity) =>
+        await context.GoodsReceipts.AddAsync(entity);
+
+    public async Task<bool> HasAnyForPurchaseOrderAsync(Guid purchaseOrderId) =>
+        await context.GoodsReceipts.AnyAsync(gr => gr.FK_PurchaseOrderId == purchaseOrderId && gr.IsActive);
+
+    public async Task<Dictionary<Guid, int>> GetAcceptedTotalsByItemAsync(Guid purchaseOrderId) =>
+        await context.GoodsReceiptItems
+            .Include(i => i.PurchaseOrderItem)
+            .Where(i => i.PurchaseOrderItem.FK_PurchaseOrderId == purchaseOrderId && i.IsActive)
+            .GroupBy(i => i.PurchaseOrderItem.FK_ItemId)
+            .Select(g => new { ItemId = g.Key, Total = g.Sum(i => i.AcceptedQuantity) })
+            .ToDictionaryAsync(x => x.ItemId, x => x.Total);
+}

Distribution/Features/Grn/GrnService.cs

@@ -0,0 +1,137 @@
+using Distribution.Features.Po;
+using Distribution.Features.Stock;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+
+namespace Distribution.Features.Grn;
+
+public class GrnService(
+    IGrnRepository repo,
+    IPoRepository poRepo,
+    IStockRepository stockRepo,
+    IUnitOfWork uow)
+{
+    private static GrnItemResponse MapItem(Models.GoodsReceiptItem i) =>
+        new(i.Id, i.FK_PurchaseOrderItemId, i.PurchaseOrderItem.FK_ItemId, i.PurchaseOrderItem.Item.Sku,
+            i.PurchaseOrderItem.Item.Name, i.AcceptedQuantity, i.RejectedQuantity);
+
+    private static GrnResponse Map(Models.GoodsReceipt gr) =>
+        new(gr.Id, gr.FK_PurchaseOrderId, gr.FK_ReceivedByUserId, gr.FK_WarehouseId, gr.Warehouse?.Name ?? string.Empty,
+            gr.ReceivedAt, gr.CreatedAt, gr.Items.Where(i => i.IsActive).Select(MapItem).ToList());
+
+    public async Task<GrnResponse?> GetByIdAsync(Guid id)
+    {
+        var gr = await repo.GetByIdAsync(id);
+        if (gr is null || !gr.IsActive) return null;
+        return Map(gr);
+    }
+
+    public async Task<List<GrnResponse>> GetByPurchaseOrderIdAsync(Guid purchaseOrderId) =>
+        (await repo.GetByPurchaseOrderIdAsync(purchaseOrderId)).Select(Map).ToList();
+
+    /// <summary>
+    /// Validates the Po status, increments PurchaseOrderItem.ReceivedQuantity, writes StockBalance/
+    /// StockMovement for AcceptedQuantity only (RejectedQuantity never touches stock), and
+    /// transitions the Po to PartiallyReceived/Received. All in one unit of work.
+    /// </summary>
+    public async Task<GrnResponse> CreateAsync(Guid purchaseOrderId, CreateGrnRequest request, Guid receivedByUserId, CancellationToken ct = default)
+    {
+        var po = await poRepo.GetByIdAsync(purchaseOrderId)
+            ?? throw new InvalidOperationException("Purchase order not found.");
+
+        if (!po.IsActive)
+            throw new InvalidOperationException("Purchase order not found.");
+
+        if (po.Status is not (PurchaseOrderStatus.Issued or PurchaseOrderStatus.PartiallyReceived))
+            throw new InvalidOperationException(
+                $"Cannot receive goods against a purchase order in {po.Status} status.");
+
+        if (request.Items is null || request.Items.Count == 0)
+            throw new InvalidOperationException("A goods receipt must have at least one line item.");
+
+        var goodsReceipt = new Models.GoodsReceipt
+        {
+            FK_PurchaseOrderId = po.Id,
+            FK_ReceivedByUserId = receivedByUserId,
+            FK_WarehouseId = request.WarehouseId,
+            ReceivedAt = DateTime.Now
+        };
+
+        foreach (var line in request.Items)
+        {
+            var poItem = po.Items.FirstOrDefault(i => i.Id == line.PurchaseOrderItemId && i.IsActive)
+                ?? throw new InvalidOperationException($"Purchase order line {line.PurchaseOrderItemId} not found on this Po.");
+
+            if (poItem.IsCancelled)
+                throw new InvalidOperationException($"Line for item {poItem.FK_ItemId} is cancelled and cannot receive stock.");
+
+            if (line.AcceptedQuantity < 0 || line.RejectedQuantity < 0)
+                throw new InvalidOperationException("Accepted/rejected quantities cannot be negative.");
+
+            if (line.AcceptedQuantity + line.RejectedQuantity + poItem.ReceivedQuantity > poItem.Quantity)
+                throw new InvalidOperationException(
+                    $"Accepted + rejected quantity for item {poItem.FK_ItemId} would exceed the ordered quantity.");
+
+            poItem.ReceivedQuantity += line.AcceptedQuantity;
+
+            goodsReceipt.Items.Add(new Models.GoodsReceiptItem
+            {
+                FK_PurchaseOrderItemId = poItem.Id,
+                AcceptedQuantity = line.AcceptedQuantity,
+                RejectedQuantity = line.RejectedQuantity
+            });
+        }
+
+        var activeLines = po.Items.Where(i => i.IsActive && !i.IsCancelled).ToList();
+        po.Status = activeLines.Count > 0 && activeLines.All(i => i.ReceivedQuantity >= i.Quantity)
+            ? PurchaseOrderStatus.Received
+            : PurchaseOrderStatus.PartiallyReceived;
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            await repo.AddAsync(goodsReceipt);
+
+            foreach (var line in goodsReceipt.Items.Where(i => i.AcceptedQuantity > 0))
+            {
+                var poItem = po.Items.First(i => i.Id == line.FK_PurchaseOrderItemId);
+
+                var balance = await stockRepo.GetBalanceAsync(poItem.FK_ItemId, request.WarehouseId);
+                if (balance is null)
+                {
+                    await stockRepo.AddBalanceAsync(new StockBalance
+                    {
+                        FK_ItemId = poItem.FK_ItemId,
+                        LocationId = request.WarehouseId,
+                        LocationType = LocationType.Warehouse,
+                        Quantity = line.AcceptedQuantity
+                    });
+                }
+                else
+                {
+                    balance.Quantity += line.AcceptedQuantity;
+                    balance.UpdatedAt = DateTime.Now;
+                    stockRepo.UpdateBalance(balance);
+                }
+
+                await stockRepo.AddMovementAsync(new StockMovement
+                {
+                    FK_ItemId = poItem.FK_ItemId,
+                    ToLocationId = request.WarehouseId,
+                    ToLocationType = LocationType.Warehouse,
+                    Quantity = line.AcceptedQuantity,
+                    Type = MovementType.PurchaseReceipt,
+                    ReferenceId = goodsReceipt.Id,
+                    CreatedBy = receivedByUserId
+                });
+            }
+
+            poRepo.Update(po);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        var saved = await repo.GetByIdAsync(goodsReceipt.Id);
+        return Map(saved!);
+    }
+}

Distribution/Features/Grn/IGrnRepository.cs

@@ -0,0 +1,14 @@
+namespace Distribution.Features.Grn;
+
+public interface IGrnRepository
+{
+    Task<Models.GoodsReceipt?> GetByIdAsync(Guid id);
+    Task<List<Models.GoodsReceipt>> GetByPurchaseOrderIdAsync(Guid purchaseOrderId);
+    Task AddAsync(Models.GoodsReceipt entity);
+
+    /// <summary>True if at least one GoodsReceipt exists against this Po (createPurchaseReturn guard).</summary>
+    Task<bool> HasAnyForPurchaseOrderAsync(Guid purchaseOrderId);
+
+    /// <summary>Sum of AcceptedQuantity per ItemId across all receipts for a Po.</summary>
+    Task<Dictionary<Guid, int>> GetAcceptedTotalsByItemAsync(Guid purchaseOrderId);
+}

Distribution/Features/LoadingEvent/ILoadingSheetRepository.cs

@@ -0,0 +1,16 @@
+using Distribution.Models;
+
+namespace Distribution.Features.LoadingEvent;
+
+public interface ILoadingSheetRepository
+{
+    Task<LoadingSheet?> GetByIdAsync(Guid id);
+    Task<LoadingSheet?> GetActiveByRideIdAsync(Guid rideId);
+    Task<List<LoadingSheet>> GetAllAsync(Guid? rideId, LoadingSheetStatus? status, int page, int pageSize);
+    Task<int> GetCountAsync(Guid? rideId, LoadingSheetStatus? status);
+    Task<List<(Guid ItemId, decimal TotalQty)>> GetAggregatedOrderItemsByRouteIdAsync(Guid routeId);
+    Task AddAsync(LoadingSheet sheet);
+    void Update(LoadingSheet sheet);
+    void RemoveItems(IEnumerable<LoadingSheetItem> items);
+    Task AddItemsAsync(IEnumerable<LoadingSheetItem> items);
+}

Distribution/Features/LoadingEvent/LoadingSheetController.cs

@@ -0,0 +1,113 @@
+using Distribution.Models;
+using Distribution.Infra.Authorization;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.LoadingEvent;
+
+[ApiController]
+[Route("api/loading-sheets")]
+[Authorize]
+public class LoadingSheetController(LoadingSheetService service, ICurrentUserService currentUser) : ControllerBase
+{
+    [HttpGet]
+    [Authorize(Policy = "loading.view")]
+    public async Task<IActionResult> GetAll(
+        [FromQuery] Guid? rideId,
+        [FromQuery] LoadingSheetStatus? status,
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 20)
+    {
+        var result = await service.GetAllAsync(rideId, status, page, pageSize);
+        return Ok(result);
+    }
+
+    [HttpGet("{id:guid}")]
+    [Authorize(Policy = "loading.view")]
+    public async Task<IActionResult> GetById(Guid id)
+    {
+        var result = await service.GetByIdAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost]
+    [Authorize(Policy = "loading.dispatch")]
+    public async Task<IActionResult> Create(CreateLoadingSheetRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.CreateAsync(request, ct);
+            return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPut("{id:guid}/items")]
+    [Authorize(Policy = "loading.dispatch")]
+    public async Task<IActionResult> SetItems(Guid id, SetItemsRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.SetItemsAsync(id, request, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPost("{id:guid}/confirm-dispatch")]
+    [Authorize(Policy = "loading.dispatch")]
+    public async Task<IActionResult> ConfirmDispatch(Guid id, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        try
+        {
+            var result = await service.ConfirmDispatchAsync(id, userId, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPut("{id:guid}/receipt-items")]
+    [Authorize(Policy = "loading.receive")]
+    public async Task<IActionResult> SetReceiptItems(Guid id, SetReceiptItemsRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.SetReceiptItemsAsync(id, request, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPost("{id:guid}/confirm-receipt")]
+    [Authorize(Policy = "loading.receive")]
+    public async Task<IActionResult> ConfirmReceipt(Guid id, ConfirmReceiptRequest request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        try
+        {
+            var result = await service.ConfirmReceiptAsync(id, request, userId, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPost("{id:guid}/resolve")]
+    [Authorize(Policy = "loading.resolve")]
+    public async Task<IActionResult> Resolve(Guid id, ResolveDiscrepancyRequest request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        try
+        {
+            var result = await service.ResolveAsync(id, request, userId, ct);
+            return Ok(result);
+        }
+        catch (KeyNotFoundException) { return NotFound(); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+}

Distribution/Features/LoadingEvent/LoadingSheetDTOs.cs

@@ -0,0 +1,37 @@
+using Distribution.Models;
+
+namespace Distribution.Features.LoadingEvent;
+
+public record LoadingSheetResponse(
+    Guid Id,
+    Guid FK_RideId,
+    Guid FK_SourceWarehouseId,
+    string WarehouseName,
+    LoadingSheetStatus Status,
+    DateTime? DispatchConfirmedAt,
+    Guid? DispatchConfirmedBy,
+    DateTime? ReceiptConfirmedAt,
+    Guid? ReceiptConfirmedBy,
+    DateTime CreatedAt,
+    List<LoadingSheetItemResponse> Items);
+
+public record LoadingSheetItemResponse(
+    Guid Id,
+    Guid FK_ItemId,
+    string ItemName,
+    decimal QuantityDispatched,
+    decimal? QuantityReceived,
+    decimal? QuantityResolved);
+
+public record CreateLoadingSheetRequest(Guid FK_RideId);
+
+public record SetItemsRequest(List<SetItemInput> Items);
+public record SetItemInput(Guid FK_ItemId, decimal Quantity);
+
+public record SetReceiptItemsRequest(List<ReceiptItemInput> Items);
+public record ReceiptItemInput(Guid FK_ItemId, decimal QuantityReceived);
+
+public record ConfirmReceiptRequest(int Meterstart);
+
+public record ResolveDiscrepancyRequest(List<ResolveItemInput> Items, int Meterstart);
+public record ResolveItemInput(Guid FK_ItemId, decimal QuantityResolved);

Distribution/Features/LoadingEvent/LoadingSheetRepository.cs

@@ -0,0 +1,63 @@
+using Distribution.Data;
+using Distribution.Models;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.LoadingEvent;
+
+public class LoadingSheetRepository(AppDBContext context) : ILoadingSheetRepository
+{
+    public async Task<LoadingSheet?> GetByIdAsync(Guid id) =>
+        await context.LoadingSheets
+            .Include(s => s.SourceWarehouse)
+            .Include(s => s.Items).ThenInclude(i => i.Item)
+            .FirstOrDefaultAsync(s => s.Id == id);
+
+    public async Task<LoadingSheet?> GetActiveByRideIdAsync(Guid rideId) =>
+        await context.LoadingSheets
+            .FirstOrDefaultAsync(s =>
+                s.FK_RideId == rideId &&
+                s.Status != LoadingSheetStatus.ReceiptConfirmed &&
+                s.Status != LoadingSheetStatus.Resolved);
+
+    public async Task<List<LoadingSheet>> GetAllAsync(Guid? rideId, LoadingSheetStatus? status, int page, int pageSize) =>
+        await context.LoadingSheets
+            .Include(s => s.SourceWarehouse)
+            .Where(s =>
+                (rideId == null || s.FK_RideId == rideId) &&
+                (status == null || s.Status == status))
+            .OrderByDescending(s => s.CreatedAt)
+            .Skip((page - 1) * pageSize)
+            .Take(pageSize)
+            .ToListAsync();
+
+    public async Task<int> GetCountAsync(Guid? rideId, LoadingSheetStatus? status) =>
+        await context.LoadingSheets
+            .CountAsync(s =>
+                (rideId == null || s.FK_RideId == rideId) &&
+                (status == null || s.Status == status));
+
+    public async Task<List<(Guid ItemId, decimal TotalQty)>> GetAggregatedOrderItemsByRouteIdAsync(Guid routeId)
+    {
+        var groups = await context.OrderItems
+            .Where(oi => oi.IsActive
+                && oi.Order.IsActive
+                && oi.Order.Store.FK_RouteId == routeId
+                && (oi.Order.Status == OrderStatus.Pending || oi.Order.Status == OrderStatus.PartiallyFulfilled))
+            .GroupBy(oi => oi.FK_ItemId)
+            .Select(g => new { ItemId = g.Key, TotalQty = g.Sum(oi => (decimal)(oi.Quantity - oi.QuantityFulfilled)) })
+            .ToListAsync();
+        return groups.Select(x => (x.ItemId, x.TotalQty)).ToList();
+    }
+
+    public async Task AddAsync(LoadingSheet sheet) =>
+        await context.LoadingSheets.AddAsync(sheet);
+
+    public void Update(LoadingSheet sheet) =>
+        context.LoadingSheets.Update(sheet);
+
+    public void RemoveItems(IEnumerable<LoadingSheetItem> items) =>
+        context.LoadingSheetItems.RemoveRange(items);
+
+    public async Task AddItemsAsync(IEnumerable<LoadingSheetItem> items) =>
+        await context.LoadingSheetItems.AddRangeAsync(items);
+}

Distribution/Features/LoadingEvent/LoadingSheetService.cs

@@ -0,0 +1,284 @@
+using Distribution.Features.Ride;
+using Distribution.Features.Stock;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+
+namespace Distribution.Features.LoadingEvent;
+
+public class LoadingSheetService(
+    ILoadingSheetRepository repo,
+    IRideRepository rideRepo,
+    IStockRepository stockRepo,
+    IUnitOfWork uow)
+{
+    public async Task<PagedResponse<LoadingSheetResponse>> GetAllAsync(Guid? rideId, LoadingSheetStatus? status, int page, int pageSize)
+    {
+        var total = await repo.GetCountAsync(rideId, status);
+        var items = await repo.GetAllAsync(rideId, status, page, pageSize);
+        return new PagedResponse<LoadingSheetResponse>(page, pageSize, total, items.Select(ToResponse).ToList());
+    }
+
+    public async Task<LoadingSheetResponse?> GetByIdAsync(Guid id)
+    {
+        var sheet = await repo.GetByIdAsync(id);
+        return sheet is null ? null : ToResponse(sheet);
+    }
+
+    public async Task<LoadingSheetResponse> CreateAsync(CreateLoadingSheetRequest request, CancellationToken ct = default)
+    {
+        var ride = await rideRepo.GetByIdAsync(request.FK_RideId)
+            ?? throw new KeyNotFoundException("Ride not found");
+
+        if (ride.Status != RideStatus.Open)
+            throw new InvalidOperationException("A loading sheet can only be created for an Open ride");
+
+        var existing = await repo.GetActiveByRideIdAsync(request.FK_RideId);
+        if (existing is not null)
+            throw new InvalidOperationException("This ride already has an active loading sheet");
+
+        var sheet = new LoadingSheet
+        {
+            FK_RideId = ride.Id,
+            FK_SourceWarehouseId = ride.FK_SourceWarehouseId,
+            Status = LoadingSheetStatus.Pending
+        };
+
+        if (ride.RideType == RideType.Delivery)
+        {
+            var orderItems = await repo.GetAggregatedOrderItemsByRouteIdAsync(ride.FK_RouteId);
+            foreach (var (itemId, qty) in orderItems)
+                sheet.Items.Add(new LoadingSheetItem { FK_ItemId = itemId, QuantityDispatched = qty });
+        }
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            await repo.AddAsync(sheet);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        var saved = await repo.GetByIdAsync(sheet.Id);
+        return ToResponse(saved!);
+    }
+
+    public async Task<LoadingSheetResponse> SetItemsAsync(Guid id, SetItemsRequest request, CancellationToken ct = default)
+    {
+        var sheet = await repo.GetByIdAsync(id)
+            ?? throw new KeyNotFoundException("Loading sheet not found");
+
+        if (sheet.Status != LoadingSheetStatus.Pending)
+            throw new InvalidOperationException("Items can only be changed while the sheet is Pending");
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            repo.RemoveItems(sheet.Items);
+            await repo.AddItemsAsync(request.Items.Select(i => new LoadingSheetItem
+            {
+                FK_LoadingSheetId = sheet.Id,
+                FK_ItemId = i.FK_ItemId,
+                QuantityDispatched = i.Quantity
+            }));
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        var saved = await repo.GetByIdAsync(sheet.Id);
+        return ToResponse(saved!);
+    }
+
+    public async Task<LoadingSheetResponse> ConfirmDispatchAsync(Guid id, Guid userId, CancellationToken ct = default)
+    {
+        var sheet = await repo.GetByIdAsync(id)
+            ?? throw new KeyNotFoundException("Loading sheet not found");
+
+        if (sheet.Status != LoadingSheetStatus.Pending)
+            throw new InvalidOperationException($"Cannot confirm dispatch for a sheet in {sheet.Status} status");
+
+        if (!sheet.Items.Any(i => i.QuantityDispatched > 0))
+            throw new InvalidOperationException("Sheet must have at least one item with quantity greater than zero");
+
+        sheet.Status = LoadingSheetStatus.DispatchConfirmed;
+        sheet.DispatchConfirmedAt = DateTime.Now;
+        sheet.DispatchConfirmedBy = userId;
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(sheet); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return ToResponse(sheet);
+    }
+
+    public async Task<LoadingSheetResponse> SetReceiptItemsAsync(Guid id, SetReceiptItemsRequest request, CancellationToken ct = default)
+    {
+        var sheet = await repo.GetByIdAsync(id)
+            ?? throw new KeyNotFoundException("Loading sheet not found");
+
+        if (sheet.Status != LoadingSheetStatus.DispatchConfirmed)
+            throw new InvalidOperationException("Receipt quantities can only be set after dispatch is confirmed");
+
+        foreach (var input in request.Items)
+        {
+            var item = sheet.Items.FirstOrDefault(i => i.FK_ItemId == input.FK_ItemId)
+                ?? throw new InvalidOperationException($"Item {input.FK_ItemId} is not on this loading sheet");
+            item.QuantityReceived = input.QuantityReceived;
+        }
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(sheet); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return ToResponse(sheet);
+    }
+
+    public async Task<LoadingSheetResponse> ConfirmReceiptAsync(Guid id, ConfirmReceiptRequest request, Guid userId, CancellationToken ct = default)
+    {
+        var sheet = await repo.GetByIdAsync(id)
+            ?? throw new KeyNotFoundException("Loading sheet not found");
+
+        if (sheet.Status != LoadingSheetStatus.DispatchConfirmed)
+            throw new InvalidOperationException($"Cannot confirm receipt for a sheet in {sheet.Status} status");
+
+        if (sheet.Items.Any(i => !i.QuantityReceived.HasValue))
+            throw new InvalidOperationException("All items must have a received quantity before confirming receipt");
+
+        var ride = await rideRepo.GetByIdAsync(sheet.FK_RideId)
+            ?? throw new KeyNotFoundException("Ride not found");
+
+        var hasDiscrepancy = sheet.Items.Any(i => i.QuantityReceived != i.QuantityDispatched);
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            if (hasDiscrepancy)
+            {
+                sheet.Status = LoadingSheetStatus.DiscrepancyFlagged;
+            }
+            else
+            {
+                sheet.Status = LoadingSheetStatus.ReceiptConfirmed;
+                sheet.ReceiptConfirmedAt = DateTime.Now;
+                sheet.ReceiptConfirmedBy = userId;
+
+                var lines = sheet.Items.Select(i => (i.FK_ItemId, i.QuantityReceived!.Value)).ToList();
+                await ApplyLoadMovementsAsync(sheet, ride.FK_VehicleId, lines, userId);
+
+                ride.Status = RideStatus.Active;
+                ride.ActivatedAt = DateTime.Now;
+                ride.Meterstart = request.Meterstart;
+                rideRepo.Update(ride);
+            }
+
+            repo.Update(sheet);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return ToResponse(sheet);
+    }
+
+    public async Task<LoadingSheetResponse> ResolveAsync(Guid id, ResolveDiscrepancyRequest request, Guid userId, CancellationToken ct = default)
+    {
+        var sheet = await repo.GetByIdAsync(id)
+            ?? throw new KeyNotFoundException("Loading sheet not found");
+
+        if (sheet.Status != LoadingSheetStatus.DiscrepancyFlagged)
+            throw new InvalidOperationException($"Cannot resolve a sheet in {sheet.Status} status");
+
+        foreach (var input in request.Items)
+        {
+            var item = sheet.Items.FirstOrDefault(i => i.FK_ItemId == input.FK_ItemId)
+                ?? throw new InvalidOperationException($"Item {input.FK_ItemId} is not on this loading sheet");
+            if (input.QuantityResolved < 0)
+                throw new InvalidOperationException("Resolved quantity cannot be negative");
+            item.QuantityResolved = input.QuantityResolved;
+        }
+
+        if (sheet.Items.Any(i => !i.QuantityResolved.HasValue))
+            throw new InvalidOperationException("All items must have a resolved quantity");
+
+        var ride = await rideRepo.GetByIdAsync(sheet.FK_RideId)
+            ?? throw new KeyNotFoundException("Ride not found");
+
+        sheet.Status = LoadingSheetStatus.Resolved;
+        sheet.ReceiptConfirmedAt = DateTime.Now;
+        sheet.ReceiptConfirmedBy = userId;
+
+        var lines = sheet.Items.Select(i => (i.FK_ItemId, i.QuantityResolved!.Value)).ToList();
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            await ApplyLoadMovementsAsync(sheet, ride.FK_VehicleId, lines, userId);
+
+            ride.Status = RideStatus.Active;
+            ride.ActivatedAt = DateTime.Now;
+            ride.Meterstart = request.Meterstart;
+            rideRepo.Update(ride);
+
+            repo.Update(sheet);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return ToResponse(sheet);
+    }
+
+    private async Task ApplyLoadMovementsAsync(LoadingSheet sheet, Guid vehicleId, List<(Guid ItemId, decimal Qty)> lines, Guid userId)
+    {
+        foreach (var (itemId, qty) in lines.Where(l => l.Qty > 0))
+        {
+            var warehouseBalance = await stockRepo.GetBalanceAsync(itemId, sheet.FK_SourceWarehouseId)
+                ?? throw new InvalidOperationException($"No stock found in warehouse for item {itemId}");
+            if (warehouseBalance.Quantity < qty)
+                throw new InvalidOperationException($"Insufficient warehouse stock for item {itemId}");
+
+            warehouseBalance.Quantity -= qty;
+            warehouseBalance.UpdatedAt = DateTime.Now;
+            stockRepo.UpdateBalance(warehouseBalance);
+
+            var vehicleBalance = await stockRepo.GetBalanceAsync(itemId, vehicleId);
+            if (vehicleBalance is null)
+            {
+                await stockRepo.AddBalanceAsync(new StockBalance
+                {
+                    FK_ItemId = itemId,
+                    LocationId = vehicleId,
+                    LocationType = LocationType.Vehicle,
+                    Quantity = qty
+                });
+            }
+            else
+            {
+                vehicleBalance.Quantity += qty;
+                vehicleBalance.UpdatedAt = DateTime.Now;
+                stockRepo.UpdateBalance(vehicleBalance);
+            }
+
+            await stockRepo.AddMovementAsync(new StockMovement
+            {
+                FK_ItemId = itemId,
+                FromLocationId = sheet.FK_SourceWarehouseId,
+                FromLocationType = LocationType.Warehouse,
+                ToLocationId = vehicleId,
+                ToLocationType = LocationType.Vehicle,
+                Quantity = qty,
+                Type = MovementType.Load,
+                ReferenceId = sheet.Id,
+                CreatedBy = userId
+            });
+        }
+    }
+
+    private static LoadingSheetResponse ToResponse(LoadingSheet s) =>
+        new(s.Id, s.FK_RideId, s.FK_SourceWarehouseId,
+            s.SourceWarehouse?.Name ?? string.Empty,
+            s.Status,
+            s.DispatchConfirmedAt, s.DispatchConfirmedBy,
+            s.ReceiptConfirmedAt, s.ReceiptConfirmedBy,
+            s.CreatedAt,
+            s.Items.Select(i => new LoadingSheetItemResponse(
+                i.Id, i.FK_ItemId, i.Item?.Name ?? string.Empty,
+                i.QuantityDispatched, i.QuantityReceived, i.QuantityResolved)).ToList());
+}

Distribution/Features/Order/IOrderRepository.cs

@@ -4,10 +4,12 @@ public interface IOrderRepository
 {
     Task<Models.Order?> GetByIdAsync(Guid id);
     Task<List<Models.Order>> GetAllAsync();
+    Task<Models.Order?> GetBySaleIdAsync(Guid saleId);
     Task AddAsync(Models.Order entity);
     void Update(Models.Order entity);
     void Remove(Models.Order entity);
     Task<List<Models.OrderItem>> GetItemsByOrderIdAsync(Guid orderId);
     Task<List<Models.Order>> GetByStoreIdAsync(Guid storeId);
     Task AddItemsAsync(IEnumerable<Models.OrderItem> items);
+    Task<List<Models.Order>> GetPendingByRouteIdAsync(Guid routeId);
 }

Distribution/Features/Order/OrderController.cs

@@ -33,16 +33,24 @@ public class OrderController(OrderService service) : ControllerBase
     [Authorize(Policy = "orders.create")]
     public async Task<IActionResult> Create(CreateOrderRequest request, CancellationToken ct)
     {
-        var result = await service.CreateAsync(request, ct);
-        return result is null ? Forbid() : CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+        try
+        {
+            var result = await service.CreateAsync(request, ct);
+            return result is null ? Forbid() : CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+        }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
     }
 
     [HttpPut("{id:guid}")]
     [Authorize(Policy = "orders.update")]
     public async Task<IActionResult> Update(Guid id, UpdateOrderRequest request, CancellationToken ct)
     {
-        var result = await service.UpdateAsync(id, request, ct);
-        return result is null ? NotFound() : Ok(result);
+        try
+        {
+            var result = await service.UpdateAsync(id, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
     }
 
     [HttpDelete("{id:guid}")]

Distribution/Features/Order/OrderDTOs.cs

@@ -1,18 +1,21 @@
+using Distribution.Models;
+
 namespace Distribution.Features.Order;
 
-public record OrderItemRequest(Guid ItemId, int Quantity, decimal? UnitPrice = null);
+public record CreateOrderRequest(Guid SaleId);
 
-public record CreateOrderRequest(Guid StoreId, DateTime OrderDate, decimal TotalAmount, List<OrderItemRequest> Items);
+public record UpdateOrderRequest(OrderStatus Status);
 
-public record UpdateOrderRequest(DateTime OrderDate, decimal TotalAmount);
-
-public record OrderItemResponse(Guid ItemId, int Quantity, decimal UnitPrice);
+public record OrderItemResponse(Guid ItemId, int Quantity, int QuantityFulfilled, decimal UnitPrice);
 
 public record OrderResponse(
     Guid Id,
+    Guid SaleId,
     DateTime OrderDate,
     Guid StoreId,
     decimal TotalAmount,
+    OrderStatus Status,
+    DateTime? FulfilledAt,
     List<OrderItemResponse> Items,
     bool IsActive,
     DateTime CreatedAt);

Distribution/Features/Order/OrderRepository.cs

@@ -1,4 +1,5 @@
 using Distribution.Data;
+using Distribution.Models;
 using Microsoft.EntityFrameworkCore;
 
 namespace Distribution.Features.Order;
@@ -11,6 +12,9 @@ public class OrderRepository(AppDBContext context) : IOrderRepository
     public async Task<List<Models.Order>> GetAllAsync() =>
         await context.Orders.ToListAsync();
 
+    public async Task<Models.Order?> GetBySaleIdAsync(Guid saleId) =>
+        await context.Orders.FirstOrDefaultAsync(o => o.FK_SaleId == saleId && o.IsActive);
+
     public async Task AddAsync(Models.Order entity) =>
         await context.Orders.AddAsync(entity);
 
@@ -19,6 +23,7 @@ public class OrderRepository(AppDBContext context) : IOrderRepository
 
     public void Remove(Models.Order entity)
     {
+        entity.Status = Models.OrderStatus.Cancelled;
         entity.IsActive = false;
         context.Orders.Update(entity);
     }
@@ -31,4 +36,14 @@ public class OrderRepository(AppDBContext context) : IOrderRepository
 
     public async Task AddItemsAsync(IEnumerable<Models.OrderItem> items) =>
         await context.OrderItems.AddRangeAsync(items);
+
+    public async Task<List<Models.Order>> GetPendingByRouteIdAsync(Guid routeId) =>
+        await context.Orders
+            .Include(o => o.Store)
+            .Include(o => o.OrderItems)
+                .ThenInclude(i => i.Item)
+            .Where(o => o.IsActive
+                && o.Store.FK_RouteId == routeId
+                && (o.Status == OrderStatus.Pending || o.Status == OrderStatus.PartiallyFulfilled))
+            .ToListAsync();
 }

Distribution/Features/Order/OrderService.cs

@@ -1,10 +1,11 @@
+using Distribution.Features.Sale;
 using Distribution.Features.Item;
 using Distribution.Features.PriceList;
 using Distribution.Features.Store;
+using Distribution.Features.Stock;
 using Distribution.Infra.Authorization;
 using Distribution.Infra.UoW;
 using Distribution.Models;
-using Microsoft.Extensions.Configuration;
 
 namespace Distribution.Features.Order;
 
@@ -12,17 +13,18 @@ public class OrderService(
     IOrderRepository repo,
     IStoreRepository storeRepo,
     IItemRepository itemRepo,
+    IStockRepository stockRepo,
     PriceListService priceListService,
+    ISaleRepository saleRepo,
     IUnitOfWork uow,
     ICurrentUserService currentUser,
-    IScopeAccessService scopeAccess,
-    IConfiguration configuration)
+    IScopeAccessService scopeAccess)
 {
     private const int GlobalScopeRoleLevel = 50;
 
     private static OrderResponse ToResponse(Models.Order o, List<Models.OrderItem> items) =>
-        new(o.Id, o.OrderDate, o.FK_StoreId, o.TotalAmount,
-            items.Select(i => new OrderItemResponse(i.FK_ItemId, i.Quantity, i.UnitPrice)).ToList(),
+        new(o.Id, o.FK_SaleId, o.OrderDate, o.FK_StoreId, o.TotalAmount, o.Status, o.FulfilledAt,
+            items.Select(i => new OrderItemResponse(i.FK_ItemId, i.Quantity, i.QuantityFulfilled, i.UnitPrice)).ToList(),
             o.IsActive, o.CreatedAt);
 
     private bool HasGlobalScope => currentUser.RoleLevel >= GlobalScopeRoleLevel;
@@ -33,29 +35,6 @@ public class OrderService(
         return await scopeAccess.HasStoreScopeAsync(currentUser.UserId.Value, storeId);
     }
 
-    /// <summary>
-    /// applyPricingAndDiscounts (price-list half, 14_pricing_and_suppliers.md): resolves the
-    /// region-scoped active price list, then global, then Item.SalePrice, and validates any
-    /// caller-supplied override falls within [MinPrice ?? Price, Price]. Returns null if no price
-    /// can be resolved, or if the requested price is outside the allowed band.
-    /// </summary>
-    private async Task<decimal?> ResolveUnitPriceAsync(Guid itemId, decimal? requestedUnitPrice, Models.Store store, DateTime orderDate)
-    {
-        var item = await itemRepo.GetByIdAsync(itemId);
-        if (item is null) return null;
-        var regionId = store.Route?.FK_RegionId;
-        var resolution = await priceListService.ResolvePriceAsync(itemId, regionId, item.SalePrice, orderDate);
-        if (resolution is null) return null;
-
-        if (!requestedUnitPrice.HasValue) return resolution.Price;
-
-        var min = resolution.MinPrice ?? resolution.Price;
-        var max = resolution.Price;
-        if (requestedUnitPrice.Value < min || requestedUnitPrice.Value > max) return null;
-
-        return requestedUnitPrice.Value;
-    }
-
     public async Task<List<OrderResponse>> GetAllAsync()
     {
         var orders = (await repo.GetAllAsync()).Where(o => o.IsActive).ToList();
@@ -97,50 +76,15 @@ public class OrderService(
 
     public async Task<OrderResponse?> CreateAsync(CreateOrderRequest request, CancellationToken ct = default)
     {
-        if (!await HasStoreScopeAsync(request.StoreId)) return null;
+        var sale = await saleRepo.GetByIdAsync(request.SaleId);
+        if (sale is null || !sale.IsActive) return null;
+        if (!await HasStoreScopeAsync(sale.FK_StoreId)) return null;
 
-        var store = await storeRepo.GetByIdWithRegionAsync(request.StoreId);
-        if (store is null || !store.IsActive) return null;
-        if (store.KycStatus != KycStatus.Verified)
-        {
-            var threshold = configuration.GetValue<decimal>("StoreManagement:UnverifiedKycOrderThreshold");
-            if (request.TotalAmount > threshold) return null;
-        }
+        var existingOrder = await repo.GetBySaleIdAsync(request.SaleId)
+            ?? throw new InvalidOperationException("Orders are created automatically from sales");
 
-        var order = new Models.Order
-        {
-            FK_StoreId = request.StoreId,
-            OrderDate = request.OrderDate,
-            TotalAmount = request.TotalAmount
-        };
-        var orderItems = new List<Models.OrderItem>();
-        foreach (var i in request.Items)
-        {
-            var unitPrice = await ResolveUnitPriceAsync(i.ItemId, i.UnitPrice, store, request.OrderDate);
-            if (unitPrice is null) return null;
-
-            orderItems.Add(new Models.OrderItem
-            {
-                FK_OrderId = order.Id,
-                FK_ItemId = i.ItemId,
-                Quantity = i.Quantity,
-                UnitPrice = unitPrice.Value
-            });
-        }
-
-        await uow.BeginAsync(ct);
-        try
-        {
-            await repo.AddAsync(order);
-            await repo.AddItemsAsync(orderItems);
-            await uow.CommitAsync(ct);
-        }
-        catch
-        {
-            await uow.RollbackAsync(ct);
-            throw;
-        }
-        return ToResponse(order, orderItems);
+        var items = await repo.GetItemsByOrderIdAsync(existingOrder.Id);
+        return ToResponse(existingOrder, items);
     }
 
     public async Task<OrderResponse?> UpdateAsync(Guid id, UpdateOrderRequest request, CancellationToken ct = default)
@@ -148,12 +92,26 @@ public class OrderService(
         var order = await repo.GetByIdAsync(id);
         if (order is null || !order.IsActive) return null;
         if (!await HasStoreScopeAsync(order.FK_StoreId)) return null;
-        order.OrderDate = request.OrderDate;
-        order.TotalAmount = request.TotalAmount;
+
+        var sale = await saleRepo.GetByIdAsync(order.FK_SaleId)
+            ?? throw new InvalidOperationException("Sale not found for this order");
+
+        order.Status = request.Status;
+        order.FulfilledAt = request.Status == OrderStatus.Fulfilled ? DateTime.Now : null;
+
+        sale.Status = request.Status switch
+        {
+            OrderStatus.Fulfilled => SaleStatus.Completed,
+            OrderStatus.Cancelled => SaleStatus.Cancelled,
+            _ => SaleStatus.Pending
+        };
+        sale.CompletedAt = request.Status == OrderStatus.Fulfilled ? DateTime.Now : null;
+
         await uow.BeginAsync(ct);
         try
         {
             repo.Update(order);
+            saleRepo.Update(sale);
             await uow.CommitAsync(ct);
         }
         catch
@@ -161,6 +119,7 @@ public class OrderService(
             await uow.RollbackAsync(ct);
             throw;
         }
+
         var items = await repo.GetItemsByOrderIdAsync(id);
         return ToResponse(order, items);
     }
@@ -170,10 +129,19 @@ public class OrderService(
         var order = await repo.GetByIdAsync(id);
         if (order is null || !order.IsActive) return false;
         if (!await HasStoreScopeAsync(order.FK_StoreId)) return false;
+
+        var sale = await saleRepo.GetByIdAsync(order.FK_SaleId);
+
         await uow.BeginAsync(ct);
         try
         {
             repo.Remove(order);
+            if (sale is not null)
+            {
+                sale.Status = SaleStatus.Cancelled;
+                sale.CompletedAt = null;
+                saleRepo.Update(sale);
+            }
             await uow.CommitAsync(ct);
         }
         catch

Distribution/Features/Payment/IPaymentRepository.cs

@@ -0,0 +1,9 @@
+using Distribution.Models;
+
+namespace Distribution.Features.Payment;
+
+public interface IPaymentRepository
+{
+    Task<List<Models.Payment>> GetBySaleIdAsync(Guid saleId);
+    Task AddAsync(Models.Payment payment);
+}

Distribution/Features/Payment/PaymentController.cs

@@ -0,0 +1,28 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.Payment;
+
+[ApiController]
+[Authorize]
+[Route("api/sales/{saleId:guid}/payments")]
+public class PaymentController(PaymentService service) : ControllerBase
+{
+    [HttpGet]
+    public async Task<IActionResult> GetBySale(Guid saleId)
+    {
+        var result = await service.GetBySaleIdAsync(saleId);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost]
+    public async Task<IActionResult> Create(Guid saleId, CreatePaymentRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.CreateAsync(saleId, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+}

Distribution/Features/Payment/PaymentDTOs.cs

@@ -0,0 +1,15 @@
+using Distribution.Models;
+
+namespace Distribution.Features.Payment;
+
+public record CreatePaymentRequest(decimal Amount, PaymentMethod Method);
+
+public record PaymentResponse(
+    Guid Id,
+    Guid SaleId,
+    Guid StoreId,
+    decimal Amount,
+    PaymentMethod Method,
+    DateTime CollectedAt,
+    Guid CollectedBy,
+    DateTime CreatedAt);

Distribution/Features/Payment/PaymentRepository.cs

@@ -0,0 +1,17 @@
+using Distribution.Data;
+using Distribution.Models;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.Payment;
+
+public class PaymentRepository(AppDBContext context) : IPaymentRepository
+{
+    public async Task<List<Models.Payment>> GetBySaleIdAsync(Guid saleId) =>
+        await context.Payments
+            .Where(p => p.FK_SaleId == saleId && p.IsActive)
+            .OrderBy(p => p.CollectedAt)
+            .ToListAsync();
+
+    public async Task AddAsync(Models.Payment payment) =>
+        await context.Payments.AddAsync(payment);
+}

Distribution/Features/Payment/PaymentService.cs

@@ -0,0 +1,67 @@
+using Distribution.Features.Sale;
+using Distribution.Infra.Authorization;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+
+namespace Distribution.Features.Payment;
+
+public class PaymentService(
+    IPaymentRepository repo,
+    ISaleRepository saleRepo,
+    IUnitOfWork uow,
+    ICurrentUserService currentUser)
+{
+    private static PaymentResponse ToResponse(Models.Payment p) =>
+        new(p.Id, p.FK_SaleId, p.FK_StoreId, p.Amount, p.Method, p.CollectedAt, p.CollectedBy, p.CreatedAt);
+
+    public async Task<List<PaymentResponse>?> GetBySaleIdAsync(Guid saleId)
+    {
+        var sale = await saleRepo.GetByIdAsync(saleId);
+        if (sale is null || !sale.IsActive) return null;
+
+        var payments = await repo.GetBySaleIdAsync(saleId);
+        return payments.Select(ToResponse).ToList();
+    }
+
+    public async Task<PaymentResponse?> CreateAsync(Guid saleId, CreatePaymentRequest request, CancellationToken ct = default)
+    {
+        var sale = await saleRepo.GetByIdAsync(saleId);
+        if (sale is null || !sale.IsActive) return null;
+        if (sale.Status == SaleStatus.Cancelled)
+            throw new InvalidOperationException("Cannot record a payment against a cancelled sale");
+
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+
+        var payment = new Models.Payment
+        {
+            FK_SaleId = saleId,
+            FK_StoreId = sale.FK_StoreId,
+            Amount = request.Amount,
+            Method = request.Method,
+            CollectedAt = DateTime.Now,
+            CollectedBy = userId
+        };
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            await repo.AddAsync(payment);
+
+            var allPayments = await repo.GetBySaleIdAsync(saleId);
+            var total = allPayments.Sum(p => p.Amount) + request.Amount;
+
+            sale.PaymentStatus = total == 0
+                ? PaymentStatus.Pending
+                : total < sale.TotalAmount
+                    ? PaymentStatus.PartiallyPaid
+                    : PaymentStatus.Paid;
+
+            saleRepo.Update(sale);
+
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return ToResponse(payment);
+    }
+}

Distribution/Features/PurchaseOrder/IPoRepository.cs

@@ -0,0 +1,19 @@
+using Distribution.Models;
+
+namespace Distribution.Features.Po;
+
+public interface IPoRepository
+{
+    Task<Models.PurchaseOrder?> GetByIdAsync(Guid id);
+    Task<List<Models.PurchaseOrder>> GetAllAsync(Guid? supplierId, PurchaseOrderStatus? status);
+    Task AddAsync(Models.PurchaseOrder entity);
+    void Update(Models.PurchaseOrder entity);
+
+    Task AddItemAsync(PurchaseOrderItem entity);
+
+    /// <summary>True if any active (non-cancelled, non-closed-and-void) PurchaseOrder references this supplier.</summary>
+    Task<bool> HasActiveForSupplierAsync(Guid supplierId);
+
+    /// <summary>All active PurchaseOrders for a supplier, with items, used by evaluateSupplier.</summary>
+    Task<List<Models.PurchaseOrder>> GetBySupplierAsync(Guid supplierId);
+}

Distribution/Features/PurchaseOrder/PoController.cs

@@ -0,0 +1,97 @@
+using Distribution.Infra.Authorization;
+using Distribution.Models;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.Po;
+
+[ApiController]
+[Route("api/purchase-orders")]
+[Authorize]
+public class PoController(PoService service, ICurrentUserService currentUser) : ControllerBase
+{
+    [HttpGet]
+    public async Task<IActionResult> GetAll([FromQuery] Guid? supplierId, [FromQuery] PurchaseOrderStatus? status) =>
+        Ok(await service.GetAllAsync(supplierId, status));
+
+    [HttpGet("{id:guid}")]
+    public async Task<IActionResult> GetById(Guid id)
+    {
+        var result = await service.GetByIdAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost]
+    public async Task<IActionResult> Create(CreatePoRequest request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        try
+        {
+            var result = await service.CreateAsync(request, userId, ct);
+            return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+
+    [HttpPut("{id:guid}")]
+    public async Task<IActionResult> Update(Guid id, UpdatePoRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.UpdateAsync(id, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+
+    [HttpPost("{id:guid}/close")]
+    public async Task<IActionResult> Close(Guid id, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.CloseAsync(id, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+
+    [HttpPost("{id:guid}/cancel")]
+    public async Task<IActionResult> Cancel(Guid id, CancelPoRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.CancelAsync(id, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+
+    [HttpPost("{id:guid}/items/{itemId:guid}/cancel")]
+    public async Task<IActionResult> CancelLine(Guid id, Guid itemId, CancelPoLineRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.CancelLineAsync(id, itemId, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+
+    [HttpPost("{id:guid}/match-invoice")]
+    public async Task<IActionResult> MatchInvoice(Guid id, [FromQuery] Guid? invoiceId, [FromQuery] Guid? grnId)
+    {
+        var result = await service.MatchInvoiceToPoAsync(id, invoiceId, grnId);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost("{id:guid}/resolve-variance")]
+    public async Task<IActionResult> ResolveVariance(Guid id, ResolveInvoiceVarianceRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.ResolveInvoiceVarianceAsync(id, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+}

Distribution/Features/PurchaseOrder/PoDTOs.cs

@@ -0,0 +1,54 @@
+using Distribution.Models;
+
+namespace Distribution.Features.Po;
+
+public record PoItemRequest(Guid ItemId, int Quantity, decimal UnitCost);
+
+public record CreatePoRequest(Guid SupplierId, List<PoItemRequest> Items);
+
+/// <summary>
+/// Update line: PurchaseOrderItemId set = update an existing unreceived line (Quantity/UnitCost),
+/// null = add a new line to the Po. Only valid while the Po is Issued.
+/// </summary>
+public record UpdatePoLineRequest(Guid? PurchaseOrderItemId, Guid ItemId, int Quantity, decimal UnitCost);
+
+public record UpdatePoRequest(List<UpdatePoLineRequest> Items);
+
+public record CancelPoRequest(string Reason);
+
+public record CancelPoLineRequest(string? Reason);
+
+public record PoItemResponse(
+    Guid Id,
+    Guid ItemId,
+    string Sku,
+    string ItemName,
+    int Quantity,
+    decimal UnitCost,
+    int ReceivedQuantity,
+    int CancelledQuantity,
+    bool IsCancelled);
+
+public record PoResponse(
+    Guid Id,
+    Guid SupplierId,
+    string SupplierName,
+    Guid CreatedByUserId,
+    PurchaseOrderStatus Status,
+    string? CancelReason,
+    bool IsActive,
+    DateTime CreatedAt,
+    List<PoItemResponse> Items);
+
+/// <summary>
+/// Minimal Po-vs-Grn quantity/cost reconciliation. Full 3-way match (Po + Grn + Invoice) activates
+/// once Finance's Invoice entity (step 19, not yet built) exists — until then this compares only
+/// PurchaseOrderItem vs GoodsReceiptItem.
+/// </summary>
+public record InvoiceMatchLineResult(Guid PurchaseOrderItemId, Guid ItemId, int OrderedQuantity, int AcceptedQuantity, decimal UnitCost, bool QuantityMatches);
+
+public record InvoiceMatchResult(Guid PurchaseOrderId, Guid? GoodsReceiptId, Guid? InvoiceId, bool IsMatched, List<InvoiceMatchLineResult> Lines, string Note);
+
+public record ResolveInvoiceVarianceRequest(string Variance, string Resolution, decimal? AdjustedUnitCost, Guid? PurchaseOrderItemId);
+
+public record InvoiceVarianceResolutionResponse(Guid PurchaseOrderId, string Variance, string Resolution, DateTime ResolvedAt);

Distribution/Features/PurchaseOrder/PoRepository.cs

@@ -0,0 +1,49 @@
+using Distribution.Data;
+using Distribution.Models;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.Po;
+
+public class PoRepository(AppDBContext context) : IPoRepository
+{
+    public async Task<Models.PurchaseOrder?> GetByIdAsync(Guid id) =>
+        await context.PurchaseOrders
+            .Include(po => po.Supplier)
+            .Include(po => po.Items).ThenInclude(i => i.Item)
+            .FirstOrDefaultAsync(po => po.Id == id);
+
+    public async Task<List<Models.PurchaseOrder>> GetAllAsync(Guid? supplierId, PurchaseOrderStatus? status)
+    {
+        var query = context.PurchaseOrders
+            .Include(po => po.Supplier)
+            .Include(po => po.Items).ThenInclude(i => i.Item)
+            .Where(po => po.IsActive)
+            .AsQueryable();
+
+        if (supplierId.HasValue) query = query.Where(po => po.FK_SupplierId == supplierId.Value);
+        if (status.HasValue) query = query.Where(po => po.Status == status.Value);
+
+        return await query.OrderByDescending(po => po.CreatedAt).ToListAsync();
+    }
+
+    public async Task AddAsync(Models.PurchaseOrder entity) =>
+        await context.PurchaseOrders.AddAsync(entity);
+
+    public void Update(Models.PurchaseOrder entity) =>
+        context.PurchaseOrders.Update(entity);
+
+    public async Task AddItemAsync(PurchaseOrderItem entity) =>
+        await context.PurchaseOrderItems.AddAsync(entity);
+
+    public async Task<bool> HasActiveForSupplierAsync(Guid supplierId) =>
+        await context.PurchaseOrders.AnyAsync(po =>
+            po.FK_SupplierId == supplierId &&
+            po.IsActive &&
+            po.Status != PurchaseOrderStatus.Cancelled);
+
+    public async Task<List<Models.PurchaseOrder>> GetBySupplierAsync(Guid supplierId) =>
+        await context.PurchaseOrders
+            .Include(po => po.Items)
+            .Where(po => po.FK_SupplierId == supplierId && po.IsActive)
+            .ToListAsync();
+}

Distribution/Features/PurchaseOrder/PoService.cs

@@ -0,0 +1,245 @@
+using Distribution.Features.Grn;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+
+namespace Distribution.Features.Po;
+
+public class PoService(
+    IPoRepository repo,
+    IGrnRepository goodsReceiptRepo,
+    IUnitOfWork uow)
+{
+    private static PoItemResponse MapItem(PurchaseOrderItem i) =>
+        new(i.Id, i.FK_ItemId, i.Item.Sku, i.Item.Name, i.Quantity, i.UnitCost, i.ReceivedQuantity, i.CancelledQuantity, i.IsCancelled);
+
+    private static PoResponse Map(Models.PurchaseOrder po) =>
+        new(po.Id, po.FK_SupplierId, po.Supplier?.Name ?? string.Empty, po.FK_CreatedByUserId,
+            po.Status, po.CancelReason, po.IsActive, po.CreatedAt,
+            po.Items.Where(i => i.IsActive).Select(MapItem).ToList());
+
+    public async Task<List<PoResponse>> GetAllAsync(Guid? supplierId, PurchaseOrderStatus? status) =>
+        (await repo.GetAllAsync(supplierId, status)).Select(Map).ToList();
+
+    public async Task<PoResponse?> GetByIdAsync(Guid id)
+    {
+        var po = await repo.GetByIdAsync(id);
+        if (po is null || !po.IsActive) return null;
+        return Map(po);
+    }
+
+    public async Task<PoResponse> CreateAsync(CreatePoRequest request, Guid createdByUserId, CancellationToken ct = default)
+    {
+        if (request.Items is null || request.Items.Count == 0)
+            throw new InvalidOperationException("A purchase order must have at least one line item.");
+
+        var po = new Models.PurchaseOrder
+        {
+            FK_SupplierId = request.SupplierId,
+            FK_CreatedByUserId = createdByUserId,
+            Status = PurchaseOrderStatus.Issued
+        };
+
+        foreach (var line in request.Items)
+        {
+            po.Items.Add(new PurchaseOrderItem
+            {
+                FK_ItemId = line.ItemId,
+                Quantity = line.Quantity,
+                UnitCost = line.UnitCost
+            });
+        }
+
+        await uow.BeginAsync(ct);
+        try { await repo.AddAsync(po); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return (await GetByIdAsync(po.Id))!;
+    }
+
+    /// <summary>
+    /// May only change unreceived lines (ReceivedQuantity == 0) and only while the Po is Issued.
+    /// Lines with a PurchaseOrderItemId update an existing line; lines without one add a new line.
+    /// </summary>
+    public async Task<PoResponse?> UpdateAsync(Guid id, UpdatePoRequest request, CancellationToken ct = default)
+    {
+        var po = await repo.GetByIdAsync(id);
+        if (po is null || !po.IsActive) return null;
+
+        if (po.Status != PurchaseOrderStatus.Issued)
+            throw new InvalidOperationException($"Cannot update a purchase order in {po.Status} status; only an Issued Po can be updated.");
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            foreach (var line in request.Items)
+            {
+                if (line.PurchaseOrderItemId.HasValue)
+                {
+                    var existing = po.Items.FirstOrDefault(i => i.Id == line.PurchaseOrderItemId.Value && i.IsActive)
+                        ?? throw new InvalidOperationException($"Purchase order line {line.PurchaseOrderItemId} not found on this Po.");
+
+                    if (existing.ReceivedQuantity > 0)
+                        throw new InvalidOperationException(
+                            $"Line for item {existing.FK_ItemId} has already received stock and cannot be edited; use cancelPurchaseOrderLine or createPurchaseReturn instead.");
+
+                    existing.FK_ItemId = line.ItemId;
+                    existing.Quantity = line.Quantity;
+                    existing.UnitCost = line.UnitCost;
+                }
+                else
+                {
+                    await repo.AddItemAsync(new PurchaseOrderItem
+                    {
+                        FK_PurchaseOrderId = po.Id,
+                        FK_ItemId = line.ItemId,
+                        Quantity = line.Quantity,
+                        UnitCost = line.UnitCost
+                    });
+                }
+            }
+
+            repo.Update(po);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return (await GetByIdAsync(id))!;
+    }
+
+    /// <summary>
+    /// Only valid once a Po is Received, or manually closed early (outstanding quantity written off).
+    /// </summary>
+    public async Task<PoResponse?> CloseAsync(Guid id, CancellationToken ct = default)
+    {
+        var po = await repo.GetByIdAsync(id);
+        if (po is null || !po.IsActive) return null;
+
+        if (po.Status is PurchaseOrderStatus.Closed or PurchaseOrderStatus.Cancelled)
+            throw new InvalidOperationException($"Cannot close a purchase order already in {po.Status} status.");
+
+        po.Status = PurchaseOrderStatus.Closed;
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(po); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return Map(po);
+    }
+
+    /// <summary>Only valid before any goods receipt exists against the Po.</summary>
+    public async Task<PoResponse?> CancelAsync(Guid id, CancelPoRequest request, CancellationToken ct = default)
+    {
+        var po = await repo.GetByIdAsync(id);
+        if (po is null || !po.IsActive) return null;
+
+        if (po.Status is PurchaseOrderStatus.Closed or PurchaseOrderStatus.Cancelled)
+            throw new InvalidOperationException($"Cannot cancel a purchase order already in {po.Status} status.");
+
+        if (await goodsReceiptRepo.HasAnyForPurchaseOrderAsync(id))
+            throw new InvalidOperationException("Cannot cancel a purchase order that already has a goods receipt against it.");
+
+        po.Status = PurchaseOrderStatus.Cancelled;
+        po.CancelReason = request.Reason;
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(po); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return Map(po);
+    }
+
+    /// <summary>
+    /// Cancels a single line instead of the whole Po. Only valid while ReceivedQuantity &lt; Quantity
+    /// and the line isn't already fully received or cancelled. Auto-completes the Po to Received once
+    /// every non-cancelled line is fully received.
+    /// </summary>
+    public async Task<PoResponse?> CancelLineAsync(Guid id, Guid poItemId, CancelPoLineRequest request, CancellationToken ct = default)
+    {
+        var po = await repo.GetByIdAsync(id);
+        if (po is null || !po.IsActive) return null;
+
+        var line = po.Items.FirstOrDefault(i => i.Id == poItemId && i.IsActive)
+            ?? throw new InvalidOperationException("Purchase order line not found on this Po.");
+
+        if (line.IsCancelled)
+            throw new InvalidOperationException("This line is already cancelled.");
+
+        if (line.ReceivedQuantity >= line.Quantity)
+            throw new InvalidOperationException("This line is already fully received and cannot be cancelled.");
+
+        line.IsCancelled = true;
+        line.CancelledQuantity = line.Quantity - line.ReceivedQuantity;
+
+        var activeLines = po.Items.Where(i => i.IsActive).ToList();
+        if (activeLines.Where(i => !i.IsCancelled).All(i => i.ReceivedQuantity >= i.Quantity)
+            && activeLines.Any(i => !i.IsCancelled))
+        {
+            po.Status = PurchaseOrderStatus.Received;
+        }
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(po); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return Map(po);
+    }
+
+    /// <summary>
+    /// Minimal Po-vs-Grn reconciliation (matchInvoiceToPo). Full 3-way match against an Invoice
+    /// entity activates once Finance (step 19) exists; this only detects and reports, never adjusts.
+    /// </summary>
+    public async Task<InvoiceMatchResult?> MatchInvoiceToPoAsync(Guid poId, Guid? invoiceId, Guid? grnId)
+    {
+        var po = await repo.GetByIdAsync(poId);
+        if (po is null || !po.IsActive) return null;
+
+        var receipts = grnId.HasValue
+            ? (await goodsReceiptRepo.GetByPurchaseOrderIdAsync(poId)).Where(g => g.Id == grnId.Value).ToList()
+            : await goodsReceiptRepo.GetByPurchaseOrderIdAsync(poId);
+
+        var acceptedByItem = receipts
+            .SelectMany(g => g.Items.Where(i => i.IsActive))
+            .GroupBy(i => i.PurchaseOrderItem.FK_ItemId)
+            .ToDictionary(g => g.Key, g => g.Sum(i => i.AcceptedQuantity));
+
+        var lines = po.Items.Where(i => i.IsActive).Select(i =>
+        {
+            acceptedByItem.TryGetValue(i.FK_ItemId, out var accepted);
+            return new InvoiceMatchLineResult(i.Id, i.FK_ItemId, i.Quantity, accepted, i.UnitCost, accepted == i.Quantity);
+        }).ToList();
+
+        var isMatched = lines.All(l => l.QuantityMatches);
+
+        return new InvoiceMatchResult(
+            poId, grnId, invoiceId, isMatched, lines,
+            "Compares PurchaseOrderItem.Quantity against GoodsReceiptItem.AcceptedQuantity only; " +
+            "invoice line comparison activates once Finance's Invoice entity (step 19) exists.");
+    }
+
+    /// <summary>
+    /// Records a Po/Grn(/invoice) variance and its resolution. Never silently adjusts anything except
+    /// when the resolution explicitly requests a retroactive UnitCost adjustment on a named line.
+    /// </summary>
+    public async Task<InvoiceVarianceResolutionResponse?> ResolveInvoiceVarianceAsync(Guid poId, ResolveInvoiceVarianceRequest request, CancellationToken ct = default)
+    {
+        var po = await repo.GetByIdAsync(poId);
+        if (po is null || !po.IsActive) return null;
+
+        if (request.AdjustedUnitCost.HasValue)
+        {
+            if (!request.PurchaseOrderItemId.HasValue)
+                throw new InvalidOperationException("PurchaseOrderItemId is required when adjusting UnitCost.");
+
+            var line = po.Items.FirstOrDefault(i => i.Id == request.PurchaseOrderItemId.Value && i.IsActive)
+                ?? throw new InvalidOperationException("Purchase order line not found on this Po.");
+
+            line.UnitCost = request.AdjustedUnitCost.Value;
+
+            await uow.BeginAsync(ct);
+            try { repo.Update(po); await uow.CommitAsync(ct); }
+            catch { await uow.RollbackAsync(ct); throw; }
+        }
+
+        return new InvoiceVarianceResolutionResponse(poId, request.Variance, request.Resolution, DateTime.Now);
+    }
+}

Distribution/Features/PurchaseReturn/IPurchaseReturnRepository.cs

@@ -0,0 +1,11 @@
+namespace Distribution.Features.PurchaseReturn;
+
+public interface IPurchaseReturnRepository
+{
+    Task<Models.PurchaseReturn?> GetByIdAsync(Guid id);
+    Task<List<Models.PurchaseReturn>> GetByPurchaseOrderIdAsync(Guid purchaseOrderId);
+    Task AddAsync(Models.PurchaseReturn entity);
+
+    /// <summary>Sum of Quantity per ItemId across all prior returns for a Po.</summary>
+    Task<Dictionary<Guid, int>> GetReturnedTotalsByItemAsync(Guid purchaseOrderId);
+}

Distribution/Features/PurchaseReturn/PurchaseReturnController.cs

@@ -0,0 +1,33 @@
+using Distribution.Infra.Authorization;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.PurchaseReturn;
+
+[ApiController]
+[Authorize]
+public class PurchaseReturnController(PurchaseReturnService service, ICurrentUserService currentUser) : ControllerBase
+{
+    [HttpGet("api/purchase-returns/{id:guid}")]
+    public async Task<IActionResult> GetById(Guid id)
+    {
+        var result = await service.GetByIdAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpGet("api/purchase-orders/{id:guid}/returns")]
+    public async Task<IActionResult> GetByPurchaseOrder(Guid id) =>
+        Ok(await service.GetByPurchaseOrderIdAsync(id));
+
+    [HttpPost("api/purchase-orders/{id:guid}/returns")]
+    public async Task<IActionResult> Create(Guid id, CreatePurchaseReturnRequest request, CancellationToken ct)
+    {
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        try
+        {
+            var result = await service.CreateAsync(id, request, userId, ct);
+            return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+}

Distribution/Features/PurchaseReturn/PurchaseReturnDTOs.cs

@@ -0,0 +1,15 @@
+namespace Distribution.Features.PurchaseReturn;
+
+public record PurchaseReturnItemRequest(Guid ItemId, int Quantity);
+
+public record CreatePurchaseReturnRequest(string Reason, List<PurchaseReturnItemRequest> Items);
+
+public record PurchaseReturnItemResponse(Guid Id, Guid ItemId, string Sku, string ItemName, int Quantity);
+
+public record PurchaseReturnResponse(
+    Guid Id,
+    Guid PurchaseOrderId,
+    string Reason,
+    bool IsActive,
+    DateTime CreatedAt,
+    List<PurchaseReturnItemResponse> Items);

Distribution/Features/PurchaseReturn/PurchaseReturnRepository.cs

@@ -0,0 +1,30 @@
+using Distribution.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.PurchaseReturn;
+
+public class PurchaseReturnRepository(AppDBContext context) : IPurchaseReturnRepository
+{
+    public async Task<Models.PurchaseReturn?> GetByIdAsync(Guid id) =>
+        await context.PurchaseReturns
+            .Include(pr => pr.Items).ThenInclude(i => i.Item)
+            .FirstOrDefaultAsync(pr => pr.Id == id);
+
+    public async Task<List<Models.PurchaseReturn>> GetByPurchaseOrderIdAsync(Guid purchaseOrderId) =>
+        await context.PurchaseReturns
+            .Include(pr => pr.Items).ThenInclude(i => i.Item)
+            .Where(pr => pr.FK_PurchaseOrderId == purchaseOrderId && pr.IsActive)
+            .OrderByDescending(pr => pr.CreatedAt)
+            .ToListAsync();
+
+    public async Task AddAsync(Models.PurchaseReturn entity) =>
+        await context.PurchaseReturns.AddAsync(entity);
+
+    public async Task<Dictionary<Guid, int>> GetReturnedTotalsByItemAsync(Guid purchaseOrderId) =>
+        await context.PurchaseReturnItems
+            .Include(i => i.PurchaseReturn)
+            .Where(i => i.PurchaseReturn.FK_PurchaseOrderId == purchaseOrderId && i.IsActive)
+            .GroupBy(i => i.FK_ItemId)
+            .Select(g => new { ItemId = g.Key, Total = g.Sum(i => i.Quantity) })
+            .ToDictionaryAsync(x => x.ItemId, x => x.Total);
+}

Distribution/Features/PurchaseReturn/PurchaseReturnService.cs

@@ -0,0 +1,122 @@
+using Distribution.Features.Grn;
+using Distribution.Features.Po;
+using Distribution.Features.Stock;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+
+namespace Distribution.Features.PurchaseReturn;
+
+public class PurchaseReturnService(
+    IPurchaseReturnRepository repo,
+    IPoRepository poRepo,
+    IGrnRepository goodsReceiptRepo,
+    IStockRepository stockRepo,
+    IUnitOfWork uow)
+{
+    private static PurchaseReturnItemResponse MapItem(Models.PurchaseReturnItem i) =>
+        new(i.Id, i.FK_ItemId, i.Item.Sku, i.Item.Name, i.Quantity);
+
+    private static PurchaseReturnResponse Map(Models.PurchaseReturn pr) =>
+        new(pr.Id, pr.FK_PurchaseOrderId, pr.Reason, pr.IsActive, pr.CreatedAt,
+            pr.Items.Where(i => i.IsActive).Select(MapItem).ToList());
+
+    public async Task<PurchaseReturnResponse?> GetByIdAsync(Guid id)
+    {
+        var pr = await repo.GetByIdAsync(id);
+        if (pr is null || !pr.IsActive) return null;
+        return Map(pr);
+    }
+
+    public async Task<List<PurchaseReturnResponse>> GetByPurchaseOrderIdAsync(Guid purchaseOrderId) =>
+        (await repo.GetByPurchaseOrderIdAsync(purchaseOrderId)).Select(Map).ToList();
+
+    /// <summary>
+    /// Requires at least one prior GoodsReceipt against the Po; return quantities per item cannot
+    /// exceed the received-but-not-already-returned quantity for that item. Decrements StockBalance
+    /// and writes a StockMovement in the same unit of work.
+    /// </summary>
+    public async Task<PurchaseReturnResponse> CreateAsync(Guid purchaseOrderId, CreatePurchaseReturnRequest request, Guid createdByUserId, CancellationToken ct = default)
+    {
+        var po = await poRepo.GetByIdAsync(purchaseOrderId);
+        if (po is null || !po.IsActive)
+            throw new InvalidOperationException("Purchase order not found.");
+
+        if (!await goodsReceiptRepo.HasAnyForPurchaseOrderAsync(purchaseOrderId))
+            throw new InvalidOperationException("Cannot return items for a purchase order with no goods receipt against it.");
+
+        if (request.Items is null || request.Items.Count == 0)
+            throw new InvalidOperationException("A purchase return must have at least one line item.");
+
+        var receivedTotals = await goodsReceiptRepo.GetAcceptedTotalsByItemAsync(purchaseOrderId);
+        var returnedTotals = await repo.GetReturnedTotalsByItemAsync(purchaseOrderId);
+
+        // The receipt(s) for this Po share a single receiving warehouse per the current model
+        // (each GoodsReceipt carries FK_WarehouseId); use the most recent receipt's warehouse
+        // as the stock-decrement location for the return.
+        var receipts = await goodsReceiptRepo.GetByPurchaseOrderIdAsync(purchaseOrderId);
+        var warehouseId = receipts.First().FK_WarehouseId;
+
+        var purchaseReturn = new Models.PurchaseReturn
+        {
+            FK_PurchaseOrderId = purchaseOrderId,
+            Reason = request.Reason
+        };
+
+        foreach (var line in request.Items)
+        {
+            if (line.Quantity <= 0)
+                throw new InvalidOperationException("Return quantity must be greater than zero.");
+
+            receivedTotals.TryGetValue(line.ItemId, out var received);
+            returnedTotals.TryGetValue(line.ItemId, out var alreadyReturned);
+            var available = received - alreadyReturned;
+
+            if (line.Quantity > available)
+                throw new InvalidOperationException(
+                    $"Return quantity for item {line.ItemId} ({line.Quantity}) exceeds the received-but-not-already-returned quantity ({available}).");
+
+            purchaseReturn.Items.Add(new Models.PurchaseReturnItem
+            {
+                FK_ItemId = line.ItemId,
+                Quantity = line.Quantity
+            });
+        }
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            await repo.AddAsync(purchaseReturn);
+
+            foreach (var line in purchaseReturn.Items)
+            {
+                var balance = await stockRepo.GetBalanceAsync(line.FK_ItemId, warehouseId)
+                    ?? throw new InvalidOperationException($"No stock balance found for item {line.FK_ItemId} at the receiving warehouse.");
+
+                if (balance.Quantity < line.Quantity)
+                    throw new InvalidOperationException($"Insufficient warehouse stock for item {line.FK_ItemId} to return.");
+
+                balance.Quantity -= line.Quantity;
+                balance.UpdatedAt = DateTime.Now;
+                stockRepo.UpdateBalance(balance);
+
+                await stockRepo.AddMovementAsync(new StockMovement
+                {
+                    FK_ItemId = line.FK_ItemId,
+                    FromLocationId = warehouseId,
+                    FromLocationType = LocationType.Warehouse,
+                    Quantity = line.Quantity,
+                    Type = MovementType.PurchaseReturn,
+                    ReasonCode = request.Reason,
+                    ReferenceId = purchaseReturn.Id,
+                    CreatedBy = createdByUserId
+                });
+            }
+
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        var saved = await repo.GetByIdAsync(purchaseReturn.Id);
+        return Map(saved!);
+    }
+}

Distribution/Features/Ride/RideService.cs

@@ -39,7 +39,7 @@ public class RideService(
         var vehicle = await vehicleRepo.GetByIdAsync(request.FK_VehicleId)
             ?? throw new InvalidOperationException("Vehicle not found");
 
-        var sourceWarehouseId = vehicle.FK_DefaultWarehouseId ?? request.FK_SourceWarehouseId;
+        var sourceWarehouseId = vehicle.DefaultWarehouseId ?? request.FK_SourceWarehouseId;
         if (!sourceWarehouseId.HasValue)
             throw new InvalidOperationException("Source warehouse is required for this vehicle");
 

Distribution/Features/Sale/ISaleRepository.cs

@@ -0,0 +1,14 @@
+using Distribution.Models;
+
+namespace Distribution.Features.Sale;
+
+public interface ISaleRepository
+{
+    Task<Models.Sale?> GetByIdAsync(Guid id);
+    Task<List<Models.Sale>> GetAllAsync();
+    Task<List<Models.Sale>> GetByStoreIdAsync(Guid storeId);
+    Task AddAsync(Models.Sale sale);
+    void Update(Models.Sale sale);
+    void Remove(Models.Sale sale);
+    Task<Models.Order?> GetOrderBySaleIdAsync(Guid saleId);
+}

Distribution/Features/Sale/SaleController.cs

@@ -0,0 +1,39 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.Sale;
+
+[ApiController]
+[Route("api/sales")]
+[Authorize]
+public class SaleController(SaleService service) : ControllerBase
+{
+    [HttpGet]
+    [Authorize(Policy = "orders.view")]
+    public async Task<IActionResult> GetAll() =>
+        Ok(await service.GetAllAsync());
+
+    [HttpGet("{id:guid}")]
+    [Authorize(Policy = "orders.view")]
+    public async Task<IActionResult> GetById(Guid id)
+    {
+        var result = await service.GetByIdAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpGet("store/{storeId:guid}")]
+    [Authorize(Policy = "orders.view")]
+    public async Task<IActionResult> GetByStore(Guid storeId)
+    {
+        var result = await service.GetByStoreIdAsync(storeId);
+        return result is null ? Forbid() : Ok(result);
+    }
+
+    [HttpPost]
+    [Authorize(Policy = "orders.create")]
+    public async Task<IActionResult> Create(CreateSaleRequest request, CancellationToken ct)
+    {
+        var result = await service.CreateAsync(request, ct);
+        return result is null ? Forbid() : CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+    }
+}

Distribution/Features/Sale/SaleDTOs.cs

@@ -0,0 +1,33 @@
+using Distribution.Models;
+
+namespace Distribution.Features.Sale;
+
+public record SaleItemRequest(Guid ItemId, int Quantity, decimal? UnitPrice = null);
+
+public record CreateSaleRequest(
+    Guid StoreId,
+    DateTime SaleDate,
+    decimal TotalAmount,
+    bool FulfillImmediately,
+    Guid? RideId,
+    List<SaleItemRequest> Items);
+
+public record SaleItemResponse(Guid ItemId, int Quantity, int QuantityFulfilled, decimal UnitPrice);
+
+public record SaleResponse(
+    Guid Id,
+    DateTime SaleDate,
+    Guid StoreId,
+    Guid CreatedByUserId,
+    Guid? RideId,
+    decimal TotalAmount,
+    SaleStatus Status,
+    PaymentStatus PaymentStatus,
+    bool FulfillImmediately,
+    DateTime? CompletedAt,
+    Guid OrderId,
+    OrderStatus OrderStatus,
+    DateTime? OrderFulfilledAt,
+    List<SaleItemResponse> Items,
+    bool IsActive,
+    DateTime CreatedAt);

Distribution/Features/Sale/SaleRepository.cs

@@ -0,0 +1,32 @@
+using Distribution.Data;
+using Distribution.Models;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.Sale;
+
+public class SaleRepository(AppDBContext context) : ISaleRepository
+{
+    public async Task<Models.Sale?> GetByIdAsync(Guid id) =>
+        await context.Sales.FindAsync(id);
+
+    public async Task<List<Models.Sale>> GetAllAsync() =>
+        await context.Sales.ToListAsync();
+
+    public async Task<List<Models.Sale>> GetByStoreIdAsync(Guid storeId) =>
+        await context.Sales.Where(s => s.FK_StoreId == storeId && s.IsActive).ToListAsync();
+
+    public async Task AddAsync(Models.Sale sale) =>
+        await context.Sales.AddAsync(sale);
+
+    public void Update(Models.Sale sale) =>
+        context.Sales.Update(sale);
+
+    public void Remove(Models.Sale sale)
+    {
+        sale.IsActive = false;
+        context.Sales.Update(sale);
+    }
+
+    public async Task<Models.Order?> GetOrderBySaleIdAsync(Guid saleId) =>
+        await context.Orders.FirstOrDefaultAsync(o => o.FK_SaleId == saleId && o.IsActive);
+}

Distribution/Features/Sale/SaleService.cs

@@ -0,0 +1,233 @@
+using Distribution.Features.Item;
+using Distribution.Features.Order;
+using Distribution.Features.PriceList;
+using Distribution.Features.Ride;
+using Distribution.Features.Stock;
+using Distribution.Features.Store;
+using Distribution.Infra.Authorization;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+using Microsoft.Extensions.Configuration;
+
+namespace Distribution.Features.Sale;
+
+public class SaleService(
+    ISaleRepository repo,
+    IOrderRepository orderRepo,
+    IStoreRepository storeRepo,
+    IItemRepository itemRepo,
+    PriceListService priceListService,
+    IStockRepository stockRepo,
+    IRideRepository rideRepo,
+    IUnitOfWork uow,
+    ICurrentUserService currentUser,
+    IScopeAccessService scopeAccess,
+    IConfiguration configuration)
+{
+    private const int GlobalScopeRoleLevel = 50;
+
+    private bool HasGlobalScope => currentUser.RoleLevel >= GlobalScopeRoleLevel;
+
+    private async Task<bool> HasStoreScopeAsync(Guid storeId)
+    {
+        if (HasGlobalScope || currentUser.UserId is null) return HasGlobalScope;
+        return await scopeAccess.HasStoreScopeAsync(currentUser.UserId.Value, storeId);
+    }
+
+    private async Task<decimal?> ResolveUnitPriceAsync(Guid itemId, decimal? requestedUnitPrice, Models.Store store, DateTime saleDate)
+    {
+        var item = await itemRepo.GetByIdAsync(itemId);
+        if (item is null) return null;
+
+        var regionId = store.Route?.FK_RegionId;
+        var resolution = await priceListService.ResolvePriceAsync(itemId, regionId, item.SalePrice, saleDate);
+        if (resolution is null) return null;
+
+        if (!requestedUnitPrice.HasValue) return resolution.Price;
+
+        var min = resolution.MinPrice ?? resolution.Price;
+        var max = resolution.Price;
+        if (requestedUnitPrice.Value < min || requestedUnitPrice.Value > max) return null;
+
+        return requestedUnitPrice.Value;
+    }
+
+    private static SaleResponse ToResponse(Models.Sale sale, Models.Order order, List<Models.OrderItem> items) =>
+        new(
+            sale.Id,
+            sale.SaleDate,
+            sale.FK_StoreId,
+            sale.CreatedByUserId,
+            sale.FK_RideId,
+            sale.TotalAmount,
+            sale.Status,
+            sale.PaymentStatus,
+            sale.FulfillImmediately,
+            sale.CompletedAt,
+            order.Id,
+            order.Status,
+            order.FulfilledAt,
+            items.Select(i => new SaleItemResponse(i.FK_ItemId, i.Quantity, i.QuantityFulfilled, i.UnitPrice)).ToList(),
+            sale.IsActive,
+            sale.CreatedAt);
+
+    public async Task<List<SaleResponse>> GetAllAsync()
+    {
+        var sales = (await repo.GetAllAsync()).Where(s => s.IsActive).ToList();
+        if (!HasGlobalScope && currentUser.UserId is not null)
+        {
+            var accessibleStoreIds = (await scopeAccess.GetAccessibleStoreIdsAsync(currentUser.UserId.Value)).ToHashSet();
+            sales = sales.Where(s => accessibleStoreIds.Contains(s.FK_StoreId)).ToList();
+        }
+
+        var result = new List<SaleResponse>();
+        foreach (var sale in sales)
+        {
+            var order = await repo.GetOrderBySaleIdAsync(sale.Id);
+            if (order is null) continue;
+            var items = await orderRepo.GetItemsByOrderIdAsync(order.Id);
+            result.Add(ToResponse(sale, order, items));
+        }
+        return result;
+    }
+
+    public async Task<SaleResponse?> GetByIdAsync(Guid id)
+    {
+        var sale = await repo.GetByIdAsync(id);
+        if (sale is null || !sale.IsActive) return null;
+        if (!await HasStoreScopeAsync(sale.FK_StoreId)) return null;
+
+        var order = await repo.GetOrderBySaleIdAsync(id);
+        if (order is null) return null;
+        var items = await orderRepo.GetItemsByOrderIdAsync(order.Id);
+        return ToResponse(sale, order, items);
+    }
+
+    public async Task<List<SaleResponse>?> GetByStoreIdAsync(Guid storeId)
+    {
+        if (!await HasStoreScopeAsync(storeId)) return null;
+
+        var sales = await repo.GetByStoreIdAsync(storeId);
+        var result = new List<SaleResponse>();
+        foreach (var sale in sales)
+        {
+            var order = await repo.GetOrderBySaleIdAsync(sale.Id);
+            if (order is null) continue;
+            var items = await orderRepo.GetItemsByOrderIdAsync(order.Id);
+            result.Add(ToResponse(sale, order, items));
+        }
+        return result;
+    }
+
+    public async Task<SaleResponse?> CreateAsync(CreateSaleRequest request, CancellationToken ct = default)
+    {
+        if (!await HasStoreScopeAsync(request.StoreId)) return null;
+
+        var userId = currentUser.UserId ?? throw new UnauthorizedAccessException();
+        var store = await storeRepo.GetByIdWithRegionAsync(request.StoreId);
+        if (store is null || !store.IsActive) return null;
+
+        if (store.KycStatus != KycStatus.Verified)
+        {
+            var threshold = configuration.GetValue<decimal>("StoreManagement:UnverifiedKycOrderThreshold");
+            if (request.TotalAmount > threshold) return null;
+        }
+
+        var saleStatus = request.FulfillImmediately ? SaleStatus.Completed : SaleStatus.Pending;
+        var orderStatus = request.FulfillImmediately ? OrderStatus.Fulfilled : OrderStatus.Pending;
+        var fulfilledAt = request.FulfillImmediately ? DateTime.Now : (DateTime?)null;
+
+        var sale = new Models.Sale
+        {
+            FK_StoreId = request.StoreId,
+            SaleDate = request.SaleDate,
+            CreatedByUserId = userId,
+            FK_RideId = request.RideId,
+            TotalAmount = request.TotalAmount,
+            Status = saleStatus,
+            FulfillImmediately = request.FulfillImmediately,
+            CompletedAt = request.FulfillImmediately ? DateTime.Now : null
+        };
+
+        var orderItems = new List<Models.OrderItem>();
+        foreach (var item in request.Items)
+        {
+            var unitPrice = await ResolveUnitPriceAsync(item.ItemId, item.UnitPrice, store, request.SaleDate);
+            if (unitPrice is null) return null;
+
+            orderItems.Add(new Models.OrderItem
+            {
+                FK_ItemId = item.ItemId,
+                Quantity = item.Quantity,
+                QuantityFulfilled = request.FulfillImmediately ? item.Quantity : 0,
+                UnitPrice = unitPrice.Value
+            });
+        }
+
+        var order = new Models.Order
+        {
+            FK_SaleId = sale.Id,
+            FK_StoreId = request.StoreId,
+            OrderDate = request.SaleDate,
+            TotalAmount = request.TotalAmount,
+            Status = orderStatus,
+            FulfilledAt = fulfilledAt
+        };
+
+        foreach (var orderItem in orderItems)
+            orderItem.FK_OrderId = order.Id;
+
+        Guid? vehicleId = null;
+        if (request.FulfillImmediately && request.RideId.HasValue)
+        {
+            var ride = await rideRepo.GetByIdAsync(request.RideId.Value);
+            if (ride is null) return null;
+            vehicleId = ride.FK_VehicleId;
+
+            foreach (var item in orderItems)
+            {
+                var balance = await stockRepo.GetBalanceAsync(item.FK_ItemId, vehicleId.Value);
+                if (balance is null || balance.Quantity < item.Quantity)
+                    return null;
+            }
+        }
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            await repo.AddAsync(sale);
+            await orderRepo.AddAsync(order);
+            await orderRepo.AddItemsAsync(orderItems);
+
+            if (vehicleId.HasValue)
+            {
+                foreach (var item in orderItems)
+                {
+                    var balance = await stockRepo.GetBalanceAsync(item.FK_ItemId, vehicleId.Value);
+                    balance!.Quantity -= item.Quantity;
+                    balance.UpdatedAt = DateTime.Now;
+                    stockRepo.UpdateBalance(balance);
+
+                    await stockRepo.AddMovementAsync(new StockMovement
+                    {
+                        FK_ItemId = item.FK_ItemId,
+                        FromLocationId = vehicleId.Value,
+                        FromLocationType = LocationType.Vehicle,
+                        Quantity = item.Quantity,
+                        Type = MovementType.Sale,
+                        ReferenceId = order.Id
+                    });
+                }
+            }
+
+            await uow.CommitAsync(ct);
+        }
+        catch
+        {
+            await uow.RollbackAsync(ct);
+            throw;
+        }
+
+        return ToResponse(sale, order, orderItems);
+    }
+}

Distribution/Features/Scheme/ISchemeRepository.cs

@@ -0,0 +1,19 @@
+namespace Distribution.Features.Scheme;
+
+public interface ISchemeRepository
+{
+    Task<Models.Scheme?> GetByIdAsync(Guid id);
+    Task<List<Models.Scheme>> GetAllAsync(Guid? regionId = null);
+    Task AddAsync(Models.Scheme entity);
+    void Update(Models.Scheme entity);
+    void Remove(Models.Scheme entity);
+
+    Task<List<Models.SchemeRedemption>> GetRedemptionsAsync(Guid schemeId);
+    Task AddRedemptionAsync(Models.SchemeRedemption entity);
+    Task<bool> HasRedemptionAsync(Guid schemeId, Guid orderId);
+
+    Task<Models.SchemeBundleComponent?> GetBundleComponentAsync(Guid schemeId, Guid itemId);
+    Task AddBundleComponentAsync(Models.SchemeBundleComponent entity);
+    void UpdateBundleComponent(Models.SchemeBundleComponent entity);
+    void RemoveBundleComponent(Models.SchemeBundleComponent entity);
+}

Distribution/Features/Scheme/SchemeController.cs

@@ -0,0 +1,139 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.Scheme;
+
+[ApiController]
+[Route("api/schemes")]
+[Authorize]
+public class SchemeController(SchemeService service) : ControllerBase
+{
+    [HttpGet]
+    public async Task<IActionResult> GetAll([FromQuery] Guid? regionId) =>
+        Ok(await service.GetAllAsync(regionId));
+
+    [HttpGet("{id:guid}")]
+    public async Task<IActionResult> GetById(Guid id)
+    {
+        var result = await service.GetByIdAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost]
+    public async Task<IActionResult> Create(CreateSchemeRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.CreateAsync(request, ct);
+            return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+        }
+        catch (InvalidOperationException ex)
+        {
+            return BadRequest(new { error = ex.Message });
+        }
+    }
+
+    [HttpPut("{id:guid}")]
+    public async Task<IActionResult> Update(Guid id, UpdateSchemeRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.UpdateAsync(id, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex)
+        {
+            return BadRequest(new { error = ex.Message });
+        }
+    }
+
+    [HttpDelete("{id:guid}")]
+    public async Task<IActionResult> Delete(Guid id, CancellationToken ct)
+    {
+        var deleted = await service.DeleteAsync(id, ct);
+        return deleted ? NoContent() : NotFound();
+    }
+
+    [HttpPut("{id:guid}/free-goods-rule")]
+    public async Task<IActionResult> SetFreeGoodsRule(Guid id, SetFreeGoodsRuleRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.SetFreeGoodsRuleAsync(id, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex)
+        {
+            return Conflict(new { error = ex.Message });
+        }
+    }
+
+    [HttpDelete("{id:guid}/free-goods-rule")]
+    public async Task<IActionResult> ClearFreeGoodsRule(Guid id, CancellationToken ct)
+    {
+        var result = await service.ClearFreeGoodsRuleAsync(id, ct);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPut("{id:guid}/bundle-components/{itemId:guid}")]
+    public async Task<IActionResult> UpsertBundleComponent(Guid id, Guid itemId, UpsertBundleComponentRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.UpsertBundleComponentAsync(id, itemId, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex)
+        {
+            return Conflict(new { error = ex.Message });
+        }
+    }
+
+    [HttpDelete("{id:guid}/bundle-components/{itemId:guid}")]
+    public async Task<IActionResult> RemoveBundleComponent(Guid id, Guid itemId, CancellationToken ct)
+    {
+        var result = await service.RemoveBundleComponentAsync(id, itemId, ct);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpGet("eligible")]
+    public async Task<IActionResult> GetEligible([FromQuery] Guid storeId, [FromQuery] Guid orderId)
+    {
+        var result = await service.EvaluateEligibilityAsync(storeId, orderId);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpGet("{id:guid}/spend")]
+    public async Task<IActionResult> GetSpend(Guid id)
+    {
+        var result = await service.GetSpendAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpGet("{id:guid}/roi")]
+    public async Task<IActionResult> GetROI(Guid id)
+    {
+        var result = await service.GetROIAsync(id);
+        return result is null ? NotFound() : Ok(result);
+    }
+}
+
+[ApiController]
+[Route("api/orders")]
+[Authorize]
+public class SchemeOrderController(SchemeService service) : ControllerBase
+{
+    [HttpPost("{id:guid}/apply-scheme")]
+    public async Task<IActionResult> ApplyScheme(Guid id, ApplySchemeRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.ApplySchemeAsync(id, request.SchemeId, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex)
+        {
+            return Conflict(new { error = ex.Message });
+        }
+    }
+}

Distribution/Features/Scheme/SchemeDTOs.cs

@@ -0,0 +1,111 @@
+using Distribution.Models;
+
+namespace Distribution.Features.Scheme;
+
+// ── Rule config payloads for percentage-based rules (serialized into Scheme.RuleConfig) ──
+
+public record SlabDiscountConfig(List<SlabTier> Tiers);
+
+public record SlabTier(decimal MinOrderAmount, decimal DiscountPercent);
+
+public record FlatPercentConfig(decimal DiscountPercent);
+
+// ── Requests ────────────────────────────────────────────────────────────
+
+public record BundleComponentRequest(Guid ItemId, int Qty);
+
+/// <summary>
+/// TriggerItemId/TriggerQty/FreeItemId/FreeQty/BundleComponents are optional so plain discount
+/// schemes (SlabDiscount/FlatPercent) can omit them entirely. When RuleType is BuyXGetY, supplying
+/// TriggerItemId+TriggerQty+FreeItemId+FreeQty here creates the scheme fully populated in one call
+/// instead of a separate PUT .../free-goods-rule. When RuleType is FreeBundle, supplying
+/// FreeItemId+FreeQty+BundleComponents does the same. These can still be added/edited later via
+/// PUT .../free-goods-rule and PUT .../bundle-components/{itemId}.
+/// </summary>
+public record CreateSchemeRequest(
+    string Name,
+    SchemeRuleType RuleType,
+    string? RuleConfig,
+    Guid? RegionId,
+    string? EligibleSegment,
+    DateTime DateRangeFrom,
+    DateTime DateRangeTo,
+    bool AgentLimitExempt,
+    decimal? BaselineExpectedSales,
+    Guid? TriggerItemId = null,
+    int? TriggerQty = null,
+    Guid? FreeItemId = null,
+    decimal? FreeQty = null,
+    List<BundleComponentRequest>? BundleComponents = null);
+
+public record UpdateSchemeRequest(
+    string Name,
+    string? RuleConfig,
+    Guid? RegionId,
+    string? EligibleSegment,
+    DateTime DateRangeFrom,
+    DateTime DateRangeTo,
+    bool AgentLimitExempt,
+    decimal? BaselineExpectedSales);
+
+public record ApplySchemeRequest(Guid SchemeId);
+
+/// <summary>
+/// Sets the free-goods payout for a scheme. For BuyXGetY, TriggerItemId/TriggerQty are required
+/// (what the store must buy); for FreeBundle they are ignored — the required items instead come
+/// from the scheme's bundle-components CRUD. FreeItemId/FreeQty is the payout in both cases.
+/// </summary>
+public record SetFreeGoodsRuleRequest(Guid? TriggerItemId, int? TriggerQty, Guid FreeItemId, decimal FreeQty);
+
+public record UpsertBundleComponentRequest(int Qty);
+
+// ── Responses ───────────────────────────────────────────────────────────
+
+public record BundleComponentResponse(Guid ItemId, string Sku, string ItemName, int Qty);
+
+public record SchemeResponse(
+    Guid Id,
+    string Name,
+    SchemeRuleType RuleType,
+    string? RuleConfig,
+    Guid? TriggerItemId,
+    string? TriggerItemName,
+    int? TriggerQty,
+    Guid? FreeItemId,
+    string? FreeItemName,
+    decimal? FreeQty,
+    List<BundleComponentResponse> BundleComponents,
+    Guid? RegionId,
+    string? RegionName,
+    string? EligibleSegment,
+    DateTime DateRangeFrom,
+    DateTime DateRangeTo,
+    bool AgentLimitExempt,
+    decimal? BaselineExpectedSales,
+    bool IsActive,
+    DateTime CreatedAt);
+
+public record SchemeEligibilityResponse(
+    Guid SchemeId,
+    string SchemeName,
+    SchemeRuleType RuleType,
+    bool Eligible,
+    string? Reason,
+    decimal? DiscountAmount,
+    Guid? FreeItemId,
+    decimal? FreeQty);
+
+public record SchemeRedemptionResponse(
+    Guid Id,
+    Guid SchemeId,
+    Guid? OrderId,
+    decimal? DiscountAmount,
+    Guid? FreeItemId,
+    string? FreeItemName,
+    decimal? FreeQty,
+    decimal? FreeItemCostValue,
+    DateTime RedeemedAt);
+
+public record SchemeSpendResponse(Guid SchemeId, decimal TotalDiscountSpend, decimal TotalFreeGoodsCostSpend, decimal TotalSpend, int RedemptionCount);
+
+public record SchemeROIResponse(Guid SchemeId, decimal BaselineExpectedSales, decimal ActualSales, decimal IncrementalSales, decimal TotalSpend, decimal? ROI);

Distribution/Features/Scheme/SchemeRepository.cs

@@ -0,0 +1,67 @@
+using Distribution.Data;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.Scheme;
+
+public class SchemeRepository(AppDBContext context) : ISchemeRepository
+{
+    public async Task<Models.Scheme?> GetByIdAsync(Guid id) =>
+        await context.Schemes
+            .Include(s => s.Region)
+            .Include(s => s.TriggerItem)
+            .Include(s => s.FreeItem)
+            .Include(s => s.BundleComponents).ThenInclude(c => c.Item)
+            .FirstOrDefaultAsync(s => s.Id == id);
+
+    public async Task<List<Models.Scheme>> GetAllAsync(Guid? regionId = null)
+    {
+        var query = context.Schemes
+            .Include(s => s.Region)
+            .Include(s => s.TriggerItem)
+            .Include(s => s.FreeItem)
+            .Include(s => s.BundleComponents).ThenInclude(c => c.Item)
+            .Where(s => s.IsActive);
+
+        if (regionId.HasValue) query = query.Where(s => s.FK_RegionId == regionId);
+
+        return await query.ToListAsync();
+    }
+
+    public async Task AddAsync(Models.Scheme entity) =>
+        await context.Schemes.AddAsync(entity);
+
+    public void Update(Models.Scheme entity) =>
+        context.Schemes.Update(entity);
+
+    public void Remove(Models.Scheme entity)
+    {
+        entity.IsActive = false;
+        context.Schemes.Update(entity);
+    }
+
+    public async Task<List<Models.SchemeRedemption>> GetRedemptionsAsync(Guid schemeId) =>
+        await context.SchemeRedemptions
+            .Include(r => r.FreeItem)
+            .Include(r => r.Order)
+            .Where(r => r.FK_SchemeId == schemeId)
+            .ToListAsync();
+
+    public async Task AddRedemptionAsync(Models.SchemeRedemption entity) =>
+        await context.SchemeRedemptions.AddAsync(entity);
+
+    public async Task<bool> HasRedemptionAsync(Guid schemeId, Guid orderId) =>
+        await context.SchemeRedemptions.AnyAsync(r => r.FK_SchemeId == schemeId && r.FK_OrderId == orderId);
+
+    public async Task<Models.SchemeBundleComponent?> GetBundleComponentAsync(Guid schemeId, Guid itemId) =>
+        await context.SchemeBundleComponents
+            .FirstOrDefaultAsync(c => c.FK_SchemeId == schemeId && c.FK_ItemId == itemId);
+
+    public async Task AddBundleComponentAsync(Models.SchemeBundleComponent entity) =>
+        await context.SchemeBundleComponents.AddAsync(entity);
+
+    public void UpdateBundleComponent(Models.SchemeBundleComponent entity) =>
+        context.SchemeBundleComponents.Update(entity);
+
+    public void RemoveBundleComponent(Models.SchemeBundleComponent entity) =>
+        context.SchemeBundleComponents.Remove(entity);
+}

Distribution/Features/Scheme/SchemeService.cs

@@ -0,0 +1,515 @@
+using System.Text.Json;
+using Distribution.Features.Item;
+using Distribution.Features.Order;
+using Distribution.Features.Stock;
+using Distribution.Features.Store;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+
+namespace Distribution.Features.Scheme;
+
+public class SchemeService(
+    ISchemeRepository repo,
+    IOrderRepository orderRepo,
+    IItemRepository itemRepo,
+    IStoreRepository storeRepo,
+    IStockRepository stockRepo,
+    IUnitOfWork uow)
+{
+    private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web);
+
+    private static SchemeResponse ToResponse(Models.Scheme s) =>
+        new(s.Id, s.Name, s.RuleType, s.RuleConfig,
+            s.FK_TriggerItemId, s.TriggerItem?.Name, s.TriggerQty,
+            s.FK_FreeItemId, s.FreeItem?.Name, s.FreeQty,
+            s.BundleComponents.Select(c => new BundleComponentResponse(c.FK_ItemId, c.Item.Sku, c.Item.Name, c.Qty)).ToList(),
+            s.FK_RegionId, s.Region?.Name, s.EligibleSegment,
+            s.DateRangeFrom, s.DateRangeTo, s.AgentLimitExempt, s.BaselineExpectedSales, s.IsActive, s.CreatedAt);
+
+    private static SchemeRedemptionResponse ToRedemptionResponse(SchemeRedemption r) =>
+        new(r.Id, r.FK_SchemeId, r.FK_OrderId, r.DiscountAmount, r.FK_FreeItemId, r.FreeItem?.Name,
+            r.FreeQty, r.FreeItemCostValue, r.RedeemedAt);
+
+    // ── CRUD ───────────────────────────────────────────────────────────────
+
+    public async Task<List<SchemeResponse>> GetAllAsync(Guid? regionId = null)
+    {
+        var schemes = await repo.GetAllAsync(regionId);
+        return schemes.Select(ToResponse).ToList();
+    }
+
+    public async Task<SchemeResponse?> GetByIdAsync(Guid id)
+    {
+        var scheme = await repo.GetByIdAsync(id);
+        return scheme is null || !scheme.IsActive ? null : ToResponse(scheme);
+    }
+
+    /// <summary>
+    /// createScheme(schemeRules, eligibility, dateRange). RuleConfig is only meaningful for
+    /// SlabDiscount/FlatPercent. For BuyXGetY/FreeBundle, the free-goods payout (and bundle
+    /// components) can be supplied inline here to create a fully-populated scheme in one call, or
+    /// added afterwards via SetFreeGoodsRuleAsync / UpsertBundleComponentAsync.
+    /// </summary>
+    public async Task<SchemeResponse> CreateAsync(CreateSchemeRequest request, CancellationToken ct = default)
+    {
+        ValidatePercentRuleConfig(request.RuleType, request.RuleConfig);
+        if (request.DateRangeFrom > request.DateRangeTo)
+            throw new InvalidOperationException("DateRangeFrom must not be after DateRangeTo.");
+
+        var hasFreeGoodsRule = request.FreeItemId.HasValue || request.FreeQty.HasValue ||
+            request.TriggerItemId.HasValue || request.TriggerQty.HasValue;
+        if (hasFreeGoodsRule)
+            await ValidateFreeGoodsRuleAsync(request.RuleType, request.TriggerItemId, request.TriggerQty, request.FreeItemId, request.FreeQty);
+
+        if (request.BundleComponents is { Count: > 0 })
+        {
+            if (request.RuleType != SchemeRuleType.FreeBundle)
+                throw new InvalidOperationException("BundleComponents only applies to FreeBundle schemes.");
+            foreach (var c in request.BundleComponents)
+            {
+                if (c.Qty <= 0)
+                    throw new InvalidOperationException("Bundle component Qty must be positive.");
+                if (await itemRepo.GetByIdAsync(c.ItemId) is null)
+                    throw new InvalidOperationException($"Bundle component item '{c.ItemId}' not found.");
+            }
+        }
+
+        var scheme = new Models.Scheme
+        {
+            Name = request.Name,
+            RuleType = request.RuleType,
+            RuleConfig = request.RuleConfig,
+            FK_RegionId = request.RegionId,
+            EligibleSegment = request.EligibleSegment,
+            DateRangeFrom = request.DateRangeFrom,
+            DateRangeTo = request.DateRangeTo,
+            AgentLimitExempt = request.AgentLimitExempt,
+            BaselineExpectedSales = request.BaselineExpectedSales
+        };
+
+        if (hasFreeGoodsRule)
+        {
+            scheme.FK_TriggerItemId = request.RuleType == SchemeRuleType.BuyXGetY ? request.TriggerItemId : null;
+            scheme.TriggerQty = request.RuleType == SchemeRuleType.BuyXGetY ? request.TriggerQty : null;
+            scheme.FK_FreeItemId = request.FreeItemId;
+            scheme.FreeQty = request.FreeQty;
+        }
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            await repo.AddAsync(scheme);
+            if (request.BundleComponents is { Count: > 0 })
+            {
+                foreach (var c in request.BundleComponents)
+                    await repo.AddBundleComponentAsync(new SchemeBundleComponent { FK_SchemeId = scheme.Id, FK_ItemId = c.ItemId, Qty = c.Qty });
+            }
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return (await GetByIdAsync(scheme.Id))!;
+    }
+
+    public async Task<SchemeResponse?> UpdateAsync(Guid id, UpdateSchemeRequest request, CancellationToken ct = default)
+    {
+        var scheme = await repo.GetByIdAsync(id);
+        if (scheme is null || !scheme.IsActive) return null;
+
+        ValidatePercentRuleConfig(scheme.RuleType, request.RuleConfig);
+        if (request.DateRangeFrom > request.DateRangeTo)
+            throw new InvalidOperationException("DateRangeFrom must not be after DateRangeTo.");
+
+        scheme.Name = request.Name;
+        scheme.RuleConfig = request.RuleConfig;
+        scheme.FK_RegionId = request.RegionId;
+        scheme.EligibleSegment = request.EligibleSegment;
+        scheme.DateRangeFrom = request.DateRangeFrom;
+        scheme.DateRangeTo = request.DateRangeTo;
+        scheme.AgentLimitExempt = request.AgentLimitExempt;
+        scheme.BaselineExpectedSales = request.BaselineExpectedSales;
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(scheme); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return ToResponse(scheme);
+    }
+
+    public async Task<bool> DeleteAsync(Guid id, CancellationToken ct = default)
+    {
+        var scheme = await repo.GetByIdAsync(id);
+        if (scheme is null || !scheme.IsActive) return false;
+
+        await uow.BeginAsync(ct);
+        try { repo.Remove(scheme); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return true;
+    }
+
+    // ── Free-goods rule CRUD (BuyXGetY trigger + shared payout) ──────────────
+
+    public async Task<SchemeResponse?> SetFreeGoodsRuleAsync(Guid schemeId, SetFreeGoodsRuleRequest request, CancellationToken ct = default)
+    {
+        var scheme = await repo.GetByIdAsync(schemeId);
+        if (scheme is null || !scheme.IsActive) return null;
+
+        await ValidateFreeGoodsRuleAsync(scheme.RuleType, request.TriggerItemId, request.TriggerQty, request.FreeItemId, request.FreeQty);
+
+        scheme.FK_TriggerItemId = scheme.RuleType == SchemeRuleType.BuyXGetY ? request.TriggerItemId : null;
+        scheme.TriggerQty = scheme.RuleType == SchemeRuleType.BuyXGetY ? request.TriggerQty : null;
+        scheme.FK_FreeItemId = request.FreeItemId;
+        scheme.FreeQty = request.FreeQty;
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(scheme); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return (await GetByIdAsync(schemeId))!;
+    }
+
+    public async Task<SchemeResponse?> ClearFreeGoodsRuleAsync(Guid schemeId, CancellationToken ct = default)
+    {
+        var scheme = await repo.GetByIdAsync(schemeId);
+        if (scheme is null || !scheme.IsActive) return null;
+
+        scheme.FK_TriggerItemId = null;
+        scheme.TriggerQty = null;
+        scheme.FK_FreeItemId = null;
+        scheme.FreeQty = null;
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(scheme); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return (await GetByIdAsync(schemeId))!;
+    }
+
+    // ── Bundle component CRUD (FreeBundle required items) ────────────────────
+
+    public async Task<SchemeResponse?> UpsertBundleComponentAsync(Guid schemeId, Guid itemId, UpsertBundleComponentRequest request, CancellationToken ct = default)
+    {
+        var scheme = await repo.GetByIdAsync(schemeId);
+        if (scheme is null || !scheme.IsActive) return null;
+
+        if (scheme.RuleType != SchemeRuleType.FreeBundle)
+            throw new InvalidOperationException("Bundle components only apply to FreeBundle schemes.");
+        if (request.Qty <= 0)
+            throw new InvalidOperationException("Qty must be positive.");
+
+        var item = await itemRepo.GetByIdAsync(itemId)
+            ?? throw new InvalidOperationException("Item not found.");
+
+        var existing = await repo.GetBundleComponentAsync(schemeId, itemId);
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            if (existing is null)
+            {
+                await repo.AddBundleComponentAsync(new SchemeBundleComponent
+                {
+                    FK_SchemeId = schemeId,
+                    FK_ItemId = item.Id,
+                    Qty = request.Qty
+                });
+            }
+            else
+            {
+                existing.Qty = request.Qty;
+                repo.UpdateBundleComponent(existing);
+            }
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return (await GetByIdAsync(schemeId))!;
+    }
+
+    public async Task<SchemeResponse?> RemoveBundleComponentAsync(Guid schemeId, Guid itemId, CancellationToken ct = default)
+    {
+        var scheme = await repo.GetByIdAsync(schemeId);
+        if (scheme is null || !scheme.IsActive) return null;
+
+        var existing = await repo.GetBundleComponentAsync(schemeId, itemId);
+        if (existing is null) return null;
+
+        await uow.BeginAsync(ct);
+        try { repo.RemoveBundleComponent(existing); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return (await GetByIdAsync(schemeId))!;
+    }
+
+    // ── evaluateSchemeEligibility(storeId, orderId) ──────────────────────────
+
+    public async Task<List<SchemeEligibilityResponse>?> EvaluateEligibilityAsync(Guid storeId, Guid orderId)
+    {
+        var store = await storeRepo.GetByIdWithRegionAsync(storeId);
+        if (store is null || !store.IsActive) return null;
+
+        var order = await orderRepo.GetByIdAsync(orderId);
+        if (order is null || !order.IsActive) return null;
+
+        var orderItems = await orderRepo.GetItemsByOrderIdAsync(orderId);
+        var regionId = store.Route?.FK_RegionId;
+
+        var candidates = await repo.GetAllAsync();
+        var result = new List<SchemeEligibilityResponse>();
+
+        foreach (var scheme in candidates)
+        {
+            if (scheme.FK_RegionId.HasValue && scheme.FK_RegionId != regionId)
+                continue;
+            if (!string.IsNullOrEmpty(scheme.EligibleSegment) &&
+                !string.Equals(scheme.EligibleSegment, store.Segment, StringComparison.OrdinalIgnoreCase))
+                continue;
+            if (order.OrderDate < scheme.DateRangeFrom || order.OrderDate > scheme.DateRangeTo)
+                continue;
+
+            result.Add(EvaluateRule(scheme, orderItems));
+        }
+
+        return result;
+    }
+
+    /// <summary>
+    /// Scope-only check (region, segment, date range as of today) with no order to evaluate line
+    /// items against — used by Store Management's `checkStoreSchemeEligibility(storeId, schemeId)`
+    /// (12_store_management.md), which has no order context. Returns null if the store or scheme
+    /// doesn't exist; otherwise (Eligible, Reason) — Eligible here means "in scope for this store",
+    /// not "this order's items satisfy the rule" (use EvaluateEligibilityAsync for that).
+    /// </summary>
+    public async Task<(bool Eligible, string? Reason)?> CheckStoreScopeEligibilityAsync(Guid storeId, Guid schemeId)
+    {
+        var store = await storeRepo.GetByIdWithRegionAsync(storeId);
+        if (store is null || !store.IsActive) return null;
+
+        var scheme = await repo.GetByIdAsync(schemeId);
+        if (scheme is null || !scheme.IsActive) return null;
+
+        var regionId = store.Route?.FK_RegionId;
+        if (scheme.FK_RegionId.HasValue && scheme.FK_RegionId != regionId)
+            return (false, "Scheme is not available in the store's region.");
+
+        if (!string.IsNullOrEmpty(scheme.EligibleSegment) &&
+            !string.Equals(scheme.EligibleSegment, store.Segment, StringComparison.OrdinalIgnoreCase))
+            return (false, $"Scheme is only available to the '{scheme.EligibleSegment}' segment.");
+
+        var today = DateTime.Now;
+        if (today < scheme.DateRangeFrom || today > scheme.DateRangeTo)
+            return (false, "Scheme is not currently active (outside its date range).");
+
+        return (true, null);
+    }
+
+    private static SchemeEligibilityResponse EvaluateRule(Models.Scheme scheme, List<OrderItem> orderItems)
+    {
+        switch (scheme.RuleType)
+        {
+            case SchemeRuleType.BuyXGetY:
+            {
+                if (scheme.FK_TriggerItemId is null || scheme.TriggerQty is null or <= 0 ||
+                    scheme.FK_FreeItemId is null || scheme.FreeQty is null or <= 0)
+                    return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, false,
+                        "Scheme has no free-goods rule configured.", null, null, null);
+
+                var boughtQty = orderItems.Where(i => i.FK_ItemId == scheme.FK_TriggerItemId).Sum(i => i.Quantity);
+                if (boughtQty < scheme.TriggerQty)
+                    return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, false,
+                        $"Requires {scheme.TriggerQty} of the trigger item; order has {boughtQty}.", null, null, null);
+
+                var multiplier = boughtQty / scheme.TriggerQty.Value;
+                return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, true, null,
+                    null, scheme.FK_FreeItemId, scheme.FreeQty * multiplier);
+            }
+            case SchemeRuleType.FreeBundle:
+            {
+                if (scheme.BundleComponents.Count == 0 || scheme.FK_FreeItemId is null || scheme.FreeQty is null or <= 0)
+                    return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, false,
+                        "Scheme has no bundle components or free-goods payout configured.", null, null, null);
+
+                var missing = scheme.BundleComponents
+                    .Where(c => orderItems.Where(i => i.FK_ItemId == c.FK_ItemId).Sum(i => i.Quantity) < c.Qty)
+                    .ToList();
+                if (missing.Count > 0)
+                    return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, false,
+                        "Order is missing required bundle components.", null, null, null);
+
+                return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, true, null,
+                    null, scheme.FK_FreeItemId, scheme.FreeQty);
+            }
+            case SchemeRuleType.FlatPercent:
+            {
+                if (string.IsNullOrEmpty(scheme.RuleConfig))
+                    return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, false, "Scheme has no RuleConfig.", null, null, null);
+                var cfg = JsonSerializer.Deserialize<FlatPercentConfig>(scheme.RuleConfig, JsonOptions)!;
+                var orderTotal = orderItems.Sum(i => i.Quantity * i.UnitPrice);
+                return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, true, null,
+                    Math.Round(orderTotal * cfg.DiscountPercent / 100m, 2), null, null);
+            }
+            case SchemeRuleType.SlabDiscount:
+            {
+                if (string.IsNullOrEmpty(scheme.RuleConfig))
+                    return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, false, "Scheme has no RuleConfig.", null, null, null);
+                var cfg = JsonSerializer.Deserialize<SlabDiscountConfig>(scheme.RuleConfig, JsonOptions)!;
+                var orderTotal = orderItems.Sum(i => i.Quantity * i.UnitPrice);
+                var tier = cfg.Tiers.Where(t => orderTotal >= t.MinOrderAmount)
+                    .OrderByDescending(t => t.MinOrderAmount).FirstOrDefault();
+                if (tier is null)
+                    return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, false,
+                        "Order total does not meet any slab threshold.", null, null, null);
+
+                return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, true, null,
+                    Math.Round(orderTotal * tier.DiscountPercent / 100m, 2), null, null);
+            }
+            default:
+                return new SchemeEligibilityResponse(scheme.Id, scheme.Name, scheme.RuleType, false, "Unknown rule type.", null, null, null);
+        }
+    }
+
+    // ── applySchemeDiscount(orderId, schemeId) ───────────────────────────────
+
+    public async Task<SchemeRedemptionResponse?> ApplySchemeAsync(Guid orderId, Guid schemeId, CancellationToken ct = default)
+    {
+        var scheme = await repo.GetByIdAsync(schemeId);
+        if (scheme is null || !scheme.IsActive) return null;
+
+        var order = await orderRepo.GetByIdAsync(orderId);
+        if (order is null || !order.IsActive) return null;
+
+        if (await repo.HasRedemptionAsync(schemeId, orderId))
+            throw new InvalidOperationException("This scheme has already been redeemed against this order.");
+
+        var orderItems = await orderRepo.GetItemsByOrderIdAsync(orderId);
+        var eligibility = EvaluateRule(scheme, orderItems);
+        if (!eligibility.Eligible)
+            throw new InvalidOperationException(eligibility.Reason ?? "Order is not eligible for this scheme.");
+
+        var redemption = new SchemeRedemption
+        {
+            FK_SchemeId = schemeId,
+            FK_OrderId = orderId,
+            DiscountAmount = eligibility.DiscountAmount
+        };
+
+        var newOrderItems = new List<OrderItem>();
+
+        if (eligibility.FreeItemId.HasValue && eligibility.FreeQty is > 0)
+        {
+            var freeItem = await itemRepo.GetByIdAsync(eligibility.FreeItemId.Value)
+                ?? throw new InvalidOperationException("Free item not found.");
+
+            var availableQty = (await stockRepo.GetBalancesByItemAsync(freeItem.Id)).Sum(b => b.Quantity);
+            if (availableQty < eligibility.FreeQty.Value)
+                throw new InvalidOperationException($"Insufficient stock of '{freeItem.Sku}' to fulfil the free-goods scheme.");
+
+            newOrderItems.Add(new OrderItem
+            {
+                FK_OrderId = orderId,
+                FK_ItemId = freeItem.Id,
+                Quantity = (int)eligibility.FreeQty.Value,
+                UnitPrice = 0m
+            });
+
+            redemption.FK_FreeItemId = freeItem.Id;
+            redemption.FreeQty = eligibility.FreeQty;
+            redemption.FreeItemCostValue = freeItem.CostPrice ?? 0m;
+        }
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            if (newOrderItems.Count > 0) await orderRepo.AddItemsAsync(newOrderItems);
+            await repo.AddRedemptionAsync(redemption);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        var reloaded = (await repo.GetRedemptionsAsync(schemeId)).First(r => r.Id == redemption.Id);
+        return ToRedemptionResponse(reloaded);
+    }
+
+    // ── trackSchemeSpend(schemeId) ───────────────────────────────────────────
+
+    public async Task<SchemeSpendResponse?> GetSpendAsync(Guid schemeId)
+    {
+        var scheme = await repo.GetByIdAsync(schemeId);
+        if (scheme is null) return null;
+
+        var redemptions = await repo.GetRedemptionsAsync(schemeId);
+        var discountSpend = redemptions.Sum(r => r.DiscountAmount ?? 0m);
+        var freeGoodsSpend = redemptions.Sum(r => (r.FreeItemCostValue ?? 0m) * (r.FreeQty ?? 0m));
+
+        return new SchemeSpendResponse(schemeId, discountSpend, freeGoodsSpend, discountSpend + freeGoodsSpend, redemptions.Count);
+    }
+
+    // ── getSchemeROI(schemeId) ───────────────────────────────────────────────
+
+    public async Task<SchemeROIResponse?> GetROIAsync(Guid schemeId)
+    {
+        var scheme = await repo.GetByIdAsync(schemeId);
+        if (scheme is null) return null;
+
+        var redemptions = await repo.GetRedemptionsAsync(schemeId);
+        var spend = await GetSpendAsync(schemeId);
+
+        var actualSales = redemptions
+            .Where(r => r.Order is not null)
+            .Select(r => r.Order!)
+            .Distinct()
+            .Sum(o => o.TotalAmount);
+
+        var baseline = scheme.BaselineExpectedSales ?? 0m;
+        var incremental = actualSales - baseline;
+        decimal? roi = spend!.TotalSpend > 0 ? incremental / spend.TotalSpend : null;
+
+        return new SchemeROIResponse(schemeId, baseline, actualSales, incremental, spend.TotalSpend, roi);
+    }
+
+    private async Task ValidateFreeGoodsRuleAsync(SchemeRuleType ruleType, Guid? triggerItemId, int? triggerQty, Guid? freeItemId, decimal? freeQty)
+    {
+        if (ruleType is not (SchemeRuleType.BuyXGetY or SchemeRuleType.FreeBundle))
+            throw new InvalidOperationException($"Free-goods rule only applies to BuyXGetY or FreeBundle schemes, not '{ruleType}'.");
+
+        if (ruleType == SchemeRuleType.BuyXGetY)
+        {
+            if (triggerItemId is null || triggerQty is null or <= 0)
+                throw new InvalidOperationException("BuyXGetY requires TriggerItemId and a positive TriggerQty.");
+            if (await itemRepo.GetByIdAsync(triggerItemId.Value) is null)
+                throw new InvalidOperationException("Trigger item not found.");
+        }
+
+        if (freeItemId is null || freeQty is null or <= 0)
+            throw new InvalidOperationException("FreeItemId and a positive FreeQty are required.");
+        if (await itemRepo.GetByIdAsync(freeItemId.Value) is null)
+            throw new InvalidOperationException("Free item not found.");
+    }
+
+    private static void ValidatePercentRuleConfig(SchemeRuleType ruleType, string? ruleConfig)
+    {
+        if (ruleType is not (SchemeRuleType.SlabDiscount or SchemeRuleType.FlatPercent)) return;
+
+        if (string.IsNullOrWhiteSpace(ruleConfig))
+            throw new InvalidOperationException($"RuleConfig is required for RuleType '{ruleType}'.");
+
+        try
+        {
+            if (ruleType == SchemeRuleType.SlabDiscount)
+            {
+                var slab = JsonSerializer.Deserialize<SlabDiscountConfig>(ruleConfig, JsonOptions) ?? throw new JsonException();
+                if (slab.Tiers.Count == 0)
+                    throw new InvalidOperationException("SlabDiscount scheme requires at least one tier.");
+            }
+            else
+            {
+                _ = JsonSerializer.Deserialize<FlatPercentConfig>(ruleConfig, JsonOptions) ?? throw new JsonException();
+            }
+        }
+        catch (JsonException)
+        {
+            throw new InvalidOperationException($"RuleConfig is not valid JSON for RuleType '{ruleType}'.");
+        }
+    }
+}

Distribution/Features/Store/StoreService.cs

@@ -1,10 +1,11 @@
+using Distribution.Features.Scheme;
 using Distribution.Infra.Authorization;
 using Distribution.Infra.UoW;
 using Distribution.Models;
 
 namespace Distribution.Features.Store;
 
-public class StoreService(IStoreRepository repo, IUnitOfWork uow, ICurrentUserService currentUser, IScopeAccessService scopeAccess)
+public class StoreService(IStoreRepository repo, IUnitOfWork uow, ICurrentUserService currentUser, IScopeAccessService scopeAccess, SchemeService schemeService)
 {
     private const int GlobalScopeRoleLevel = 50;
     private const int CreditApproverRoleLevel = 20;
@@ -217,8 +218,10 @@ public class StoreService(IStoreRepository repo, IUnitOfWork uow, ICurrentUserSe
         var store = await repo.GetByIdAsync(id);
         if (store is null || !store.IsActive) return null;
         if (!await HasStoreScopeAsync(id)) return null;
-        // Wired to Step 17 (Promotions & Schemes) once scheme rules exist.
-        return new SchemeEligibilityResponse(true, null);
+
+        var result = await schemeService.CheckStoreScopeEligibilityAsync(id, schemeId);
+        if (result is null) return null;
+        return new SchemeEligibilityResponse(result.Value.Eligible, result.Value.Reason);
     }
 
     public async Task<StoreDashboardResponse?> GetDashboardAsync(Guid id, string period)

Distribution/Features/Supplier/SupplierController.cs

@@ -36,7 +36,18 @@ public class SupplierController(SupplierService service) : ControllerBase
     [HttpDelete("{id:guid}")]
     public async Task<IActionResult> Delete(Guid id, CancellationToken ct)
     {
-        var deleted = await service.DeleteAsync(id, ct);
-        return deleted ? NoContent() : NotFound();
+        try
+        {
+            var deleted = await service.DeleteAsync(id, ct);
+            return deleted ? NoContent() : NotFound();
+        }
+        catch (InvalidOperationException ex) { return Conflict(new { error = ex.Message }); }
+    }
+
+    [HttpPost("{id:guid}/evaluate")]
+    public async Task<IActionResult> Evaluate(Guid id, CancellationToken ct)
+    {
+        var result = await service.EvaluateAsync(id, ct);
+        return result is null ? NotFound() : Ok(result);
     }
 }

Distribution/Features/Supplier/SupplierService.cs

@@ -1,8 +1,14 @@
+using Distribution.Features.Grn;
+using Distribution.Features.Po;
 using Distribution.Infra.UoW;
 
 namespace Distribution.Features.Supplier;
 
-public class SupplierService(ISupplierRepository repo, IUnitOfWork uow)
+public class SupplierService(
+    ISupplierRepository repo,
+    IPoRepository purchaseOrderRepo,
+    IGrnRepository goodsReceiptRepo,
+    IUnitOfWork uow)
 {
     private static SupplierResponse Map(Models.Supplier s) =>
         new(s.Id, s.Name, s.ContactInfo, s.PerformanceScore, s.IsActive, s.CreatedAt);
@@ -52,10 +58,83 @@ public class SupplierService(ISupplierRepository repo, IUnitOfWork uow)
         var supplier = await repo.GetByIdAsync(id);
         if (supplier is null || !supplier.IsActive) return false;
 
+        if (await purchaseOrderRepo.HasActiveForSupplierAsync(id))
+            throw new InvalidOperationException(
+                "Cannot delete a supplier that is referenced by an active purchase order.");
+
         await uow.BeginAsync(ct);
         try { repo.Remove(supplier); await uow.CommitAsync(ct); }
         catch { await uow.RollbackAsync(ct); throw; }
 
         return true;
     }
+
+    /// <summary>
+    /// The only writer of Supplier.PerformanceScore. Computes a simple 0-100 score from this
+    /// supplier's own purchase-order history:
+    ///   - lineFulfillmentRatio: received (non-cancelled, fully-received) Po lines / all non-active
+    ///     Po lines seen (received + cancelled) - how reliably the supplier fulfils what it commits to.
+    ///   - acceptanceRatio: AcceptedQuantity / (AcceptedQuantity + RejectedQuantity) across every
+    ///     GoodsReceipt against this supplier's Pos - how much of what arrives is usable.
+    /// score = round(average(lineFulfillmentRatio, acceptanceRatio) * 100, 2).
+    /// Defaults to 50 (neutral) when there is no history yet, rather than hardcoding a fixed score.
+    /// </summary>
+    public async Task<SupplierResponse?> EvaluateAsync(Guid id, CancellationToken ct = default)
+    {
+        var supplier = await repo.GetByIdAsync(id);
+        if (supplier is null || !supplier.IsActive) return null;
+
+        var purchaseOrders = await purchaseOrderRepo.GetBySupplierAsync(id);
+
+        var receivedLines = 0;
+        var cancelledLines = 0;
+        foreach (var po in purchaseOrders)
+        {
+            foreach (var item in po.Items.Where(i => i.IsActive))
+            {
+                if (item.IsCancelled) cancelledLines++;
+                else if (item.ReceivedQuantity >= item.Quantity) receivedLines++;
+            }
+        }
+
+        var totalAccepted = 0;
+        var totalRejected = 0;
+        foreach (var po in purchaseOrders)
+        {
+            foreach (var receipt in await goodsReceiptRepo.GetByPurchaseOrderIdAsync(po.Id))
+            {
+                foreach (var item in receipt.Items.Where(i => i.IsActive))
+                {
+                    totalAccepted += item.AcceptedQuantity;
+                    totalRejected += item.RejectedQuantity;
+                }
+            }
+        }
+
+        var lineFulfillmentRatio = receivedLines + cancelledLines > 0
+            ? (decimal)receivedLines / (receivedLines + cancelledLines)
+            : (decimal?)null;
+
+        var acceptanceRatio = totalAccepted + totalRejected > 0
+            ? (decimal)totalAccepted / (totalAccepted + totalRejected)
+            : (decimal?)null;
+
+        decimal score;
+        if (lineFulfillmentRatio.HasValue && acceptanceRatio.HasValue)
+            score = Math.Round((lineFulfillmentRatio.Value + acceptanceRatio.Value) / 2m * 100m, 2);
+        else if (lineFulfillmentRatio.HasValue)
+            score = Math.Round(lineFulfillmentRatio.Value * 100m, 2);
+        else if (acceptanceRatio.HasValue)
+            score = Math.Round(acceptanceRatio.Value * 100m, 2);
+        else
+            score = 50m;
+
+        supplier.PerformanceScore = score;
+
+        await uow.BeginAsync(ct);
+        try { repo.Update(supplier); await uow.CommitAsync(ct); }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return Map(supplier);
+    }
 }

Distribution/Migrations/20260820064447_AddStoreCreditAndKyc.cs

@@ -1,716 +0,0 @@
-using System;
-using Microsoft.EntityFrameworkCore.Migrations;
-
-#nullable disable
-
-#pragma warning disable CA1814 // Prefer jagged arrays over multidimensional
-
-namespace Distribution.Migrations
-{
-    /// <inheritdoc />
-    public partial class AddStoreCreditAndKyc : Migration
-    {
-        /// <inheritdoc />
-        protected override void Up(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000021"), new Guid("10000000-0000-0000-0000-000000000001") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000022"), new Guid("10000000-0000-0000-0000-000000000001") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000001") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000035"), new Guid("10000000-0000-0000-0000-000000000001") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000021"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000022"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000035"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000021"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000022"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000032"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000021"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000022"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000032"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000005") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000032"), new Guid("10000000-0000-0000-0000-000000000005") });
-
-            migrationBuilder.AddColumn<decimal>(
-                name: "CreditLimit",
-                table: "Stores",
-                type: "decimal(65,30)",
-                nullable: false,
-                defaultValue: 0m);
-
-            migrationBuilder.AddColumn<int>(
-                name: "KycStatus",
-                table: "Stores",
-                type: "int",
-                nullable: false,
-                defaultValue: 0);
-
-            migrationBuilder.AddColumn<decimal>(
-                name: "OutstandingBalance",
-                table: "Stores",
-                type: "decimal(65,30)",
-                nullable: false,
-                defaultValue: 0m);
-
-            migrationBuilder.AddColumn<string>(
-                name: "Segment",
-                table: "Stores",
-                type: "longtext",
-                nullable: true)
-                .Annotation("MySql:CharSet", "utf8mb4");
-
-            migrationBuilder.CreateTable(
-                name: "StoreKycDocuments",
-                columns: table => new
-                {
-                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    FK_StoreId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    DocumentType = table.Column<string>(type: "longtext", nullable: false)
-                        .Annotation("MySql:CharSet", "utf8mb4"),
-                    FileReference = table.Column<string>(type: "longtext", nullable: false)
-                        .Annotation("MySql:CharSet", "utf8mb4"),
-                    UploadedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_StoreKycDocuments", x => x.Id);
-                    table.ForeignKey(
-                        name: "FK_StoreKycDocuments_Stores_FK_StoreId",
-                        column: x => x.FK_StoreId,
-                        principalTable: "Stores",
-                        principalColumn: "Id",
-                        onDelete: ReferentialAction.Cascade);
-                })
-                .Annotation("MySql:CharSet", "utf8mb4");
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000017"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "stores.kyc.verify", "Verify or reject store KYC documents" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000018"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "stores.credit.update", "Update store credit limit and outstanding balance" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000019"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "warehouses.view", "View warehouses" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000020"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "warehouses.create", "Create warehouses" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000021"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "warehouses.update", "Update warehouses" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000022"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "warehouses.delete", "Delete warehouses" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000023"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "orders.view", "View orders" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000024"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "orders.create", "Create orders" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000025"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "orders.update", "Update orders" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000026"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "orders.delete", "Delete orders" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000027"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.view", "View users" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000028"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.create", "Create users" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000029"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.update", "Update users" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000030"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.deactivate", "Deactivate users" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000031"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.assign_role", "Assign a role to a user" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000032"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.assign_scope", "Assign region/route/store scope to a user" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000033"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "items.view", "View items, brands and UOMs" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000034"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "items.create", "Create items, brands and UOMs" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000035"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "items.update", "Update items, brands and UOMs" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000036"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "items.delete", "Delete items, brands and UOMs" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000037"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "categories.view", "View categories" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000038"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "categories.create", "Create categories and subcategories" });
-
-            migrationBuilder.InsertData(
-                table: "Permissions",
-                columns: new[] { "Id", "Code", "CreatedAt", "Description", "IsActive" },
-                values: new object[,]
-                {
-                    { new Guid("20000000-0000-0000-0000-000000000039"), "categories.update", new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), "Update categories and subcategories", true },
-                    { new Guid("20000000-0000-0000-0000-000000000040"), "categories.delete", new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), "Delete categories and subcategories", true }
-                });
-
-            migrationBuilder.InsertData(
-                table: "RolePermissions",
-                columns: new[] { "FK_PermissionId", "FK_RoleId", "CreatedAt", "Id", "IsActive" },
-                values: new object[,]
-                {
-                    { new Guid("20000000-0000-0000-0000-000000000024"), new Guid("10000000-0000-0000-0000-000000000001"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("c0739b84-50a2-0971-429b-02bab8354c51"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000025"), new Guid("10000000-0000-0000-0000-000000000001"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("c268a531-44eb-0f29-82ba-18394ac2dcb5"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000033"), new Guid("10000000-0000-0000-0000-000000000001"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("ddb2d04d-19b0-20b1-2639-b157d12a9eec"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000037"), new Guid("10000000-0000-0000-0000-000000000001"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("320ba3fb-666c-ce57-3e61-95c9824c4048"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000018"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("f2c14d55-d557-5cd2-a70a-4a6f58933436"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000025"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("1b126bb0-e582-3e84-4728-a7ab5628fe7b"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000026"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("f50b201c-6c8d-0df8-85ad-08cb137bc213"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000033"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("0f291826-e169-c06a-0735-bd06cbb2062d"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000037"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("10dd0249-ce04-c5d9-8f94-ccb348c1d979"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000018"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("d92d572f-f1bf-9e7d-1d4d-7c7b0d575c8e"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000019"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("f367f6f6-3d26-7a6c-888b-da1a240b59af"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000025"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("929950da-d51b-ad5d-c4e5-55175908fb43"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000026"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("a9a49749-f99d-3166-5d92-b7e380fcabb2"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000034"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("b17df3df-022c-c903-6ce0-e6423e648dc8"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000037"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("a41f94ba-c24d-93dc-9f25-c462df19785a"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000016"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("e0b27435-f505-43f5-7ed9-4711f2248495"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000018"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("5e10d61c-2d7a-3388-722f-45232d2cfb71"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000019"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("d8257363-d838-fe7e-57a5-51b626dbfc83"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000025"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("04ece77e-b36f-8ed0-4ef9-2f6962b6f9c6"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000026"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("bf2a2f96-04ed-905d-5a8a-9047d814aa3e"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000026"), new Guid("10000000-0000-0000-0000-000000000005"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("4d287b19-ba40-7d4d-3d39-291be64197f8"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000027"), new Guid("10000000-0000-0000-0000-000000000005"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("43a4c7b4-a50f-aa37-b147-a30636d9d65f"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000039"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("a66f3854-5a8f-95c2-cb1c-b2b2e67ee226"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000040"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("14bcecd1-b1a2-6da3-155a-233611484467"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000039"), new Guid("10000000-0000-0000-0000-000000000005"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("aeb29e0e-e819-1446-6cc6-1fb64b5ecc6b"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000040"), new Guid("10000000-0000-0000-0000-000000000005"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("e18a6eca-1009-bcc6-35e9-ead943c1649f"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000039"), new Guid("10000000-0000-0000-0000-000000000006"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("3f32cdac-6925-23f2-064e-8226d781d4a3"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000040"), new Guid("10000000-0000-0000-0000-000000000006"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("dc3dd9ff-b123-a8d4-dcea-b4f5f8ff171e"), true }
-                });
-
-            migrationBuilder.CreateIndex(
-                name: "IX_StoreKycDocuments_FK_StoreId",
-                table: "StoreKycDocuments",
-                column: "FK_StoreId");
-        }
-
-        /// <inheritdoc />
-        protected override void Down(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.DropTable(
-                name: "StoreKycDocuments");
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000024"), new Guid("10000000-0000-0000-0000-000000000001") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000025"), new Guid("10000000-0000-0000-0000-000000000001") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000033"), new Guid("10000000-0000-0000-0000-000000000001") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000037"), new Guid("10000000-0000-0000-0000-000000000001") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000018"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000025"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000026"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000033"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000037"), new Guid("10000000-0000-0000-0000-000000000002") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000018"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000019"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000025"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000026"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000034"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000037"), new Guid("10000000-0000-0000-0000-000000000003") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000016"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000018"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000019"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000025"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000026"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000039"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000040"), new Guid("10000000-0000-0000-0000-000000000004") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000026"), new Guid("10000000-0000-0000-0000-000000000005") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000027"), new Guid("10000000-0000-0000-0000-000000000005") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000039"), new Guid("10000000-0000-0000-0000-000000000005") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000040"), new Guid("10000000-0000-0000-0000-000000000005") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000039"), new Guid("10000000-0000-0000-0000-000000000006") });
-
-            migrationBuilder.DeleteData(
-                table: "RolePermissions",
-                keyColumns: new[] { "FK_PermissionId", "FK_RoleId" },
-                keyValues: new object[] { new Guid("20000000-0000-0000-0000-000000000040"), new Guid("10000000-0000-0000-0000-000000000006") });
-
-            migrationBuilder.DeleteData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000039"));
-
-            migrationBuilder.DeleteData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000040"));
-
-            migrationBuilder.DropColumn(
-                name: "CreditLimit",
-                table: "Stores");
-
-            migrationBuilder.DropColumn(
-                name: "KycStatus",
-                table: "Stores");
-
-            migrationBuilder.DropColumn(
-                name: "OutstandingBalance",
-                table: "Stores");
-
-            migrationBuilder.DropColumn(
-                name: "Segment",
-                table: "Stores");
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000017"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "warehouses.view", "View warehouses" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000018"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "warehouses.create", "Create warehouses" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000019"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "warehouses.update", "Update warehouses" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000020"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "warehouses.delete", "Delete warehouses" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000021"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "orders.view", "View orders" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000022"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "orders.create", "Create orders" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000023"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "orders.update", "Update orders" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000024"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "orders.delete", "Delete orders" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000025"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.view", "View users" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000026"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.create", "Create users" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000027"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.update", "Update users" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000028"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.deactivate", "Deactivate users" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000029"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.assign_role", "Assign a role to a user" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000030"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "users.assign_scope", "Assign region/route/store scope to a user" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000031"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "items.view", "View items, brands and UOMs" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000032"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "items.create", "Create items, brands and UOMs" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000033"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "items.update", "Update items, brands and UOMs" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000034"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "items.delete", "Delete items, brands and UOMs" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000035"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "categories.view", "View categories" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000036"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "categories.create", "Create categories and subcategories" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000037"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "categories.update", "Update categories and subcategories" });
-
-            migrationBuilder.UpdateData(
-                table: "Permissions",
-                keyColumn: "Id",
-                keyValue: new Guid("20000000-0000-0000-0000-000000000038"),
-                columns: new[] { "Code", "Description" },
-                values: new object[] { "categories.delete", "Delete categories and subcategories" });
-
-            migrationBuilder.InsertData(
-                table: "RolePermissions",
-                columns: new[] { "FK_PermissionId", "FK_RoleId", "CreatedAt", "Id", "IsActive" },
-                values: new object[,]
-                {
-                    { new Guid("20000000-0000-0000-0000-000000000021"), new Guid("10000000-0000-0000-0000-000000000001"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("85ef4e27-8643-9c43-71f6-da56f66a5c47"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000022"), new Guid("10000000-0000-0000-0000-000000000001"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("1e353909-d682-58f6-df5c-8e57fa2512c9"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000001"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("7596f703-c6ab-316c-7c80-3f4e3daa174e"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000035"), new Guid("10000000-0000-0000-0000-000000000001"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("aa120c36-488e-34ba-e10a-2ac45e46e119"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000021"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("e4648655-7267-141e-51fa-f7d5fe3d2356"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000022"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("d427b9ea-2c9b-d93e-0843-02dfa1ae8887"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("b7dee5e3-f329-95a5-75c1-d02c3e40e229"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000035"), new Guid("10000000-0000-0000-0000-000000000002"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("e5506b30-527d-08f9-6caa-8a45d3d02999"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000021"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("0dd5c943-3ace-0560-6fbc-54d8e37ce014"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000022"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("ca97fb3d-132c-d8a5-4ab8-f7b8fc60f5e5"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("7780d277-9597-84ff-1a1a-f63fc6b4d3cb"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000032"), new Guid("10000000-0000-0000-0000-000000000003"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("8083c659-9506-0bd9-b793-3d6148ce9192"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000021"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("5c00e972-a697-d71a-6545-1fd8618826cf"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000022"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("e9b6af8e-7947-7290-9c92-2d9b6239f395"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("a701da28-aa75-3c1d-abdb-4317404f8df6"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000032"), new Guid("10000000-0000-0000-0000-000000000004"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("2c025310-765f-7d07-ab9a-50524c13d1d3"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000031"), new Guid("10000000-0000-0000-0000-000000000005"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("69f93a29-1df1-7b20-9d5c-94c264f8c4b8"), true },
-                    { new Guid("20000000-0000-0000-0000-000000000032"), new Guid("10000000-0000-0000-0000-000000000005"), new DateTime(2026, 8, 18, 0, 0, 0, 0, DateTimeKind.Unspecified), new Guid("070813f7-4053-2889-0d14-d0d5834208c2"), true }
-                });
-        }
-    }
-}

Distribution/Migrations/20260820074212_RideLifecycle.cs

@@ -1,257 +0,0 @@
-using System;
-using Microsoft.EntityFrameworkCore.Migrations;
-
-#nullable disable
-
-namespace Distribution.Migrations
-{
-    /// <inheritdoc />
-    public partial class RideLifecycle : Migration
-    {
-        /// <inheritdoc />
-        protected override void Up(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.AddColumn<Guid>(
-                name: "FK_DefaultWarehouseId",
-                table: "Vehicles",
-                type: "char(36)",
-                nullable: true,
-                collation: "ascii_general_ci");
-
-            migrationBuilder.AddColumn<DateTime>(
-                name: "ActivatedAt",
-                table: "DeliveryRuns",
-                type: "datetime(6)",
-                nullable: true);
-
-            migrationBuilder.AddColumn<DateTime>(
-                name: "ClosedAt",
-                table: "DeliveryRuns",
-                type: "datetime(6)",
-                nullable: true);
-
-            migrationBuilder.AddColumn<Guid>(
-                name: "FK_DriverProfileId",
-                table: "DeliveryRuns",
-                type: "char(36)",
-                nullable: false,
-                defaultValue: new Guid("00000000-0000-0000-0000-000000000000"),
-                collation: "ascii_general_ci");
-
-            migrationBuilder.AddColumn<Guid>(
-                name: "FK_SourceWarehouseId",
-                table: "DeliveryRuns",
-                type: "char(36)",
-                nullable: false,
-                defaultValue: new Guid("00000000-0000-0000-0000-000000000000"),
-                collation: "ascii_general_ci");
-
-            migrationBuilder.AddColumn<int>(
-                name: "RideType",
-                table: "DeliveryRuns",
-                type: "int",
-                nullable: false,
-                defaultValue: 0);
-
-            migrationBuilder.AddColumn<DateTime>(
-                name: "StartedAt",
-                table: "DeliveryRuns",
-                type: "datetime(6)",
-                nullable: true);
-
-            migrationBuilder.AddColumn<int>(
-                name: "Status",
-                table: "DeliveryRuns",
-                type: "int",
-                nullable: false,
-                defaultValue: 0);
-
-            migrationBuilder.CreateTable(
-                name: "DriverComplianceConfigs",
-                columns: table => new
-                {
-                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    EnforceLicenseExpiry = table.Column<bool>(type: "tinyint(1)", nullable: false),
-                    EnforceMedicalClearance = table.Column<bool>(type: "tinyint(1)", nullable: false),
-                    UpdatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    UpdatedBy = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci")
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_DriverComplianceConfigs", x => x.Id);
-                })
-                .Annotation("MySql:CharSet", "utf8mb4");
-
-            migrationBuilder.CreateTable(
-                name: "DriverProfiles",
-                columns: table => new
-                {
-                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    FK_UserId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    LicenseNumber = table.Column<string>(type: "longtext", nullable: false)
-                        .Annotation("MySql:CharSet", "utf8mb4"),
-                    LicenseExpiry = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    MedicalClearanceExpiry = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_DriverProfiles", x => x.Id);
-                    table.ForeignKey(
-                        name: "FK_DriverProfiles_Users_FK_UserId",
-                        column: x => x.FK_UserId,
-                        principalTable: "Users",
-                        principalColumn: "Id",
-                        onDelete: ReferentialAction.Cascade);
-                })
-                .Annotation("MySql:CharSet", "utf8mb4");
-
-            migrationBuilder.CreateTable(
-                name: "RideCancelRequests",
-                columns: table => new
-                {
-                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    FK_RideId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    TypeCode = table.Column<int>(type: "int", nullable: false),
-                    Reason = table.Column<string>(type: "longtext", nullable: false)
-                        .Annotation("MySql:CharSet", "utf8mb4"),
-                    RequestedBy = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    RequestedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    Status = table.Column<int>(type: "int", nullable: false),
-                    ApprovedBy = table.Column<Guid>(type: "char(36)", nullable: true, collation: "ascii_general_ci"),
-                    ApprovedAt = table.Column<DateTime>(type: "datetime(6)", nullable: true)
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_RideCancelRequests", x => x.Id);
-                    table.ForeignKey(
-                        name: "FK_RideCancelRequests_DeliveryRuns_FK_RideId",
-                        column: x => x.FK_RideId,
-                        principalTable: "DeliveryRuns",
-                        principalColumn: "Id",
-                        onDelete: ReferentialAction.Cascade);
-                })
-                .Annotation("MySql:CharSet", "utf8mb4");
-
-            migrationBuilder.CreateIndex(
-                name: "IX_Vehicles_FK_DefaultWarehouseId",
-                table: "Vehicles",
-                column: "FK_DefaultWarehouseId");
-
-            migrationBuilder.CreateIndex(
-                name: "IX_DeliveryRuns_FK_DriverProfileId",
-                table: "DeliveryRuns",
-                column: "FK_DriverProfileId");
-
-            migrationBuilder.CreateIndex(
-                name: "IX_DeliveryRuns_FK_SourceWarehouseId",
-                table: "DeliveryRuns",
-                column: "FK_SourceWarehouseId");
-
-            migrationBuilder.CreateIndex(
-                name: "IX_DriverProfiles_FK_UserId",
-                table: "DriverProfiles",
-                column: "FK_UserId",
-                unique: true);
-
-            migrationBuilder.CreateIndex(
-                name: "IX_RideCancelRequests_FK_RideId",
-                table: "RideCancelRequests",
-                column: "FK_RideId");
-
-            migrationBuilder.AddForeignKey(
-                name: "FK_DeliveryRuns_DriverProfiles_FK_DriverProfileId",
-                table: "DeliveryRuns",
-                column: "FK_DriverProfileId",
-                principalTable: "DriverProfiles",
-                principalColumn: "Id",
-                onDelete: ReferentialAction.Restrict);
-
-            migrationBuilder.AddForeignKey(
-                name: "FK_DeliveryRuns_Warehouses_FK_SourceWarehouseId",
-                table: "DeliveryRuns",
-                column: "FK_SourceWarehouseId",
-                principalTable: "Warehouses",
-                principalColumn: "Id",
-                onDelete: ReferentialAction.Restrict);
-
-            migrationBuilder.AddForeignKey(
-                name: "FK_Vehicles_Warehouses_FK_DefaultWarehouseId",
-                table: "Vehicles",
-                column: "FK_DefaultWarehouseId",
-                principalTable: "Warehouses",
-                principalColumn: "Id",
-                onDelete: ReferentialAction.Restrict);
-        }
-
-        /// <inheritdoc />
-        protected override void Down(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.DropForeignKey(
-                name: "FK_DeliveryRuns_DriverProfiles_FK_DriverProfileId",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropForeignKey(
-                name: "FK_DeliveryRuns_Warehouses_FK_SourceWarehouseId",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropForeignKey(
-                name: "FK_Vehicles_Warehouses_FK_DefaultWarehouseId",
-                table: "Vehicles");
-
-            migrationBuilder.DropTable(
-                name: "DriverComplianceConfigs");
-
-            migrationBuilder.DropTable(
-                name: "DriverProfiles");
-
-            migrationBuilder.DropTable(
-                name: "RideCancelRequests");
-
-            migrationBuilder.DropIndex(
-                name: "IX_Vehicles_FK_DefaultWarehouseId",
-                table: "Vehicles");
-
-            migrationBuilder.DropIndex(
-                name: "IX_DeliveryRuns_FK_DriverProfileId",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropIndex(
-                name: "IX_DeliveryRuns_FK_SourceWarehouseId",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropColumn(
-                name: "FK_DefaultWarehouseId",
-                table: "Vehicles");
-
-            migrationBuilder.DropColumn(
-                name: "ActivatedAt",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropColumn(
-                name: "ClosedAt",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropColumn(
-                name: "FK_DriverProfileId",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropColumn(
-                name: "FK_SourceWarehouseId",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropColumn(
-                name: "RideType",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropColumn(
-                name: "StartedAt",
-                table: "DeliveryRuns");
-
-            migrationBuilder.DropColumn(
-                name: "Status",
-                table: "DeliveryRuns");
-        }
-    }
-}

Distribution/Migrations/20260820083344_ridelife.cs

@@ -1,23 +0,0 @@
-using System;
-using Microsoft.EntityFrameworkCore.Migrations;
-
-#nullable disable
-
-#pragma warning disable CA1814 // Prefer jagged arrays over multidimensional
-
-namespace Distribution.Migrations
-{
-    /// <inheritdoc />
-    public partial class ridelife : Migration
-    {
-        /// <inheritdoc />
-        protected override void Up(MigrationBuilder migrationBuilder)
-        {
-        }
-
-        /// <inheritdoc />
-        protected override void Down(MigrationBuilder migrationBuilder)
-        {
-        }
-    }
-}

Distribution/Migrations/20260820101525_AddPricingAndSuppliers.cs

@@ -1,116 +0,0 @@
-using System;
-using Microsoft.EntityFrameworkCore.Migrations;
-
-#nullable disable
-
-namespace Distribution.Migrations
-{
-    /// <inheritdoc />
-    public partial class AddPricingAndSuppliers : Migration
-    {
-        /// <inheritdoc />
-        protected override void Up(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.CreateTable(
-                name: "PriceLists",
-                columns: table => new
-                {
-                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    Name = table.Column<string>(type: "longtext", nullable: false)
-                        .Annotation("MySql:CharSet", "utf8mb4"),
-                    FK_RegionId = table.Column<Guid>(type: "char(36)", nullable: true, collation: "ascii_general_ci"),
-                    EffectiveFrom = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    EffectiveTo = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_PriceLists", x => x.Id);
-                    table.ForeignKey(
-                        name: "FK_PriceLists_Regions_FK_RegionId",
-                        column: x => x.FK_RegionId,
-                        principalTable: "Regions",
-                        principalColumn: "Id");
-                })
-                .Annotation("MySql:CharSet", "utf8mb4");
-
-            migrationBuilder.CreateTable(
-                name: "Suppliers",
-                columns: table => new
-                {
-                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    Name = table.Column<string>(type: "longtext", nullable: false)
-                        .Annotation("MySql:CharSet", "utf8mb4"),
-                    ContactInfo = table.Column<string>(type: "longtext", nullable: true)
-                        .Annotation("MySql:CharSet", "utf8mb4"),
-                    PerformanceScore = table.Column<decimal>(type: "decimal(65,30)", nullable: true),
-                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_Suppliers", x => x.Id);
-                })
-                .Annotation("MySql:CharSet", "utf8mb4");
-
-            migrationBuilder.CreateTable(
-                name: "PriceListItems",
-                columns: table => new
-                {
-                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    FK_PriceListId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    FK_ItemId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
-                    Price = table.Column<decimal>(type: "decimal(65,30)", nullable: false),
-                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
-                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
-                },
-                constraints: table =>
-                {
-                    table.PrimaryKey("PK_PriceListItems", x => x.Id);
-                    table.ForeignKey(
-                        name: "FK_PriceListItems_Items_FK_ItemId",
-                        column: x => x.FK_ItemId,
-                        principalTable: "Items",
-                        principalColumn: "Id",
-                        onDelete: ReferentialAction.Cascade);
-                    table.ForeignKey(
-                        name: "FK_PriceListItems_PriceLists_FK_PriceListId",
-                        column: x => x.FK_PriceListId,
-                        principalTable: "PriceLists",
-                        principalColumn: "Id",
-                        onDelete: ReferentialAction.Cascade);
-                })
-                .Annotation("MySql:CharSet", "utf8mb4");
-
-            migrationBuilder.CreateIndex(
-                name: "IX_PriceListItems_FK_ItemId",
-                table: "PriceListItems",
-                column: "FK_ItemId");
-
-            migrationBuilder.CreateIndex(
-                name: "IX_PriceListItems_FK_PriceListId_FK_ItemId",
-                table: "PriceListItems",
-                columns: new[] { "FK_PriceListId", "FK_ItemId" },
-                unique: true);
-
-            migrationBuilder.CreateIndex(
-                name: "IX_PriceLists_FK_RegionId",
-                table: "PriceLists",
-                column: "FK_RegionId");
-        }
-
-        /// <inheritdoc />
-        protected override void Down(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.DropTable(
-                name: "PriceListItems");
-
-            migrationBuilder.DropTable(
-                name: "Suppliers");
-
-            migrationBuilder.DropTable(
-                name: "PriceLists");
-        }
-    }
-}

Distribution/Migrations/20260820105946_AddPriceListItemMinPrice.cs

@@ -1,28 +0,0 @@
-using Microsoft.EntityFrameworkCore.Migrations;
-
-#nullable disable
-
-namespace Distribution.Migrations
-{
-    /// <inheritdoc />
-    public partial class AddPriceListItemMinPrice : Migration
-    {
-        /// <inheritdoc />
-        protected override void Up(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.AddColumn<decimal>(
-                name: "MinPrice",
-                table: "PriceListItems",
-                type: "decimal(65,30)",
-                nullable: true);
-        }
-
-        /// <inheritdoc />
-        protected override void Down(MigrationBuilder migrationBuilder)
-        {
-            migrationBuilder.DropColumn(
-                name: "MinPrice",
-                table: "PriceListItems");
-        }
-    }
-}

Distribution/Migrations/20260820134953_RidePermissions.cs

@@ -1,22 +0,0 @@
-using Microsoft.EntityFrameworkCore.Migrations;
-
-#nullable disable
-
-namespace Distribution.Migrations
-{
-    /// <inheritdoc />
-    public partial class RidePermissions : Migration
-    {
-        /// <inheritdoc />
-        protected override void Up(MigrationBuilder migrationBuilder)
-        {
-
-        }
-
-        /// <inheritdoc />
-        protected override void Down(MigrationBuilder migrationBuilder)
-        {
-
-        }
-    }
-}

Distribution/Migrations/20260824110925_AddProcurement.cs

@@ -0,0 +1,257 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Distribution.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddProcurement : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.CreateTable(
+                name: "PurchaseOrders",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_SupplierId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_CreatedByUserId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    Status = table.Column<int>(type: "int", nullable: false),
+                    CancelReason = table.Column<string>(type: "longtext", nullable: true)
+                        .Annotation("MySql:CharSet", "utf8mb4"),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_PurchaseOrders", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_PurchaseOrders_Suppliers_FK_SupplierId",
+                        column: x => x.FK_SupplierId,
+                        principalTable: "Suppliers",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateTable(
+                name: "GoodsReceipts",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_PurchaseOrderId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_ReceivedByUserId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_WarehouseId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    ReceivedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_GoodsReceipts", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_GoodsReceipts_PurchaseOrders_FK_PurchaseOrderId",
+                        column: x => x.FK_PurchaseOrderId,
+                        principalTable: "PurchaseOrders",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                    table.ForeignKey(
+                        name: "FK_GoodsReceipts_Warehouses_FK_WarehouseId",
+                        column: x => x.FK_WarehouseId,
+                        principalTable: "Warehouses",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateTable(
+                name: "PurchaseOrderItems",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_PurchaseOrderId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_ItemId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    Quantity = table.Column<int>(type: "int", nullable: false),
+                    UnitCost = table.Column<decimal>(type: "decimal(65,30)", nullable: false),
+                    ReceivedQuantity = table.Column<int>(type: "int", nullable: false),
+                    CancelledQuantity = table.Column<int>(type: "int", nullable: false),
+                    IsCancelled = table.Column<bool>(type: "tinyint(1)", nullable: false),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_PurchaseOrderItems", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_PurchaseOrderItems_Items_FK_ItemId",
+                        column: x => x.FK_ItemId,
+                        principalTable: "Items",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                    table.ForeignKey(
+                        name: "FK_PurchaseOrderItems_PurchaseOrders_FK_PurchaseOrderId",
+                        column: x => x.FK_PurchaseOrderId,
+                        principalTable: "PurchaseOrders",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateTable(
+                name: "PurchaseReturns",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_PurchaseOrderId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    Reason = table.Column<string>(type: "longtext", nullable: false)
+                        .Annotation("MySql:CharSet", "utf8mb4"),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_PurchaseReturns", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_PurchaseReturns_PurchaseOrders_FK_PurchaseOrderId",
+                        column: x => x.FK_PurchaseOrderId,
+                        principalTable: "PurchaseOrders",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateTable(
+                name: "GoodsReceiptItems",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_GoodsReceiptId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_PurchaseOrderItemId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    AcceptedQuantity = table.Column<int>(type: "int", nullable: false),
+                    RejectedQuantity = table.Column<int>(type: "int", nullable: false),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_GoodsReceiptItems", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_GoodsReceiptItems_GoodsReceipts_FK_GoodsReceiptId",
+                        column: x => x.FK_GoodsReceiptId,
+                        principalTable: "GoodsReceipts",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                    table.ForeignKey(
+                        name: "FK_GoodsReceiptItems_PurchaseOrderItems_FK_PurchaseOrderItemId",
+                        column: x => x.FK_PurchaseOrderItemId,
+                        principalTable: "PurchaseOrderItems",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateTable(
+                name: "PurchaseReturnItems",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_PurchaseReturnId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_ItemId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    Quantity = table.Column<int>(type: "int", nullable: false),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_PurchaseReturnItems", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_PurchaseReturnItems_Items_FK_ItemId",
+                        column: x => x.FK_ItemId,
+                        principalTable: "Items",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                    table.ForeignKey(
+                        name: "FK_PurchaseReturnItems_PurchaseReturns_FK_PurchaseReturnId",
+                        column: x => x.FK_PurchaseReturnId,
+                        principalTable: "PurchaseReturns",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_GoodsReceiptItems_FK_GoodsReceiptId",
+                table: "GoodsReceiptItems",
+                column: "FK_GoodsReceiptId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_GoodsReceiptItems_FK_PurchaseOrderItemId",
+                table: "GoodsReceiptItems",
+                column: "FK_PurchaseOrderItemId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_GoodsReceipts_FK_PurchaseOrderId",
+                table: "GoodsReceipts",
+                column: "FK_PurchaseOrderId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_GoodsReceipts_FK_WarehouseId",
+                table: "GoodsReceipts",
+                column: "FK_WarehouseId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_PurchaseOrderItems_FK_ItemId",
+                table: "PurchaseOrderItems",
+                column: "FK_ItemId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_PurchaseOrderItems_FK_PurchaseOrderId",
+                table: "PurchaseOrderItems",
+                column: "FK_PurchaseOrderId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_PurchaseOrders_FK_SupplierId",
+                table: "PurchaseOrders",
+                column: "FK_SupplierId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_PurchaseReturnItems_FK_ItemId",
+                table: "PurchaseReturnItems",
+                column: "FK_ItemId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_PurchaseReturnItems_FK_PurchaseReturnId",
+                table: "PurchaseReturnItems",
+                column: "FK_PurchaseReturnId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_PurchaseReturns_FK_PurchaseOrderId",
+                table: "PurchaseReturns",
+                column: "FK_PurchaseOrderId");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "GoodsReceiptItems");
+
+            migrationBuilder.DropTable(
+                name: "PurchaseReturnItems");
+
+            migrationBuilder.DropTable(
+                name: "GoodsReceipts");
+
+            migrationBuilder.DropTable(
+                name: "PurchaseOrderItems");
+
+            migrationBuilder.DropTable(
+                name: "PurchaseReturns");
+
+            migrationBuilder.DropTable(
+                name: "PurchaseOrders");
+        }
+    }
+}

Distribution/Migrations/20260824155602_payment.cs

@@ -0,0 +1,236 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Distribution.Migrations
+{
+    /// <inheritdoc />
+    public partial class payment : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<Guid>(
+                name: "FK_SaleId",
+                table: "Orders",
+                type: "char(36)",
+                nullable: false,
+                defaultValue: new Guid("00000000-0000-0000-0000-000000000000"),
+                collation: "ascii_general_ci");
+
+            migrationBuilder.AddColumn<DateTime>(
+                name: "FulfilledAt",
+                table: "Orders",
+                type: "datetime(6)",
+                nullable: true);
+
+            migrationBuilder.AddColumn<int>(
+                name: "Status",
+                table: "Orders",
+                type: "int",
+                nullable: false,
+                defaultValue: 0);
+
+            migrationBuilder.AddColumn<int>(
+                name: "QuantityFulfilled",
+                table: "OrderItems",
+                type: "int",
+                nullable: false,
+                defaultValue: 0);
+
+            migrationBuilder.CreateTable(
+                name: "DeliveryTasks",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_RideId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_OrderId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    Sequence = table.Column<int>(type: "int", nullable: false),
+                    Status = table.Column<int>(type: "int", nullable: false),
+                    CustomerConfirmed = table.Column<bool>(type: "tinyint(1)", nullable: false),
+                    ConfirmedAt = table.Column<DateTime>(type: "datetime(6)", nullable: true),
+                    Note = table.Column<string>(type: "longtext", nullable: true)
+                        .Annotation("MySql:CharSet", "utf8mb4"),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_DeliveryTasks", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_DeliveryTasks_DeliveryRuns_FK_RideId",
+                        column: x => x.FK_RideId,
+                        principalTable: "DeliveryRuns",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                    table.ForeignKey(
+                        name: "FK_DeliveryTasks_Orders_FK_OrderId",
+                        column: x => x.FK_OrderId,
+                        principalTable: "Orders",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateTable(
+                name: "Sales",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    SaleDate = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    FK_StoreId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    CreatedByUserId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_RideId = table.Column<Guid>(type: "char(36)", nullable: true, collation: "ascii_general_ci"),
+                    TotalAmount = table.Column<decimal>(type: "decimal(65,30)", nullable: false),
+                    Status = table.Column<int>(type: "int", nullable: false),
+                    PaymentStatus = table.Column<int>(type: "int", nullable: false),
+                    FulfillImmediately = table.Column<bool>(type: "tinyint(1)", nullable: false),
+                    CompletedAt = table.Column<DateTime>(type: "datetime(6)", nullable: true),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_Sales", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_Sales_DeliveryRuns_FK_RideId",
+                        column: x => x.FK_RideId,
+                        principalTable: "DeliveryRuns",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                    table.ForeignKey(
+                        name: "FK_Sales_Stores_FK_StoreId",
+                        column: x => x.FK_StoreId,
+                        principalTable: "Stores",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                    table.ForeignKey(
+                        name: "FK_Sales_Users_CreatedByUserId",
+                        column: x => x.CreatedByUserId,
+                        principalTable: "Users",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Restrict);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateTable(
+                name: "Payments",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_SaleId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    FK_StoreId = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    Amount = table.Column<decimal>(type: "decimal(65,30)", nullable: false),
+                    Method = table.Column<int>(type: "int", nullable: false),
+                    CollectedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    CollectedBy = table.Column<Guid>(type: "char(36)", nullable: false, collation: "ascii_general_ci"),
+                    CreatedAt = table.Column<DateTime>(type: "datetime(6)", nullable: false),
+                    IsActive = table.Column<bool>(type: "tinyint(1)", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_Payments", x => x.Id);
+                    table.ForeignKey(
+                        name: "FK_Payments_Sales_FK_SaleId",
+                        column: x => x.FK_SaleId,
+                        principalTable: "Sales",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                    table.ForeignKey(
+                        name: "FK_Payments_Stores_FK_StoreId",
+                        column: x => x.FK_StoreId,
+                        principalTable: "Stores",
+                        principalColumn: "Id",
+                        onDelete: ReferentialAction.Cascade);
+                })
+                .Annotation("MySql:CharSet", "utf8mb4");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Orders_FK_SaleId",
+                table: "Orders",
+                column: "FK_SaleId",
+                unique: true);
+
+            migrationBuilder.CreateIndex(
+                name: "IX_DeliveryTasks_FK_OrderId",
+                table: "DeliveryTasks",
+                column: "FK_OrderId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_DeliveryTasks_FK_RideId",
+                table: "DeliveryTasks",
+                column: "FK_RideId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Payments_FK_SaleId",
+                table: "Payments",
+                column: "FK_SaleId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Payments_FK_StoreId",
+                table: "Payments",
+                column: "FK_StoreId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Sales_CreatedByUserId",
+                table: "Sales",
+                column: "CreatedByUserId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Sales_FK_RideId",
+                table: "Sales",
+                column: "FK_RideId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Sales_FK_StoreId",
+                table: "Sales",
+                column: "FK_StoreId");
+
+            migrationBuilder.AddForeignKey(
+                name: "FK_Orders_Sales_FK_SaleId",
+                table: "Orders",
+                column: "FK_SaleId",
+                principalTable: "Sales",
+                principalColumn: "Id",
+                onDelete: ReferentialAction.Restrict);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropForeignKey(
+                name: "FK_Orders_Sales_FK_SaleId",
+                table: "Orders");
+
+            migrationBuilder.DropTable(
+                name: "DeliveryTasks");
+
+            migrationBuilder.DropTable(
+                name: "Payments");
+
+            migrationBuilder.DropTable(
+                name: "Sales");
+
+            migrationBuilder.DropIndex(
+                name: "IX_Orders_FK_SaleId",
+                table: "Orders");
+
+            migrationBuilder.DropColumn(
+                name: "FK_SaleId",
+                table: "Orders");
+
+            migrationBuilder.DropColumn(
+                name: "FulfilledAt",
+                table: "Orders");
+
+            migrationBuilder.DropColumn(
+                name: "Status",
+                table: "Orders");
+
+            migrationBuilder.DropColumn(
+                name: "QuantityFulfilled",
+                table: "OrderItems");
+        }
+    }
+}

Distribution/Models/DeliveryTask.cs

@@ -0,0 +1,21 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class DeliveryTask : Template
+    {
+        public Guid FK_RideId { get; set; }
+        [ForeignKey("FK_RideId")]
+        public DeliveryRun Ride { get; set; }
+
+        public Guid FK_OrderId { get; set; }
+        [ForeignKey("FK_OrderId")]
+        public Order Order { get; set; }
+
+        public int Sequence { get; set; }
+        public DeliveryTaskStatus Status { get; set; } = DeliveryTaskStatus.Pending;
+        public bool CustomerConfirmed { get; set; } = false;
+        public DateTime? ConfirmedAt { get; set; }
+        public string? Note { get; set; }
+    }
+}

Distribution/Models/Enums.cs

@@ -18,7 +18,19 @@ namespace Distribution.Models
         CustomerReturn,
         Transfer,
         Damage,
-        Adjustment
+        Adjustment,
+        Load,
+        PurchaseReceipt,
+        PurchaseReturn
+    }
+
+    public enum LoadingSheetStatus
+    {
+        Pending,
+        DispatchConfirmed,
+        ReceiptConfirmed,
+        DiscrepancyFlagged,
+        Resolved
     }
 
     public enum RideType { Delivery, Sale }
@@ -28,4 +40,22 @@ namespace Distribution.Models
     public enum CancelRequestType { VehicleBreakdown, DriverUnavailable, RouteIssue, Other }
 
     public enum CancelRequestStatus { Pending, Approved, Rejected }
+
+    public enum PurchaseOrderStatus { Issued, PartiallyReceived, Received, Closed, Cancelled }
+
+    public enum SaleStatus { Pending, Completed, Cancelled }
+
+    public enum OrderStatus { Pending, PartiallyFulfilled, Fulfilled, Cancelled }
+
+    public enum PaymentStatus { Pending, PartiallyPaid, Paid }
+
+    public enum PaymentMethod { Cash, Credit }
+
+    public enum DeliveryTaskStatus
+    {
+        Pending,
+        Delivered,
+        PartiallyDelivered,
+        Failed
+    }
 }

Distribution/Models/GoodsReceipt.cs

@@ -0,0 +1,26 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class GoodsReceipt : Template
+    {
+        public Guid FK_PurchaseOrderId { get; set; }
+        [ForeignKey("FK_PurchaseOrderId")]
+        public PurchaseOrder PurchaseOrder { get; set; }
+
+        public Guid FK_ReceivedByUserId { get; set; }
+
+        /// <summary>
+        /// Warehouse the accepted quantities are received into. Not listed as a field in
+        /// docs/15_procurement.md's GoodsReceipt table, but required to write StockBalance/
+        /// StockMovement rows (both keyed by LocationId+LocationType) for the accepted quantities.
+        /// </summary>
+        public Guid FK_WarehouseId { get; set; }
+        [ForeignKey("FK_WarehouseId")]
+        public Warehouse Warehouse { get; set; }
+
+        public DateTime ReceivedAt { get; set; } = DateTime.Now;
+
+        public ICollection<GoodsReceiptItem> Items { get; set; } = [];
+    }
+}

Distribution/Models/GoodsReceiptItem.cs

@@ -0,0 +1,21 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class GoodsReceiptItem : Template
+    {
+        public Guid FK_GoodsReceiptId { get; set; }
+        [ForeignKey("FK_GoodsReceiptId")]
+        public GoodsReceipt GoodsReceipt { get; set; }
+
+        public Guid FK_PurchaseOrderItemId { get; set; }
+        [ForeignKey("FK_PurchaseOrderItemId")]
+        public PurchaseOrderItem PurchaseOrderItem { get; set; }
+
+        /// <summary>Added to warehouse stock.</summary>
+        public int AcceptedQuantity { get; set; }
+
+        /// <summary>Damaged/short at receipt, not added to stock.</summary>
+        public int RejectedQuantity { get; set; } = 0;
+    }
+}

Distribution/Models/Item.cs

@@ -26,6 +26,9 @@ namespace Distribution.Models
 
         public decimal? SalePrice { get; set; }
 
+        /// <summary>Cost/purchase price, used to value free-goods scheme redemptions for getSchemeROI.</summary>
+        public decimal? CostPrice { get; set; }
+
         public SyncSource SyncSource { get; set; } = SyncSource.Manual;
         public int? ExternalErpItemId { get; set; }
         public DateTime? LastSyncedAt { get; set; }

Distribution/Models/LoadingSheet.cs

@@ -0,0 +1,24 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class LoadingSheet : Template
+    {
+        public Guid FK_RideId { get; set; }
+        [ForeignKey("FK_RideId")]
+        public DeliveryRun Ride { get; set; }
+
+        public Guid FK_SourceWarehouseId { get; set; }
+        [ForeignKey("FK_SourceWarehouseId")]
+        public Warehouse SourceWarehouse { get; set; }
+
+        public LoadingSheetStatus Status { get; set; } = LoadingSheetStatus.Pending;
+
+        public DateTime? DispatchConfirmedAt { get; set; }
+        public Guid? DispatchConfirmedBy { get; set; }
+        public DateTime? ReceiptConfirmedAt { get; set; }
+        public Guid? ReceiptConfirmedBy { get; set; }
+
+        public List<LoadingSheetItem> Items { get; set; } = [];
+    }
+}

Distribution/Models/LoadingSheetItem.cs

@@ -0,0 +1,21 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class LoadingSheetItem
+    {
+        public Guid Id { get; set; } = Guid.NewGuid();
+
+        public Guid FK_LoadingSheetId { get; set; }
+        [ForeignKey("FK_LoadingSheetId")]
+        public LoadingSheet LoadingSheet { get; set; }
+
+        public Guid FK_ItemId { get; set; }
+        [ForeignKey("FK_ItemId")]
+        public Item Item { get; set; }
+
+        public decimal QuantityDispatched { get; set; }
+        public decimal? QuantityReceived { get; set; }
+        public decimal? QuantityResolved { get; set; }
+    }
+}

Distribution/Models/Order.cs

@@ -4,10 +4,18 @@ namespace Distribution.Models
 {
     public class Order : Template
     {
+        public Guid FK_SaleId { get; set; }
+        [ForeignKey("FK_SaleId")]
+        public Sale Sale { get; set; }
+
         public DateTime OrderDate { get; set; }
         public Guid FK_StoreId { get; set; }
         [ForeignKey("FK_StoreId")]
         public Store Store { get; set; }
         public decimal TotalAmount { get; set; }
+        public OrderStatus Status { get; set; } = OrderStatus.Pending;
+        public DateTime? FulfilledAt { get; set; }
+
+        public ICollection<OrderItem> OrderItems { get; set; } = new List<OrderItem>();
     }
 }

Distribution/Models/OrderItem.cs

@@ -11,6 +11,7 @@ namespace Distribution.Models
         [ForeignKey("FK_ItemId")]
         public Item Item { get; set; }
         public int Quantity { get; set; }
+        public int QuantityFulfilled { get; set; } = 0;
         public decimal UnitPrice { get; set; }
     }
 }

Distribution/Models/Payment.cs

@@ -0,0 +1,20 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class Payment : Template
+    {
+        public Guid FK_SaleId { get; set; }
+        [ForeignKey("FK_SaleId")]
+        public Sale Sale { get; set; }
+
+        public Guid FK_StoreId { get; set; }
+        [ForeignKey("FK_StoreId")]
+        public Store Store { get; set; }
+
+        public decimal Amount { get; set; }
+        public PaymentMethod Method { get; set; }
+        public DateTime CollectedAt { get; set; }
+        public Guid CollectedBy { get; set; }
+    }
+}

Distribution/Models/PurchaseOrder.cs

@@ -0,0 +1,19 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class PurchaseOrder : Template
+    {
+        public Guid FK_SupplierId { get; set; }
+        [ForeignKey("FK_SupplierId")]
+        public Supplier Supplier { get; set; }
+
+        public Guid FK_CreatedByUserId { get; set; }
+
+        public PurchaseOrderStatus Status { get; set; } = PurchaseOrderStatus.Issued;
+
+        public string? CancelReason { get; set; }
+
+        public ICollection<PurchaseOrderItem> Items { get; set; } = [];
+    }
+}

Distribution/Models/PurchaseOrderItem.cs

@@ -0,0 +1,32 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class PurchaseOrderItem : Template
+    {
+        public Guid FK_PurchaseOrderId { get; set; }
+        [ForeignKey("FK_PurchaseOrderId")]
+        public PurchaseOrder PurchaseOrder { get; set; }
+
+        public Guid FK_ItemId { get; set; }
+        [ForeignKey("FK_ItemId")]
+        public Item Item { get; set; }
+
+        public int Quantity { get; set; }
+
+        /// <summary>Agreed cost per unit at the time the PO was issued.</summary>
+        public decimal UnitCost { get; set; }
+
+        /// <summary>Running total, incremented by createGoodsReceipt; drives PurchaseOrder.Status.</summary>
+        public int ReceivedQuantity { get; set; } = 0;
+
+        /// <summary>
+        /// Set by cancelPurchaseOrderLine. Outstanding qty for receiving purposes is
+        /// Quantity - ReceivedQuantity - CancelledQuantity.
+        /// </summary>
+        public int CancelledQuantity { get; set; } = 0;
+
+        /// <summary>True once this line is individually cancelled.</summary>
+        public bool IsCancelled { get; set; } = false;
+    }
+}

Distribution/Models/PurchaseReturn.cs

@@ -0,0 +1,15 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class PurchaseReturn : Template
+    {
+        public Guid FK_PurchaseOrderId { get; set; }
+        [ForeignKey("FK_PurchaseOrderId")]
+        public PurchaseOrder PurchaseOrder { get; set; }
+
+        public string Reason { get; set; }
+
+        public ICollection<PurchaseReturnItem> Items { get; set; } = [];
+    }
+}

Distribution/Models/PurchaseReturnItem.cs

@@ -0,0 +1,18 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class PurchaseReturnItem : Template
+    {
+        public Guid FK_PurchaseReturnId { get; set; }
+        [ForeignKey("FK_PurchaseReturnId")]
+        public PurchaseReturn PurchaseReturn { get; set; }
+
+        public Guid FK_ItemId { get; set; }
+        [ForeignKey("FK_ItemId")]
+        public Item Item { get; set; }
+
+        /// <summary>Returned quantity, decremented from warehouse stock.</summary>
+        public int Quantity { get; set; }
+    }
+}

Distribution/Models/Sale.cs

@@ -0,0 +1,27 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class Sale : Template
+    {
+        public DateTime SaleDate { get; set; }
+
+        public Guid FK_StoreId { get; set; }
+        [ForeignKey("FK_StoreId")]
+        public Store Store { get; set; }
+
+        public Guid CreatedByUserId { get; set; }
+        [ForeignKey("CreatedByUserId")]
+        public User CreatedByUser { get; set; }
+
+        public Guid? FK_RideId { get; set; }
+        [ForeignKey("FK_RideId")]
+        public DeliveryRun? Ride { get; set; }
+
+        public decimal TotalAmount { get; set; }
+        public SaleStatus Status { get; set; } = SaleStatus.Pending;
+        public PaymentStatus PaymentStatus { get; set; } = PaymentStatus.Pending;
+        public bool FulfillImmediately { get; set; }
+        public DateTime? CompletedAt { get; set; }
+    }
+}

Distribution/Models/Scheme.cs

@@ -0,0 +1,62 @@
+namespace Distribution.Models
+{
+    public enum SchemeRuleType
+    {
+        BuyXGetY,
+        SlabDiscount,
+        FlatPercent,
+        FreeBundle
+    }
+
+    public class Scheme : Template
+    {
+        public string Name { get; set; }
+        public SchemeRuleType RuleType { get; set; }
+
+        /// <summary>
+        /// JSON payload for percentage-based rules only (SlabDiscount tiers, FlatPercent). Free-goods
+        /// rules (BuyXGetY / FreeBundle) are structured fields/child rows below, not JSON, so they can
+        /// be managed through their own CRUD endpoints instead of a hand-edited blob.
+        /// </summary>
+        public string? RuleConfig { get; set; }
+
+        // ── BuyXGetY: trigger item/qty; shares FK_FreeItemId/FreeQty below as the payout. ──────────
+
+        public Guid? FK_TriggerItemId { get; set; }
+        public Item? TriggerItem { get; set; }
+        public int? TriggerQty { get; set; }
+
+        // ── Free-goods payout, used by both BuyXGetY and FreeBundle. ─────────────────────────────
+
+        public Guid? FK_FreeItemId { get; set; }
+        public Item? FreeItem { get; set; }
+        public decimal? FreeQty { get; set; }
+
+        /// <summary>Required component items for a FreeBundle scheme — managed via its own CRUD.</summary>
+        public ICollection<SchemeBundleComponent> BundleComponents { get; set; } = [];
+
+        public Guid? FK_RegionId { get; set; }
+        public Region? Region { get; set; }
+
+        /// <summary>Store segment this scheme applies to (Gold/Silver/Key Account/...); null = all segments.</summary>
+        public string? EligibleSegment { get; set; }
+
+        public DateTime DateRangeFrom { get; set; }
+        public DateTime DateRangeTo { get; set; }
+
+        /// <summary>
+        /// When true, this scheme's discount is exempt from the per-role discount ceiling in
+        /// 08_sales_agent_controls.md and stacks on top of it unconditionally.
+        /// </summary>
+        public bool AgentLimitExempt { get; set; }
+
+        /// <summary>
+        /// Manual baseline (expected sales with no scheme running) used by getSchemeROI. Per the
+        /// open question in docs/17_promotions_schemes.md, this is entered at scheme creation
+        /// rather than computed from a trailing-period average.
+        /// </summary>
+        public decimal? BaselineExpectedSales { get; set; }
+
+        public ICollection<SchemeRedemption> Redemptions { get; set; } = [];
+    }
+}

Distribution/Models/SchemeBundleComponent.cs

@@ -0,0 +1,20 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    /// <summary>A required item+qty line of a FreeBundle scheme (e.g. "buy A + B, get C free").</summary>
+    public class SchemeBundleComponent
+    {
+        public Guid Id { get; set; } = Guid.NewGuid();
+
+        public Guid FK_SchemeId { get; set; }
+        [ForeignKey("FK_SchemeId")]
+        public Scheme Scheme { get; set; }
+
+        public Guid FK_ItemId { get; set; }
+        [ForeignKey("FK_ItemId")]
+        public Item Item { get; set; }
+
+        public int Qty { get; set; }
+    }
+}

Distribution/Models/SchemeRedemption.cs

@@ -0,0 +1,36 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Distribution.Models
+{
+    public class SchemeRedemption
+    {
+        public Guid Id { get; set; } = Guid.NewGuid();
+
+        public Guid FK_SchemeId { get; set; }
+        [ForeignKey("FK_SchemeId")]
+        public Scheme Scheme { get; set; }
+
+        public Guid? FK_OrderId { get; set; }
+        [ForeignKey("FK_OrderId")]
+        public Order? Order { get; set; }
+
+        /// <summary>Placeholder for the future field-invoice module — no FieldInvoice entity exists yet.</summary>
+        public Guid? FieldInvoiceId { get; set; }
+
+        public decimal? DiscountAmount { get; set; }
+
+        public Guid? FK_FreeItemId { get; set; }
+        [ForeignKey("FK_FreeItemId")]
+        public Item? FreeItem { get; set; }
+
+        public decimal? FreeQty { get; set; }
+
+        /// <summary>
+        /// Cost price of the free item snapshotted at redemption time, so getSchemeROI stays
+        /// accurate even after the item's cost price later changes.
+        /// </summary>
+        public decimal? FreeItemCostValue { get; set; }
+
+        public DateTime RedeemedAt { get; set; } = DateTime.Now;
+    }
+}

Distribution/Models/Vehicle.cs

@@ -1,6 +1,4 @@
-using System.ComponentModel.DataAnnotations.Schema;
-
-namespace Distribution.Models
+namespace Distribution.Models
 {
     public class Vehicle : Template
     {
@@ -8,9 +6,7 @@ namespace Distribution.Models
         public string NumberPlate { get; set; }
         public VehicleType Type { get; set; }
 
-        public Guid? FK_DefaultWarehouseId { get; set; }
-        [ForeignKey("FK_DefaultWarehouseId")]
-        public Warehouse DefaultWarehouse { get; set; }
+        public Guid? DefaultWarehouseId { get; set; }
     }
     public enum VehicleType
     {

Distribution/PLAN.md

@@ -1,267 +1,78 @@
-# Phase Plan — Route & Store Management
+# Phase Plan - Route and Store Management
 
 ## Scope
 
-Build the full vertical-slice stack for: **Region, Route, Vehicle, Store, Warehouse, Order, OrderItem**.  
-Item model is sourced from ERP Core — excluded from this phase.  
-SaleRoute shape is TBD — excluded until clarified.
+Build the full vertical-slice stack for: **Region, Route, Vehicle, Store, Warehouse, Order,
+OrderItem**.
+
+Item model is sourced from ERP Core - excluded from this phase.
+
+Historical note: `SaleRoute` was marked TBD here. For now, rides stay single-route and route
+assignment remains simple until further clarification.
 
 ---
 
 ## Project Structure (target)
 
-```
+```text
 Distribution/
-├── Models/                          # All entity POCOs — unchanged
-│   ├── Template.cs
-│   ├── Region.cs
-│   ├── Route.cs
-│   ├── Vehicle.cs
-│   ├── Store.cs
-│   ├── Warehouse.cs
-│   ├── SaleRoute.cs                 # TBD
-│   ├── Order.cs
-│   ├── OrderItem.cs
-│   ├── DeliveryRun.cs
-│   └── Item.cs                      # Sourced from ERP Core
-├── Data/
-│   └── AppDBContext.cs              # DbSets + Fluent API config
-├── Infra/
-│   ├── UoW/                         # Already implemented
-│   │   ├── IUnitOfWork.cs
-│   │   └── EFUnitOfWork.cs
-│   └── Repositories/                # Shared generic base only
-│       ├── IGenericRepo.cs
-│       └── GenericRepo.cs
-└── Features/
-    ├── Region/
-    │   ├── RegionDTOs.cs
-    │   ├── IRegionRepository.cs
-    │   ├── RegionRepository.cs
-    │   ├── RegionService.cs
-    │   └── RegionController.cs
-    ├── Route/
-    │   ├── RouteDTOs.cs
-    │   ├── IRouteRepository.cs
-    │   ├── RouteRepository.cs
-    │   ├── RouteService.cs
-    │   └── RouteController.cs
-    ├── Vehicle/
-    │   ├── VehicleDTOs.cs
-    │   ├── IVehicleRepository.cs
-    │   ├── VehicleRepository.cs
-    │   ├── VehicleService.cs
-    │   └── VehicleController.cs
-    ├── Store/
-    │   ├── StoreDTOs.cs
-    │   ├── IStoreRepository.cs
-    │   ├── StoreRepository.cs
-    │   ├── StoreService.cs
-    │   └── StoreController.cs
-    ├── Warehouse/
-    │   ├── WarehouseDTOs.cs
-    │   ├── IWarehouseRepository.cs
-    │   ├── WarehouseRepository.cs
-    │   ├── WarehouseService.cs
-    │   └── WarehouseController.cs
-    └── Order/
-        ├── OrderDTOs.cs
-        ├── IOrderRepository.cs
-        ├── OrderRepository.cs
-        ├── OrderService.cs
-        └── OrderController.cs
+|-- Models/
+|   |-- Template.cs
+|   |-- Region.cs
+|   |-- Route.cs
+|   |-- Vehicle.cs
+|   |-- Store.cs
+|   |-- Warehouse.cs
+|   |-- SaleRoute.cs
+|   |-- Order.cs
+|   |-- OrderItem.cs
+|   |-- DeliveryRun.cs
+|   `-- Item.cs
+|-- Data/
+|   `-- AppDBContext.cs
+|-- Infra/
+|   |-- UoW/
+|   |   |-- IUnitOfWork.cs
+|   |   `-- EFUnitOfWork.cs
+|   `-- Repositories/
+|       |-- IGenericRepo.cs
+|       `-- GenericRepo.cs
+`-- Features/
+    |-- Region/
+    |-- Route/
+    |-- Vehicle/
+    |-- Store/
+    |-- Warehouse/
+    `-- Order/
 ```
 
 ---
 
-## Hard Rules (from AGENTS.md)
+## Hard Rules
 
-- Only `uow.CommitAsync()` in services — never in repositories.
-- Use `DateTime.Now` — never `DateTime.UtcNow`.
+- Only `uow.CommitAsync()` in services - never in repositories.
+- Use `DateTime.Now` - never `DateTime.UtcNow`.
 - Never build anything not explicitly requested.
 
 ---
 
-## Step 2 — Complete AppDBContext
-
-File: `Data/AppDBContext.cs`
-
-Add DbSets and Fluent API configuration:
-
-```csharp
-public DbSet<Region> Regions { get; set; }
-public DbSet<Route> Routes { get; set; }
-public DbSet<Vehicle> Vehicles { get; set; }
-public DbSet<Store> Stores { get; set; }
-public DbSet<Warehouse> Warehouses { get; set; }
-public DbSet<SaleRoute> SaleRoutes { get; set; }
-public DbSet<Order> Orders { get; set; }
-public DbSet<OrderItem> OrderItems { get; set; }
-public DbSet<DeliveryRun> DeliveryRuns { get; set; }
-public DbSet<Item> Items { get; set; }
-
-// OnModelCreating
-modelBuilder.Entity<OrderItem>()
-    .HasKey(oi => new { oi.FK_OrderId, oi.FK_ItemId });
-```
-
----
-
-## Step 3 — Initial Migration
-
-```powershell
-dotnet ef migrations add InitialCreate --project Distribution
-dotnet ef database update --project Distribution
-```
-
-Each developer applies this locally. No migration files are shared.
-
----
-
-## Step 4 — Generic Repository (Infra/Repositories)
-
-**`IGenericRepo<T>`**
-```
-GetByIdAsync(Guid id)
-GetAllAsync()
-AddAsync(T entity)
-Update(T entity)
-Remove(T entity)
-```
-
-**`GenericRepo<T>`** — implements above using DbContext. No `SaveChanges` calls.
-
----
-
-## Step 5 — Feature Implementation Order
-
-Build each feature in this dependency order:
-
-```
-1. Region      → no dependencies
-2. Route       → no dependencies
-3. Vehicle     → no dependencies
-4. Store       → no dependencies
-5. Warehouse   → depends on Vehicle (FK)
-6. Order       → depends on Store (FK)
-7. OrderItem   → depends on Order + Item (composite FK)
-```
-
-### Per-feature deliverables
-
-#### DTOs (`{Feature}DTOs.cs`)
-- `CreateRequest` — fields accepted on POST
-- `UpdateRequest` — fields accepted on PUT
-- `Response` — shape returned to client (never expose the entity directly)
-
-#### Repository interface (`I{Feature}Repository.cs`)
-Extends `IGenericRepo<T>`. Add feature-specific queries (e.g., `GetByStoreId`).
-
-#### Repository implementation (`{Feature}Repository.cs`)
-Inherits `GenericRepo<T>`. Implements feature-specific queries. No `CommitAsync` calls.
-
-#### Service (`{Feature}Service.cs`)
-- Contains all business logic.
-- Calls `_uow.CommitAsync(ct)` after write operations.
-- For multi-step writes: `BeginAsync → work → CommitAsync` (catch → `RollbackAsync`).
-
-#### Controller (`{Feature}Controller.cs`)
-Thin — maps HTTP → service call → returns result. No logic, no UoW calls.
-
----
-
-## Step 6 — Endpoints
-
-### Region — `/api/regions`
-| Method | Route | Description |
-|---|---|---|
-| GET | `/` | Get all active regions |
-| GET | `/{id}` | Get region by id |
-| POST | `/` | Create region |
-| PUT | `/{id}` | Update region |
-| DELETE | `/{id}` | Soft delete (set IsActive = false) |
-
-### Route — `/api/routes`
-| Method | Route | Description |
-|---|---|---|
-| GET | `/` | Get all active routes |
-| GET | `/{id}` | Get route by id |
-| POST | `/` | Create route |
-| PUT | `/{id}` | Update route |
-| DELETE | `/{id}` | Soft delete |
-
-### Vehicle — `/api/vehicles`
-| Method | Route | Description |
-|---|---|---|
-| GET | `/` | Get all active vehicles |
-| GET | `/{id}` | Get vehicle by id |
-| POST | `/` | Create vehicle |
-| PUT | `/{id}` | Update vehicle |
-| DELETE | `/{id}` | Soft delete |
-
-### Store — `/api/stores`
-| Method | Route | Description |
-|---|---|---|
-| GET | `/` | Get all active stores |
-| GET | `/{id}` | Get store by id |
-| POST | `/` | Create store |
-| PUT | `/{id}` | Update store |
-| DELETE | `/{id}` | Soft delete |
-
-### Warehouse — `/api/warehouses`
-| Method | Route | Description |
-|---|---|---|
-| GET | `/` | Get all active warehouses |
-| GET | `/{id}` | Get warehouse by id |
-| POST | `/` | Create warehouse |
-| PUT | `/{id}` | Update warehouse |
-| DELETE | `/{id}` | Soft delete |
-
-### Order — `/api/orders`
-| Method | Route | Description |
-|---|---|---|
-| GET | `/` | Get all active orders |
-| GET | `/{id}` | Get order with items |
-| GET | `/store/{storeId}` | Get orders by store |
-| POST | `/` | Create order with items |
-| PUT | `/{id}` | Update order |
-| DELETE | `/{id}` | Soft delete |
-
----
-
-## Step 7 — DI Registration (Program.cs)
-
-Register all feature repositories and services:
-
-```csharp
-// Generic base
-builder.Services.AddScoped(typeof(IGenericRepo<>), typeof(GenericRepo<>));
-
-// Feature repositories
-builder.Services.AddScoped<IRegionRepository, RegionRepository>();
-builder.Services.AddScoped<IRouteRepository, RouteRepository>();
-builder.Services.AddScoped<IVehicleRepository, VehicleRepository>();
-builder.Services.AddScoped<IStoreRepository, StoreRepository>();
-builder.Services.AddScoped<IWarehouseRepository, WarehouseRepository>();
-builder.Services.AddScoped<IOrderRepository, OrderRepository>();
-
-// Feature services
-builder.Services.AddScoped<RegionService>();
-builder.Services.AddScoped<RouteService>();
-builder.Services.AddScoped<VehicleService>();
-builder.Services.AddScoped<StoreService>();
-builder.Services.AddScoped<WarehouseService>();
-builder.Services.AddScoped<OrderService>();
-```
-
----
-
 ## Deferred
 
 | Item | Reason |
 |---|---|
-| `SaleRoute` | Shape undefined — implement after clarification |
-| `Item` model | Sourced from ERP Core — user handles integration |
+| `SaleRoute` | Re-evaluate after ride/route design is clarified |
+| `Item` model | Sourced from ERP Core |
 | `DeliveryRun` | Not in scope for this phase |
-| Driver FK on DeliveryRun | Commented out — depends on HR/Driver module |
-| Tests | No test project yet — add after endpoints stabilize |
+| Tests | No test project yet |
+
+---
+
+## Note
+
+This file is historical phase planning only. Current business definitions for ride, sale, order,
+and fulfillment are maintained in:
+
+- `docs/03_ride_lifecycle.md`
+- `docs/04_loading_event.md`
+- `docs/05_delivery_ride.md`
+- `docs/06_sale_ride.md`

Distribution/Program.cs

@@ -3,15 +3,23 @@ using Distribution.Data;
 using Distribution.Features.Auth;
 using Distribution.Features.Brand;
 using Distribution.Features.Category;
+using Distribution.Features.DeliveryRide;
+using Distribution.Features.Payment;
 using Distribution.Features.DriverComplianceConfig;
 using Distribution.Features.DriverProfile;
+using Distribution.Features.Grn;
 using Distribution.Features.Item;
 using Distribution.Features.Order;
 using Distribution.Features.PriceList;
+using Distribution.Features.Po;
+using Distribution.Features.PurchaseReturn;
 using Distribution.Features.Region;
+using Distribution.Features.LoadingEvent;
 using Distribution.Features.Ride;
 using Distribution.Features.Role;
 using Distribution.Features.Route;
+using Distribution.Features.Sale;
+using Distribution.Features.Scheme;
 using Distribution.Features.Store;
 using Distribution.Features.Store.Kyc;
 using Distribution.Features.Supplier;
@@ -44,6 +52,7 @@ builder.Services.AddScoped<IVehicleRepository, VehicleRepository>();
 builder.Services.AddScoped<IStoreRepository, StoreRepository>();
 builder.Services.AddScoped<IWarehouseRepository, WarehouseRepository>();
 builder.Services.AddScoped<IOrderRepository, OrderRepository>();
+builder.Services.AddScoped<ISaleRepository, SaleRepository>();
 builder.Services.AddScoped<IUserRepository, UserRepository>();
 builder.Services.AddScoped<IRoleRepository, RoleRepository>();
 builder.Services.AddScoped<ICategoryRepository, CategoryRepository>();
@@ -56,9 +65,16 @@ builder.Services.AddScoped<IDriverProfileRepository, DriverProfileRepository>();
 builder.Services.AddScoped<IDriverComplianceConfigRepository, DriverComplianceConfigRepository>();
 builder.Services.AddScoped<IRideRepository, RideRepository>();
 builder.Services.AddScoped<IRideCancelRequestRepository, RideCancelRequestRepository>();
+builder.Services.AddScoped<ILoadingSheetRepository, LoadingSheetRepository>();
 builder.Services.AddScoped<IStoreKycDocumentRepository, StoreKycDocumentRepository>();
 builder.Services.AddScoped<IPriceListRepository, PriceListRepository>();
 builder.Services.AddScoped<ISupplierRepository, SupplierRepository>();
+builder.Services.AddScoped<ISchemeRepository, SchemeRepository>();
+builder.Services.AddScoped<IPoRepository, PoRepository>();
+builder.Services.AddScoped<IGrnRepository, GrnRepository>();
+builder.Services.AddScoped<IPurchaseReturnRepository, PurchaseReturnRepository>();
+builder.Services.AddScoped<IDeliveryTaskRepository, DeliveryTaskRepository>();
+builder.Services.AddScoped<IPaymentRepository, PaymentRepository>();
 
 builder.Services.AddScoped<RegionService>();
 builder.Services.AddScoped<RouteService>();
@@ -66,6 +82,7 @@ builder.Services.AddScoped<VehicleService>();
 builder.Services.AddScoped<StoreService>();
 builder.Services.AddScoped<WarehouseService>();
 builder.Services.AddScoped<OrderService>();
+builder.Services.AddScoped<SaleService>();
 builder.Services.AddScoped<UserService>();
 builder.Services.AddScoped<RoleService>();
 builder.Services.AddScoped<AuthService>();
@@ -81,6 +98,13 @@ builder.Services.AddScoped<SupplierService>();
 builder.Services.AddScoped<DriverProfileService>();
 builder.Services.AddScoped<DriverComplianceConfigService>();
 builder.Services.AddScoped<RideService>();
+builder.Services.AddScoped<LoadingSheetService>();
+builder.Services.AddScoped<SchemeService>();
+builder.Services.AddScoped<PoService>();
+builder.Services.AddScoped<GrnService>();
+builder.Services.AddScoped<PurchaseReturnService>();
+builder.Services.AddScoped<DeliveryTaskService>();
+builder.Services.AddScoped<PaymentService>();
 
 builder.Services.AddHttpContextAccessor();
 builder.Services.AddScoped<ICurrentUserService, CurrentUserService>();

Distribution/docs/03_ride_lifecycle.md

@@ -1,41 +1,59 @@
-# 03 — Ride Lifecycle
+# 03 - Ride Lifecycle
 
 **Status**: Done
-**Depends On**: 02 — Stock Ledger
+**Depends On**: 02 - Stock Ledger
 
 ---
 
 ## Goal
 
-Turn the currently-unused `DeliveryRun` model into a fully working ride — a session that turns a
+Turn the currently-unused `DeliveryRun` model into a fully working ride - a session that turns a
 vehicle into a temporary warehouse. Covers driver profile management, ride creation, state
 transitions, cancellation workflow, and the vehicle breakdown scenario.
 
 ---
 
+## Current Business Understanding
+
+- A `Ride` is one operational trip for one vehicle and one driver on one route for now.
+- `RideType` distinguishes business behavior:
+  - `Delivery` ride: used to fulfill existing orders.
+  - `Sale` ride: used by sales agents in the field to create sales, and every sale creates an
+    order.
+- `Sale` and `Order` are different:
+  - `Sale` is the commercial transaction created by the sales agent.
+  - `Order` is the fulfillment document created from every sale.
+  - Item lines are maintained once in `OrderItem`; `Sale` does not keep a separate item-line table.
+- `Sale` statuses use sales language such as `Completed`.
+- `Order` statuses use logistics language such as `Fulfilled`.
+
+---
+
 ## Data Model Changes
 
-### New Entity — DriverProfile
+### New Entity - DriverProfile
 
-Linked one-to-one with `User`. Holds compliance data only — no login or auth fields.
+Linked one-to-one with `User`. Holds compliance data only - no login or auth fields.
 
 | Column | Type | Notes |
 |---|---|---|
 | Id | Guid | PK |
-| FK_UserId | Guid | FK → User (unique) |
+| FK_UserId | Guid | FK -> User (unique) |
 | LicenseNumber | string | |
 | LicenseExpiry | DateTime | |
 | MedicalClearanceExpiry | DateTime | |
 | IsActive | bool | Can be suspended without deleting |
 | CreatedAt | DateTime | |
 
-No license class tied to vehicle type — not required.
+No license class tied to vehicle type - not required.
 
-**Compliance check rule:** Driver is compliant if `IsActive = true`, plus any checks that are enabled in `DriverComplianceConfig`. By default all checks are disabled. When enabled: `LicenseExpiry > today` AND/OR `MedicalClearanceExpiry > today`.
+**Compliance check rule:** Driver is compliant if `IsActive = true`, plus any checks that are
+enabled in `DriverComplianceConfig`. By default all checks are disabled. When enabled:
+`LicenseExpiry > today` and/or `MedicalClearanceExpiry > today`.
 
 ---
 
-### Updated Entity — Vehicle
+### Updated Entity - Vehicle
 
 Add one nullable field:
 
@@ -45,7 +63,7 @@ Add one nullable field:
 
 ---
 
-### Updated Entity — DeliveryRun (becomes Ride)
+### Updated Entity - DeliveryRun (becomes Ride)
 
 Add the following fields to the existing `DeliveryRun`:
 
@@ -53,34 +71,43 @@ Add the following fields to the existing `DeliveryRun`:
 |---|---|---|
 | RideType | RideType | Delivery or Sale |
 | Status | RideStatus | State machine below |
-| FK_DriverProfileId | Guid | FK → DriverProfile |
+| FK_DriverProfileId | Guid | FK -> DriverProfile |
 | FK_SourceWarehouseId | Guid | Where stock is loaded from. Must be the same warehouse stock returns to on cancel/close. |
-| StartedAt | DateTime? | Set when Draft → Open |
-| ActivatedAt | DateTime? | Set when Open → Active |
-| ClosedAt | DateTime? | Set when Active → Closed |
+| StartedAt | DateTime? | Set when Draft -> Open |
+| ActivatedAt | DateTime? | Set when Open -> Active |
+| ClosedAt | DateTime? | Set when Active -> Closed |
 
 ---
 
-### New Enum — RideType
+### New Enum - RideType
 
 ```csharp
 public enum RideType { Delivery, Sale }
 ```
 
-### New Enum — RideStatus
+### New Enum - RideStatus
 
 ```csharp
 public enum RideStatus { Draft, Open, Active, CancelRequested, Cancelled, Closed }
 ```
 
+Meaning of statuses:
+
+- `Draft`: ride exists but operational work has not started.
+- `Open`: ride is prepared and ready for loading/preparation work.
+- `Active`: ride is live in the field.
+- `CancelRequested`: active ride is waiting for cancellation approval or rejection.
+- `Cancelled`: ride ended through approved cancellation.
+- `Closed`: ride ended normally.
+
 ---
 
-### New Entity — RideCancelRequest
+### New Entity - RideCancelRequest
 
 | Column | Type | Notes |
 |---|---|---|
 | Id | Guid | PK |
-| FK_RideId | Guid | FK → DeliveryRun |
+| FK_RideId | Guid | FK -> DeliveryRun |
 | TypeCode | CancelRequestType | Reason category |
 | Reason | string | Free text explanation |
 | RequestedBy | Guid | UserId |
@@ -89,7 +116,7 @@ public enum RideStatus { Draft, Open, Active, CancelRequested, Cancelled, Closed
 | ApprovedBy | Guid? | UserId of approver |
 | ApprovedAt | DateTime? | |
 
-### New Enum — CancelRequestType
+### New Enum - CancelRequestType
 
 ```csharp
 public enum CancelRequestType
@@ -101,7 +128,7 @@ public enum CancelRequestType
 }
 ```
 
-### New Entity — DriverComplianceConfig
+### New Entity - DriverComplianceConfig
 
 Single-row configuration table. Controls which compliance checks are enforced at ride open time.
 
@@ -117,7 +144,7 @@ Managed via a dedicated config endpoint. Only one row ever exists.
 
 ---
 
-### New Enum — CancelRequestStatus
+### New Enum - CancelRequestStatus
 
 ```csharp
 public enum CancelRequestStatus { Pending, Approved, Rejected }
@@ -127,21 +154,22 @@ public enum CancelRequestStatus { Pending, Approved, Rejected }
 
 ## State Machine
 
-```
-Draft → Open → Active → Closed
-                      ↘ CancelRequested → Cancelled
+```text
+Draft -> Open -> Active -> Closed
+                  \-> CancelRequested -> Cancelled
 ```
 
 | Transition | Trigger | What it does |
 |---|---|---|
-| Draft → Open | `POST /api/rides/{id}/open` | Validates driver compliance. Checks vehicle has no other Open/Active ride. Sets `StartedAt`. |
-| Open → Active | `POST /api/rides/{id}/activate` | Called by loading event confirmation (Step 04). Sets `ActivatedAt`. |
-| Active → Closed | `POST /api/rides/{id}/close` | Called after ride reconciliation (Step 07). All stock must be returned to source warehouse. Sets `ClosedAt`. |
-| Active → CancelRequested | `POST /api/rides/{id}/cancel-request` | Driver submits cancel request with type code and reason. Ride status changes to `CancelRequested`. |
-| CancelRequested → Cancelled | `POST /api/rides/cancel-requests/{id}/approve` | Supervisor approves. Ride status changes to `Cancelled`. All stock must return to source warehouse before cancel completes. |
-| CancelRequested → Active | `POST /api/rides/cancel-requests/{id}/reject` | Supervisor rejects. Ride returns to `Active`. |
+| Draft -> Open | `POST /api/rides/{id}/open` | Validates driver compliance. Checks vehicle has no other Open/Active ride. Sets `StartedAt`. |
+| Open -> Active | `POST /api/rides/{id}/activate` | Called by loading event confirmation (Step 04). Sets `ActivatedAt`. |
+| Active -> Closed | `POST /api/rides/{id}/close` | Called after ride reconciliation (Step 07). All stock must be returned to source warehouse. Sets `ClosedAt`. |
+| Active -> CancelRequested | `POST /api/rides/{id}/cancel-request` | Driver submits cancel request with type code and reason. Ride status changes to `CancelRequested`. |
+| CancelRequested -> Cancelled | `POST /api/rides/cancel-requests/{id}/approve` | Supervisor approves. Ride status changes to `Cancelled`. All stock must return to source warehouse before cancel completes. |
+| CancelRequested -> Active | `POST /api/rides/cancel-requests/{id}/reject` | Supervisor rejects. Ride returns to `Active`. |
 
-**Order assignment window:** Orders can be assigned to a Delivery ride from Draft until the ride transitions to Open. No new orders after Open.
+**Order assignment window:** Orders can be assigned to a Delivery ride from Draft until the ride
+transitions to Open. No new orders after Open.
 
 ---
 
@@ -150,7 +178,7 @@ Draft → Open → Active → Closed
 Per vehicle. A vehicle either has `FK_DefaultWarehouseId` set (always loads from that warehouse)
 or it is null (warehouse is selected manually at ride creation time).
 
-Loading and unloading warehouse are always the same — stock must return to its source warehouse
+Loading and unloading warehouse are always the same - stock must return to its source warehouse
 before a ride can close or cancel.
 
 ---
@@ -160,12 +188,12 @@ before a ride can close or cancel.
 1. Driver submits cancel request with `TypeCode = VehicleBreakdown`.
 2. Ride status moves to `CancelRequested`.
 3. Supervisor views a breakdown assist endpoint that lists all currently `Active` rides with their
-   current vehicle stock levels and the stranded ride's open orders — supervisor decides manually
+   current vehicle stock levels and the stranded ride's open orders. Supervisor decides manually
    which ride takes over which orders.
 4. Supervisor approves the cancel request.
 5. Ride moves to `Cancelled` once all stock is confirmed returned to source warehouse.
 
-The system surfaces the information — it does not automatically reassign orders.
+The system surfaces the information - it does not automatically reassign orders.
 
 ---
 
@@ -179,14 +207,14 @@ Base route: `/api/rides`
 | GET | `/` | List rides (paginated). Filter by status, type, driverProfileId, vehicleId. |
 | GET | `/{id}` | Get ride detail |
 | PUT | `/{id}/driver` | Assign or change driver profile |
-| POST | `/{id}/open` | Transition Draft → Open |
-| POST | `/{id}/activate` | Transition Open → Active (called by loading event) |
-| POST | `/{id}/close` | Transition Active → Closed (called by reconciliation) |
+| POST | `/{id}/open` | Transition Draft -> Open |
+| POST | `/{id}/activate` | Transition Open -> Active (called by loading event) |
+| POST | `/{id}/close` | Transition Active -> Closed (called by reconciliation) |
 | POST | `/{id}/cancel-request` | Submit cancel request (Active rides only) |
 | GET | `/cancel-requests` | List cancel requests (paginated). Filter by status. |
 | POST | `/cancel-requests/{id}/approve` | Approve cancel request |
 | POST | `/cancel-requests/{id}/reject` | Reject cancel request |
-| GET | `/breakdown-assist/{rideId}` | Lists active rides with stock + stranded ride's open orders |
+| GET | `/breakdown-assist/{rideId}` | Lists active rides with stock plus stranded ride's open orders |
 
 ### DriverComplianceConfig
 
@@ -215,37 +243,42 @@ Base route: `/api/driver-profiles`
 
 ## Business Rules
 
-1. A ride cannot transition Draft → Open if `IsActive = false` on the driver profile. If `EnforceLicenseExpiry = true`, also blocks if license is expired. If `EnforceMedicalClearance = true`, also blocks if medical clearance is expired.
+1. A ride cannot transition Draft -> Open if `IsActive = false` on the driver profile. If
+   `EnforceLicenseExpiry = true`, also block if license is expired. If
+   `EnforceMedicalClearance = true`, also block if medical clearance is expired.
 2. A vehicle cannot be on more than one Open or Active ride at a time.
 3. Orders can only be assigned to a Delivery ride while it is in Draft status.
-4. Loading and unloading warehouse must be the same — enforced at close/cancel.
+4. Loading and unloading warehouse must be the same - enforced at close/cancel.
 5. A CancelRequested ride cannot close or activate until the request is resolved.
-6. All cancel requests must have a TypeCode — free text reason alone is not sufficient.
+6. All cancel requests must have a TypeCode - free text reason alone is not sufficient.
 7. All list endpoints return paginated responses.
+8. A ride uses a single route for now.
 
 ---
 
 ## Open Questions
 
-1. **Cancel request type codes** — ✅ Resolved. `VehicleBreakdown`, `DriverUnavailable`, `RouteIssue`, `Other`.
-2. **Breakdown assist endpoint** — ✅ Resolved. System shows info only, supervisor decides manually. No auto-reassignment.
-3. **Driver compliance** — ✅ Resolved. Checks are configurable via `DriverComplianceConfig`. `IsActive` is always enforced. License and medical checks are optional flags, default off.
+1. Cancel request type codes - resolved. `VehicleBreakdown`, `DriverUnavailable`, `RouteIssue`,
+   `Other`.
+2. Breakdown assist endpoint - resolved. System shows info only, supervisor decides manually. No
+   auto-reassignment.
+3. Driver compliance - resolved. Checks are configurable via `DriverComplianceConfig`. `IsActive`
+   is always enforced. License and medical checks are optional flags, default off.
+4. Multi-route ride assignment - deferred for now. Current model stays single-route.
 
 ---
 
 ## Implementation Notes
 
 **Build order:**
-1. ✅ Enums — `RideType`, `RideStatus`, `CancelRequestType`, `CancelRequestStatus` → added to `Models/Enums.cs`
-2. ✅ Entities — `DriverProfile`, `DriverComplianceConfig`, `RideCancelRequest` (new); updated `Vehicle` (+`FK_DefaultWarehouseId`), updated `DeliveryRun` (+`RideType`, `Status`, `FK_DriverProfileId`, `FK_SourceWarehouseId`, `StartedAt`, `ActivatedAt`, `ClosedAt`)
-3. ✅ `AppDBContext` — new DbSets + Fluent config
-4. ✅ Migrations — `RideLifecycle` (schema), `RidePermissions` (10 new permissions seeded across all roles)
-5. ✅ DTOs — `DriverProfileDTOs.cs`, `DriverComplianceConfigDTOs.cs`, `RideDTOs.cs`
-6. ✅ Repositories — `IDriverProfileRepository`, `IDriverComplianceConfigRepository`, `IRideRepository`, `IRideCancelRequestRepository`
-7. ✅ Services — `DriverProfileService`, `DriverComplianceConfigService`, `RideService`
-8. ✅ Controllers — `DriverProfileController`, `DriverComplianceConfigController`, `RideController`
-9. ✅ DI registration in `Program.cs`
+1. Enums - `RideType`, `RideStatus`, `CancelRequestType`, `CancelRequestStatus`
+2. Entities - `DriverProfile`, `DriverComplianceConfig`, `RideCancelRequest`
+3. `AppDBContext` - new DbSets plus Fluent config
+4. Migrations - ride lifecycle schema and permissions
+5. DTOs - driver profile, compliance config, ride
+6. Repositories - ride and ride cancel request support
+7. Services - driver profile, compliance config, ride
+8. Controllers - driver profile, compliance config, ride
+9. DI registration in `Program.cs`
 
 **Feature folders:** `Features/Ride/`, `Features/DriverProfile/`, `Features/DriverComplianceConfig/`
-
-**Pending:** `dotnet ef database update` to apply migrations to DB. Tests for the three new services.

Distribution/docs/04_loading_event.md

@@ -1,83 +1,179 @@
-# 04 — Loading Event
+# 04 - Loading Event
 
-**Status**: Not Started
-**Depends On**: 03 — Ride Lifecycle
+**Status**: Planning
+**Depends On**: 03 - Ride Lifecycle
 
 ---
 
 ## Goal
 
 Move stock from a source warehouse onto an opened ride's vehicle, with two-party confirmation.
-Covers the dispatch half of [mainPlan.md §6](./mainPlan.md#6-warehouse-management):
-`generatePickList`, `confirmPicking`, `packOrder`, `buildDispatchLoad`, and `calculateLoadPlan`
-from §5.
+When loading is confirmed, the vehicle's stock ledger is credited and the ride transitions
+`Open -> Active` automatically.
+
+This loading flow serves both ride types:
+- `Delivery` rides load stock to fulfill orders already linked to the ride.
+- `Sale` rides load stock so the sales agent can sell in the field and create sale-linked orders.
 
 ---
 
 ## Background / Context
 
-This is the first place the [02_stock_ledger.md](./02_stock_ledger.md) movement model gets
-exercised end-to-end: a `Load` movement debits the warehouse and credits the vehicle location
-created when the ride opened ([03_ride_lifecycle.md](./03_ride_lifecycle.md)).
+A vehicle is just a location with `LocationType.Vehicle` in the stock ledger - the same math as a
+warehouse. When loading is confirmed, two stock movements are created per item:
+
+- Debit source warehouse: `-qty` at `LocationType.Warehouse`
+- Credit vehicle: `+qty` at `LocationType.Vehicle`
+
+From this point the vehicle carries live inventory that decreases with every sale or delivery and
+must return to zero before the ride can close.
 
 ---
 
 ## Data Model Changes
 
-### Loading Sheet
+### New Entity - LoadingSheet
 
-Header record: `RideId`, `SourceWarehouseId`, `Status` (`Pending`, `DispatchConfirmed`,
-`ReceiptConfirmed`, `DiscrepancyFlagged`, `Resolved`).
+| Column | Type | Notes |
+|---|---|---|
+| Id | Guid | PK |
+| FK_RideId | Guid | FK -> DeliveryRun |
+| FK_SourceWarehouseId | Guid | FK -> Warehouse |
+| Status | LoadingSheetStatus | State machine below |
+| DispatchConfirmedAt | DateTime? | Set when warehouse confirms dispatch |
+| DispatchConfirmedBy | Guid? | UserId of warehouse manager |
+| ReceiptConfirmedAt | DateTime? | Set when driver confirms receipt |
+| ReceiptConfirmedBy | Guid? | UserId of driver |
+| CreatedAt | DateTime | |
 
-### Loading Line Item
+### New Entity - LoadingSheetItem
 
-`LoadingSheetId`, `ItemId`, `QuantityDispatched` (set by warehouse manager), `QuantityReceived`
-(set by driver) — a mismatch between the two is a discrepancy.
+| Column | Type | Notes |
+|---|---|---|
+| Id | Guid | PK |
+| FK_LoadingSheetId | Guid | FK -> LoadingSheet |
+| FK_ItemId | Guid | FK -> Item |
+| QuantityDispatched | decimal | Set by warehouse manager at confirm-dispatch |
+| QuantityReceived | decimal? | Set by driver before confirm-receipt |
+| QuantityResolved | decimal? | Set by supervisor when resolving a discrepancy |
 
-### Two-Party Confirmation
+### New Enum - LoadingSheetStatus
 
-Warehouse manager confirms what was dispatched (`generatePickList` → `confirmPicking` →
-`packOrder`); driver separately confirms what was received onto the vehicle. Both confirmations are
-required before the ride can move `Open → Active`.
+```csharp
+public enum LoadingSheetStatus
+{
+    Pending,
+    DispatchConfirmed,
+    ReceiptConfirmed,
+    DiscrepancyFlagged,
+    Resolved
+}
+```
+
+No changes to existing entities. Vehicle capacity check is deferred to Step 13.
+
+---
+
+## State Machine
+
+```text
+Pending -> DispatchConfirmed -> ReceiptConfirmed
+                           \-> DiscrepancyFlagged -> Resolved
+```
+
+| Transition | Trigger | What it does |
+|---|---|---|
+| Pending -> DispatchConfirmed | `POST /{id}/confirm-dispatch` | Warehouse manager locks in `QuantityDispatched` per line. Ride stays `Open`. |
+| DispatchConfirmed -> ReceiptConfirmed | `POST /{id}/confirm-receipt` | Driver's received quantities all match dispatched. Creates stock movements. Auto-triggers ride `Open -> Active`. |
+| DispatchConfirmed -> DiscrepancyFlagged | `POST /{id}/confirm-receipt` | Any line mismatch. No stock movements created. Ride stays `Open`. |
+| DiscrepancyFlagged -> Resolved | `POST /{id}/resolve` | Supervisor enters `QuantityResolved` per line. Creates stock movements using resolved quantities. Auto-triggers ride `Open -> Active`. |
+
+---
+
+## Item Population by Ride Type
+
+| Ride Type | How items are added to the sheet |
+|---|---|
+| Delivery | Auto-populated on sheet creation from the aggregate of all order lines assigned to the ride's route |
+| Sale | Manually entered by warehouse manager via `PUT /{id}/items` based on expected field selling demand |
+
+For Delivery rides the warehouse manager reviews the pre-populated quantities and may adjust before
+confirming dispatch. `PUT /{id}/items` is still available to override if needed.
+
+---
+
+## Stock Movements
+
+Created at `ReceiptConfirmed` or `Resolved`. One pair per line item:
+
+- Debit warehouse: `-QuantityFinal` at `LocationType.Warehouse`, `FK_LocationId = SourceWarehouseId`
+- Credit vehicle: `+QuantityFinal` at `LocationType.Vehicle`, `FK_LocationId = VehicleId`
+
+`QuantityFinal` = `QuantityReceived` on a clean confirmation, or `QuantityResolved` when a
+discrepancy was resolved.
+
+Movement `Type` = `Load`.
 
 ---
 
 ## API Endpoints
 
-| Function reference | Endpoint intent |
-|---|---|
-| `generatePickList(orderIds[])` (§6) | `POST /api/loading-sheets` |
-| `confirmPicking(pickListId, pickedItems[])` (§6) | `POST /api/loading-sheets/{id}/confirm-dispatch` |
-| `packOrder(orderId, packageDetails)` (§6) | `POST /api/loading-sheets/{id}/pack` |
-| `buildDispatchLoad(vehicleId, orderIds[])` (§6) | Groups multiple orders into one loading sheet |
-| `calculateLoadPlan(vehicleId, orderIds[])` (§5) | Validates total volume/weight against vehicle capacity before dispatch confirmation |
-| — | `POST /api/loading-sheets/{id}/confirm-receipt` — driver-side confirmation |
+Base route: `/api/loading-sheets`
+
+| Method | Route | Who | Description |
+|---|---|---|---|
+| POST | `/` | Warehouse mgr | Create sheet for an Open ride. Delivery rides auto-populate items from orders. |
+| GET | `/` | Any | List sheets. Filter by `rideId`, `status`. Paginated. |
+| GET | `/{id}` | Any | Get sheet detail with all line items |
+| PUT | `/{id}/items` | Warehouse mgr | Set or override item quantities |
+| POST | `/{id}/confirm-dispatch` | Warehouse mgr | Pending -> DispatchConfirmed |
+| PUT | `/{id}/receipt-items` | Driver | Set `QuantityReceived` per line |
+| POST | `/{id}/confirm-receipt` | Driver | -> ReceiptConfirmed or DiscrepancyFlagged |
+| POST | `/{id}/resolve` | Supervisor | Enter `QuantityResolved` per line -> Resolved plus ride activation |
 
 ---
 
 ## Business Rules
 
-- `QuantityDispatched != QuantityReceived` on any line flags the sheet `DiscrepancyFlagged` and
-  blocks ride activation until resolved.
-- `calculateLoadPlan` must reject a load exceeding vehicle capacity before dispatch is confirmed,
-  not after.
+1. A loading sheet can only be created for a ride in `Open` status.
+2. A ride can only have one active loading sheet at a time.
+3. `QuantityDispatched != QuantityReceived` on any line -> `DiscrepancyFlagged`. No partial activation.
+4. Stock movements are created only once - at `ReceiptConfirmed` or `Resolved`. Never on dispatch.
+5. Discrepancies must be resolved per line item with an explicit `QuantityResolved` value.
+6. All list endpoints return paginated responses.
+7. Vehicle capacity check is not enforced in this step.
+8. Immediate handover from a Sale ride does not remove the need for an `Order`; every sale still
+   creates an order, and that order is fulfilled immediately when stock is handed over at sale time.
+
+---
+
+## Permissions to Seed
+
+| Code | Who |
+|---|---|
+| `loading.view` | All roles |
+| `loading.dispatch` | Warehouse manager and above |
+| `loading.receive` | Driver |
+| `loading.resolve` | Supervisor and above |
 
 ---
 
 ## Fraud / Control Considerations
 
-- Discrepancies must be immediately visible, not silently averaged into stock adjustments — see
-  [09_fraud_controls.md](./09_fraud_controls.md).
+- Discrepancies are immediately visible and block activation.
+- `QuantityResolved` is permanently stored per line for audit purposes.
 
 ---
 
 ## Open Questions
 
-- Does `Vehicle` need a `Capacity` field added now (volume/weight), or is `calculateLoadPlan`
-  deferred until that's available?
+1. Vehicle capacity check - deferred to Step 13.
+2. Discrepancy resolution - supervisor enters `QuantityResolved` per line item.
+3. Ride activation trigger - `confirm-receipt` and `resolve` auto-trigger `Open -> Active`.
+4. Delivery item population - from assigned orders on the ride's route.
 
 ---
 
 ## Implementation Notes
 
-> Fill this section in during planning discussion before writing any code.
+Build after the ride model and before full delivery/sale execution.

Distribution/docs/05_delivery_ride.md

@@ -1,79 +1,148 @@
 # 05 — Delivery Ride Execution
 
-**Status**: Not Started
+**Status**: Done
 **Depends On**: 04 — Loading Event
 
 ---
 
 ## Goal
 
-Execute pre-confirmed orders against a loaded, active delivery ride. Covers the order-status half
-of [mainPlan.md §1](./mainPlan.md#1-order-management):
-`updateOrderStatus`, `convertOrderToInvoice`, `createBackorder`. Requires `Order.Status` to exist
-first — see gap #7 in [00_existing_gaps.md](./00_existing_gaps.md).
+Fulfill pending orders against an active Delivery ride. The driver visits each store on the route,
+delivers the ordered items, gets customer confirmation, and the system creates the stock movement,
+updates the order, and completes the sale.
 
 ---
 
 ## Background / Context
 
-Today `Order` has no status and no link to a ride. This step is where the order lifecycle
-(`pending → approved → picked → dispatched → delivered → invoiced`) actually gets driven, once the
-order has been picked/loaded ([04_loading_event.md](./04_loading_event.md)).
+- A Delivery ride goes `Active` after the loading event is confirmed.
+- Orders are linked to a ride implicitly through route: `Ride → Route → Stores → Pending Orders`.
+- `QuantityFulfilled` on `OrderItem` tracks what was actually delivered (added in pre-planning).
+- No separate backorder entity — partially fulfilled orders stay `PartiallyFulfilled` and get picked
+  up by the next delivery ride on the same route.
+- Customer confirmation in v1 is a boolean flag (`CustomerConfirmed`). Full signature/OTP deferred
+  to Step 09 (Fraud Controls).
 
 ---
 
 ## Data Model Changes
 
-### Delivery Task (per order on ride)
+### New Entity — DeliveryTask
 
-`RideId`, `OrderId`, `Sequence` (visit order), `Status` (`Pending`, `Delivered`, `PartiallyDelivered`,
-`Failed`).
+Extends `Template` (adds `IsActive`, `CreatedAt` — consistent with all other entities).
 
-### Delivery Outcome
+| Column | Type | Notes |
+|---|---|---|
+| Id | Guid | PK (from Template) |
+| FK_RideId | Guid | FK → DeliveryRun |
+| FK_OrderId | Guid | FK → Order |
+| Sequence | int | Visit order on the route |
+| Status | DeliveryTaskStatus | State machine below |
+| CustomerConfirmed | bool | Set to true at confirm time |
+| ConfirmedAt | DateTime? | Timestamp of customer confirmation |
+| Note | string? | Driver note on failure or partial delivery |
+| IsActive | bool | From Template (soft delete) |
+| CreatedAt | DateTime | From Template |
 
-Per delivery task: quantities actually delivered per line, vs. ordered — feeds `createBackorder`
-for the shortfall.
+### New Enum — DeliveryTaskStatus
 
-### Customer Confirmation
+```csharp
+public enum DeliveryTaskStatus
+{
+    Pending,
+    Delivered,
+    PartiallyDelivered,
+    Failed
+}
+```
 
-Signature or OTP captured against the delivery task before it can be marked complete.
+### No new columns on OrderItem
+
+`QuantityFulfilled` already added in pre-planning. No further model changes needed.
+
+---
+
+## State Machine
+
+```
+Pending → Delivered          (all lines fully delivered + customer confirmed)
+Pending → PartiallyDelivered (some lines short + customer confirmed)
+Pending → Failed             (driver could not deliver, no stock movement)
+```
+
+---
+
+## Stock Movements
+
+Created on `Delivered` or `PartiallyDelivered` after customer confirmation. One movement per item:
+
+- **Debit** vehicle: `-QuantityFulfilled` at `LocationType.Vehicle`, `FK_LocationId = VehicleId`
+- `VehicleId` is resolved from `DeliveryTask.FK_RideId → DeliveryRun.FK_VehicleId`
+- `MovementType.Sale`
+- `ReferenceId = OrderId`
+
+No movement on `Failed`.
+
+---
+
+## Order and Sale Status Transitions (triggered internally)
+
+| Condition | Order | Sale |
+|---|---|---|
+| All OrderItem lines: QuantityFulfilled == Quantity | → Fulfilled | → Completed |
+| Any OrderItem line: QuantityFulfilled < Quantity | → PartiallyFulfilled | stays Pending |
+| Task Failed | stays Pending | stays Pending |
 
 ---
 
 ## API Endpoints
 
-| Function reference | Endpoint intent |
-|---|---|
-| `updateOrderStatus(orderId, status)` (§1) | `PUT /api/rides/{rideId}/tasks/{orderId}/status` |
-| `convertOrderToInvoice(orderId)` (§1) | Triggered automatically on `Delivered`/`PartiallyDelivered` — see [19_finance_accounting.md](./19_finance_accounting.md) |
-| `createBackorder(orderId, unfulfilledItems[])` (§1) | Triggered automatically on `PartiallyDelivered` |
-| — | `POST /api/rides/{rideId}/tasks/{orderId}/confirm` — captures customer signature/OTP |
+Base routes: `/api/rides/{rideId}/tasks` and `/api/delivery-tasks`
+
+| Method | Route | Who | Description |
+|---|---|---|---|
+| POST | `/api/rides/{rideId}/tasks/generate` | Driver/System | Auto-create tasks from all Pending/PartiallyFulfilled orders for stores on ride's route |
+| GET | `/api/rides/{rideId}/tasks` | Driver | List all tasks for this ride with current status |
+| GET | `/api/delivery-tasks/{id}` | Driver | Task detail with order items and quantities |
+| PUT | `/api/delivery-tasks/{id}/quantities` | Driver | Set QuantityFulfilled per order item before confirming |
+| POST | `/api/delivery-tasks/{id}/confirm` | Driver | Customer confirmed — creates stock movements, transitions order/sale |
+| POST | `/api/delivery-tasks/{id}/fail` | Driver | Mark task as failed with a note |
 
 ---
 
 ## Business Rules
 
-- A delivery task cannot be marked `Delivered` without a customer confirmation.
-- `PartiallyDelivered` always creates a `createBackorder` entry and a credit note for the
-  undelivered quantity (see [18_returns_claims.md](./18_returns_claims.md) for credit note shape).
-- Each confirmed delivery task creates a stock movement (`Sale`/consumption) against the vehicle
-  location per [02_stock_ledger.md](./02_stock_ledger.md).
+1. Delivery tasks can only be created for a ride in `Active` status and of type `Delivery`.
+2. One task per order per ride — cannot create a second task for the same order on the same ride.
+3. `QuantityFulfilled` must be set on all order items before calling confirm.
+4. `QuantityFulfilled` cannot exceed `Quantity` on any line.
+5. `CustomerConfirmed` must be true before the task can move to `Delivered` or `PartiallyDelivered`.
+6. Stock movement is created only once — at confirm. Never on fail.
+7. A failed task does not change the order or sale status — the order stays available for the next ride.
+8. Partial delivery: the unfulfilled quantity (`Quantity - QuantityFulfilled`) remains on the same
+   order. The next delivery ride on the same route will pick it up automatically via `generate`.
 
 ---
 
-## Fraud / Control Considerations
+## Implementation Build Order
 
-- OTP/signature capture must be tamper-evident (timestamped, tied to the delivery task, not
-  editable after submission).
+1. Enum — add `DeliveryTaskStatus` to `Models/Enums.cs`
+2. Entity — `DeliveryTask` in `Models/`
+3. `AppDBContext` — new DbSet + Fluent config (Restrict on Ride, Order FKs)
+4. Migration
+5. DTOs — `DeliveryTaskDTOs.cs` in `Features/DeliveryRide/`
+6. Repository — `IDeliveryTaskRepository`, `DeliveryTaskRepository`
+7. Service — `DeliveryTaskService`
+8. Controller — `DeliveryTaskController`
+9. DI registration in `Program.cs`
+
+**Feature folder:** `Features/DeliveryRide/`
 
 ---
 
-## Open Questions
+## Open Questions — Resolved
 
-- Signature capture (image) or OTP (SMS code) — one, or both, in v1?
-
----
-
-## Implementation Notes
-
-> Fill this section in during planning discussion before writing any code.
+- ✅ Customer confirmation — boolean flag in v1, full signature/OTP in Step 09
+- ✅ Backorder — no separate entity; same order stays PartiallyFulfilled for next ride
+- ✅ Task generation — on-demand via `generate` endpoint, not automatic on ride activation
+- ✅ Failed task — order stays Pending, available for next ride, no stock movement

Distribution/docs/06_sale_ride.md

@@ -1,80 +1,132 @@
 # 06 — Sale Ride Execution
 
-**Status**: Not Started
+**Status**: Done
 **Depends On**: 04 — Loading Event
 
 ---
 
 ## Goal
 
-Support on-the-spot van sales with no pre-order: driver picks items/quantities, an invoice is
-generated immediately, and payment is captured at point of sale. Covers `createInvoice`,
-`recordPayment` from [mainPlan.md §13](./mainPlan.md#13-finance--accounting),
-and reuses `applyPricingAndDiscounts` (§1) plus `evaluateSchemeEligibility`/`applySchemeDiscount`
-(§11) if promotions are live by the time this ships.
+Allow a sales agent on an active Sale ride to create sales in the field. Every sale creates an
+order. Immediate handover deducts vehicle stock and closes the order immediately. Non-immediate
+handover leaves the order pending for a future delivery ride.
 
 ---
 
 ## Background / Context
 
-Distinct from [05_delivery_ride.md](./05_delivery_ride.md): there is no pre-existing `Order` row —
-the field invoice *is* the order, created and settled in one step.
+- `SaleService.CreateAsync` already exists and handles both `FulfillImmediately` paths.
+- What Step 06 adds: vehicle stock validation and deduction on immediate handover, and the
+  Payment recording endpoint.
+- `Sale.PaymentStatus` and the `Payment` model were added in pre-planning.
+- Pricing is already resolved via `PriceListService` inside `SaleService`.
 
 ---
 
 ## Data Model Changes
 
-### Field Invoice
+No new entities. Everything needed was added in pre-planning:
 
-`RideId`, `StoreId`, `CreatedByUserId`, `TotalAmount`, `PaymentStatus` (`Paid`, `PartiallyPaid`,
-`OnCredit`).
+| What | Where | Status |
+|---|---|---|
+| `Payment` entity | `Models/Payment.cs` | ✅ Done |
+| `PaymentStatus` enum | `Models/Enums.cs` | ✅ Done |
+| `PaymentMethod` enum | `Models/Enums.cs` | ✅ Done |
+| `Sale.PaymentStatus` | `Models/Sale.cs` | ✅ Done |
+| `OrderItem.QuantityFulfilled` | `Models/OrderItem.cs` | ✅ Done |
 
-### Field Invoice Line Item
-
-`FieldInvoiceId`, `ItemId`, `Quantity`, `UnitPrice` (subject to the discount-limit rules in
-[08_sales_agent_controls.md](./08_sales_agent_controls.md)).
-
-### Payment Record
-
-`FieldInvoiceId`, `Amount`, `Method` (`Cash`, `Credit`), `CollectedAt`.
+Migration needed for: `Payment` table, `Sale.PaymentStatus` column, `OrderItem.QuantityFulfilled` column.
 
 ---
 
-## API Endpoints
+## Changes to Existing SaleService
 
-| Function reference | Endpoint intent |
-|---|---|
-| `createInvoice(orderId)` (§13) | `POST /api/rides/{rideId}/field-invoices` — orderId is the field invoice itself here |
-| `recordPayment(invoiceId, amount, method)` (§13) | `POST /api/field-invoices/{id}/payments` |
-| `applyPricingAndDiscounts(orderId)` (§1) | Applied at line-item entry time, within agent discount limits |
+`SaleService.CreateAsync` needs two additions when `FulfillImmediately = true` and `RideId` is set:
+
+1. **Stock check** — for each item, verify vehicle has enough stock (`StockBalance` at
+   `LocationType.Vehicle` with `LocationId = VehicleId`). Reject the whole sale if any item is short.
+2. **Stock deduction** — debit vehicle balance per item, create one `StockMovement` per item:
+   - `MovementType.Sale`
+   - `FromLocationId = VehicleId`, `FromLocationType = Vehicle`
+   - `ReferenceId = OrderId`
+
+`VehicleId` is resolved from `Sale.FK_RideId → DeliveryRun.FK_VehicleId`.
+
+**SaleService constructor additions required:**
+- `IStockRepository` — for stock balance check and debit
+- `IRideRepository` — to look up the ride and resolve `FK_VehicleId`
+
+When `FulfillImmediately = false`, no stock movement — order stays Pending for a delivery ride.
+
+---
+
+## New Feature — Payment
+
+**Feature folder:** `Features/Payment/`
+
+### API Endpoints
+
+| Method | Route | Who | Description |
+|---|---|---|---|
+| POST | `/api/sales/{id}/payments` | Driver/Agent | Record a payment against a sale |
+| GET | `/api/sales/{id}/payments` | Any | List all payments for a sale |
+
+### Payment Creation Logic
+
+On `POST /api/sales/{id}/payments`:
+1. Validate sale exists and is not `Cancelled`.
+2. Add `Payment` record (`FK_SaleId`, `FK_StoreId` from sale, `Amount`, `Method`, `CollectedAt`, `CollectedBy`).
+3. Sum all payments for this sale. Recalculate `Sale.PaymentStatus`:
+   - `sum == 0` → `Pending`
+   - `sum < Sale.TotalAmount` → `PartiallyPaid`
+   - `sum >= Sale.TotalAmount` → `Paid`
+4. Update `Sale.PaymentStatus` in the same transaction.
+
+### DTOs
+
+```csharp
+public record CreatePaymentRequest(decimal Amount, PaymentMethod Method);
+public record PaymentResponse(Guid Id, Guid SaleId, Guid StoreId, decimal Amount,
+    PaymentMethod Method, DateTime CollectedAt, Guid CollectedBy);
+```
 
 ---
 
 ## Business Rules
 
-- Driver cannot sell more than what is loaded on the vehicle — every line item is checked against
-  the vehicle's current stock balance ([02_stock_ledger.md](./02_stock_ledger.md)) before the
-  invoice is finalized.
-- Each confirmed sale line creates a `Sale` stock movement against the vehicle location,
-  immediately (not batched at ride close).
-- Discount applied per line must not exceed the agent's role-level limit (§8).
+1. Driver cannot sell more than vehicle stock for immediate handover — entire sale rejected if any
+   item is short (no partial sale creation).
+2. Every sale creates an order, even when all items are handed over immediately.
+3. `FulfillImmediately = true`:
+   - Vehicle stock debited immediately per item.
+   - Order → `Fulfilled`, Sale → `Completed` at creation time (already in SaleService).
+   - `QuantityFulfilled = Quantity` on all order items (already in SaleService).
+4. `FulfillImmediately = false`:
+   - No stock movement at sale time.
+   - Order → `Pending`, Sale → `Pending` at creation time.
+5. Payment can be recorded at any time — sale does not need to be `Completed` first.
+6. Overpayment is allowed (`sum > TotalAmount`) — `PaymentStatus` stays `Paid`.
+7. A `Cancelled` sale cannot receive new payments.
 
 ---
 
-## Fraud / Control Considerations
+## Implementation Build Order
 
-- Cash collected must reconcile against invoiced totals at ride close — see
-  [07_ride_reconciliation.md](./07_ride_reconciliation.md).
+1. Migration — `Payment` table, `Sale.PaymentStatus`, `OrderItem.QuantityFulfilled`
+2. Extend `SaleService.CreateAsync` — stock check + stock movement on `FulfillImmediately`
+3. DTOs — `PaymentDTOs.cs` in `Features/Payment/`
+4. Repository — `IPaymentRepository`, `PaymentRepository`
+5. Service — `PaymentService`
+6. Controller — `PaymentController`
+7. DI registration in `Program.cs`
+
+**Feature folder:** `Features/Payment/` (new), `Features/Sale/` (extended)
 
 ---
 
-## Open Questions
+## Open Questions — Resolved
 
-- Are field invoices numbered/sequenced separately from warehouse-issued invoices, or share one
-  sequence?
-
----
-
-## Implementation Notes
-
-> Fill this section in during planning discussion before writing any code.
+- ✅ Payment timing — can be recorded at any time, not locked to sale completion
+- ✅ Overpayment — allowed, status stays Paid
+- ✅ Stock check scope — entire sale rejected if any item is short, no partial creation
+- ✅ Non-immediate handover — no stock movement at sale time, order picked up by delivery ride

Distribution/docs/12_store_management.md

@@ -21,12 +21,18 @@ gap #8 in [00_existing_gaps.md](./00_existing_gaps.md). Credit fields exist info
 `OneTimeAmount` / `CreditAmount`, which stay as-is; this step adds the real credit-limit +
 outstanding-balance + KYC-gated-ordering flow on top.
 
-`getStoreVisitHistory` and `checkStoreSchemeEligibility` are read-only integration points into
-modules that don't exist yet ([11_route_sales_management.md](./11_route_sales_management.md) for
-visits, [17_promotions_schemes.md](./17_promotions_schemes.md) for schemes). Implement them now
-with the query shape defined below; wire the actual join once those modules land — return an empty
-list / `eligible: true` (no active schemes to check) until then, guarded by a `NotImplementedYet`
-style short-circuit, not a broken query.
+`getStoreVisitHistory` and `checkStoreSchemeEligibility` were originally read-only integration
+points into modules that didn't exist yet ([11_route_sales_management.md](./11_route_sales_management.md)
+for visits, [17_promotions_schemes.md](./17_promotions_schemes.md) for schemes) — both shipped as
+placeholders (empty list / `eligible: true`) guarded by a `NotImplementedYet`-style short-circuit.
+
+**Update (2026-08-21, after 17_promotions_schemes.md landed):** `checkStoreSchemeEligibility` is now
+wired for real. `StoreService.CheckSchemeEligibilityAsync` calls
+`SchemeService.CheckStoreScopeEligibilityAsync(storeId, schemeId)`, which checks the scheme's
+region/segment/date-range scope against the store (no order context, since this endpoint takes no
+`orderId` — that's a *scope* eligibility check, not the full order-line rule evaluation that
+`GET /api/schemes/eligible?storeId=...&orderId=...` does). `getStoreVisitHistory` is still an empty
+list — [11_route_sales_management.md](./11_route_sales_management.md) remains Not Started.
 
 ---
 
@@ -102,7 +108,7 @@ One migration needed:
 | GET | /api/stores/{id}/outstanding-balance | stores.view | Returns cached value + CreditLimit + available credit |
 | PUT | /api/stores/{id}/segment | stores.update | Body: `{ "segment": "Gold" }` |
 | GET | /api/stores/{id}/visit-history | stores.view | Paginated. Empty list until Step 11 wiring lands |
-| GET | /api/stores/{id}/schemes/{schemeId}/eligibility | stores.view | Returns `{ eligible: true, reason: null }` until Step 17 wiring lands |
+| GET | /api/stores/{id}/schemes/{schemeId}/eligibility | stores.view | Wired to Step 17 — returns real region/segment/date-range eligibility for the store against that scheme |
 | GET | /api/stores/{id}/dashboard?period=... | stores.view | Aggregates order count/value for the period from existing Order tables |
 
 ---
@@ -206,7 +212,9 @@ Features/
     StoreController.cs        (extended — credit-limit, balance, kyc/verify, segment,
                                 visit-history, scheme-eligibility, dashboard endpoints)
     StoreDTOs.cs               (extended — new request/response records)
-    StoreService.cs            (extended — new methods, RoleLevel >= 20 credit-approver check)
+    StoreService.cs            (extended — new methods, RoleLevel >= 20 credit-approver check;
+                                CheckSchemeEligibilityAsync now depends on Features/Scheme's
+                                SchemeService for the real region/segment/date-range check)
     IStoreRepository.cs        (extended — GetOrdersForDashboardAsync)
     StoreRepository.cs         (extended)
     Kyc/

Distribution/docs/15_procurement.md

@@ -1,74 +1,413 @@
 # 15 — Procurement / Purchasing
 
-**Status**: Not Started
-**Depends On**: 01 — Item Catalog, 14 — Pricing & Supplier Master Data
+**Status**: Done — migration applied to the database
+**Depends On**: 01 — Item Catalog (Done), 14 — Pricing & Supplier Master Data (Done)
 
 ---
 
 ## Goal
 
-Covers [mainPlan.md §9](./mainPlan.md#9-procurement--purchasing) in full
-— an entirely new subsystem, nothing in this area exists in the current schema.
+Covers [mainPlan.md §9](./mainPlan.md#9-procurement--purchasing) — inbound stock from suppliers,
+the mirror of Order Management's outbound flow to stores. Purchase Requisition is deliberately
+**not** part of this scope (see Background/Context) — `createPurchaseOrder` is the entry point.
 
 ---
 
 ## Background / Context
 
 Inbound stock (`createGoodsReceipt` in [04_loading_event.md](./04_loading_event.md)/
-[mainPlan.md §6](./mainPlan.md#6-warehouse-management)) currently has no
-purchase order to receive against — this step is what creates that PO in the first place.
+[mainPlan.md §6](./mainPlan.md#6-warehouse-management)) had no purchase order to receive against —
+this step creates that PO in the first place.
+
+Sales reps take orders **from** shops (existing `Features/Order`, outbound — decreases stock,
+references `Store`, prices via `PriceListItem.Price`); procurement is the mirror — bringing stock
+**in** from suppliers (`Features/PurchaseOrder`, inbound — increases stock, references `Supplier`,
+costs via `PurchaseOrderItem.UnitCost`). Same header+line-item shape, opposite direction and
+counterparty, which is why they're separate features rather than one generic "Order" entity.
+
+### No requisition step — how "raise a request to purchase" is actually handled
+
+[mainPlan.md §9](./mainPlan.md#9-procurement--purchasing) originally listed
+`createPurchaseRequisition(items[], requestedBy)` as a candidate function. **Dropped from this
+app's design** — the request and the decision to buy collapse into one step:
+
+- Whoever notices stock is low (owner, manager, or eventually an automated low-stock notice) calls
+  `createPurchaseOrder(supplierId, items[])` directly. Issuing the PO **is** the request; it needs
+  no separate approval because only an already-authenticated user can call it (see Permissions —
+  enforcement itself is deferred, matching Supplier/PriceList).
+- There is no Draft → Submitted → Approved chain because restocking authority isn't delegated down
+  to sales reps the way order-taking is.
+- A lower-level "we're low on X" signal is `sendLowStockAlert` (§15 Notifications & Alerts, not yet
+  built) — a notification, not a requisition with its own approval workflow.
+
+### Connections to existing modules
+
+- **Item Catalog** ([01_item_catalog.md](./01_item_catalog.md)): `PurchaseOrderItem.FK_ItemId`,
+  `GoodsReceiptItem` (via `PurchaseOrderItemId` → `PurchaseOrderItem.FK_ItemId`), and
+  `PurchaseReturnItem.FK_ItemId` all reference the same `Item` table sales orders use — one
+  catalog, two directions of stock movement.
+- **Stock Ledger** ([02_stock_ledger.md](./02_stock_ledger.md)): procurement writes to the same
+  `StockBalance`/`StockMovement` tables as the rest of the system rather than a separate stock
+  field — `createGoodsReceipt` credits `StockBalance` (`MovementType.PurchaseReceipt`),
+  `createPurchaseReturn` debits it (`MovementType.PurchaseReturn`). No new stock model was needed.
+- **Pricing** ([14_pricing_and_suppliers.md](./14_pricing_and_suppliers.md)): `PriceListItem.Price`
+  (what you charge a shop) and `PurchaseOrderItem.UnitCost` (what you pay a supplier) are
+  deliberately separate, unlinked fields — procurement never reads or writes `PriceList` rows.
+  Cost-vs-sale margin reporting is left for a later reporting step (see Open Questions).
+- **Supplier Master Data** ([14_pricing_and_suppliers.md](./14_pricing_and_suppliers.md)):
+  `PurchaseOrder.FK_SupplierId` links every PO to one supplier. `SupplierService.EvaluateAsync`
+  (`evaluateSupplier`) is now the only writer of `Supplier.PerformanceScore`, and
+  `SupplierService.DeleteAsync` now blocks soft-delete if any active `PurchaseOrder` references the
+  supplier — both were previously open items in 14's doc, now closed by this step.
+- **Order Management** ([mainPlan.md §1](./mainPlan.md#1-order-management)): while implementing
+  this step, `OrderService.CreateAsync` was found to have no `checkStockAvailability` check at all
+  (mainPlan's own documented gap) — fixed alongside this step: it now rejects an order if requested
+  quantity exceeds total on-hand `StockBalance` for the item, summed across all locations. It still
+  does not decrement stock at order time — that stays deferred to loading/delivery (§04-06), per the
+  existing architecture, to avoid double-decrementing once those steps are built.
 
 ---
 
 ## Data Model Changes
 
-### Purchase Requisition
+Six new tables — three header/line-item pairs (mirrors the `PriceList`/`PriceListItem` split).
 
-`RequestedByUserId`, `Status` (`Draft`, `Submitted`, `Approved`, `Rejected`), line items
-(`ItemId`, `Quantity`).
+### PurchaseOrder
+```
+PurchaseOrder
+├── Id (Guid)                  — PK, from Template
+├── FK_SupplierId (Guid)       — required
+├── FK_CreatedByUserId (Guid)  — required, the user who issued the PO
+├── Status (enum)              — Issued, PartiallyReceived, Received, Closed, Cancelled
+├── CancelReason (string?)     — set by cancelPurchaseOrder
+├── IsActive, CreatedAt        — from Template
+```
 
-### Purchase Order
+### PurchaseOrderItem
+```
+PurchaseOrderItem
+├── Id (Guid)                  — PK, from Template
+├── FK_PurchaseOrderId (Guid)  — required
+├── FK_ItemId (Guid)           — required
+├── Quantity (int)             — ordered quantity
+├── UnitCost (decimal)         — agreed cost per unit at the time the PO was issued
+├── ReceivedQuantity (int)     — running total, incremented by createGoodsReceipt; drives PO Status
+├── CancelledQuantity (int)    — set by cancelPurchaseOrderLine, default 0; outstanding qty for
+│                                 receiving = Quantity - ReceivedQuantity - CancelledQuantity
+├── IsCancelled (bool)         — true once this line is individually cancelled, default false
+```
 
-`SupplierId`, `RequisitionId` (nullable — a PO can be raised without a prior requisition), `Status`
-(`Issued`, `PartiallyReceived`, `Received`, `Closed`), line items (`ItemId`, `Quantity`, `UnitCost`).
+### GoodsReceipt
+```
+GoodsReceipt
+├── Id (Guid)                  — PK, from Template
+├── FK_PurchaseOrderId (Guid)  — required
+├── FK_ReceivedByUserId (Guid) — required
+├── FK_WarehouseId (Guid)      — required; the warehouse the accepted quantities are received into.
+│                                 Not anticipated in the original design — added because
+│                                 StockBalance/StockMovement are keyed by (LocationId, LocationType),
+│                                 so a receiving location is mandatory to credit stock at all.
+├── ReceivedAt (DateTime)
+├── IsActive, CreatedAt        — from Template
+```
 
-### Purchase Return
+### GoodsReceiptItem
+```
+GoodsReceiptItem
+├── Id (Guid)                       — PK, from Template
+├── FK_GoodsReceiptId (Guid)        — required
+├── FK_PurchaseOrderItemId (Guid)   — required, ties the receipt line back to its ordered line
+├── AcceptedQuantity (int)          — added to warehouse stock
+├── RejectedQuantity (int)          — damaged/short at receipt, default 0, not added to stock
+```
 
-`PurchaseOrderId`, reason, line items — goods sent back to the supplier post-receipt.
+### PurchaseReturn
+```
+PurchaseReturn
+├── Id (Guid)                  — PK, from Template
+├── FK_PurchaseOrderId (Guid)  — required
+├── Reason (string)
+├── IsActive, CreatedAt        — from Template
+```
+
+### PurchaseReturnItem
+```
+PurchaseReturnItem
+├── Id (Guid)                    — PK, from Template
+├── FK_PurchaseReturnId (Guid)   — required
+├── FK_ItemId (Guid)             — required
+├── Quantity (int)               — returned quantity, decremented from warehouse stock
+```
+Stock is decremented at the warehouse of the PO's most recent `GoodsReceipt` (the current model
+gives one receiving warehouse per PO in practice; see Open Questions for the multi-warehouse case).
+
+---
+
+## Migrations
+
+One migration, applied:
+1. **AddProcurement** (`20260824110925_AddProcurement`) — created `PurchaseOrders`,
+   `PurchaseOrderItems`, `GoodsReceipts`, `GoodsReceiptItems`, `PurchaseReturns`,
+   `PurchaseReturnItems`, with FKs to `Suppliers`/`Items`/`Warehouses` and indexes on every FK
+   column. Applied via `dotnet ef database update`.
 
 ---
 
 ## API Endpoints
 
-| Function reference | Endpoint intent |
+> No permission policy is enforced on any route below — matches the Supplier/PriceList convention
+> from step 14 (bare `[Authorize]`, authentication required, no per-action policy). See
+> Permissions to Add to Seed.
+
+### Purchase Orders (`Features/PurchaseOrder`)
+| Function reference | Endpoint |
 |---|---|
-| `createPurchaseRequisition(items[], requestedBy)` | `POST /api/purchase-requisitions` |
 | `createPurchaseOrder(supplierId, items[])` | `POST /api/purchase-orders` |
-| `matchInvoiceToPO(invoiceId, poId, grnId)` | `POST /api/purchase-orders/{id}/match-invoice` |
-| `evaluateSupplier(supplierId, criteria)` | `POST /api/suppliers/{id}/evaluate` |
+| `getPurchaseOrder(poId)` | `GET /api/purchase-orders/{id}` |
+| `listPurchaseOrders(filters)` | `GET /api/purchase-orders` |
+| `updatePurchaseOrder(poId, items[])` | `PUT /api/purchase-orders/{id}` |
+| `closePurchaseOrder(poId)` | `POST /api/purchase-orders/{id}/close` |
+| `cancelPurchaseOrder(poId, reason)` | `POST /api/purchase-orders/{id}/cancel` |
+| `cancelPurchaseOrderLine(poId, poItemId, reason)` | `POST /api/purchase-orders/{id}/items/{itemId}/cancel` |
+| `matchInvoiceToPO(poId, invoiceId?, grnId?)` | `POST /api/purchase-orders/{id}/match-invoice` |
+| `resolveInvoiceVariance(poId, variance, resolution)` | `POST /api/purchase-orders/{id}/resolve-variance` |
+
+### Goods Receipt (`Features/Grn`)
+| Function reference | Endpoint |
+|---|---|
+| `createGoodsReceipt(poId, warehouseId, items[])` | `POST /api/purchase-orders/{id}/goods-receipts` |
+| `getGoodsReceipt(grnId)` | `GET /api/goods-receipts/{id}` |
+| `listGoodsReceipts(poId)` | `GET /api/purchase-orders/{id}/goods-receipts` |
+
+### Purchase Returns (`Features/PurchaseReturn`)
+| Function reference | Endpoint |
+|---|---|
 | `createPurchaseReturn(poId, items[], reason)` | `POST /api/purchase-orders/{id}/returns` |
+| `getPurchaseReturn(returnId)` | `GET /api/purchase-returns/{id}` |
+| `listPurchaseReturns(poId)` | `GET /api/purchase-orders/{id}/returns` |
+
+### Supplier Evaluation (`Features/Supplier`, extended)
+| Function reference | Endpoint |
+|---|---|
+| `evaluateSupplier(supplierId)` | `POST /api/suppliers/{id}/evaluate` |
+
+---
+
+## Request / Response Shapes
+
+### POST `/api/purchase-orders`
+```json
+{ "supplierId": "...", "items": [{ "itemId": "...", "quantity": 100, "unitCost": 45.50 }] }
+```
+
+### POST `/api/purchase-orders/{id}/goods-receipts`
+```json
+{ "warehouseId": "...", "items": [
+    { "purchaseOrderItemId": "...", "acceptedQuantity": 95, "rejectedQuantity": 5 }
+] }
+```
+`rejectedQuantity` defaults to 0 if omitted; only `acceptedQuantity` is credited to
+`StockBalance`.
+
+### POST `/api/purchase-orders/{id}/returns`
+```json
+{ "reason": "Damaged in transit", "items": [{ "itemId": "...", "quantity": 10 }] }
+```
+
+### POST `/api/purchase-orders/{id}/resolve-variance`
+```json
+{ "variance": "Quantity mismatch: PO 100, GRN 95", "resolution": "Accepted — short shipment",
+  "adjustedUnitCost": null, "purchaseOrderItemId": "..." }
+```
 
 ---
 
 ## Business Rules
 
-- `createGoodsReceipt` (§6, [04_loading_event.md](./04_loading_event.md)'s warehouse-inbound
-  counterpart) must reference an `Issued`/`PartiallyReceived` Purchase Order — no receipts against
-  a closed or nonexistent PO.
-- `matchInvoiceToPO` (3-way match) must block payment posting in
-  [19_finance_accounting.md](./19_finance_accounting.md) until PO, GRN, and invoice quantities/
-  amounts reconcile within a configurable tolerance.
+1. `createPurchaseOrder` is the entry point to procurement — no prior approval step. A PO starts
+   in `Issued`.
+2. `createGoodsReceipt` must reference an `Issued`/`PartiallyReceived` PurchaseOrder — no receipts
+   against a `Closed`/`Cancelled`/nonexistent PO. Each receipt increments
+   `PurchaseOrderItem.ReceivedQuantity` by `AcceptedQuantity`, credits `StockBalance` at the
+   supplied `warehouseId` (+ a `StockMovement` row, `Type = PurchaseReceipt`), and transitions the
+   PO to `PartiallyReceived` or `Received` (every non-cancelled line's `ReceivedQuantity ==
+   Quantity`).
+3. `closePurchaseOrder` is only valid once a PO is `Received` (or manually closed early with
+   outstanding quantity written off); `cancelPurchaseOrder` is only valid before any goods receipt
+   exists against the PO.
+4. `cancelPurchaseOrderLine` cancels a single `PurchaseOrderItem` (`IsCancelled = true`,
+   `CancelledQuantity = Quantity - ReceivedQuantity`) instead of the whole PO. Only valid while
+   `ReceivedQuantity < Quantity` and the line isn't already fully received or cancelled. The PO
+   auto-completes to `Received` once every non-cancelled line is fully received.
+5. `updatePurchaseOrder` may only change unreceived lines (`ReceivedQuantity == 0`) and only while
+   the PO is `Issued` — a line that has already received stock, or a PO past `Issued`, cannot be
+   edited (use `cancelPurchaseOrderLine`/`createPurchaseReturn` instead).
+6. `createPurchaseReturn` requires at least one prior `createGoodsReceipt` against the PO; return
+   quantity per item cannot exceed `receivedTotal - alreadyReturned` for that item. Debits
+   `StockBalance` at the PO's (most recent) receiving warehouse (+ `StockMovement`,
+   `Type = PurchaseReturn`).
+7. `matchInvoiceToPO` performs PO-vs-GRN quantity/cost reconciliation only — no `Invoice` entity
+   exists yet (step 19 Finance, not built), so `invoiceId` is accepted but not compared against
+   anything. Full 3-way match activates once Finance's `Invoice` model exists. Until then it
+   compares `PurchaseOrderItem.Quantity`/`UnitCost` against `GoodsReceiptItem.AcceptedQuantity` per
+   line and returns a match/variance result — it never blocks or adjusts anything itself.
+8. `resolveInvoiceVariance` is the explicit function that records a variance and its resolution
+   (accept it, request a corrected invoice, or adjust `PurchaseOrderItem.UnitCost` retroactively) —
+   `matchInvoiceToPO` only detects, this function is what acts on a mismatch.
+9. `evaluateSupplier` is the only function permitted to write `Supplier.PerformanceScore`
+   ([14_pricing_and_suppliers.md](./14_pricing_and_suppliers.md) rule 4) — implemented in
+   `SupplierService.EvaluateAsync`, scored from that supplier's PO/GRN history (accepted vs
+   rejected quantity ratio, cancelled vs fulfilled line ratio).
+10. `SupplierService.DeleteAsync` blocks (soft-)deleting a `Supplier` if any active `PurchaseOrder`
+    references it — implemented, closing the previously-open item from
+    [14_pricing_and_suppliers.md](./14_pricing_and_suppliers.md).
+11. `OrderService.CreateAsync` (`checkStockAvailability`, mainPlan §1) now rejects an order if any
+    line's requested quantity exceeds total `StockBalance` for that item summed across every
+    location — added alongside this step since it was a documented gap. Does not reserve or
+    decrement stock; actual decrement stays deferred to loading/delivery (§04-06).
+
+---
+
+## Permissions to Add to Seed
+
+**Status: Not implemented, matching Supplier/PriceList (step 14).** All procurement controllers use
+bare `[Authorize]` (authentication only, no per-action policy) — deliberately kept consistent with
+how Supplier and PriceList currently ship rather than introducing enforcement piecemeal. Target
+permission codes for when policy enforcement is turned on across steps 14/15 together:
+```
+procurement.view, procurement.create, procurement.update, procurement.receive, procurement.return,
+suppliers.evaluate
+```
+No role assignments seeded yet — would mirror the pricing/supplier tier (AreaManager (30) and
+above) per 14's existing target design.
 
 ---
 
 ## Open Questions
 
-- Is procurement in scope for this project at all right now, or is inbound stock assumed to be
-  seeded/manual for the foreseeable future? Confirm before investing in this step — it's the
-  largest net-new subsystem in the reference doc.
+- Where should cost-vs-sale-price margin reporting (`PurchaseOrderItem.UnitCost` vs
+  `PriceListItem.Price`/`Item.SalePrice`) live — a read-only endpoint/report in this step, or a
+  later analytics/reporting step? Not a blocker for the core PO→GRN flow.
+- Landed cost (freight, duty, taxes allocated onto received stock) is out of scope —
+  `PurchaseOrderItem.UnitCost` is the only cost basis captured. Defer unless accurate per-unit cost
+  is needed sooner.
+- Reorder triggers (`setReorderPoint`/`sendLowStockAlert`) are not wired to procurement — restocking
+  stays fully manual until Notifications & Alerts exists.
+- `createPurchaseReturn` assumes a single receiving warehouse per PO (uses the most recent
+  `GoodsReceipt.FK_WarehouseId`). If a PO is ever received across multiple warehouses, the return
+  needs a `warehouseId` on the request instead of inferring one — not needed yet since nothing
+  splits a receipt across warehouses today.
+- Permission policy enforcement (`procurement.*`) is deferred — see Permissions to Add to Seed.
 
 ---
 
 ## Implementation Notes
 
-> Fill this section in during planning discussion before writing any code.
+### File structure (as built)
+```
+Features/
+  PurchaseOrder/
+    PoController.cs        — /api/purchase-orders (create/get/list/update/close/cancel/
+                              cancel-line/match-invoice/resolve-variance)
+    PoDTOs.cs               — CreatePoRequest, UpdatePoRequest(+Line), CancelPoRequest(+Line),
+                              PoResponse(+Item), InvoiceMatchResult(+Line), ResolveInvoiceVarianceRequest
+    PoService.cs            — createPurchaseOrder, updatePurchaseOrder, closePurchaseOrder,
+                              cancelPurchaseOrder, cancelPurchaseOrderLine, matchInvoiceToPO,
+                              resolveInvoiceVariance
+    IPoRepository.cs / PoRepository.cs
+  Grn/
+    GrnController.cs        — nested under /api/purchase-orders/{id}/goods-receipts,
+                              /api/goods-receipts/{id}
+    GrnDTOs.cs               — CreateGrnRequest, GrnResponse(+Item)
+    GrnService.cs            — createGoodsReceipt (credits StockBalance/StockMovement, updates
+                              PurchaseOrderItem.ReceivedQuantity, transitions PO status)
+    IGrnRepository.cs / GrnRepository.cs
+  PurchaseReturn/
+    PurchaseReturnController.cs   — nested under /api/purchase-orders/{id}/returns,
+                                     /api/purchase-returns/{id}
+    PurchaseReturnDTOs.cs
+    PurchaseReturnService.cs      — createPurchaseReturn (debits StockBalance/StockMovement)
+    IPurchaseReturnRepository.cs / PurchaseReturnRepository.cs
+  Supplier/
+    SupplierController.cs   — extended: POST /{id}/evaluate
+    SupplierService.cs      — extended: EvaluateAsync (only writer of PerformanceScore),
+                              DeleteAsync now blocks if an active PurchaseOrder references the supplier
+  Order/
+    OrderService.cs          — extended: CreateAsync now calls HasSufficientStockAsync
+                              (checkStockAvailability) before resolving price/inserting the order
+
+Models/
+  PurchaseOrder.cs, PurchaseOrderItem.cs   (new)
+  GoodsReceipt.cs, GoodsReceiptItem.cs     (new)
+  PurchaseReturn.cs, PurchaseReturnItem.cs (new)
+  Enums.cs                                 (extended — PurchaseOrderStatus enum added)
+
+Data/AppDBContext.cs
+  DbSets added for all six entities; FK relationships via Fluent API, DeleteBehavior.Restrict
+
+Migrations/
+  20260824110925_AddProcurement   (applied)
+
+Program.cs
+  IPoRepository/PoRepository, IGrnRepository/GrnRepository,
+  IPurchaseReturnRepository/PurchaseReturnRepository registered; PoService, GrnService,
+  PurchaseReturnService registered (Supplier registrations already existed from step 14)
+```
+
+### How the models connect
+```
+Supplier (existing, step 14)
+   ▲
+   │ FK_SupplierId
+PurchaseOrder ──► GoodsReceipt ──► StockBalance/StockMovement (Stock Ledger, §02)
+   │                  │               (credited: AcceptedQuantity, MovementType.PurchaseReceipt)
+   │                  └─ GoodsReceiptItem ─► PurchaseOrderItem
+   │                     (AcceptedQuantity increments stock; also increments
+   │                      PurchaseOrderItem.ReceivedQuantity, which drives PurchaseOrder.Status)
+   │
+   ├─ PurchaseOrderItem (FK_ItemId, Quantity, UnitCost, ReceivedQuantity, CancelledQuantity)
+   │
+   └─ PurchaseReturn ──► PurchaseReturnItem ──► StockBalance/StockMovement
+      (FK_PurchaseOrderId)  (FK_ItemId, Quantity;    (debited: MovementType.PurchaseReturn,
+                              via the PO's receiving   at the PO's receiving warehouse)
+                              warehouse)
+
+Invoice (Finance, step 19 — not yet built)
+   └─ matchInvoiceToPO reconciles PurchaseOrderItem vs GoodsReceiptItem only, today (invoiceId
+      accepted but unused); full 3-way match activates once Invoice exists.
+
+evaluateSupplier reads that supplier's PurchaseOrders/GoodsReceipts (accepted-vs-rejected quantity,
+cancelled-vs-fulfilled line ratio) and writes Supplier.PerformanceScore — no other function may
+write it.
+```
+
+### Goods receipt flow (as implemented)
+```
+GrnService.CreateAsync(purchaseOrderId, request, receivedByUserId):
+  po = load PurchaseOrder with Items, must be Issued or PartiallyReceived else throw
+  for each (purchaseOrderItemId, acceptedQty, rejectedQty) in request.Items:
+    poItem = po.Items.Single(purchaseOrderItemId)
+    outstanding = poItem.Quantity - poItem.ReceivedQuantity - poItem.CancelledQuantity
+    guard acceptedQty + rejectedQty <= outstanding else throw
+    poItem.ReceivedQuantity += acceptedQty
+    credit StockBalance(itemId, request.WarehouseId, Warehouse) += acceptedQty
+    add StockMovement(Type = PurchaseReceipt, ToLocation = warehouse, ReferenceId = goodsReceipt.Id)
+  po.Status = every non-cancelled poItem.ReceivedQuantity == poItem.Quantity
+              ? Received : PartiallyReceived
+  commit GoodsReceipt + GoodsReceiptItems + updated PurchaseOrderItem rows + StockBalance/Movement
+  in one transaction (IUnitOfWork.Begin/Commit)
+```
+
+### Purchase return flow (as implemented)
+```
+PurchaseReturnService.CreateAsync(purchaseOrderId, request, createdByUserId):
+  po = load PurchaseOrder, must have >= 1 GoodsReceipt else throw
+  warehouseId = most recent GoodsReceipt.FK_WarehouseId for this Po
+  for each (itemId, qty) in request.Items:
+    received = sum(GoodsReceiptItem.AcceptedQuantity for itemId across po's receipts)
+    alreadyReturned = sum(PurchaseReturnItem.Quantity for itemId across po's prior returns)
+    guard qty <= received - alreadyReturned else throw
+    debit StockBalance(itemId, warehouseId) -= qty
+    add StockMovement(Type = PurchaseReturn, FromLocation = warehouseId, ReferenceId = purchaseReturn.Id)
+  commit PurchaseReturn + PurchaseReturnItems + StockBalance/Movement in one transaction
+```

Distribution/docs/17_promotions_schemes.md

@@ -1,70 +1,378 @@
 # 17 — Promotions & Trade Scheme Management
 
-**Status**: Not Started
-**Depends On**: 01 — Item Catalog, 14 — Pricing & Supplier Master Data
+**Status**: Done — migrations applied to the database
+**Depends On**: 01 — Item Catalog (Done), 14 — Pricing & Supplier Master Data (Done), 02 — Stock Ledger (Done)
 
 ---
 
 ## Goal
 
 Covers [mainPlan.md §11](./mainPlan.md#11-promotions--trade-scheme-management)
-in full — an entirely new subsystem. Once built, `applyPricingAndDiscounts` (§1) and
+in full — an entirely new subsystem. `applyPricingAndDiscounts` (§1) and
 `checkStoreSchemeEligibility` (§4) both read from it.
 
 ---
 
 ## Background / Context
 
-No scheme/promotion entity exists today. Every reference to "eligible discount" elsewhere in this
-doc set (order pricing, field invoices, agent discount limits) currently has no scheme data source
-— it only enforces the flat per-role discount ceiling from
+No scheme/promotion entity existed before this step. Every reference to "eligible discount"
+elsewhere in this doc set (order pricing, field invoices, agent discount limits) had no scheme data
+source — it only enforced the flat per-role discount ceiling from
 [08_sales_agent_controls.md](./08_sales_agent_controls.md).
 
+For an enterprise distributor, free-goods/bundle promotions ("buy 10 get 1 free", "buy A + B get C
+free") are operationally different from discount schemes because they move physical stock at zero
+revenue, not just reduce a price. That distinction shaped the data model below: `BuyXGetY` and
+`FreeBundle` rules are structured columns/child rows (with their own CRUD), not a JSON blob, so a
+free-goods rule can be validated (item exists, positive qty, stock available) the same way any other
+order line is. `SlabDiscount`/`FlatPercent` stay JSON in `RuleConfig` since they're pure
+percentage-off rules with no inventory or fulfilment side effects.
+
 ---
 
 ## Data Model Changes
 
 ### Scheme
+```
+Scheme
+├── Id (Guid)                  — PK, from Template
+├── Name (string)
+├── RuleType (enum)            — BuyXGetY, SlabDiscount, FlatPercent, FreeBundle
+├── RuleConfig (string?)       — JSON, only used by SlabDiscount/FlatPercent (see below); null
+│                                 for BuyXGetY/FreeBundle
+├── FK_TriggerItemId (Guid?)   — BuyXGetY only: the item the store must buy
+├── TriggerQty (int?)          — BuyXGetY only: qty of TriggerItem required to earn one payout
+├── FK_FreeItemId (Guid?)      — shared payout for BuyXGetY and FreeBundle: item given free
+├── FreeQty (decimal?)         — shared payout: qty of FreeItem given free
+├── FK_RegionId (Guid?)        — nullable, null = all regions
+├── EligibleSegment (string?)  — Store.Segment match (Gold/Silver/Key Account/...); null = all segments
+├── DateRangeFrom (DateTime)
+├── DateRangeTo (DateTime)
+├── AgentLimitExempt (bool)    — if true, this scheme's discount stacks on top of the per-role
+│                                 discount ceiling (08_sales_agent_controls.md) unconditionally
+├── BaselineExpectedSales (decimal?) — manual baseline used by getSchemeROI (see Open Questions)
+├── IsActive, CreatedAt        — from Template
+```
 
-`Name`, `RuleType` (`BuyXGetY`, `SlabDiscount`, `FlatPercent`), `RuleConfig` (JSON), `Eligibility`
-(store segment / region scope), `DateRangeFrom`, `DateRangeTo`.
+`RuleConfig` JSON shape (SlabDiscount/FlatPercent only):
+- `FlatPercent` — `{ "discountPercent": 10 }`
+- `SlabDiscount` — `{ "tiers": [{ "minOrderAmount": 5000, "discountPercent": 5 }, ...] }`, the
+  highest tier whose `minOrderAmount` the order total meets or exceeds wins.
 
-### Scheme Redemption
+### SchemeBundleComponent
+```
+SchemeBundleComponent
+├── Id (Guid)                  — PK
+├── FK_SchemeId (Guid)         — required, cascade delete with parent Scheme
+├── FK_ItemId (Guid)           — required
+├── Qty (int)                  — required qty of this item for the FreeBundle rule to trigger
+```
+Unique constraint on `(SchemeId, ItemId)`. Only meaningful when `Scheme.RuleType = FreeBundle` — the
+order must contain every component in at least its listed `Qty` before the scheme's
+`FK_FreeItemId`/`FreeQty` payout is granted.
 
-`SchemeId`, `OrderId` (or `FieldInvoiceId`), `DiscountAmount`, `RedeemedAt` — feeds
-`trackSchemeSpend` and `getSchemeROI` without re-scanning every order.
+### SchemeRedemption
+```
+SchemeRedemption
+├── Id (Guid)                  — PK
+├── FK_SchemeId (Guid)         — required
+├── FK_OrderId (Guid?)         — nullable (see FieldInvoiceId below)
+├── FieldInvoiceId (Guid?)     — placeholder for the future field-invoice module; no FieldInvoice
+│                                 entity exists yet, so this is an unconstrained Guid for now
+├── DiscountAmount (decimal?)  — set for SlabDiscount/FlatPercent redemptions
+├── FK_FreeItemId (Guid?)      — set for BuyXGetY/FreeBundle redemptions
+├── FreeQty (decimal?)
+├── FreeItemCostValue (decimal?) — free item's Item.CostPrice snapshotted at redemption time, so
+│                                   getSchemeROI/trackSchemeSpend stay accurate after CostPrice
+│                                   later changes
+├── RedeemedAt (DateTime)
+```
+At least one of `DiscountAmount` or `FreeQty` is set per redemption; `Scheme`/`Order` restrict-delete
+(a scheme or order with redemptions can't be hard-deleted, and soft-delete leaves history intact).
+
+### Item (extended)
+```
+Item
+├── ...
+├── CostPrice (decimal?)       — new: cost/purchase price, used to value free-goods redemptions
+```
+
+---
+
+## Migrations
+
+Two migrations:
+1. **AddPromotionsSchemes** (applied) — creates `Schemes`, `SchemeRedemptions`; adds `Item.CostPrice`.
+2. **AddSchemeFreeGoodsRuleAndBundleComponents** (applied) — makes `Scheme.RuleConfig` nullable, adds
+   `Scheme.FK_TriggerItemId`/`TriggerQty`/`FK_FreeItemId`/`FreeQty`, creates `SchemeBundleComponents`.
+
+(Split into two because the free-goods columns were promoted from a JSON blob to structured
+columns/child table after the first migration had already been applied to the dev database.)
 
 ---
 
 ## API Endpoints
 
-| Function reference | Endpoint intent |
-|---|---|
-| `createScheme(schemeRules, eligibility, dateRange)` | `POST /api/schemes` |
-| `evaluateSchemeEligibility(storeId, orderId)` | `GET /api/schemes/eligible?storeId=...&orderId=...` |
-| `applySchemeDiscount(orderId, schemeId)` | `POST /api/orders/{id}/apply-scheme` |
-| `trackSchemeSpend(schemeId)` | `GET /api/schemes/{id}/spend` |
-| `getSchemeROI(schemeId)` | `GET /api/schemes/{id}/roi` |
+| Function reference | Endpoint | Notes |
+|---|---|---|
+| `createScheme(schemeRules, eligibility, dateRange)` | `POST /api/schemes` | `RuleConfig` required only for SlabDiscount/FlatPercent; `TriggerItemId`/`TriggerQty`/`FreeItemId`/`FreeQty`/`BundleComponents` can be supplied inline to fully create a BuyXGetY/FreeBundle scheme in one call |
+| — | `GET /api/schemes` | Filterable by region |
+| — | `GET /api/schemes/{id}` | Includes trigger/free item, bundle components |
+| — | `PUT /api/schemes/{id}` | Updates name/eligibility/date range/`RuleConfig` |
+| — | `DELETE /api/schemes/{id}` | Soft delete |
+| — | `PUT /api/schemes/{id}/free-goods-rule` | Sets the BuyXGetY trigger + shared free-goods payout (also the payout for FreeBundle) |
+| — | `DELETE /api/schemes/{id}/free-goods-rule` | Clears it |
+| — | `PUT /api/schemes/{id}/bundle-components/{itemId}` | Upserts one FreeBundle required-item row |
+| — | `DELETE /api/schemes/{id}/bundle-components/{itemId}` | Removes one FreeBundle required-item row |
+| `evaluateSchemeEligibility(storeId, orderId)` | `GET /api/schemes/eligible?storeId=...&orderId=...` | Returns eligibility for every in-scope scheme, not just one |
+| `applySchemeDiscount(orderId, schemeId)` | `POST /api/orders/{id}/apply-scheme` | Adds a zero-price order line for free-goods payouts |
+| `trackSchemeSpend(schemeId)` | `GET /api/schemes/{id}/spend` | Discount spend + free-goods cost spend |
+| `getSchemeROI(schemeId)` | `GET /api/schemes/{id}/roi` | Uses `BaselineExpectedSales` |
+
+---
+
+## Request / Response Shapes
+
+### POST `/api/schemes` (BuyXGetY — created fully populated in one call)
+```json
+{
+  "name": "Soap Buy10Get1",
+  "ruleType": "BuyXGetY",
+  "ruleConfig": null,
+  "regionId": null,
+  "eligibleSegment": "Gold",
+  "dateRangeFrom": "2026-08-01T00:00:00",
+  "dateRangeTo": "2026-08-31T23:59:59",
+  "agentLimitExempt": false,
+  "baselineExpectedSales": 50000,
+  "triggerItemId": "<soapItemId>",
+  "triggerQty": 10,
+  "freeItemId": "<soapItemId>",
+  "freeQty": 1
+}
+```
+`triggerItemId`/`triggerQty`/`freeItemId`/`freeQty` are optional on create — omit them for a plain
+SlabDiscount/FlatPercent scheme, or omit and set them later via `PUT .../free-goods-rule` if you want
+to create the shell first and configure the payout afterwards.
+
+### POST `/api/schemes` (FreeBundle — created fully populated in one call)
+```json
+{
+  "name": "Soap+Shampoo -> Free Toothbrush",
+  "ruleType": "FreeBundle",
+  "ruleConfig": null,
+  "regionId": null,
+  "eligibleSegment": null,
+  "dateRangeFrom": "2026-08-01T00:00:00",
+  "dateRangeTo": "2026-08-31T23:59:59",
+  "agentLimitExempt": false,
+  "baselineExpectedSales": null,
+  "freeItemId": "<toothbrushId>",
+  "freeQty": 1,
+  "bundleComponents": [ { "itemId": "<soapId>", "qty": 1 }, { "itemId": "<shampooId>", "qty": 1 } ]
+}
+```
+`triggerItemId`/`triggerQty` are ignored for FreeBundle — the required items come from
+`bundleComponents` instead.
+
+### PUT `/api/schemes/{id}/free-goods-rule`
+```json
+{ "triggerItemId": "<soapItemId>", "triggerQty": 10, "freeItemId": "<soapItemId>", "freeQty": 1 }
+```
+Same shape as the inline create fields — use this to add or change the free-goods payout on a
+scheme that was created without one.
+
+### PUT `/api/schemes/{id}/bundle-components/{itemId}` (FreeBundle)
+```json
+{ "qty": 1 }
+```
+Use this to add/edit one bundle component after creation.
+
+### POST `/api/schemes` (SlabDiscount)
+```json
+{
+  "name": "Volume Discount",
+  "ruleType": "SlabDiscount",
+  "ruleConfig": "{\"tiers\":[{\"minOrderAmount\":5000,\"discountPercent\":5},{\"minOrderAmount\":10000,\"discountPercent\":8}]}",
+  "regionId": null,
+  "eligibleSegment": null,
+  "dateRangeFrom": "2026-08-01T00:00:00",
+  "dateRangeTo": "2026-08-31T23:59:59",
+  "agentLimitExempt": false,
+  "baselineExpectedSales": null
+}
+```
+
+### POST `/api/orders/{id}/apply-scheme`
+```json
+{ "schemeId": "..." }
+```
 
 ---
 
 ## Business Rules
 
-- A scheme discount stacks with, but does not bypass, the per-role discount ceiling in
-  [08_sales_agent_controls.md](./08_sales_agent_controls.md) unless explicitly flagged as an
-  agent-limit-exempt scheme.
-- `getSchemeROI` requires a baseline (pre-scheme expected sales) to compare against — confirm data
-  source before implementing (see Open Questions).
+1. A scheme discount stacks with, but does not bypass, the per-role discount ceiling in
+   [08_sales_agent_controls.md](./08_sales_agent_controls.md) unless `AgentLimitExempt = true`.
+   (Enforcement against the actual ceiling is deferred — 08_sales_agent_controls.md's discount
+   ceiling isn't implemented in code yet; this is recorded as the target behavior.)
+2. `evaluateSchemeEligibility` matches a scheme to a store/order only if: the scheme's `RegionId` is
+   null or matches the store's region; `EligibleSegment` is null or matches `Store.Segment`; and the
+   order's date falls within `[DateRangeFrom, DateRangeTo]`.
+3. `BuyXGetY` eligibility: the order must contain at least `TriggerQty` of `TriggerItem`; the payout
+   scales with how many multiples of `TriggerQty` were bought (`FreeQty × floor(boughtQty / TriggerQty)`).
+4. `FreeBundle` eligibility: the order must contain every `SchemeBundleComponent` in at least its
+   listed `Qty`; payout is the flat `FreeQty` of `FreeItem` (no multiplier).
+5. `applySchemeDiscount` adds a zero-price `OrderItem` line for the free-goods payout (`UnitPrice = 0`,
+   `Quantity = FreeQty`), rather than only recording a discount amount — the free line still needs to
+   be picked, delivered, and stock-tracked like any other sold line.
+6. A free-goods redemption is blocked if the free item's available `StockBalance` (summed across all
+   locations) is less than the payout `FreeQty` — same out-of-stock guard as a normal sold line.
+7. A scheme can only be redeemed once per order (`HasRedemptionAsync` check in `applySchemeDiscount`).
+8. `SchemeRedemption.FreeItemCostValue` snapshots `Item.CostPrice` at redemption time, so
+   `trackSchemeSpend`/`getSchemeROI` stay accurate even after the item's cost price later changes.
+9. Free goods are typically still a taxable "deemed supply" at zero net value under GST/VAT-style
+   regimes — not yet wired into a tax calculation, since no tax subsystem exists in this codebase
+   yet. Flagged for whoever builds tax/invoicing.
+10. `trackSchemeSpend` = sum(`DiscountAmount`) + sum(`FreeItemCostValue × FreeQty`) across all
+    redemptions. `getSchemeROI` = `(actualSales − BaselineExpectedSales) / totalSpend`, where
+    `actualSales` is the sum of `Order.TotalAmount` for every distinct order that redeemed the scheme.
 
 ---
 
 ## Open Questions
 
-- What counts as "incremental sales" for `getSchemeROI` — a manual baseline entered when the scheme
-  is created, or a trailing-period average computed automatically?
+- What counts as "incremental sales" for `getSchemeROI` — **resolved for v1**: a manual
+  `BaselineExpectedSales` entered at scheme creation, not a trailing-period average. Revisit if
+  historical order data volume later makes an automatic trailing average preferable.
+- Per-role discount ceiling stacking (`AgentLimitExempt`) is unenforced pending
+  [08_sales_agent_controls.md](./08_sales_agent_controls.md) having an actual ceiling implementation
+  to stack against.
+- Deemed-supply tax treatment for free goods — deferred until a tax/invoicing subsystem exists.
 
 ---
 
 ## Implementation Notes
 
-> Fill this section in during planning discussion before writing any code.
+### File structure created / touched
+```
+Features/
+  Scheme/
+    SchemeController.cs     (also hosts SchemeOrderController for POST /api/orders/{id}/apply-scheme)
+    SchemeDTOs.cs
+    SchemeService.cs         (EvaluateRule — the core eligibility/payout calculator; ApplySchemeAsync
+                               — the free-goods order-line + stock-check + redemption write path)
+    ISchemeRepository.cs
+    SchemeRepository.cs
+
+Models/
+  Scheme.cs                  (new — includes SchemeRuleType enum)
+  SchemeBundleComponent.cs   (new)
+  SchemeRedemption.cs        (new)
+  Item.cs                    (extended — CostPrice)
+
+Data/AppDBContext.cs
+  add Schemes, SchemeRedemptions, SchemeBundleComponents DbSets; relationships (Scheme→TriggerItem/
+  FreeItem restrict-delete, SchemeBundleComponent→Scheme cascade-delete, →Item restrict-delete,
+  SchemeRedemption→Scheme/Order/FreeItem restrict-delete); unique index on
+  SchemeBundleComponent(FK_SchemeId, FK_ItemId)
+
+Migrations/
+  AddPromotionsSchemes                                  (applied)
+  AddSchemeFreeGoodsRuleAndBundleComponents              (applied)
+
+Program.cs
+  register ISchemeRepository/SchemeRepository, SchemeService
+```
+
+### Eligibility + payout logic (pseudo)
+```
+EvaluateRule(scheme, orderItems):
+  switch scheme.RuleType:
+    BuyXGetY:
+      boughtQty = sum(orderItems where ItemId = scheme.TriggerItemId).Quantity
+      if boughtQty < scheme.TriggerQty: not eligible
+      multiplier = boughtQty / scheme.TriggerQty  // integer division
+      → eligible, FreeItemId = scheme.FreeItemId, FreeQty = scheme.FreeQty * multiplier
+
+    FreeBundle:
+      missing = scheme.BundleComponents where sum(orderItems qty for that item) < component.Qty
+      if missing.any(): not eligible
+      → eligible, FreeItemId = scheme.FreeItemId, FreeQty = scheme.FreeQty
+
+    FlatPercent / SlabDiscount:
+      parse RuleConfig JSON, compute DiscountAmount off orderItems total
+```
+
+### applySchemeDiscount flow (pseudo)
+```
+ApplySchemeAsync(orderId, schemeId):
+  reject if scheme already redeemed against this order
+  eligibility = EvaluateRule(scheme, order's items)
+  reject if not eligible
+
+  if eligibility has a free-goods payout:
+    check StockBalance across all locations >= FreeQty, else reject
+    add OrderItem { ItemId = FreeItemId, Quantity = FreeQty, UnitPrice = 0 }
+    redemption.FreeItemCostValue = freeItem.CostPrice ?? 0
+
+  save SchemeRedemption { DiscountAmount, FreeItemId, FreeQty, FreeItemCostValue }
+```
+
+---
+
+## Worked Example
+
+Item `Soap-500ml` has `CostPrice = 12`. Store is in the "Gold" segment.
+
+**Create the scheme (one call, fully populated):**
+```
+POST /api/schemes
+{ "name": "Soap Buy10Get1", "ruleType": "BuyXGetY", "ruleConfig": null,
+  "regionId": null, "eligibleSegment": "Gold",
+  "dateRangeFrom": "2026-08-01", "dateRangeTo": "2026-08-31",
+  "agentLimitExempt": false, "baselineExpectedSales": 50000,
+  "triggerItemId": "<soapId>", "triggerQty": 10, "freeItemId": "<soapId>", "freeQty": 1 }
+→ Scheme { Id, ... }
+```
+
+**Store places an order** for 20 units of `Soap-500ml` → `Order { Id, TotalAmount }`.
+
+**Check eligibility:**
+```
+GET /api/schemes/eligible?storeId=...&orderId=...
+→ [{ "schemeId": "...", "eligible": true, "freeItemId": "<soapId>", "freeQty": 2 }]
+```
+20 ÷ 10 = 2 multiples → 2 free units.
+
+**Apply it:**
+```
+POST /api/orders/{orderId}/apply-scheme
+{ "schemeId": "..." }
+```
+Adds an `OrderItem` line (`Soap-500ml`, qty 2, `UnitPrice = 0`) and a `SchemeRedemption` with
+`FreeQty = 2`, `FreeItemCostValue = 12`.
+
+**Spend/ROI:**
+```
+GET /api/schemes/{id}/spend
+→ { "totalDiscountSpend": 0, "totalFreeGoodsCostSpend": 24, "totalSpend": 24, "redemptionCount": 1 }
+
+GET /api/schemes/{id}/roi
+→ { "baselineExpectedSales": 50000, "actualSales": 62000, "incrementalSales": 12000,
+    "totalSpend": 24, "roi": 500.0 }
+```
+
+**FreeBundle variant** ("buy Soap + Shampoo, get a free Toothbrush") — also one call:
+```
+POST /api/schemes
+{ "name": "Soap+Shampoo -> Free Toothbrush", "ruleType": "FreeBundle", "ruleConfig": null,
+  "regionId": null, "eligibleSegment": null,
+  "dateRangeFrom": "2026-08-01", "dateRangeTo": "2026-08-31",
+  "agentLimitExempt": false, "baselineExpectedSales": null,
+  "freeItemId": "<toothbrushId>", "freeQty": 1,
+  "bundleComponents": [ { "itemId": "<soapId>", "qty": 1 }, { "itemId": "<shampooId>", "qty": 1 } ] }
+```
+Eligibility now requires both Soap ≥1 and Shampoo ≥1 in the order; payout is 1 free toothbrush,
+flat (no multiplier). Components/payout can still be edited afterwards via
+`PUT .../bundle-components/{itemId}` and `PUT .../free-goods-rule`.

Distribution/docs/mainPlan.md

@@ -10,10 +10,13 @@
 | Role Management | Done (read-only) | 6 roles seeded, no create/update via API |
 | Region / Route / Vehicle CRUD | Done | Full API surface with permission checks |
 | Store / Warehouse CRUD | Done | Full API surface with permission checks |
+| Store Management (Beyond CRUD) | Done | Credit limit, KYC, segment, dashboard, scheme eligibility; see [12_store_management.md](./12_store_management.md) |
 | Order CRUD | Done | Scope-aware (user only sees their assigned stores) |
 | Unit of Work + Repositories | Done | Transaction support throughout |
 | Soft Deletes | Done | IsActive pattern on all entities |
 | Price Lists / Suppliers | Done | Region-scoped price lists + supplier master; see [14_pricing_and_suppliers.md](./14_pricing_and_suppliers.md) |
+| Promotions & Trade Schemes | Done | BuyXGetY/FreeBundle/SlabDiscount/FlatPercent schemes, free-goods fulfillment, spend/ROI tracking; see [17_promotions_schemes.md](./17_promotions_schemes.md) |
+| Procurement / Purchasing | Done | Purchase Order → Goods Receipt → Purchase Return, supplier evaluation; see [15_procurement.md](./15_procurement.md) |
 
 ## Known Gaps in Existing System (Pre-Work)
 
@@ -39,20 +42,20 @@ They must be resolved before new feature steps begin because later steps depend
 | 01 | Item Catalog | Done | 00 | [01_item_catalog.md](./01_item_catalog.md) |
 | 02 | Stock Ledger | Done | 01 | [02_stock_ledger.md](./02_stock_ledger.md) |
 | 03 | Ride Lifecycle | Done | 02 | [03_ride_lifecycle.md](./03_ride_lifecycle.md) |
-| 04 | Loading Event | Not Started | 03 | [04_loading_event.md](./04_loading_event.md) |
-| 05 | Delivery Ride Execution | Not Started | 04 | [05_delivery_ride.md](./05_delivery_ride.md) |
-| 06 | Sale Ride Execution | Not Started | 04 | [06_sale_ride.md](./06_sale_ride.md) |
+| 04 | Loading Event | Done | 03 | [04_loading_event.md](./04_loading_event.md) |
+| 05 | Delivery Ride Execution | Done | 04 | [05_delivery_ride.md](./05_delivery_ride.md) |
+| 06 | Sale Ride Execution | Done | 04 | [06_sale_ride.md](./06_sale_ride.md) |
 | 07 | Ride Close & Reconciliation | Not Started | 05, 06 | [07_ride_reconciliation.md](./07_ride_reconciliation.md) |
 | 08 | Sales Agent Controls | Not Started | 07 | [08_sales_agent_controls.md](./08_sales_agent_controls.md) |
 | 09 | Fraud Controls & Audit Trail | Not Started | 08 | [09_fraud_controls.md](./09_fraud_controls.md) |
 | 10 | Region Management (Beyond CRUD) | Not Started | 00 | [10_region_management.md](./10_region_management.md) |
 | 11 | Route & Sales Visit Management | Not Started | 00 | [11_route_sales_management.md](./11_route_sales_management.md) |
-| 12 | Store Management (Beyond CRUD) | In Progress | 00 | [12_store_management.md](./12_store_management.md) |
+| 12 | Store Management (Beyond CRUD) | Done | 00 | [12_store_management.md](./12_store_management.md) |
 | 13 | Fleet Management (Beyond CRUD) | Not Started | 00 | [13_fleet_management.md](./13_fleet_management.md) |
 | 14 | Pricing & Supplier Master Data | Done | 01 | [14_pricing_and_suppliers.md](./14_pricing_and_suppliers.md) |
-| 15 | Procurement / Purchasing | Not Started | 01, 14 | [15_procurement.md](./15_procurement.md) |
+| 15 | Procurement / Purchasing | Done | 01, 14 | [15_procurement.md](./15_procurement.md) |
 | 16 | Sales Force Automation / CRM | Not Started | 12 | [16_sfa_crm.md](./16_sfa_crm.md) |
-| 17 | Promotions & Trade Scheme Management | Not Started | 01, 14 | [17_promotions_schemes.md](./17_promotions_schemes.md) |
+| 17 | Promotions & Trade Scheme Management | Done | 01, 14 | [17_promotions_schemes.md](./17_promotions_schemes.md) |
 | 18 | Returns & Claims Management | Not Started | 05, 06 | [18_returns_claims.md](./18_returns_claims.md) |
 | 19 | Finance & Accounting | Not Started | 05, 06, 18 | [19_finance_accounting.md](./19_finance_accounting.md) |
 | 20 | Reporting, Analytics & BI | Not Started | all prior | [20_reporting_analytics.md](./20_reporting_analytics.md) |
@@ -80,10 +83,10 @@ here — see `SRS_User_Management_Module.pdf`.
 
 | Function | What it does | Status |
 |---|---|---|
-| `createOrder(storeId, items[], salesRepId)` | Validates stock/credit, creates a new order in `pending` state. | Partially implemented - `OrderService.CreateAsync` exists, enforces store scope, blocks inactive stores, and applies the unverified-KYC order threshold from config. It still has no stock validation, credit-limit validation, approval flow, or order state machine. |
+| `createOrder(storeId, items[], salesRepId)` | Validates stock/credit, creates a new order in `pending` state. | Partially implemented - `OrderService.CreateAsync` exists, enforces store scope, blocks inactive stores, applies the unverified-KYC order threshold from config, and now checks stock availability (see `checkStockAvailability` below). It still has no credit-limit validation, approval flow, or order state machine. |
 | `validateCreditLimit(storeId, orderAmount)` | Checks store's outstanding balance + new order value against its credit limit. | Not implemented - `Store` now has `CreditLimit` and `OutstandingBalance`, but there is no dedicated validator or order-time credit-limit enforcement yet. |
-| `checkStockAvailability(items[])` | Confirms requested SKUs/quantities are available at the fulfilling warehouse. | Not implemented — depends on [02_stock_ledger.md](./02_stock_ledger.md). |
-| `applyPricingAndDiscounts(orderId)` | Runs the active price list and eligible scheme rules against order lines. | Partially implemented — `OrderService.CreateAsync` resolves the price-list half via `PriceListService.ResolveUnitPriceAsync` (region-scoped → global → `Item.SalePrice`, or a caller-supplied `UnitPrice`); the scheme-discount half still depends on §11 Promotions below. |
+| `checkStockAvailability(items[])` | Confirms requested SKUs/quantities are available at the fulfilling warehouse. | Implemented — `OrderService.CreateAsync` rejects an order if any line's requested quantity exceeds total `StockBalance` for that item summed across every location (added alongside [15_procurement.md](./15_procurement.md)). Not location-specific yet (no fulfilling-warehouse concept on `Store`/`Order`), and does not reserve or decrement stock — that stays deferred to loading/delivery (§05-06). |
+| `applyPricingAndDiscounts(orderId)` | Runs the active price list and eligible scheme rules against order lines. | Partially implemented — `OrderService.CreateAsync` resolves the price-list half via `PriceListService.ResolveUnitPriceAsync` (region-scoped → global → `Item.SalePrice`, or a caller-supplied `UnitPrice`). The scheme-discount half now exists as a separate call — `SchemeService.EvaluateEligibilityAsync`/`ApplySchemeAsync` (§11) — but is not yet auto-invoked from `OrderService.CreateAsync`; the caller applies a scheme explicitly via `POST /api/orders/{id}/apply-scheme` after order creation. |
 | `submitOrderForApproval(orderId)` | Routes the order to the correct approver based on its value/discount threshold. | Not implemented — depends on [08_sales_agent_controls.md](./08_sales_agent_controls.md). |
 | `approveOrder(orderId, approverId)` / `rejectOrder(orderId, reason)` | Moves order to `approved` or `rejected`, logging the actor. | Not implemented. |
 | `updateOrderStatus(orderId, status)` | Transitions order through `pending → approved → picked → dispatched → delivered → invoiced`. | Not implemented — `Order` has no status field or state machine today. |
@@ -132,7 +135,7 @@ here — see `SRS_User_Management_Module.pdf`.
 | `classifyStore(storeId, segment)` | Sets/updates the store's segment (key account, general trade, etc.). | Implemented - `PUT /api/stores/{id}/segment` updates the free-text `Store.Segment` field. |
 | `deactivateStore(storeId, reason)` | Soft-deletes a store, blocking new orders against it. | Partially implemented — `DELETE /api/stores/{id}` soft-deletes via `IsActive`, no reason code captured. |
 | `getStoreVisitHistory(storeId)` | Returns visit compliance history from Route Management. | Placeholder only - endpoint exists (`GET /api/stores/{id}/visit-history`) but currently returns an empty list until Route/Sales Visit Management lands. |
-| `checkStoreSchemeEligibility(storeId, schemeId)` | Evaluates whether a store qualifies for a given promotion. | Placeholder only - endpoint exists (`GET /api/stores/{id}/schemes/{schemeId}/eligibility`) but currently returns a default eligible response until Promotions is implemented. |
+| `checkStoreSchemeEligibility(storeId, schemeId)` | Evaluates whether a store qualifies for a given promotion. | Implemented — `GET /api/stores/{id}/schemes/{schemeId}/eligibility` now calls `SchemeService.CheckStoreScopeEligibilityAsync` (region/segment/date-range scope check, no order context). For full order-line rule evaluation against a specific order, use `evaluateSchemeEligibility(storeId, orderId)` instead (`GET /api/schemes/eligible?storeId=...&orderId=...`, §11). |
 | `getStoreSalesDashboard(storeId, period)` | Store-level sales and outstanding summary. | Partially implemented - `GET /api/stores/{id}/dashboard` aggregates order count, total order value, and last order date for the selected month. It does not yet include full sales/outstanding analytics from Finance. |
 
 ### 5. Vehicle / Fleet Management
@@ -154,7 +157,7 @@ here — see `SRS_User_Management_Module.pdf`.
 
 | Function | What it does | Status |
 |---|---|---|
-| `createGoodsReceipt(poId, receivedItems[])` | Records inbound stock against a purchase order (GRN). | Not implemented — depends on §9 Procurement. |
+| `createGoodsReceipt(poId, receivedItems[])` | Records inbound stock against a purchase order (GRN). | Implemented — `POST /api/purchase-orders/{id}/goods-receipts`, see [15_procurement.md](./15_procurement.md). Credits `StockBalance`/`StockMovement` for accepted quantities and transitions the PO's status. |
 | `inspectGoodsReceipt(grnId, inspectionResult)` | Logs quality-check outcome before putaway. | Not implemented. |
 | `putawayStock(grnId, locationAssignments[])` | Assigns received stock to warehouse locations (zone/ABC-based). | Not implemented — depends on [02_stock_ledger.md](./02_stock_ledger.md). |
 | `getStockByLocation(warehouseId, sku)` | Returns real-time quantity and location for a SKU. | Not implemented — depends on [02_stock_ledger.md](./02_stock_ledger.md). |
@@ -193,10 +196,10 @@ here — see `SRS_User_Management_Module.pdf`.
 | Function | What it does | Status |
 |---|---|---|
 | `createPurchaseRequisition(items[], requestedBy)` | Raises an internal request to purchase stock. | Not implemented — no procurement entities exist. |
-| `createPurchaseOrder(supplierId, items[])` | Issues a PO to a supplier. | Not implemented. |
-| `matchInvoiceToPO(invoiceId, poId, grnId)` | Performs the 3-way match (PO–GRN–Invoice) before payment. | Not implemented. |
-| `evaluateSupplier(supplierId, criteria)` | Scores a supplier on delivery/quality/price performance. | Not implemented. |
-| `createPurchaseReturn(poId, items[], reason)` | Initiates a return of received goods to the supplier. | Not implemented. |
+| `createPurchaseOrder(supplierId, items[])` | Issues a PO to a supplier. | Implemented — `POST /api/purchase-orders`, see [15_procurement.md](./15_procurement.md). Also has `updatePurchaseOrder`, `closePurchaseOrder`, `cancelPurchaseOrder`, `cancelPurchaseOrderLine`. |
+| `matchInvoiceToPO(invoiceId, poId, grnId)` | Performs the 3-way match (PO–GRN–Invoice) before payment. | Partially implemented — `POST /api/purchase-orders/{id}/match-invoice` reconciles PurchaseOrderItem vs GoodsReceiptItem quantities/cost only; full 3-way match activates once Finance's `Invoice` entity (§13, not built) exists. `resolveInvoiceVariance` records the mismatch and its resolution. |
+| `evaluateSupplier(supplierId, criteria)` | Scores a supplier on delivery/quality/price performance. | Implemented — `POST /api/suppliers/{id}/evaluate`, the only writer of `Supplier.PerformanceScore`. Scored from accepted-vs-rejected quantity ratio and cancelled-vs-fulfilled line ratio across that supplier's PurchaseOrders/GoodsReceipts. |
+| `createPurchaseReturn(poId, items[], reason)` | Initiates a return of received goods to the supplier. | Implemented — `POST /api/purchase-orders/{id}/returns`, see [15_procurement.md](./15_procurement.md). Debits `StockBalance`/`StockMovement` at the PO's receiving warehouse. |
 
 ### 10. Sales Force Automation (SFA) / CRM
 
@@ -212,11 +215,11 @@ here — see `SRS_User_Management_Module.pdf`.
 
 | Function | What it does | Status |
 |---|---|---|
-| `createScheme(schemeRules, eligibility, dateRange)` | Defines a promotion (buy-X-get-Y, slab discount, etc.). | Not implemented — no scheme entity exists. |
-| `evaluateSchemeEligibility(storeId, orderId)` | Checks whether an order qualifies for a scheme. | Not implemented. |
-| `applySchemeDiscount(orderId, schemeId)` | Applies the scheme's discount to order pricing. | Not implemented. |
-| `trackSchemeSpend(schemeId)` | Aggregates total discount value given under a scheme. | Not implemented. |
-| `getSchemeROI(schemeId)` | Compares scheme spend against incremental sales generated. | Not implemented. |
+| `createScheme(schemeRules, eligibility, dateRange)` | Defines a promotion (buy-X-get-Y, slab discount, etc.). | Implemented — `POST /api/schemes`. Supports `BuyXGetY`, `FreeBundle`, `SlabDiscount`, `FlatPercent`; free-goods trigger/payout and bundle components can be supplied inline in the same call. See [17_promotions_schemes.md](./17_promotions_schemes.md). |
+| `evaluateSchemeEligibility(storeId, orderId)` | Checks whether an order qualifies for a scheme. | Implemented — `GET /api/schemes/eligible?storeId=...&orderId=...`, returns eligibility (and computed discount/free-goods payout) for every in-scope scheme, not just one. |
+| `applySchemeDiscount(orderId, schemeId)` | Applies the scheme's discount to order pricing. | Implemented — `POST /api/orders/{id}/apply-scheme`. For free-goods schemes this adds a zero-price `OrderItem` line and checks `StockBalance` availability first; not yet auto-invoked from `createOrder`/`applyPricingAndDiscounts` (§1) — caller applies it explicitly after order creation. |
+| `trackSchemeSpend(schemeId)` | Aggregates total discount value given under a scheme. | Implemented — `GET /api/schemes/{id}/spend`, sums `DiscountAmount` plus free-goods cost (`FreeItemCostValue × FreeQty`) across redemptions. |
+| `getSchemeROI(schemeId)` | Compares scheme spend against incremental sales generated. | Implemented — `GET /api/schemes/{id}/roi`, using a manually-entered `BaselineExpectedSales` per scheme (no trailing-period auto-baseline yet). |
 
 ### 12. Returns & Claims Management
 
@@ -300,13 +303,17 @@ Introduce the concept of stock per location. Every warehouse (fixed or vehicle)
 of each item. Stock is never edited directly — all changes happen through movement transactions
 (load, sale, return, damage, adjustment). The current balance is always the running sum.
 This is the single most important architectural decision for the whole system.
+For now, the shop is treated as a business destination, not a tracked stock location in this
+system. That means warehouse-to-vehicle and vehicle-to-warehouse movements update tracked stock
+balances, while vehicle-to-shop handover reduces vehicle stock and updates sale/order fulfillment
+state without creating a shop stock balance.
 **Gate**: Stock balance for any item at any location can be queried. Every change is a traceable transaction.
 
 ### 03 — Ride Lifecycle
 A ride is a session that turns a vehicle into a temporary warehouse. It has a state machine:
 Draft → Open → Active → Closed. A vehicle can only be on one active ride at a time.
 Two ride types exist: Delivery (pre-orders) and Sale (van sales). The ride tracks who is driving,
-which route, which vehicle, and when it started and ended.
+which route, which vehicle, and when it started and ended. For now, one ride uses one route.
 **Gate**: A ride can be created, opened, and closed. A vehicle's stock ledger is created when a ride opens.
 
 ### 04 — Loading Event
@@ -321,14 +328,18 @@ On a delivery ride, the driver fulfills pre-confirmed orders. Each order becomes
 The driver marks each as delivered, partially delivered, or failed. Partially delivered orders
 generate a credit note for the undelivered quantity. Customer confirmation (signature or OTP)
 is required to mark a delivery complete. Stock movements are created per delivery event.
+Vehicle-to-shop handover reduces vehicle stock only; the shop does not yet exist as a tracked stock
+location in the ledger.
 **Gate**: A delivery ride can execute all orders on its route and produce a delivery report.
 
 ### 06 — Sale Ride Execution
-On a sale ride, the driver visits customers and creates invoices on the spot. No pre-orders exist.
-The driver selects items, quantities, and prices (within approved discount limits), and the invoice
-is generated immediately. Payment is collected (cash or credit) at the point of sale.
-The vehicle's stock ledger decreases with each sale. The driver cannot sell more than what is loaded.
-**Gate**: A sale ride can generate invoices in the field. Stock on vehicle decreases with each sale.
+On a sale ride, the sales agent visits customers and creates sales in the field. Every sale creates
+an order. If items are handed over immediately, the order is fulfilled immediately and the sale is
+completed immediately. If items are not handed over immediately, the order stays pending for later
+fulfillment. Payment is collected based on the final sale flow. The vehicle's stock ledger decreases
+only for quantities actually handed over from the vehicle. The shop is not yet a tracked stock
+location in the ledger.
+**Gate**: A sale ride can create sales in the field, create linked orders, and reduce vehicle stock for immediate handover quantities.
 
 ### 07 — Ride Close & Reconciliation
 When a ride ends, the system performs a full reconciliation. The equation must balance: