Special Loan

Navigation Path

Loan → Special Loan

URL:
/loan/special-loan-master

Description

The Special Loan page is used to create, view, edit, and delete special loan configurations for employees based on Unit, Designation, and Loan Head.
This page contains both Add Form and List View in a single screen.

Add Special Loan

Purpose

To define a special loan with installment details, eligibility, and status.

Form Fields

Field Name	Description
Unit	Select or create a unit
Designation	Select designation
Head	Select or create a loan head
Order Number	Reference order number
Allotment Date	Loan allotment date
Loan Type	Select loan type
Loan Amount	Total loan amount
Number of Installments	Total number of installments
Installment Amount	Amount per installment
Date	Auto-filled current date
Effective Date	Date from which loan is effective
Status	Loan status (e.g., PENDING)
Is Active	Enable/Disable loan
Remarks	Additional remarks

Actions

Save – Saves the special loan record
Reset – Clears all form fields
Close – Closes the add form and returns to list view

Special Loan List

Purpose

To view and manage all special loan records.

Search & Filters

Filter	Description
Unit	Filter loans by unit
Search by Loan Code	Search using loan code

Table Columns

Column	Description
S No	Serial number
Loan Code	Auto-generated loan code
Unit	Unit name
Designation	Designation name
Head Name	Loan head
Actions	Edit / Delete

🔹 Row Actions

Edit
- Opens the selected loan in the form
- Allows updating all editable fields
Delete
- Deletes the selected loan
- Confirmation alert is shown before deletion

Validations & Notes

Unit selection is mandatory before selecting loan head
Loan amount and installment values must be numeric
Status controls whether the loan is active or not
Delete action is irreversible

API Endpoints

The Special Loan Master module interacts with the following API endpoints:

Base URL

export const SPECIALLOAN_URL = '/api/specialLoanMaster'

Endpoints

Endpoint	Method	Description	Parameters/Body
`\$\{SPECIALLOAN_URL\}`	POST	Create a new special loan	Body: `data`
`\$\{SPECIALLOAN_URL\}`	GET	Get all special loans with pagination	Query: `page`, `limit`
`\$\{SPECIALLOAN_URL\}/:functionId`	GET	Get special loan by ID	Path: `functionId`
`\$\{SPECIALLOAN_URL\}/:functionId`	PATCH	Update an existing special loan	Path: `functionId`, Body: `body`
`\$\{SPECIALLOAN_URL\}/delete/:functionId`	PATCH	Delete a special loan (soft delete)	Path: `functionId`
`\$\{SPECIALLOAN_URL\}/search/functions`	POST	Search special loans with filters	Body: `data` (search criteria)
`\$\{SPECIALLOAN_URL\}/import`	POST	Import special loans from Excel	Body: `data` (file)
`\$\{SPECIALLOAN_URL\}/export/functions`	POST	Search and export special loans to Excel	Body: `data` (export criteria), Returns: Excel file (blob)
`\$\{SPECIALLOAN_URL\}/bulk-update`	POST	Bulk update special loans	Body: `data` (array of updates)

RTK Query Hooks

The following hooks are available for frontend integration:

useCreateSpecialLoanMutation
useGetAllSpecialLoansQuery
useGetSpecialLoanByIdQuery
useUpdateSpecialLoanMutation
useDeleteSpecialLoanMutation
useSearchSpecialLoanMutation
useImportSpecialLoansMutation
useSearchAndExportSpecialFunctionsMutation
useBulkUpdateSpecialLoansMutation

Summary

Single-page module (Add + List)
Supports Create, View, Edit, Delete
Searchable and filterable loan records
Role-based operational loan configuration

Field Definitions, Usage, and Calculation Logic

The Special Loan module functions as a Configuration Template system. Rather than creating individual employee records manually, it defines rules to automatically grant loans to entire groups based on their Unit and Designation.

1. Field Definitions

Field Name	Technical Name	Category	Description
Template Code	`loanCode`	Identity	Unique identifier for the special loan rule.
Loan Type	`loanType`	Category	Template category: `TRAINEE` or `UNIFORM`.
Loan Amount	`loanAmount`	Financial	The principal amount granted to each eligible employee.
Installment Amt	`installmentAmount`	Financial	The monthly recovery amount per employee.
Designation	`designationId`	Eligibility	The target employee group for this rule.
Unit	`unitId`	Scope	The branch/unit where this rule applies.
Effective Date	`effectiveDate`	Timing	The cutoff date for employee eligibility.

2. Field Usage & Business Rules

A. The Auto-Assignment Hook

When a new Special Loan is saved, the system executes a Post-Save Hook (assignSpecialLoanToExistingEmployees).
It scans the target Unit and Designation for employees joined after the effectiveDate.
For each match, a standardized Individual Loan (LoanMaster) is automatically created in PENDING status.

B. Unit Dependency

Special Loans only activate if the target Unit has the corresponding functional flag enabled:
- loanType: UNIFORM requires unit.Uniform = true.
- loanType: TRAINEE requires unit.Trainee = true.

C. Unique Constraint

To prevent configuration conflicts, the system enforces a Unique Constraint on the designationId + headId combination (where isDeleted is false). Each designation can only have one active template per loan head.

3. Calculation Logic

A. Employee Eligibility Window

The system identifies employees for auto-assignment using the following condition:

Employee.Unit == SpecialLoan.Unit AND
Employee.Designation == SpecialLoan.Designation AND
Employee.JoiningDate >= SpecialLoan.EffectiveDate (or same month/year).

B. Automated Loan Code Generation

For each individual loan created by this template, the system generates a unique record using the following logic:

Formula: LOAN{empCode}{timestamp}{type}{index}.
This ensures that every auto-generated loan is uniquely traceable back to the employee and the type of grant.

C. Lifecycle Sync

Deleting or updating a Special Loan rule does not retrospectively affect individual loans already created; it only affects future employee assignments or bulk updates.

End of Technical Documentation

Loan Installment Pay Voucher