make account service with grn

2026-08-15 15:43:01 +05:30
parent ee9fa40edf
commit ae6a87022d
25 changed files with 8298 additions and 24 deletions
@@ -11,8 +11,13 @@ namespace ERPCore.Controllers;
 public sealed class GrnsController : ApiControllerBase
 {
    private readonly IGrnService _grns;
+    private readonly IGrnPaymentService _payments;

-    public GrnsController(IGrnService grns) => _grns = grns;
+    public GrnsController(IGrnService grns, IGrnPaymentService payments)
+    {
+        _grns = grns;
+        _payments = payments;
+    }

    /// <summary>List GRNs, newest first.</summary>
    [HttpGet]
@@ -59,4 +64,23 @@ public sealed class GrnsController : ApiControllerBase
    public async Task<ActionResult<ReleaseLineResultDto>> Release(
        int grnId, int grnLineId, [FromBody] ReleaseLineRequest request, CancellationToken ct)
        => Ok(await _grns.ReleaseLineAsync(grnId, grnLineId, request.Action, ct));
+
+    /// <summary>Pay the vendor against this GRN's balance, in full or in installments; posts a real GL journal entry.</summary>
+    [HttpPost("{grnId:int}/payments")]
+    [ProducesResponseType(typeof(GrnPaymentDto), StatusCodes.Status201Created)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status409Conflict)]
+    public async Task<ActionResult<GrnPaymentDto>> Pay(int grnId, [FromBody] CreateGrnPaymentRequest request, CancellationToken ct)
+    {
+        var dto = await _payments.PayAsync(grnId, request, ct);
+        return Created($"/api/v1/grns/{grnId}/payments/{dto.GrnPaymentId}", dto);
+    }
+
+    /// <summary>Payment history for this GRN, newest first.</summary>
+    [HttpGet("{grnId:int}/payments")]
+    [ProducesResponseType(typeof(IReadOnlyList<GrnPaymentDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<ActionResult<IReadOnlyList<GrnPaymentDto>>> ListPayments(int grnId, CancellationToken ct)
+        => Ok(await _payments.ListAsync(grnId, ct));
 }
@@ -30,8 +30,18 @@ public class Grn
    public DateTime CreatedAt { get; set; }
    public DateTime? PostedAt { get; set; }

+    /// <summary>Journal number of the real GL journal entry posted for this GRN's receipt (set on confirm).</summary>
+    public string? GlJournalNo { get; set; }
+    public DateTime? GlPostedAt { get; set; }
+
+    /// <summary>Sum of vendor payments made against this GRN's total payable (<see cref="GrnLine.LineTotal"/>).</summary>
+    public decimal PaidAmount { get; set; }
+    /// <summary>Total payable minus <see cref="PaidAmount"/>; installments accrue against this until it reaches zero.</summary>
+    public decimal BalanceAmount { get; set; }
+
    /// <summary>PostgreSQL xmin-backed optimistic concurrency token.</summary>
    public uint RowVersion { get; set; }

    public ICollection<GrnLine> Lines { get; set; } = new List<GrnLine>();
+    public ICollection<GrnPayment> Payments { get; set; } = new List<GrnPayment>();
 }
@@ -0,0 +1,31 @@
+namespace ERPCore.Domain.Entities;
+
+/// <summary>
+/// A vendor payment made against a confirmed GRN's balance (installments allowed —
+/// see GrnPaymentService.PayAsync). Posts its own real GL journal entry (Debit GRN
+/// Clearing / Credit the selected bank-or-cash account) before being recorded here.
+/// </summary>
+public class GrnPayment
+{
+    public int GrnPaymentId { get; set; }
+
+    public int GrnId { get; set; }
+    public Grn? Grn { get; set; }
+
+    public decimal Amount { get; set; }
+    public DateTime PaymentDate { get; set; }
+
+    /// <summary>GL's numeric id for the bank/cash account the payment was made from.</summary>
+    public long GlBankAccountId { get; set; }
+    /// <summary>Snapshot of the account's display name at payment time (GL account lists have no local FK).</summary>
+    public string BankAccountName { get; set; } = string.Empty;
+
+    public string? Reference { get; set; }
+
+    /// <summary>Journal number of the real GL journal entry this payment posted.</summary>
+    public string? GlJournalNo { get; set; }
+
+    public int CreatedBy { get; set; }
+    public User? Creator { get; set; }
+    public DateTime CreatedAt { get; set; }
+}
@@ -16,23 +16,36 @@ public sealed record GrnLineDto(

 public sealed record GrnDto(
    int GrnId, string DocNo, int? PoId, int VendorId, int WarehouseId, GrnStatus Status,
-    int CreatedBy, DateTime CreatedAt, DateTime? PostedAt, IReadOnlyList<GrnLineDto> Lines);
+    int CreatedBy, DateTime CreatedAt, DateTime? PostedAt, string? GlJournalNo,
+    decimal PaidAmount, decimal BalanceAmount, IReadOnlyList<GrnLineDto> Lines);

 /// <summary>Row shape for <c>GET /grns</c> — line count instead of the lines themselves.</summary>
 public sealed record GrnSummaryDto(
    int GrnId, string DocNo, int? PoId, int VendorId, int WarehouseId, GrnStatus Status,
-    int CreatedBy, DateTime CreatedAt, DateTime? PostedAt, int LineCount);
+    int CreatedBy, DateTime CreatedAt, DateTime? PostedAt, int LineCount,
+    decimal PaidAmount, decimal BalanceAmount);

 public sealed record CreatedLayerDto(
    int LayerId, int ItemId, int WarehouseId, int? BatchId,
    decimal QtyReceived, decimal QtyRemaining, decimal UnitCost, DateTime ReceiptDate);

 public sealed record GrnConfirmResultDto(
-    int GrnId, GrnStatus Status, DateTime PostedAt,
+    int GrnId, GrnStatus Status, DateTime PostedAt, string GlJournalNo, decimal BalanceAmount,
    IReadOnlyList<CreatedLayerDto> CreatedLayers, IReadOnlyList<int> LedgerRefs, PurchaseOrderStatus? PoStatus);

 public sealed record ReleaseLineResultDto(int GrnLineId, HoldStatus HoldStatus);

