feat: add cheque books and received cheques management

- Implemented ChequeBooksPage for viewing and filtering cheque books.
- Added NewReceivedChequePage for recording received cheques.
- Created ReceivedChequesPage for listing and managing received cheques.
- Introduced API endpoints for bank accounts, cheque books, and received cheques.
- Defined types for payments including bank accounts, cheque books, and received cheques.

Distribution/Features/ChequeBook/ChequeBookController.cs

@@ -0,0 +1,55 @@
+using Distribution.Models;
+using Microsoft.AspNetCore.Mvc;
+
+namespace Distribution.Features.ChequeBook;
+
+[ApiController]
+[Route("api")]
+public class ChequeBookController(ChequeBookService service) : ControllerBase
+{
+    [HttpGet("cheque-books")]
+    public async Task<IActionResult> List(
+        [FromQuery] Guid? bankAccountId,
+        [FromQuery] int? branchId,
+        [FromQuery] ChequeBookStatus? status,
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 50)
+        => Ok(await service.ListAsync(bankAccountId, branchId, status, page, pageSize));
+
+    [HttpGet("cheque-books/{chequeBookNo}")]
+    public async Task<IActionResult> Get(string chequeBookNo, [FromQuery] string? expand)
+    {
+        var expandPages = string.Equals(expand, "pages", StringComparison.OrdinalIgnoreCase);
+        var result = await service.GetAsync(chequeBookNo, expandPages);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost("cheque-books")]
+    public async Task<IActionResult> Create(CreateChequeBookRequest request, CancellationToken ct)
+    {
+        try { return Ok(await service.CreateAsync(request, ct)); }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPut("cheque-pages/{chequeNo}/issue")]
+    public async Task<IActionResult> Issue(string chequeNo, IssueChequePageRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.IssueAsync(chequeNo, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+
+    [HttpPut("cheque-pages/{chequeNo}/status")]
+    public async Task<IActionResult> UpdateStatus(string chequeNo, UpdateChequePageStatusRequest request, CancellationToken ct)
+    {
+        try
+        {
+            var result = await service.UpdatePageStatusAsync(chequeNo, request, ct);
+            return result is null ? NotFound() : Ok(result);
+        }
+        catch (InvalidOperationException ex) { return BadRequest(new { error = ex.Message }); }
+    }
+}

Distribution/Features/ChequeBook/ChequeBookDTOs.cs

@@ -0,0 +1,74 @@
+using Distribution.Models;
+
+namespace Distribution.Features.ChequeBook;
+
+public record ChequePageResponse(
+    string ChequeNo,
+    string ChequeBookNo,
+    ChequePageIssueStatus IssueStatus,
+    PayeeType? PayeeType,
+    int? PayeeId,
+    string? PayeeName,
+    DateTime? IssueDate,
+    decimal? Amount,
+    string? CurrencyCode,
+    int? VoucherId,
+    string? ReferenceNo,
+    string? Purpose,
+    bool? IsCrossCheque,
+    bool? IsAccountPayee,
+    bool? IsPostDated,
+    string? Notes,
+    string? PrintedBy,
+    DateTime? PrintedAt,
+    DateTime? ClearedDate,
+    bool? ClearedByBank,
+    string? CancelReason);
+
+public record ChequeBookResponse(
+    string ChequeBookNo,
+    int BranchId,
+    Guid BankAccountId,
+    string StartChequeNo,
+    string EndChequeNo,
+    int TotalLeaves,
+    DateTime ReceivedDate,
+    string? Description,
+    string? CreatedBy,
+    ChequeBookStatus Status,
+    List<ChequePageResponse> Pages);
+
+public record PagedResult<T>(IReadOnlyList<T> Items, int TotalCount, int? Page, int? PageSize);
+
+public record CreateChequeBookRequest(
+    int BranchId,
+    Guid BankAccountId,
+    string ChequeBookNo,
+    string StartChequeNo,
+    string EndChequeNo,
+    int TotalLeaves,
+    DateTime ReceivedDate,
+    string? Description,
+    string? CreatedBy);
+
+public record IssueChequePageRequest(
+    PayeeType PayeeType,
+    int? PayeeId,
+    string PayeeName,
+    DateTime IssueDate,
+    decimal Amount,
+    string? CurrencyCode,
+    int? VoucherId,
+    string? ReferenceNo,
+    string? Purpose,
+    bool? IsCrossCheque,
+    bool? IsAccountPayee,
+    bool? IsPostDated,
+    string? Notes,
+    string? PrintedBy);
+
+public record UpdateChequePageStatusRequest(
+    ChequePageStatusAction Action,
+    DateTime? ClearedDate,
+    string? CancelReason,
+    string? PerformedBy);

Distribution/Features/ChequeBook/ChequeBookRepository.cs

@@ -0,0 +1,46 @@
+using Distribution.Data;
+using Distribution.Models;
+using Microsoft.EntityFrameworkCore;
+
+namespace Distribution.Features.ChequeBook;
+
+public class ChequeBookRepository(AppDBContext context) : IChequeBookRepository
+{
+    public async Task<Models.ChequeBook?> GetByNoAsync(string chequeBookNo, bool includePages)
+    {
+        var query = context.ChequeBooks.AsQueryable();
+        if (includePages) query = query.Include(b => b.Pages);
+        return await query.FirstOrDefaultAsync(b => b.ChequeBookNo == chequeBookNo);
+    }
+
+    public async Task<(List<Models.ChequeBook> Items, int TotalCount)> ListAsync(
+        Guid? bankAccountId, int? branchId, ChequeBookStatus? status, int page, int pageSize)
+    {
+        var query = context.ChequeBooks.AsQueryable();
+        if (bankAccountId is not null) query = query.Where(b => b.FK_BankAccountId == bankAccountId);
+        if (branchId is not null) query = query.Where(b => b.BranchId == branchId);
+        if (status is not null) query = query.Where(b => b.Status == status);
+
+        var total = await query.CountAsync();
+        var items = await query
+            .OrderByDescending(b => b.CreatedAt)
+            .Skip((page - 1) * pageSize)
+            .Take(pageSize)
+            .ToListAsync();
+        return (items, total);
+    }
+
+    public async Task<bool> BookNoExistsAsync(string chequeBookNo) =>
+        await context.ChequeBooks.AnyAsync(b => b.ChequeBookNo == chequeBookNo);
+
+    public async Task AddAsync(Models.ChequeBook book) => await context.ChequeBooks.AddAsync(book);
+
+    public void Update(Models.ChequeBook book) => context.ChequeBooks.Update(book);
+
+    public async Task<Models.ChequePage?> GetPageByNoAsync(string chequeNo) =>
+        await context.ChequePages
+            .Include(p => p.ChequeBook)
+            .FirstOrDefaultAsync(p => p.ChequeNo == chequeNo);
+
+    public void UpdatePage(Models.ChequePage page) => context.ChequePages.Update(page);
+}

Distribution/Features/ChequeBook/ChequeBookService.cs

@@ -0,0 +1,176 @@
+using Distribution.Features.BankAccount;
+using Distribution.Infra.UoW;
+using Distribution.Models;
+
+namespace Distribution.Features.ChequeBook;
+
+public class ChequeBookService(
+    IChequeBookRepository repo,
+    IBankAccountRepository bankAccountRepo,
+    IUnitOfWork uow)
+{
+    private const string DefaultCurrency = "LKR";
+
+    private static ChequePageResponse ToPageResponse(Models.ChequePage p, string chequeBookNo) =>
+        new(p.ChequeNo, chequeBookNo, p.IssueStatus, p.PayeeType, p.PayeeId, p.PayeeName,
+            p.IssueDate, p.Amount, p.CurrencyCode, p.VoucherId, p.ReferenceNo, p.Purpose,
+            p.IsCrossCheque, p.IsAccountPayee, p.IsPostDated, p.Notes,
+            p.PrintedBy, p.PrintedAt, p.ClearedDate, p.ClearedByBank, p.CancelReason);
+
+    private static ChequeBookResponse ToBookResponse(Models.ChequeBook b, bool includePages) =>
+        new(b.ChequeBookNo, b.BranchId, b.FK_BankAccountId, b.StartChequeNo, b.EndChequeNo,
+            b.TotalLeaves, b.ReceivedDate, b.Description, b.CreatedBy, b.Status,
+            includePages ? b.Pages.OrderBy(p => p.ChequeNo).Select(p => ToPageResponse(p, b.ChequeBookNo)).ToList() : new());
+
+    public async Task<PagedResult<ChequeBookResponse>> ListAsync(
+        Guid? bankAccountId, int? branchId, ChequeBookStatus? status, int page, int pageSize)
+    {
+        if (page < 1) page = 1;
+        if (pageSize < 1 || pageSize > 200) pageSize = 50;
+
+        var (items, total) = await repo.ListAsync(bankAccountId, branchId, status, page, pageSize);
+        return new PagedResult<ChequeBookResponse>(
+            items.Select(b => ToBookResponse(b, includePages: false)).ToList(),
+            total, page, pageSize);
+    }
+
+    public async Task<ChequeBookResponse?> GetAsync(string chequeBookNo, bool expandPages)
+    {
+        var book = await repo.GetByNoAsync(chequeBookNo, includePages: expandPages);
+        return book is null ? null : ToBookResponse(book, includePages: expandPages);
+    }
+
+    public async Task<ChequeBookResponse> CreateAsync(CreateChequeBookRequest request, CancellationToken ct = default)
+    {
+        if (string.IsNullOrWhiteSpace(request.ChequeBookNo))
+            throw new InvalidOperationException("ChequeBookNo is required");
+        if (request.TotalLeaves <= 0)
+            throw new InvalidOperationException("TotalLeaves must be greater than zero");
+        if (!long.TryParse(request.StartChequeNo, out var start) ||
+            !long.TryParse(request.EndChequeNo, out var end))
+            throw new InvalidOperationException("StartChequeNo and EndChequeNo must be numeric");
+        if (end < start)
+            throw new InvalidOperationException("EndChequeNo must be greater than or equal to StartChequeNo");
+        if (end - start + 1 != request.TotalLeaves)
+            throw new InvalidOperationException("TotalLeaves does not match the Start/End cheque range");
+        if (await repo.BookNoExistsAsync(request.ChequeBookNo))
+            throw new InvalidOperationException("A cheque book with this number already exists");
+
+        var bankAccount = await bankAccountRepo.GetByIdAsync(request.BankAccountId);
+        if (bankAccount is null || bankAccount.AccountType != BankAccountType.Bank)
+            throw new InvalidOperationException("BankAccountId does not reference a valid bank account");
+
+        var book = new Models.ChequeBook
+        {
+            ChequeBookNo = request.ChequeBookNo,
+            BranchId = request.BranchId,
+            FK_BankAccountId = request.BankAccountId,
+            StartChequeNo = request.StartChequeNo,
+            EndChequeNo = request.EndChequeNo,
+            TotalLeaves = request.TotalLeaves,
+            ReceivedDate = request.ReceivedDate,
+            Description = request.Description,
+            CreatedBy = request.CreatedBy,
+            Status = ChequeBookStatus.Active
+        };
+
+        var width = request.StartChequeNo.Length;
+        for (var n = start; n <= end; n++)
+        {
+            book.Pages.Add(new Models.ChequePage
+            {
+                ChequeNo = n.ToString().PadLeft(width, '0'),
+                IssueStatus = ChequePageIssueStatus.Unused
+            });
+        }
+
+        await uow.BeginAsync(ct);
+        try
+        {
+            await repo.AddAsync(book);
+            await uow.CommitAsync(ct);
+        }
+        catch { await uow.RollbackAsync(ct); throw; }
+
+        return ToBookResponse(book, includePages: true);
+    }
+
+    public async Task<ChequePageResponse?> IssueAsync(string chequeNo, IssueChequePageRequest request, CancellationToken ct = default)
+    {
+        var page = await repo.GetPageByNoAsync(chequeNo);
+        if (page is null) return null;
+        if (page.IssueStatus != ChequePageIssueStatus.Unused)
+            throw new InvalidOperationException($"Cannot issue a cheque in status '{page.IssueStatus}'");
+        if (page.ChequeBook is null || page.ChequeBook.Status != ChequeBookStatus.Active)
+            throw new InvalidOperationException("The cheque book is not active");
+        if (request.Amount <= 0)
+            throw new InvalidOperationException("Amount must be greater than zero");
+        if (string.IsNullOrWhiteSpace(request.PayeeName))
+            throw new InvalidOperationException("PayeeName is required");
+
+        page.IssueStatus = ChequePageIssueStatus.Issued;
+        page.PayeeType = request.PayeeType;
+        page.PayeeId = request.PayeeId;
+        page.PayeeName = request.PayeeName;
+        page.IssueDate = request.IssueDate;
+        page.Amount = request.Amount;
+        page.CurrencyCode = string.IsNullOrWhiteSpace(request.CurrencyCode) ? DefaultCurrency : request.CurrencyCode;
+        page.VoucherId = request.VoucherId;
+        page.ReferenceNo = request.ReferenceNo;
+        page.Purpose = request.Purpose;
+        page.IsCrossCheque = request.IsCrossCheque;
+        page.IsAccountPayee = request.IsAccountPayee;
+        page.IsPostDated = request.IsPostDated;
+        page.Notes = request.Notes;
+        page.PrintedBy = request.PrintedBy;
+        page.PrintedAt = DateTime.Now;
+
+        repo.UpdatePage(page);
+        await uow.CommitAsync(ct);
+        return ToPageResponse(page, page.ChequeBook!.ChequeBookNo);
+    }
+
+    public async Task<ChequePageResponse?> UpdatePageStatusAsync(string chequeNo, UpdateChequePageStatusRequest request, CancellationToken ct = default)
+    {
+        var page = await repo.GetPageByNoAsync(chequeNo);
+        if (page is null) return null;
+
+        switch (request.Action)
+        {
+            case ChequePageStatusAction.Clear:
+                if (page.IssueStatus != ChequePageIssueStatus.Issued)
+                    throw new InvalidOperationException("Only issued cheques can be cleared");
+                if (request.ClearedDate is null)
+                    throw new InvalidOperationException("ClearedDate is required when clearing a cheque");
+                page.IssueStatus = ChequePageIssueStatus.Cleared;
+                page.ClearedDate = request.ClearedDate;
+                page.ClearedByBank = true;
+                break;
+
+            case ChequePageStatusAction.Bounce:
+                if (page.IssueStatus != ChequePageIssueStatus.Issued)
+                    throw new InvalidOperationException("Only issued cheques can be bounced");
+                page.IssueStatus = ChequePageIssueStatus.Bounced;
+                break;
+
+            case ChequePageStatusAction.Cancel:
+                if (page.IssueStatus != ChequePageIssueStatus.Issued)
+                    throw new InvalidOperationException("Only issued cheques can be cancelled");
+                if (string.IsNullOrWhiteSpace(request.CancelReason))
+                    throw new InvalidOperationException("CancelReason is required when cancelling a cheque");
+                page.IssueStatus = ChequePageIssueStatus.Cancelled;
+                page.CancelReason = request.CancelReason;
+                break;
+
+            case ChequePageStatusAction.Void:
+                if (page.IssueStatus != ChequePageIssueStatus.Unused)
+                    throw new InvalidOperationException("Only unused cheques can be voided");
+                page.IssueStatus = ChequePageIssueStatus.Void;
+                break;
+        }
+
+        repo.UpdatePage(page);
+        await uow.CommitAsync(ct);
+        return ToPageResponse(page, page.ChequeBook!.ChequeBookNo);
+    }
+}

Distribution/Features/ChequeBook/IChequeBookRepository.cs

@@ -0,0 +1,16 @@
+using Distribution.Models;
+
+namespace Distribution.Features.ChequeBook;
+
+public interface IChequeBookRepository
+{
+    Task<Models.ChequeBook?> GetByNoAsync(string chequeBookNo, bool includePages);
+    Task<(List<Models.ChequeBook> Items, int TotalCount)> ListAsync(
+        Guid? bankAccountId, int? branchId, ChequeBookStatus? status, int page, int pageSize);
+    Task<bool> BookNoExistsAsync(string chequeBookNo);
+    Task AddAsync(Models.ChequeBook book);
+    void Update(Models.ChequeBook book);
+
+    Task<Models.ChequePage?> GetPageByNoAsync(string chequeNo);
+    void UpdatePage(Models.ChequePage page);
+}