# Nimit Sevak & Receipt Service

## What is Nimit Sevak

Nimit Sevak is the volunteer registration system. Volunteers (sevaks) register with:
- Personal details (name, address, contact)
- Aadhar card number
- Seva preferences (list of seva types)
- Availability dates
- Vehicle availability

---

## NimitSevak Model (key fields)

```
NimitSevak
  ├── firstName, middleName, lastName
  ├── address fields (houseNo, societyName, locality, landmark, city, state, pincode, country)
  ├── aadharCardNo
  ├── mobileNo
  ├── occupation, age, gender
  ├── preferredLanguage         -- ENGLISH | GUJARATI | HINDI
  ├── pradeshId / pradeshName
  ├── mandalName / mandalPramukhName
  ├── referencePersonPhoneNo
  ├── selectedSevas (String[])  -- list of seva names
  ├── sevaSelections (JSON)     -- structured seva selection data
  ├── otherSevaDetails
  ├── sevaAvailableFrom / sevaAvailableTo
  ├── nightShiftAvailable
  ├── drivableVehicles (String[])
  ├── availableVehicles (String[])
  ├── vehicleAvailableFrom / vehicleAvailableTo
  ├── profilePhotoUrl / profilePhotoStoragePath
  ├── aadharCardImageUrl / aadharCardImageStoragePath
  ├── receiptNumber
  ├── receiptUrl / receiptStoragePath
  └── receiptGeneratedAt
```

---

## Nimit Sevak Receipt Flow

1. Volunteer submits form → `NimitSevak` record created.
2. Backend calls `nimitSevakReceiptApiService.js` which calls the `sdm-receipt` microservice.
3. The microservice generates a Gujarati-language PDF receipt.
4. PDF is uploaded to Firebase Storage.
5. `receiptUrl` and `receiptStoragePath` are stored back on the `NimitSevak` record.

---

## SDM Receipt Microservice (`sdm-receipt/`)

Standalone Python FastAPI microservice. Intentionally decoupled from `sdm-backend`.

### Stack
- Python 3.13 (3.14 not supported — `uharfbuzz` and `Pillow` build failures)
- FastAPI
- reportlab / weasyprint for PDF generation
- Firebase Admin SDK for storage upload

### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/health` | Health check |
| `POST` | `/receipts/nimit-sevak` | Generate + upload Nimit Sevak receipt |

### Setup

```bash
# Create venv with Python 3.13
py -3.13 -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# Copy env file
copy .env.example .env

# Start service
uvicorn app.main:app --reload
```

### Font Requirement

The receipt uses a Gujarati-capable TTF font. Supported options:
- System-installed font: Nirmala UI or Shruti (Windows)
- Custom font: place TTF file in `assets/fonts/`

### Firebase Credentials

Service uses Firebase service-account JSON directly from disk (not env var injection):
1. Auto-discovered local JSON in `app/services/`
2. `GOOGLE_APPLICATION_CREDENTIALS` env var path

### Request Payload (POST /receipts/nimit-sevak)

```json
{
  "applicant_name": "Gujarati name",
  "address": "address string",
  "aadhar_card_no": "123412341234",
  "mobile_no": "9876543210",
  "occupation": "seva",
  "age": "32",
  "gender": "પુરુષ",
  "pradesh": "Pradesh name",
  "mandal_name": "Mandal name",
  "reference_person_name": "Name",
  "reference_person_phone_no": "9898989898",
  "available_sevas": ["seva1", "seva2"],
  "other_seva_details": "...",
  "seva_available_from": "2026-10-10",
  "seva_available_to": "2026-10-20",
  "available_vehicles": ["car"],
  "drivable_vehicles": ["tractor", "car"],
  "vehicle_available_from": "2026-10-12",
  "vehicle_available_to": "2026-10-18",
  "night_shift_available": true
}
```

---

## Phone Number Precheck (Nimit Sevak vs Registration)

Nimit Sevak phone precheck queries the `NimitSevak` table **only**.  
Registration phone precheck queries the `Registration` table **only**.

These two checks must remain **completely separate** — never cross-query between them.

---

## Haridham Receipt Integration

`haridhamReceiptFetchService.js` + `haridhamReceiptApiService.js` handle fetching an external Haridham receipt for a completed transaction. Fields stored on `Transaction`:
- `haridhamReceiptId`
- `haridhamReceiptUrl`
- `haridhamReceiptStoragePath`
- `haridhamReceiptUploadedAt`