+public sealed record GrnPaymentDto(
+    int GrnPaymentId, int GrnId, decimal Amount, DateTime PaymentDate,
+    long GlBankAccountId, string BankAccountName, string? Reference, string? GlJournalNo, DateTime CreatedAt);
+
+public sealed class CreateGrnPaymentRequest
+{
+    [Range(0.01, double.MaxValue)] public decimal Amount { get; set; }
+    [Required] public long GlBankAccountId { get; set; }
+    [StringLength(100)] public string? Reference { get; set; }
+}
+
 // Requests ----------------------------------------------------------------------

 public sealed class BatchInput
@@ -16,6 +16,9 @@ public sealed class GrnConfiguration : IEntityTypeConfiguration<Grn>

        builder.Property(g => g.Status).HasConversion<string>().HasMaxLength(20).IsRequired();
        builder.Property(g => g.CreatedAt).IsRequired();
+        builder.Property(g => g.GlJournalNo).HasMaxLength(30);
+        builder.Property(g => g.PaidAmount).HasPrecision(18, 4);
+        builder.Property(g => g.BalanceAmount).HasPrecision(18, 4);
        builder.Property(g => g.RowVersion).IsRowVersion();

        builder.HasOne(g => g.PurchaseOrder).WithMany().HasForeignKey(g => g.PoId).OnDelete(DeleteBehavior.Restrict);
@@ -28,6 +31,27 @@ public sealed class GrnConfiguration : IEntityTypeConfiguration<Grn>
    }
 }

+public sealed class GrnPaymentConfiguration : IEntityTypeConfiguration<GrnPayment>
+{
+    public void Configure(EntityTypeBuilder<GrnPayment> builder)
+    {
+        builder.ToTable("grn_payments");
+        builder.HasKey(p => p.GrnPaymentId);
+
+        builder.Property(p => p.Amount).HasPrecision(18, 4);
+        builder.Property(p => p.PaymentDate).IsRequired();
+        builder.Property(p => p.BankAccountName).IsRequired().HasMaxLength(200);
+        builder.Property(p => p.Reference).HasMaxLength(100);
+        builder.Property(p => p.GlJournalNo).HasMaxLength(30);
+        builder.Property(p => p.CreatedAt).IsRequired();
+
+        builder.HasOne(p => p.Grn).WithMany(g => g.Payments).HasForeignKey(p => p.GrnId).OnDelete(DeleteBehavior.Restrict);
+        builder.HasOne(p => p.Creator).WithMany().HasForeignKey(p => p.CreatedBy).OnDelete(DeleteBehavior.Restrict);
+
+        builder.HasIndex(p => p.GrnId);
+    }
+}
+
 public sealed class GrnLineConfiguration : IEntityTypeConfiguration<GrnLine>
 {
    public void Configure(EntityTypeBuilder<GrnLine> builder)
@@ -63,6 +63,7 @@ public class ErpDbContext : DbContext
    // --- Goods Receipt (docs/10 Part C.3) ---
    public DbSet<Grn> Grns => Set<Grn>();
    public DbSet<GrnLine> GrnLines => Set<GrnLine>();
+    public DbSet<GrnPayment> GrnPayments => Set<GrnPayment>();

    // --- Batch / Serial (docs/10 Part C.4) ---
    public DbSet<Batch> Batches => Set<Batch>();
@@ -0,0 +1,113 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Npgsql.EntityFrameworkCore.PostgreSQL.Metadata;
+
+#nullable disable
+
+namespace ERPCore.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddGrnGlPostingAndPayments : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<decimal>(
+                name: "BalanceAmount",
+                table: "grns",
+                type: "numeric(18,4)",
+                precision: 18,
+                scale: 4,
+                nullable: false,
+                defaultValue: 0m);
+
+            migrationBuilder.AddColumn<string>(
+                name: "GlJournalNo",
+                table: "grns",
+                type: "character varying(30)",
+                maxLength: 30,
+                nullable: true);
+
+            migrationBuilder.AddColumn<DateTime>(
+                name: "GlPostedAt",
+                table: "grns",
+                type: "timestamp with time zone",
+                nullable: true);
+
+            migrationBuilder.AddColumn<decimal>(
+                name: "PaidAmount",
+                table: "grns",
+                type: "numeric(18,4)",
+                precision: 18,
+                scale: 4,
+                nullable: false,
+                defaultValue: 0m);
+
+            migrationBuilder.CreateTable(
+                name: "grn_payments",
+                columns: table => new
+                {
+                    GrnPaymentId = table.Column<int>(type: "integer", nullable: false)
+                        .Annotation("Npgsql:ValueGenerationStrategy", NpgsqlValueGenerationStrategy.IdentityByDefaultColumn),
+                    GrnId = table.Column<int>(type: "integer", nullable: false),
+                    Amount = table.Column<decimal>(type: "numeric(18,4)", precision: 18, scale: 4, nullable: false),
+                    PaymentDate = table.Column<DateTime>(type: "timestamp with time zone", nullable: false),
+                    GlBankAccountId = table.Column<long>(type: "bigint", nullable: false),
+                    BankAccountName = table.Column<string>(type: "character varying(200)", maxLength: 200, nullable: false),
+                    Reference = table.Column<string>(type: "character varying(100)", maxLength: 100, nullable: true),
+                    GlJournalNo = table.Column<string>(type: "character varying(30)", maxLength: 30, nullable: true),
+                    CreatedBy = table.Column<int>(type: "integer", nullable: false),
+                    CreatedAt = table.Column<DateTime>(type: "timestamp with time zone", nullable: false)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_grn_payments", x => x.GrnPaymentId);
+                    table.ForeignKey(
+                        name: "FK_grn_payments_grns_GrnId",
+                        column: x => x.GrnId,
+                        principalTable: "grns",
+                        principalColumn: "GrnId",
+                        onDelete: ReferentialAction.Restrict);
+                    table.ForeignKey(
+                        name: "FK_grn_payments_users_CreatedBy",
+                        column: x => x.CreatedBy,
+                        principalTable: "users",
+                        principalColumn: "UserId",
+                        onDelete: ReferentialAction.Restrict);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_grn_payments_CreatedBy",
+                table: "grn_payments",
+                column: "CreatedBy");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_grn_payments_GrnId",
+                table: "grn_payments",
+                column: "GrnId");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "grn_payments");
+
+            migrationBuilder.DropColumn(
+                name: "BalanceAmount",
+                table: "grns");
+
+            migrationBuilder.DropColumn(
+                name: "GlJournalNo",
+                table: "grns");
+
+            migrationBuilder.DropColumn(
+                name: "GlPostedAt",
+                table: "grns");
+
+            migrationBuilder.DropColumn(
+                name: "PaidAmount",
+                table: "grns");
+        }
+    }
+}
@@ -1406,6 +1406,10 @@ namespace ERPCore.Migrations

                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<int>("GrnId"));

