Implement store credit tracking and enforcement

Introduced StoreCreditMovement entity and migration to track store credit usage and settlements. Updated payment flow to enforce credit limits and record credit movements. Modified outstanding balance calculation to use credit movements. Enhanced frontend to display real-time credit info and prevent over-credit payments. Updated API types, seed data, and DI registrations accordingly.

Distribution/Features/Invoice/InvoiceDTOs.cs

@@ -10,6 +10,7 @@ public record PrintInvoiceRequest(Guid? PrintedByUserId = null);
 public record InvoiceResponse(
     Guid Id,
     Guid ShopPOId,
+    Guid StoreId,
     string StoreName,
     InvoiceStatus Status,
     PaymentStatus PaymentStatus,
@@ -19,6 +20,7 @@ public record InvoiceResponse(
     DateTime? FinalizedAt,
     Guid? FinalizedBy,
     decimal TotalAmount,
+    decimal PaidAmount,
     bool IsActive,
     DateTime CreatedAt);
 

Distribution/Features/Invoice/InvoiceRepository.cs

@@ -21,6 +21,7 @@ public class InvoiceRepository(AppDBContext context) : IInvoiceRepository
     public async Task<List<Models.Invoice>> GetAllAsync(Guid? agentId, Guid? routeId, Guid? shopId, InvoiceStatus? status, PaymentStatus? paymentStatus, int page, int pageSize) =>
         await context.Invoices
             .Include(i => i.ShopPO).ThenInclude(p => p.Store)
+            .Include(i => i.Payments.Where(p => p.IsActive))
             .Where(i => i.IsActive
                 && (agentId == null || i.ShopPO.RaisedById == agentId)
                 && (routeId == null || i.ShopPO.Store.FK_RouteId == routeId)

Distribution/Features/Invoice/InvoiceService.cs

@@ -12,11 +12,14 @@ public class InvoiceService(
 {
     private static InvoiceResponse ToResponse(Models.Invoice i) =>
         new(i.Id, i.FK_ShopPOId,
+            i.ShopPO?.FK_StoreId ?? Guid.Empty,
             i.ShopPO?.Store?.StoreName ?? string.Empty,
             i.Status, i.PaymentStatus, i.CreatedBy,
             i.PrintedAt, i.PrintedBy,
             i.FinalizedAt, i.FinalizedBy,
-            i.TotalAmount, i.IsActive, i.CreatedAt);
+            i.TotalAmount,
+            i.Payments?.Where(p => p.IsActive).Sum(p => p.Amount) ?? 0m,
+            i.IsActive, i.CreatedAt);
 
     public async Task<InvoiceResponse?> GetByIdAsync(Guid id)
     {

Distribution/Features/Payment/PaymentService.cs

@@ -1,6 +1,7 @@
 using Distribution.Features.BankAccount;
 using Distribution.Features.Invoice;
 using Distribution.Features.ReceivedCheque;
+using Distribution.Features.StoreCredit;
 using Distribution.Infra.Authorization;
 using Distribution.Infra.UoW;
 using Distribution.Models;
@@ -12,6 +13,7 @@ public class PaymentService(
     IInvoiceRepository invoiceRepo,
     IBankAccountRepository bankAccountRepo,
     IReceivedChequeRepository receivedChequeRepo,
+    IStoreCreditMovementRepository creditRepo,
     IUnitOfWork uow,
     ICurrentUserService currentUser)
 {
@@ -34,12 +36,16 @@ public class PaymentService(
     {
         var invoice = await invoiceRepo.GetByIdAsync(invoiceId);
         if (invoice is null || !invoice.IsActive) return null;
-        if (invoice.Status == InvoiceStatus.Finalized)
-            throw new InvalidOperationException("Cannot record a payment against a finalized invoice");
 
         if (request.Amount <= 0)
             throw new InvalidOperationException("Amount must be greater than zero");
 
+        var existingPaid = (await repo.GetByInvoiceIdAsync(invoiceId)).Sum(p => p.Amount);
+        var remaining = invoice.TotalAmount - existingPaid;
+        if (request.Amount > remaining)
+            throw new InvalidOperationException(
+                $"Amount exceeds the outstanding balance of {remaining:0.##}");
+
         if (request.Method == PaymentMethod.Cheque &&
             (string.IsNullOrWhiteSpace(request.ChequeNumber) || request.ChequeDate is null))
             throw new InvalidOperationException("ChequeNumber and ChequeDate are required when Method is Cheque");
@@ -47,6 +53,19 @@ public class PaymentService(
         if (request.Method == PaymentMethod.Cash && request.BankAccountId is null)
             throw new InvalidOperationException("BankAccountId is required when Method is Cash");
 
+        if (request.Method == PaymentMethod.Credit)
+        {
+            var store = invoice.ShopPO?.Store
+                ?? throw new InvalidOperationException("Invoice is missing the owning store; cannot record a credit payment");
+            var currentOutstanding = await creditRepo.GetOutstandingForStoreAsync(store.Id);
+            if (currentOutstanding + request.Amount > store.CreditLimit)
+            {
+                var available = store.CreditLimit - currentOutstanding;
+                throw new InvalidOperationException(
+                    $"Credit limit exceeded. Available credit: {available:0.##}");
+            }
+        }
+
         Models.BankAccount? bankAccount = null;
         if (request.BankAccountId is not null)
         {
@@ -107,9 +126,22 @@ public class PaymentService(
 
             await repo.AddAsync(payment);
 
-            var allPayments = await repo.GetByInvoiceIdAsync(invoiceId);
-            var total = allPayments.Sum(p => p.Amount) + request.Amount;
+            if (request.Method == PaymentMethod.Credit)
+            {
+                var movement = new StoreCreditMovement
+                {
+                    FK_StoreId = invoice.ShopPO!.Store!.Id,
+                    Direction = StoreCreditMovementDirection.Usage,
+                    Amount = request.Amount,
+                    FK_InvoiceId = invoice.Id,
+                    FK_PaymentId = payment.Id,
+                    OccurredAt = DateTime.Now,
+                    RecordedBy = recorderId
+                };
+                await creditRepo.AddAsync(movement);
+            }
 
+            var total = existingPaid + request.Amount;
             invoice.PaymentStatus = total == 0
                 ? PaymentStatus.Pending
                 : total < invoice.TotalAmount

Distribution/Features/Store/StoreService.cs

@@ -1,12 +1,13 @@
 using Distribution.Features.Scheme;
 using Distribution.Features.Stock;
+using Distribution.Features.StoreCredit;
 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, SchemeService schemeService, Route.IRouteRepository routeRepo)
+public class StoreService(IStoreRepository repo, IUnitOfWork uow, ICurrentUserService currentUser, IScopeAccessService scopeAccess, SchemeService schemeService, Route.IRouteRepository routeRepo, IStoreCreditMovementRepository creditRepo)
 {
     private const int GlobalScopeRoleLevel = 50;
     private const int CreditApproverRoleLevel = 20;
@@ -167,7 +168,8 @@ 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;
-        return new OutstandingBalanceResponse(store.Id, store.CreditLimit, store.OutstandingBalance, store.CreditLimit - store.OutstandingBalance);
+        var outstanding = await creditRepo.GetOutstandingForStoreAsync(id);
+        return new OutstandingBalanceResponse(store.Id, store.CreditLimit, outstanding, store.CreditLimit - outstanding);
     }
     public async Task<StoreResponse?> ClassifySegmentAsync(Guid id, ClassifySegmentRequest request, CancellationToken ct = default)
     {

Distribution/Features/StoreCredit/IStoreCreditMovementRepository.cs

@@ -0,0 +1,11 @@
+using Distribution.Models;
+
+namespace Distribution.Features.StoreCredit;
+
+public interface IStoreCreditMovementRepository
+{
+    Task<decimal> GetOutstandingForStoreAsync(Guid storeId);
+    Task<List<StoreCreditMovement>> GetByStoreAsync(Guid storeId, int page, int pageSize);
+    Task<int> GetCountByStoreAsync(Guid storeId);
+    Task AddAsync(StoreCreditMovement movement);
+}

Distribution/Features/StoreCredit/StoreCreditMovementRepository.cs

@@ -0,0 +1,36 @@
+using Distribution.Data;
+using Distribution.Models;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.StoreCredit;
+
+public class StoreCreditMovementRepository(AppDBContext context) : IStoreCreditMovementRepository
+{
+    public async Task<decimal> GetOutstandingForStoreAsync(Guid storeId)
+    {
+        var usage = await context.StoreCreditMovements
+            .Where(m => m.IsActive && m.FK_StoreId == storeId && m.Direction == StoreCreditMovementDirection.Usage)
+            .SumAsync(m => (decimal?)m.Amount) ?? 0m;
+
+        var settlements = await context.StoreCreditMovements
+            .Where(m => m.IsActive && m.FK_StoreId == storeId && m.Direction == StoreCreditMovementDirection.Settlement)
+            .SumAsync(m => (decimal?)m.Amount) ?? 0m;
+
+        return usage - settlements;
+    }
+
+    public async Task<List<StoreCreditMovement>> GetByStoreAsync(Guid storeId, int page, int pageSize) =>
+        await context.StoreCreditMovements
+            .Where(m => m.IsActive && m.FK_StoreId == storeId)
+            .OrderByDescending(m => m.OccurredAt)
+            .Skip((page - 1) * pageSize)
+            .Take(pageSize)
+            .ToListAsync();
+
+    public async Task<int> GetCountByStoreAsync(Guid storeId) =>
+        await context.StoreCreditMovements
+            .CountAsync(m => m.IsActive && m.FK_StoreId == storeId);
+
+    public async Task AddAsync(StoreCreditMovement movement) =>
+        await context.StoreCreditMovements.AddAsync(movement);
+}