# Karyakarta Data System

## Two Separate Karyakarta Concepts

There are **two distinct** karyakarta-related models. Do not confuse them:

| Model | Purpose |
|---|---|
| `Karyakarta` | Login hierarchy table — maps haridhamId to a Mandal and optionally to a User account |
| `KaryakartaDataTable` | Extended data table — stores detailed karyakarta personal/ID data (uploaded separately) |

---

## Karyakarta (Hierarchy Table)

```
Karyakarta
  ├── id
  ├── name
  ├── haridhamId           -- The Haridham code (unique, stored as "code" column in DB via @map)
  ├── phone
  ├── mandalId             -- Which mandal this karyakarta belongs to
  └── userId               -- Optional link to User login account
```

- Used for hierarchy lookup during registration (karyakarta lookup by code).
- `haridhamId` is unique and is the primary search key.
- When a karyakarta creates a login account, `userId` is set.

---

## KaryakartaDataTable (Extended Data)

```
KaryakartaDataTable
  ├── id
  ├── name
  ├── phone (unique)
  ├── haridhamId (unique, optional)
  ├── aadharCardNo, panCardNo
  ├── aadharCardUrl / aadharCardStoragePath
  ├── panCardUrl / panCardStoragePath
  ├── profilePhotoUrl / profilePhotoStoragePath
  ├── pradesh, pradeshId
  ├── mandal, district
  ├── detectedDistrict
  ├── latitude, longitude
  ├── createdAt, updatedAt
  └── pradeshRef           -- FK to Pradesh model
```

- Managed via `karyakartaDataController.js` + `karyakartaDataRoutes.js`.
- File uploads handled by `karyakartaDataUploadMiddleware.js`.
- Supports bulk import and individual record management.

---

## Form Lookup API

`GET /api/form/karyakarta/:code`

Returns karyakarta info by Haridham ID code. Used in the registration form to auto-fill mandal/pradesh from a known karyakarta code.

- Response is cached with `FORM_DETAIL_CACHE_TTL_MS` (default: 120,000 ms / 2 min).
- Cache is in-memory per process.

The Super Admin "Change Karyakarta" panel uses the same `Karyakarta` hierarchy table as the source of truth. It changes a registration's assigned karyakarta by validating the new karyakarta Haridham ID against `Karyakarta.haridhamId`, then syncing `Registration.karyakartaHaridhamId`, `Registration.mandalId`, `Registration.pradeshId`, and the linked `User` hierarchy fields.

---

## Migration Notes

- `migrate-karyakarta-phone-to-karyakarta-table.js` was a one-time migration to move phone numbers from a legacy location into the `Karyakarta` table's `phone` field.
- `seed-karyakarta-table.js` seeds the Karyakarta hierarchy from a source CSV.