+                    b.Property<decimal>("BalanceAmount")
+                        .HasPrecision(18, 4)
+                        .HasColumnType("numeric(18,4)");
+
                    b.Property<DateTime>("CreatedAt")
                        .HasColumnType("timestamp with time zone");

@@ -1417,6 +1421,17 @@ namespace ERPCore.Migrations
                        .HasMaxLength(30)
                        .HasColumnType("character varying(30)");

+                    b.Property<string>("GlJournalNo")
+                        .HasMaxLength(30)
+                        .HasColumnType("character varying(30)");
+
+                    b.Property<DateTime?>("GlPostedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<decimal>("PaidAmount")
+                        .HasPrecision(18, 4)
+                        .HasColumnType("numeric(18,4)");
+
                    b.Property<int?>("PoId")
                        .HasColumnType("integer");

@@ -1537,6 +1552,55 @@ namespace ERPCore.Migrations
                    b.ToTable("grn_lines", (string)null);
                });

+            modelBuilder.Entity("ERPCore.Domain.Entities.GrnPayment", b =>
+                {
+                    b.Property<int>("GrnPaymentId")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("integer");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<int>("GrnPaymentId"));
+
+                    b.Property<decimal>("Amount")
+                        .HasPrecision(18, 4)
+                        .HasColumnType("numeric(18,4)");
+
+                    b.Property<string>("BankAccountName")
+                        .IsRequired()
+                        .HasMaxLength(200)
+                        .HasColumnType("character varying(200)");
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<int>("CreatedBy")
+                        .HasColumnType("integer");
+
+                    b.Property<long>("GlBankAccountId")
+                        .HasColumnType("bigint");
+
+                    b.Property<string>("GlJournalNo")
+                        .HasMaxLength(30)
+                        .HasColumnType("character varying(30)");
+
+                    b.Property<int>("GrnId")
+                        .HasColumnType("integer");
+
+                    b.Property<DateTime>("PaymentDate")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<string>("Reference")
+                        .HasMaxLength(100)
+                        .HasColumnType("character varying(100)");
+
+                    b.HasKey("GrnPaymentId");
+
+                    b.HasIndex("CreatedBy");
+
+                    b.HasIndex("GrnId");
+
+                    b.ToTable("grn_payments", (string)null);
+                });
+
            modelBuilder.Entity("ERPCore.Domain.Entities.GrnLineWarrantyNumber", b =>
                {
                    b.Property<int>("GrnLineWarrantyNumberId")
@@ -3999,6 +4063,87 @@ namespace ERPCore.Migrations
                    b.ToTable("sales_return_lines", (string)null);
                });

