# Vendor KYC & Verification Flow

This document details the trust mechanics, document screening process, and the administrator back-office approval workflows that govern the verification of **Vendors** on the Bharat Seva platform.

---

## 1. Trust & Verification Architecture

To protect customers, vendors must go through a structured identity verification process. This includes verifying Government IDs, Business Registrations, and Staff Documents.

The backend dynamically computes a trust status using a **KYC Summary Service** that categorizes vendors into **Tiers 1 to 4** based on approved documentation.

### A. Document Status Lifecycle
All documents uploaded by vendors begin in a `pending` state and move to `approved` or `rejected` after manual admin inspection.

```mermaid
stateDiagram-v2
    [*] --> Pending : Document Uploaded
    Pending --> Approved : Admin Approves ID/Reg
    Pending --> Rejected : Admin Rejects Document
    Rejected --> Pending : Vendor Re-uploads File via API
    Approved --> [*]
```

### B. Dynamic Trust Tier Calculation
Tiers determine the level of access and public visibility the vendor receives. The tier is computed in `VendorBusinessService::getVendorKycSummary`:
* **Tier 1** (Default): 0 or 1 approved document.
* **Tier 2**: 2 approved documents.
* **Tier 3**: 3 approved documents.
* **Tier 4** (Fully Verified): 4 or more approved documents.
* **KYC Status**: Set to `verified` ONLY if there is at least one uploaded document and **every single document** has status `approved`. Otherwise, status remains `pending`.

---

## 2. Vendor API: KYC Status Tracking

### A. Get KYC Summary
Retrieves the overall verification status and trust tier.
* **Endpoint**: `GET /api/v1/vendor/kyc-summary/{businessId}`
* **Authentication**: Protected (`jwt.auth`), Vendor role check.
* **Response (200 OK)**:
  ```json
  {
    "business_id": 23,
    "business_name": "Patel Electrical Services",
    "kyc_status": "pending",
    "tier": "Tier 2"
  }
  ```

### B. Get Complete KYC Document Data
List all uploaded documents, ID numbers, and individual approval statuses.
* **Endpoint**: `GET /api/v1/vendor/kyc/{businessId}`
* **Authentication**: Protected (`jwt.auth`), Vendor role check.
* **Response (200 OK)**:
  ```json
  {
    "status": true,
    "message": "KYC data fetched successfully",
    "data": {
      "government_ids": [
        { "id": 1, "id_type": "Aadhaar Card", "id_number": "1234-5678-9012", "verification_status": "approved" },
        { "id": 2, "id_type": "PAN Card", "id_number": "ABCDE1234F", "verification_status": "pending" }
      ],
      "business_registrations": [
        { "id": 1, "registration_type": "GSTIN", "registration_number": "27AAAAA1111A1Z1", "verification_status": "approved" }
      ],
      "bank_details": {
        "bank_name": "State Bank of India",
        "account_holder_name": "Patel Electrical Services",
        "verification_status": "pending"
      }
    }
  }
  ```

### C. Re-upload / Update Rejected Document
Allows a vendor to correct a rejected document by uploading a new file.
* **Endpoint**: `POST /api/v1/vendor/kyc/upload/{id}`
* **Authentication**: Protected (`jwt.auth`), Vendor role check.
* **Request Format**: `multipart/form-data`
* **Request Payload**:
  * `doc_type`: "government" or "business" or "staff_document"
  * `file`: `[new_document_file.pdf]`
* **Database Updates**: Replaces the document file path in the database and resets `verification_status` back to `pending`.
* **Response (200 OK)**:
  ```json
  {
    "status": true,
    "message": "Document updated successfully"
  }
  ```

---

## 3. Back-Office Admin Verification Flow

These routes are defined for administrators and volunteers in the system backend interface (`web.php`).

```mermaid
sequenceDiagram
    autonumber
    actor Admin as Admin / Volunteer
    participant API as Laravel Backend
    participant DB as MySQL Database

    Admin->>API: GET /vendor-verifications
    API->>DB: Fetch pending KYC requests
    API-->>Admin: HTML List of Pending Vendors
    
    Admin->>API: POST /verify-government-registration/{id} (status: approved)
    API->>DB: UPDATE vendor_government_ids SET verification_status = approved
    API-->>Admin: 200 OK / Redirect
    
    Admin->>API: POST /vendor-verifications/{id}/verify (final action)
    API->>DB: UPDATE vendor_verifications SET overall_status = verified
    API-->>Admin: Vendor Approved, QR Enabled
```

### A. List Pending Verifications
* **Endpoint**: `GET /vendor-verifications` (Route name: `vendor.verifications`)
* **Purpose**: Fetches a dashboard of vendors awaiting documents or field checks.

### B. Assign Volunteer for Site Checks
For physical validation of brick-and-mortar shops.
* **Endpoint**: `POST /assign-volunteer` (Route name: `assign.volunteer`)
* **Request Payload**:
  ```json
  {
    "vendor_id": 102,
    "volunteer_id": 4
  }
  ```
* **Database**: Inserts record into `vendor_volunteer_assignments`.

### C. Verify Government ID Document
* **Endpoint**: `POST /verify-government-registration/{id}` (Route name: `vendor.government.registration.verify`)
* **Request Payload**:
  ```json
  {
    "status": "approved" // or "rejected"
  }
  ```
* **Database**: Updates `vendor_government_ids.verification_status`.

### D. Verify Business Registration Document
* **Endpoint**: `POST /verify-registration/{id}` (Route name: `vendor.business.verify`)
* **Request Payload**:
  ```json
  {
    "status": "approved" // or "rejected"
  }
  ```
* **Database**: Updates `vendor_business_registrations.verification_status`.

### E. Approve Vendor Staff
* **Endpoint**: `POST /staff/{id}/approve` (Route name: `staff.approve`)
* **Request Payload**:
  ```json
  {
    "status": "approved" // or "rejected"
  }
  ```
* **Database**: Updates `business_staff_details.status`.

---

## 4. Codebase Reference Map

* **Routes**:
  * [api.php (lines 90-92)](file:///d:/WHIZZACT/bharatseva_backend/routes/api.php#L90-L92) — Vendor endpoints for KYC querying and uploading.
  * [web.php (lines 168-178)](file:///d:/WHIZZACT/bharatseva_backend/routes/web.php#L168-L178) — Admin control panel verification endpoints.
* **Controllers**:
  * [VendorBusinessController](file:///d:/WHIZZACT/bharatseva_backend/app/Http/Controllers/Api/VendorBusiness/VendorBusinessController.php) — Serves KYC metadata APIs.
  * [AdminVendorVerificationController](file:///d:/WHIZZACT/bharatseva_backend/app/Http/Controllers/Master/AdminVendorVerificationController.php) — Processes admin verification approvals and volunteer coordination.
* **Services**:
  * [VendorBusinessService](file:///d:/WHIZZACT/bharatseva_backend/app/Services/VendorBusiness/VendorBusinessService.php) — Handles file updates (`updateKycDocument`), parses summaries, and tracks the approved document count.
* **Models**:
  * [VendorGovernmentId](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorGovernmentId.php)
  * [VendorBusinessRegistration](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/VendorBusinessRegistration.php)
  * [BusinessStaffDetail](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/BusinessStaffDetail.php)
  * [BusinessStaffDocument](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/BusinessStaffDocument.php)
  * [VendorVolunteerAssignment](file:///d:/WHIZZACT/bharatseva_backend/app/Models/Master/VendorVolunteerAssignment.php)
