District Master

The District Master is used to define and manage districts mapped to their respective states.
These districts are referenced across multiple modules such as City Master, Units, and Client configurations.

Module URL

• District Master Page
  /masters/district-master

1. District List Page

Purpose

Displays all created districts with filtering, searching, and action controls for managing records.

Page Elements

Table Columns

• S No
• State
• District
• Code
• Actions

Available Features

• Global search:
  • Search by District Name
  • Search by Code
• Filter by State dropdown
• Column-level filters for:
  • State
  • District
  • Code
• Checkbox selection for rows
• Edit and Delete actions for each record
• Table configuration option

2. Add District

Purpose

Allows users to create a new district and map it to a specific state.

Form Fields

• State

  • Dropdown
  • Option to select or create a state
  • Mandatory field

• District Name

  • Text input
  • Placeholder: Enter District Name
  • Mandatory field

• Code

  • Text input
  • Optional or system-defined (as per configuration)

Actions

• Save
  • Validates input
  • Saves the new district
• Reset
  • Clears all entered data

Validation Rules

• State selection is mandatory
• District Name cannot be empty
• Duplicate district names within the same state are not allowed

3. Edit District

Purpose

Allows modification of an existing district record.

Behavior

• Clicking the Edit icon opens the district in editable mode
• Existing values are pre-filled in the form

Editable Fields

• State
• District Name
• Code

Actions

• Save
  • Updates the district details
• Reset
  • Restores the original values

4. Delete District

Purpose

Allows removal of an existing district record.

Delete Flow

1. Click the Delete icon from the Actions column

2. A confirmation popup appears:

   Are you sure you want to delete this District?

3. User options:

   • Yes – Permanently deletes the district
   • Cancel – Aborts the action

Field Definitions, Usage, and Calculation Logic

This section provides a technical analysis of the District Master's data structure and its role in regional administration.

1. Field Definitions

2. Field Usage & System Impact

3. Business & Calculation Logic

The District Master facilitates regional groupings with following logic:

A. Automated Code Generation

The system implements a sequential numbering logic for district codes:

1. Lookup: On save, the system searches for the highest existing code matching the pattern DIST\d{4} for the current company.
2. Increment: It extracts the numeric suffix, increments it, and pads it with leading zeros.
3. Collision Handling: It performs up to 100 retry attempts with incremented numbers to ensure uniqueness in high-concurrency environments.

B. Bulk Import & Auto-Seeding

The /import endpoint features heavy automation:

• State Auto-Creation: If the State provided in the Excel sheet does not exist, the system automatically creates a new State record (defaulting country to INDIA).
• Atomic Upserts: It uses findOneAndUpdate with upsert: true for state lookups to prevent duplicate state creation during parallel record processing.
• Deduplication: Records matching the companyId, state, and description are updated; otherwise, new districts are created.

C. Relational Integrity

Districts are the primary link between States and Cities. While a district can be soft-deleted, it remains in the database to maintain referential integrity for legacy city records and historical reporting.

The District Master module interacts with the following API endpoints:

Base URL

export const DISTRICTMASTER_URL = '/api/districtMaster'

Endpoints

RTK Query Hooks

The following hooks are available for frontend integration:

• useCreateDistrictMasterMutation
• useGetAllDistrictMastersQuery
• useSearchDistrictMastersQuery
• useGetDistrictMasterByIdQuery
• useUpdateDistrictMasterMutation
• useDeleteDistrictMasterMutation
• useExportDistrictMastersMutation
• useImportDistrictMastersMutation

End of Documentation