+            modelBuilder.Entity("ERPCore.Domain.Entities.SalesReturn", b =>
+                {
+                    b.Property<int>("ReturnId")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("integer");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<int>("ReturnId"));
+
+                    b.Property<DateTime>("CreatedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<int>("CreatedBy")
+                        .HasColumnType("integer");
+
+                    b.Property<int>("CustomerId")
+                        .HasColumnType("integer");
+
+                    b.Property<string>("DocNo")
+                        .IsRequired()
+                        .HasMaxLength(30)
+                        .HasColumnType("character varying(30)");
+
+                    b.Property<int>("ReasonCodeId")
+                        .HasColumnType("integer");
+
+                    b.Property<string>("Status")
+                        .IsRequired()
+                        .HasMaxLength(20)
+                        .HasColumnType("character varying(20)");
+
+                    b.Property<int>("WarehouseId")
+                        .HasColumnType("integer");
+
+                    b.HasKey("ReturnId");
+
+                    b.HasIndex("CreatedBy");
+
+                    b.HasIndex("CustomerId");
+
+                    b.HasIndex("DocNo")
+                        .IsUnique();
+
+                    b.HasIndex("ReasonCodeId");
+
+                    b.HasIndex("WarehouseId");
+
+                    b.ToTable("sales_returns", (string)null);
+                });
+
+            modelBuilder.Entity("ERPCore.Domain.Entities.SalesReturnLine", b =>
+                {
+                    b.Property<int>("ReturnLineId")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("integer");
+
+                    NpgsqlPropertyBuilderExtensions.UseIdentityByDefaultColumn(b.Property<int>("ReturnLineId"));
+
+                    b.Property<int>("ItemId")
+                        .HasColumnType("integer");
+
+                    b.Property<decimal>("Qty")
+                        .HasPrecision(18, 4)
+                        .HasColumnType("numeric(18,4)");
+
+                    b.Property<int>("ReturnId")
+                        .HasColumnType("integer");
+
+                    b.Property<int?>("SalesInvoiceLineId")
+                        .HasColumnType("integer");
+
+                    b.HasKey("ReturnLineId");
+
+                    b.HasIndex("ItemId");
+
+                    b.HasIndex("ReturnId");
+
+                    b.HasIndex("SalesInvoiceLineId");
+
+                    b.ToTable("sales_return_lines", (string)null);
+                });
+
            modelBuilder.Entity("ERPCore.Domain.Entities.SalesSlip", b =>
                {
                    b.Property<int>("SalesSlipId")
@@ -5831,6 +5976,25 @@ namespace ERPCore.Migrations
                    b.Navigation("PoLine");
                });

+            modelBuilder.Entity("ERPCore.Domain.Entities.GrnPayment", b =>
+                {
+                    b.HasOne("ERPCore.Domain.Entities.User", "Creator")
+                        .WithMany()
+                        .HasForeignKey("CreatedBy")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    b.HasOne("ERPCore.Domain.Entities.Grn", "Grn")
+                        .WithMany("Payments")
+                        .HasForeignKey("GrnId")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    b.Navigation("Creator");
+
+                    b.Navigation("Grn");
+                });
+
            modelBuilder.Entity("ERPCore.Domain.Entities.GrnLineWarrantyNumber", b =>
                {
                    b.HasOne("ERPCore.Domain.Entities.GrnLine", "GrnLine")
@@ -6528,6 +6692,67 @@ namespace ERPCore.Migrations
                    b.Navigation("SalesInvoiceLine");
                });

