Loan / Advance Transaction

Navigation Path

Loan → Loan/Advance

URL

loan/loan-or-advance-transaction

Description

The Loan / Advance Transaction page is used to create, edit, view, and delete employee loan or advance records.
All operations (Add, Edit, Delete, View) are handled within a single page.

Employee Search Section

Used to search and filter employees before creating a loan/advance entry.

Fields

• Code – Employee Code
• Name – Employee Name
• Unit – Select or create a unit
• Department – Select department

Actions

• Search Employee – Fetch employee details based on search criteria
• Clear – Reset search inputs

Loan / Advance Entry Form

Used to add or update loan/advance details for the selected employee.

Fields

• Employee Code – Select employee
• Employee Name – Auto-filled
• Department – Auto-filled
• Unit – Select or create a unit
• Head – Select or create loan/advance head
• Allotment / Order No – Select order number
• Dated – Select date
• Effective Date – Select effective date
• Loan Type – Select loan type
• Remarks – Enter remarks

Actions

• Save – Create or update loan/advance transaction
• Reset – Clear form fields

Loan / Advance List Table

Displays all existing loan and advance records.

Table Columns

• S No
• Loan/Adv. Code
• Employee Code
• Employee Name
• Loan/Adv Type
• Actions

Table Features

• Column-wise search/filter
• Search by employee code
• Pagination support

Row Actions

• Edit – Loads the selected record into the form for updating
• Delete – Removes the selected record after confirmation

Delete Confirmation

When deleting a record, a confirmation alert is shown to prevent accidental deletion.

Notes

• This module uses only one URL for all operations.
• Add, Edit, View, and Delete are handled on the same page.
• Employee details are auto-populated after selection.

API Endpoints

The Loan or Advance Master module interacts with the following API endpoints:

Base URL

export const LOANORADVANCE_URL = '/api/loanMaster'

Endpoints

RTK Query Hooks

The following hooks are available for frontend integration:

• useGetAllLoansQuery
• useGetLoanByIdQuery
• useCreateLoanMutation
• useUpdateLoanMutation
• useDeleteLoanMutation
• useSearchAndExportLoansQuery
• useImportLoanReportMutation
• useGetLoansBySearchQuery
• useImportLoansFromExportedSheetMutation
• useGetLoansOfLeftEmployeesMutation

Field Definitions, Usage, and Calculation Logic

The Loan / Advance module manages the lifecycle of employee debt, from application to full recovery through monthly payroll deductions.

1. Field Definitions

2. Field Usage & Business Rules

A. Employee Status Validation

• The system prevents loan creation if the employee's leftStatus is 'Y'.
• Active loans of "Left" employees can be tracked via the specialized Left Employee Search endpoint.

B. Special Loan Constraints (Uniform & Trainee)

• Singleton Rule: An employee can only have one UNIFORM and one TRAINEE loan active in their entire history (not soft-deleted).
• Master Synchronization: Saving a UNIFORM or TRAINEE loan automatically updates the corresponding flags (uniformLoanDeducted, traineeLoanDeducted) in the Employee Master.

C. Status Lifecycle

1. PENDING: Initial entry. No deductions occur.
2. ACTIVE: Eligible for deduction during the next monthly salary process.
3. COMPLETED: Automatically set when balanceAmount reaches zero.
4. CANCELLED: Manual override to stop recovery permanently.

3. Calculation Logic

A. Monthly Deduction Formula

During the Salary Auto Process, the logic for each ACTIVE loan is:

• New Balance: BalanceAmount = BalanceAmount - InstallmentAmount.
• New Remaining Inst.: RemainingInst = RemainingInst - 1.
• If New Balance <= 0, the loan status is updated to COMPLETED.

B. Reversion Logic (Salary Deletion)

If a processed salary is deleted or recalculated:

• Restoration: BalanceAmount = BalanceAmount + PreviouslyDeductedAmount.
• Inst. Correction: RemainingInst = RemainingInst + 1.
• Status is reverted from COMPLETED back to ACTIVE if the balance becomes positive.

C. Installment Auto-Calculation

By default, the installmentAmount is calculated as:

• InstallmentAmount = LoanAmount / numberOfInstallments.
• The system allows manual overrides of the installmentAmount during entry without forcing the division result.

End of Technical Documentation