+            modelBuilder.Entity("ERPCore.Domain.Entities.SalesReturn", b =>
+                {
+                    b.HasOne("ERPCore.Domain.Entities.User", "Creator")
+                        .WithMany()
+                        .HasForeignKey("CreatedBy")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    b.HasOne("ERPCore.Domain.Entities.Customer", "Customer")
+                        .WithMany()
+                        .HasForeignKey("CustomerId")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    b.HasOne("ERPCore.Domain.Entities.ReasonCode", "ReasonCode")
+                        .WithMany()
+                        .HasForeignKey("ReasonCodeId")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    b.HasOne("ERPCore.Domain.Entities.Warehouse", "Warehouse")
+                        .WithMany()
+                        .HasForeignKey("WarehouseId")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    b.Navigation("Creator");
+
+                    b.Navigation("Customer");
+
+                    b.Navigation("ReasonCode");
+
+                    b.Navigation("Warehouse");
+                });
+
+            modelBuilder.Entity("ERPCore.Domain.Entities.SalesReturnLine", b =>
+                {
+                    b.HasOne("ERPCore.Domain.Entities.Item", "Item")
+                        .WithMany()
+                        .HasForeignKey("ItemId")
+                        .OnDelete(DeleteBehavior.Restrict)
+                        .IsRequired();
+
+                    b.HasOne("ERPCore.Domain.Entities.SalesReturn", "Return")
+                        .WithMany("Lines")
+                        .HasForeignKey("ReturnId")
+                        .OnDelete(DeleteBehavior.Cascade)
+                        .IsRequired();
+
+                    b.HasOne("ERPCore.Domain.Entities.SalesInvoiceLine", "SalesInvoiceLine")
+                        .WithMany()
+                        .HasForeignKey("SalesInvoiceLineId")
+                        .OnDelete(DeleteBehavior.Restrict);
+
+                    b.Navigation("Item");
+
+                    b.Navigation("Return");
+
+                    b.Navigation("SalesInvoiceLine");
+                });
+
            modelBuilder.Entity("ERPCore.Domain.Entities.SalesSlip", b =>
                {
                    b.HasOne("ERPCore.Domain.Entities.User", "CashierUser")
@@ -7025,6 +7250,13 @@ namespace ERPCore.Migrations
            modelBuilder.Entity("ERPCore.Domain.Entities.Grn", b =>
                {
                    b.Navigation("Lines");
+
+                    b.Navigation("Payments");
+                });
+
+            modelBuilder.Entity("ERPCore.Domain.Entities.GrnLine", b =>
+                {
+                    b.Navigation("WarrantyNumbers");
                });

            modelBuilder.Entity("ERPCore.Domain.Entities.GrnLine", b =>
@@ -7111,6 +7343,11 @@ namespace ERPCore.Migrations
                    b.Navigation("Lines");
                });

+            modelBuilder.Entity("ERPCore.Domain.Entities.SalesReturn", b =>
+                {
+                    b.Navigation("Lines");
+                });
+
            modelBuilder.Entity("ERPCore.Domain.Entities.SalesSlip", b =>
                {
                    b.Navigation("Lines");
@@ -103,6 +103,7 @@ builder.Services.AddScoped<IItemMeasure, ItemMeasure>();
 builder.Services.AddScoped<IFifoCostingService, FifoCostingService>();
 builder.Services.AddScoped<IStockService, StockService>();
 builder.Services.AddScoped<IGrnService, GrnService>();
+builder.Services.AddScoped<IGrnPaymentService, GrnPaymentService>();

 // Sales (Phase 1)
 builder.Services.AddScoped<ISalesPricingService, SalesPricingService>();
@@ -1,11 +1,21 @@
+using System.Text;
+using System.Text.Json;
 using ERPCore.Infra.Gl;
+using ERPCore.Services.Gl;
 using ERPCore.Services.Interfaces;
+using ERPCore.System.Errors;

 namespace ERPCore.Services;

 /// <inheritdoc cref="IGeneralLedgerService"/>
 public sealed class GeneralLedgerService : IGeneralLedgerService
 {
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        PropertyNameCaseInsensitive = true
+    };
+
    private readonly IGeneralLedgerClient _client;

    public GeneralLedgerService(IGeneralLedgerClient client) => _client = client;
@@ -13,4 +23,89 @@ public sealed class GeneralLedgerService : IGeneralLedgerService
    public Task<GeneralLedgerResponse> ForwardAsync(
        HttpMethod method, string path, string? queryString, string? contentType, Stream? body, CancellationToken ct)
        => _client.SendAsync(method, path, queryString, contentType, body, ct);
+
+    public async Task<GlJournalEntryResult> PostJournalEntryAsync(GlJournalEntryRequest request, CancellationToken ct)
+    {
+        using var body = new MemoryStream(JsonSerializer.SerializeToUtf8Bytes(request, JsonOptions));
+        var response = await _client.SendAsync(HttpMethod.Post, "journal-entries", null, "application/json", body, ct);
+        var data = ParseSuccess<GlJournalEntryData>(response);
+        return new GlJournalEntryResult(data.JournalNo, data.IsPosted);
+    }
+
+    public async Task<GlPeriod> GetPeriodByDateAsync(DateOnly date, CancellationToken ct)
+    {
+        var response = await _client.SendAsync(
+            HttpMethod.Get, "fiscal-years/periods/by-date", $"?date={date:yyyy-MM-dd}", null, null, ct);
+        var data = ParseSuccess<GlPeriodData>(response);
+        return new GlPeriod(data.PeriodId, data.FiscalYearId);
+    }
+
+    public async Task<IReadOnlyList<GlBankAccount>> ListBankAccountsAsync(CancellationToken ct)
+    {
+        var response = await _client.SendAsync(HttpMethod.Get, "bank-accounts", "?accountType=Both", null, null, ct);
+        var data = ParseSuccess<List<GlBankAccountData>>(response);
+        return data.Select(a => new GlBankAccount(
+            a.AccountType, a.AccountId, a.AccountName, a.BankName,
+            a.CashAccountTypeName, a.AccountNumber, a.GlAccountId, a.GlAccountCode, a.CurrencyCode)).ToList();
+    }
+
+    /// <summary>
+    /// Parses GL's <c>ApiResponse</c> envelope (case-insensitively, since GL's success bodies are
+    /// camelCase and its error bodies are PascalCase — docs/12 §4) and throws
+    /// <see cref="DomainException"/> if the call didn't succeed.
+    /// </summary>
+    private static T ParseSuccess<T>(GeneralLedgerResponse response)
+    {
+        GlEnvelope<T>? envelope;
+        try
+        {
+            envelope = JsonSerializer.Deserialize<GlEnvelope<T>>(response.Body, JsonOptions);
+        }
+        catch (JsonException)
+        {
+            envelope = null;
+        }
+
+        if (response.StatusCode is < 200 or >= 300 || envelope is null || !envelope.Success || envelope.Data is null)
+        {
+            var message = envelope?.Message ?? "The General Ledger service rejected the request.";
+            var status = response.StatusCode is >= 400 and < 500 ? response.StatusCode : 502;
+            throw new DomainException(ErrorCodes.GlRequestFailed, message, status);
+        }
+
+        return envelope.Data;
+    }
+
+    private sealed class GlEnvelope<T>
+    {
+        public int StatusCode { get; set; }
+        public bool Success { get; set; }
+        public string? Message { get; set; }
+        public T? Data { get; set; }
+    }
+
+    private sealed class GlJournalEntryData
+    {
+        public string JournalNo { get; set; } = string.Empty;
+        public bool IsPosted { get; set; }
+    }
+
+    private sealed class GlPeriodData
+    {
+        public int PeriodId { get; set; }
+        public int FiscalYearId { get; set; }
+    }
+
+    private sealed class GlBankAccountData
+    {
+        public string AccountType { get; set; } = string.Empty;
+        public long AccountId { get; set; }
+        public string AccountName { get; set; } = string.Empty;
+        public string? BankName { get; set; }
+        public string? CashAccountTypeName { get; set; }
+        public string? AccountNumber { get; set; }
+        public long GlAccountId { get; set; }
+        public string GlAccountCode { get; set; } = string.Empty;
+        public string CurrencyCode { get; set; } = string.Empty;
+    }
 }
@@ -0,0 +1,27 @@
+namespace ERPCore.Services.Gl;
+
+/// <summary>
+/// Purpose-built request/response shapes for the specific GL endpoints ERPCore's GRN
+/// module calls directly (journal-entries, period lookup, bank-account listing) — not
+/// a full model of GL's contract (docs/12-GENERAL-LEDGER-INTEGRATION.md §5/§6: typed
+/// DTOs are added only for the flow that actually needs them).
+/// </summary>
+public sealed record GlJournalEntryLineRequest(string AccountCode, decimal DebitAmount, decimal CreditAmount, string? Memo = null);
+
+public sealed class GlJournalEntryRequest
+{
+    public int PeriodId { get; set; }
+    public DateOnly EntryDate { get; set; }
+    public string? SourceModule { get; set; }
+    public string? Reference { get; set; }
+    public string? Narration { get; set; }
+    public List<GlJournalEntryLineRequest> Lines { get; set; } = new();
+}
+
+public sealed record GlJournalEntryResult(string JournalNo, bool IsPosted);
+
+public sealed record GlPeriod(int PeriodId, int FiscalYearId);
+
+public sealed record GlBankAccount(
+    string AccountType, long AccountId, string AccountName, string? BankName,
+    string? CashAccountTypeName, string? AccountNumber, long GlAccountId, string GlAccountCode, string CurrencyCode);
@@ -0,0 +1,120 @@
+using ERPCore.Domain.Entities;
+using ERPCore.Domain.Enums;
+using ERPCore.Dtos.Grn;
+using ERPCore.Infra.Auth;
+using ERPCore.Infra.UoW;
+using ERPCore.Repositories.Interfaces;
+using ERPCore.Services.Gl;
+using ERPCore.Services.Interfaces;
+using ERPCore.System.Errors;
+using Microsoft.EntityFrameworkCore;
+
+namespace ERPCore.Services;
+
+/// <summary>
+/// Vendor payments against a confirmed GRN. Multiple installments are allowed until
+/// <see cref="Grn.BalanceAmount"/> reaches zero. Each payment posts its own real GL
+/// journal entry (Debit GRN Clearing / Credit the selected bank-or-cash account) before
+/// being recorded, using the same call-GL-before-commit pattern as <see cref="GrnService.ConfirmAsync"/>
+/// so a rejected/unreachable GL post rolls back the whole payment atomically.
+/// </summary>
+public sealed class GrnPaymentService : IGrnPaymentService
+{
+    private readonly IRepository<Grn> _grns;
+    private readonly IRepository<GrnPayment> _payments;
+    private readonly IGeneralLedgerService _gl;
+    private readonly ICurrentUser _currentUser;
+    private readonly IUnitOfWork _uow;
+    private readonly string _glClearingAccountCode;
+
+    public GrnPaymentService(
+        IRepository<Grn> grns, IRepository<GrnPayment> payments, IGeneralLedgerService gl,
+        ICurrentUser currentUser, IUnitOfWork uow, IConfiguration configuration)
+    {
+        _grns = grns;
+        _payments = payments;
+        _gl = gl;
+        _currentUser = currentUser;
+        _uow = uow;
+        _glClearingAccountCode = configuration["Grn:GlClearingAccountCode"] ?? string.Empty;
+    }
+
+    public async Task<GrnPaymentDto> PayAsync(int grnId, CreateGrnPaymentRequest request, CancellationToken ct = default)
+    {
+        var grn = await _grns.Query().FirstOrDefaultAsync(g => g.GrnId == grnId, ct)
+            ?? throw new NotFoundException($"GRN {grnId} was not found.");
+
+        if (grn.Status == GrnStatus.Draft)
+            throw new DomainException(ErrorCodes.GrnNotPayable, $"GRN {grnId} must be confirmed before it can be paid.", 409);
+        if (request.Amount > grn.BalanceAmount)
+            throw new DomainException(ErrorCodes.GrnPaymentExceedsBalance,
+                $"Payment amount {request.Amount} exceeds the remaining balance {grn.BalanceAmount}.", 400);
+
+        var accounts = await _gl.ListBankAccountsAsync(ct);
+        var account = accounts.FirstOrDefault(a => a.AccountId == request.GlBankAccountId)
+            ?? throw new DomainException(ErrorCodes.GrnBankAccountNotFound, $"Bank/cash account {request.GlBankAccountId} was not found.", 404);
+
+        var actor = _currentUser.AuditUserId;
+        var now = DateTime.UtcNow;
+
+        var payment = await _uow.ExecuteInTransactionAsync(async token =>
+        {
+            // Same atomicity approach as GrnService.ConfirmAsync: post to GL first, inside
+            // this transaction, before anything is committed — a GL rejection/timeout rolls
+            // the whole payment back with no partial local state.
+            var period = await _gl.GetPeriodByDateAsync(DateOnly.FromDateTime(now), token);
+            var posted = await _gl.PostJournalEntryAsync(new GlJournalEntryRequest
+            {
+                PeriodId = period.PeriodId,
+                EntryDate = DateOnly.FromDateTime(now),
+                SourceModule = "GRN_PAYMENT",
+                Reference = grn.DocNo,
+                Narration = $"Payment against GRN {grn.DocNo}",
+                Lines =
+                [
+                    new GlJournalEntryLineRequest(_glClearingAccountCode, request.Amount, 0m, $"Payment against GRN {grn.DocNo}"),
+                    new GlJournalEntryLineRequest(account.GlAccountCode, 0m, request.Amount, $"Payment against GRN {grn.DocNo}")
+                ]
+            }, token);
+
+            var entity = new GrnPayment
+            {
+                GrnId = grn.GrnId,
+                Amount = request.Amount,
+                PaymentDate = now,
+                GlBankAccountId = account.AccountId,
+                BankAccountName = account.AccountName,
+                Reference = request.Reference,
+                GlJournalNo = posted.JournalNo,
+                CreatedBy = actor,
+                CreatedAt = now
+            };
+            await _payments.AddAsync(entity, token);
+
+            grn.PaidAmount += request.Amount;
+            grn.BalanceAmount -= request.Amount;
+
+            return entity;
+        }, ct);
+
+        return Map(payment);
+    }
+
+    public async Task<IReadOnlyList<GrnPaymentDto>> ListAsync(int grnId, CancellationToken ct = default)
+    {
+        if (!await _grns.Query().AnyAsync(g => g.GrnId == grnId, ct))
+            throw new NotFoundException($"GRN {grnId} was not found.");
+
+        return await _payments.Query().AsNoTracking()
+            .Where(p => p.GrnId == grnId)
+            .OrderByDescending(p => p.GrnPaymentId)
+            .Select(p => new GrnPaymentDto(
+                p.GrnPaymentId, p.GrnId, p.Amount, p.PaymentDate,
+                p.GlBankAccountId, p.BankAccountName, p.Reference, p.GlJournalNo, p.CreatedAt))
+            .ToListAsync(ct);
+    }
+
+    private static GrnPaymentDto Map(GrnPayment p) => new(
+        p.GrnPaymentId, p.GrnId, p.Amount, p.PaymentDate,
+        p.GlBankAccountId, p.BankAccountName, p.Reference, p.GlJournalNo, p.CreatedAt);
+}
@@ -6,6 +6,7 @@ using ERPCore.Dtos.Grn;
 using ERPCore.Infra.Auth;
 using ERPCore.Infra.UoW;
 using ERPCore.Repositories.Interfaces;
+using ERPCore.Services.Gl;
 using ERPCore.Services.Interfaces;
 using ERPCore.System.Errors;
 using Microsoft.EntityFrameworkCore;
@@ -38,13 +39,18 @@ public sealed class GrnService : IGrnService
    private readonly INumberSequenceService _numbers;
    private readonly ICurrentUser _currentUser;
    private readonly IUnitOfWork _uow;
+    private readonly IGeneralLedgerService _gl;
+    private readonly string _glInventoryAccountCode;
+    private readonly string _glVatRecoverableAccountCode;
+    private readonly string _glClearingAccountCode;

    public GrnService(
        IRepository<Grn> grns, IRepository<PurchaseOrder> pos, IRepository<PoLine> poLines,
        IRepository<Item> items, IRepository<Warehouse> warehouses,
        IRepository<Bin> bins, IRepository<Vendor> vendors, IRepository<Batch> batches,
        IRepository<StockLayer> layers, IRepository<StockLedger> ledger,
-        IFifoCostingService fifo, INumberSequenceService numbers, ICurrentUser currentUser, IUnitOfWork uow)
+        IFifoCostingService fifo, INumberSequenceService numbers, ICurrentUser currentUser, IUnitOfWork uow,
+        IGeneralLedgerService gl, IConfiguration configuration)
    {
        _grns = grns;
        _pos = pos;
@@ -60,6 +66,10 @@ public sealed class GrnService : IGrnService
        _numbers = numbers;
        _currentUser = currentUser;
        _uow = uow;
+        _gl = gl;
+        _glInventoryAccountCode = configuration["Grn:GlInventoryAccountCode"] ?? string.Empty;
+        _glVatRecoverableAccountCode = configuration["Grn:GlVatRecoverableAccountCode"] ?? string.Empty;
+        _glClearingAccountCode = configuration["Grn:GlClearingAccountCode"] ?? string.Empty;
    }

    public async Task<PagedResponse<GrnSummaryDto>> ListAsync(
@@ -82,7 +92,7 @@ public sealed class GrnService : IGrnService
            .Skip(query.Skip).Take(query.PageSize)
            .Select(g => new GrnSummaryDto(
                g.GrnId, g.DocNo, g.PoId, g.VendorId, g.WarehouseId, g.Status,
-                g.CreatedBy, g.CreatedAt, g.PostedAt, g.Lines.Count))
+                g.CreatedBy, g.CreatedAt, g.PostedAt, g.Lines.Count, g.PaidAmount, g.BalanceAmount))
            .ToListAsync(ct);

        return PagedResponse<GrnSummaryDto>.Create(rows, query.Page, query.PageSize, total);
@@ -260,15 +270,47 @@ public sealed class GrnService : IGrnService
                }
            }

+            // Post the real GL journal entry for this receipt before committing — if GL
+            // rejects it or is unreachable, the exception propagates out of this callback
+            // and the whole transaction (FIFO layers, stock ledger, PO accrual) rolls back
+            // with it, so inventory and the ledger never diverge (user-approved "fails
+            // atomically" behavior; residual risk if GL posts but the local commit still
+            // fails afterward is accepted for this phase, see the integration plan).
+            var period = await _gl.GetPeriodByDateAsync(DateOnly.FromDateTime(now), token);
+            var glLines = new List<GlJournalEntryLineRequest>();
+            decimal totalPayable = 0m;
+            foreach (var line in grn.Lines.OrderBy(l => l.GrnLineId))
+            {
+                glLines.Add(new GlJournalEntryLineRequest(_glInventoryAccountCode, line.ReceivedValue, 0m, $"GRN {grn.DocNo} line {line.GrnLineId}"));
+                if (line.VatAmount > 0)
+                    glLines.Add(new GlJournalEntryLineRequest(_glVatRecoverableAccountCode, line.VatAmount, 0m, $"GRN {grn.DocNo} line {line.GrnLineId} VAT"));
+                totalPayable += line.LineTotal;
+            }
+            glLines.Add(new GlJournalEntryLineRequest(_glClearingAccountCode, 0m, totalPayable, $"GRN {grn.DocNo} received"));
+
+            var posted = await _gl.PostJournalEntryAsync(new GlJournalEntryRequest
+            {
+                PeriodId = period.PeriodId,
+                EntryDate = DateOnly.FromDateTime(now),
+                SourceModule = "GRN",
+                Reference = grn.DocNo,
+                Narration = $"Goods received - GRN {grn.DocNo}",
+                Lines = glLines
+            }, token);
+
            grn.Status = GrnStatus.Confirmed;
            grn.PostedAt = now;
+            grn.GlJournalNo = posted.JournalNo;
+            grn.GlPostedAt = now;
+            grn.PaidAmount = 0m;
+            grn.BalanceAmount = totalPayable;

            await UpdatePoStatusAsync(grn.PoId, token);
            return 0;
        }, ct);

        return new GrnConfirmResultDto(
-            grn.GrnId, grn.Status, now,
+            grn.GrnId, grn.Status, now, grn.GlJournalNo ?? string.Empty, grn.BalanceAmount,
            createdLayers.Select(ToCreatedLayer).ToList(),
            ledgerRefs.Select(l => l.LedgerId).ToList(),
            await GetPoStatusAsync(grn.PoId, ct));
@@ -395,7 +437,7 @@ public sealed class GrnService : IGrnService
            .Select(l => l.LedgerId).ToListAsync(ct);

        return new GrnConfirmResultDto(
-            grn.GrnId, grn.Status, grn.PostedAt ?? grn.CreatedAt,
+            grn.GrnId, grn.Status, grn.PostedAt ?? grn.CreatedAt, grn.GlJournalNo ?? string.Empty, grn.BalanceAmount,
            layers.Select(ToCreatedLayer).ToList(), ledgerRefs, await GetPoStatusAsync(grn.PoId, ct));
    }

@@ -404,6 +446,7 @@ public sealed class GrnService : IGrnService

    private static GrnDto Map(Grn g) => new(
        g.GrnId, g.DocNo, g.PoId, g.VendorId, g.WarehouseId, g.Status, g.CreatedBy, g.CreatedAt, g.PostedAt,
+        g.GlJournalNo, g.PaidAmount, g.BalanceAmount,
        g.Lines.OrderBy(l => l.GrnLineId).Select(l => new GrnLineDto(
            l.GrnLineId, l.PoLineId, l.ItemId, l.BinId, l.Qty, l.UnitCost, l.PoUnitPrice,
            l.DiscountPct, l.NetUnitCost, l.VatPct, l.VatAmount, l.ReceivedValue, l.LineTotal,
@@ -1,16 +1,27 @@
 using ERPCore.Infra.Gl;
+using ERPCore.Services.Gl;

 namespace ERPCore.Services.Interfaces;

 /// <summary>
 /// Single entry point into the external General Ledger service — the one function
 /// used both by <see cref="ERPCore.Controllers.GeneralLedgerController"/> (frontend
-/// requests, forwarded verbatim) and, once wired, other ERPCore services that need to
-/// post directly to GL (e.g. GRN confirm, adjustments — docs/12-GENERAL-LEDGER-INTEGRATION.md).
-/// No business logic lives here yet; this pass only connects the transport.
+/// requests, forwarded verbatim) and by other ERPCore services that post directly to
+/// GL (docs/12-GENERAL-LEDGER-INTEGRATION.md §5/§6). <see cref="ForwardAsync"/> stays a
+/// byte-for-byte passthrough; the three typed methods below are the first internal
+/// callers (GRN receipt + payment posting) and model only what those flows need.
 /// </summary>
 public interface IGeneralLedgerService
 {
    Task<GeneralLedgerResponse> ForwardAsync(
        HttpMethod method, string path, string? queryString, string? contentType, Stream? body, CancellationToken ct);
+
+    /// <summary>Creates and posts a balanced journal entry. Throws <see cref="ERPCore.System.Errors.DomainException"/> on rejection/unreachability.</summary>
+    Task<GlJournalEntryResult> PostJournalEntryAsync(GlJournalEntryRequest request, CancellationToken ct);
+
+    /// <summary>Resolves the accounting period covering <paramref name="date"/>.</summary>
+    Task<GlPeriod> GetPeriodByDateAsync(DateOnly date, CancellationToken ct);
+
+    /// <summary>Lists GL's cash and bank accounts (default: both types).</summary>
+    Task<IReadOnlyList<GlBankAccount>> ListBankAccountsAsync(CancellationToken ct);
 }
@@ -0,0 +1,10 @@
+using ERPCore.Dtos.Grn;
+
+namespace ERPCore.Services.Interfaces;
+
+/// <summary>Vendor payments against a confirmed GRN's balance (installments allowed).</summary>
+public interface IGrnPaymentService
+{
+    Task<GrnPaymentDto> PayAsync(int grnId, CreateGrnPaymentRequest request, CancellationToken ct = default);
+    Task<IReadOnlyList<GrnPaymentDto>> ListAsync(int grnId, CancellationToken ct = default);
+}
@@ -70,4 +70,11 @@ public static class ErrorCodes

    // General Ledger service proxy (GeneralLedgerController → external GL service, docs/12)
    public const string GlServiceUnavailable = "GL_SERVICE_UNAVAILABLE";
+    // General Ledger typed internal calls (GRN receipt/payment posting, docs/12 §5's deferred work)
+    public const string GlRequestFailed = "GL_REQUEST_FAILED";
+
+    // GRN payments
+    public const string GrnNotPayable = "GRN_NOT_PAYABLE";
+    public const string GrnPaymentExceedsBalance = "GRN_PAYMENT_EXCEEDS_BALANCE";
+    public const string GrnBankAccountNotFound = "GRN_BANK_ACCOUNT_NOT_FOUND";
 }
@@ -26,5 +26,10 @@
    "BaseUrl": "https://localhost:7024/api/v1/",
    "ApiKey": "1A5FE0E389C029B1FBCD2A94650CEBF0656083BF06FF48E5E11987040ABA262D"
  },
+  "Grn": {
+    "GlInventoryAccountCode": "1100",
+    "GlVatRecoverableAccountCode": "1200",
+    "GlClearingAccountCode": "2000"
+  },
  "AllowedHosts": "*"
 }