# Functional Flow of the Entire Project

This document maps out the operational core of the Bharat Seva platform, detailing how customers discover vendors, how direct and broadcast bookings are managed, and how secondary features (like inventory, staff, and QR verifications) operate.

---

## 1. Directory Discovery & Geolocation Search

Before booking, customers search and discover nearby active vendors based on categories and distance.

### A. Location Master Data Queries
* `GET /states` — Fetch available states.
* `GET /districts` — Fetch districts.
* `GET /cities` — Fetch cities.
* `GET /zones` / `GET /zonal-areas` — Fetch specific operational sub-zones.

### B. Discover Nearby Vendors
* **Endpoint**: `POST /api/v2/customer/nearby`
* **Authentication**: None (Guest or Authenticated Customer)
* **Request Payload**:
  ```json
  {
    "category_id": 3,
    "latitude": 19.0835,
    "longitude": 72.9960
  }
  ```
* **Logic**: Computes Haversine distance from the given latitude/longitude to all verified active vendors in the database.
* **Response (200 OK)**: Returns list of matching vendors sorted by distance, with average review ratings, business name, and active status.

---

## 2. Transactional Booking Flows

Bharat Seva supports two modes of service fulfillment:
* **Flow A: Direct Booking** (Direct choice of vendor)
* **Flow B: Broadcast RFQ Booking** (Open bidding & quotation request)

---

### Flow A: Direct Booking (Selected Vendor)

Used when a customer navigates to a vendor's profile page and books them directly.

```mermaid
sequenceDiagram
    autonumber
    actor Customer
    actor Vendor
    participant Backend

    Customer->>Backend: POST /v2/customer/book (vendor_id=4, direct=true)
    Note over Backend: Lead created (status: pending, is_direct: true)
    Backend-->>Vendor: FCM Notification (New Direct Lead)
    
    Vendor->>Backend: POST /v2/vendor/leads/{leadId}/accept
    Note over Backend: Lead status: accepted. Generate start_otp
    Backend-->>Customer: FCM Notification (Accepted, start_otp sent)
    
    Note over Vendor: Vendor arrives at customer's house
    Vendor->>Backend: POST /v2/vendor/lead/start/{leadId} (otp=XXXX)
    Note over Backend: Validate OTP. Lead status: in_progress
    
    Note over Vendor: Vendor completes service
    Vendor->>Backend: POST /v2/vendor/lead/complete/{leadId}
    Note over Backend: Lead status: completed
    
    Customer->>Backend: POST /v2/customer/bookings/{leadId}/review (rating, comment)
```

---

### Flow B: Broadcast Booking (RFQ Flow)

Used when a customer needs quotes from multiple nearby vendors.

```mermaid
sequenceDiagram
    autonumber
    actor Customer
    actor Vendor A
    actor Vendor B
    participant Backend

    Customer->>Backend: POST /v2/customer/book (vendor_id=null, direct=false)
    Note over Backend: Lead created (status: pending, is_direct: false)
    Backend-->>Vendor A: FCM Broadcast Notification
    Backend-->>Vendor B: FCM Broadcast Notification

    Vendor A->>Backend: POST /v2/vendor/leads/{leadId}/accept
    Note over Backend: Record added in lead_vendors table. Lead status: pending
    
    Customer->>Backend: GET /v2/customer/bookings/{leadId}/accepted-vendors
    Backend-->>Customer: Lists interested vendors (including Vendor A)
    
    Customer->>Backend: POST /v2/customer/bookings/{leadId}/choose-vendor (vendor_id=Vendor A)
    Note over Backend: Lead status: accepted. Other bidders released
    Backend-->>Vendor A: FCM Notification (Assigned to Lead)

    Note over Vendor A: Vendor A inspects site
    Vendor A->>Backend: POST /v2/vendor/leads/{leadId}/quotation (price=650, schedule)
    Note over Backend: Lead status: quotation_pending
    Backend-->>Customer: Notification (Quotation submitted)

    Customer->>Backend: POST /v2/customer/bookings/{leadId}/quotation/respond (response=accept)
    Note over Backend: Lead status: accepted. Generate start_otp
    Backend-->>Vendor A: FCM Notification (Quote approved, start_otp sent)

    Note over Vendor A: Vendor starts work
    Vendor A->>Backend: POST /v2/vendor/lead/start/{leadId} (otp=XXXX)
    Note over Backend: Lead status: in_progress
    
    Vendor A->>Backend: POST /v2/vendor/lead/complete/{leadId}
    Note over Backend: Lead status: completed
```

---

## 3. Product Catalog & Inventory (Vendor)

Vendors can list products they offer for direct sale or service-associated parts.

* **Add Product**: `POST /api/v1/vendor/add/product-details`
  * Payload: `product_name`, `price`, `description`, `product_image` (file).
* **Bulk Import Catalog**: `POST /api/v1/vendor/products/bulk-upload`
  * Payload: `excel_file` (parsed using Maatwebsite Excel).
* **Inventory Inquiry**: `GET /api/v1/vendor/inventory`
* **Delete Product**: `POST /api/v1/vendor/delete/{id}/product`

---

## 4. Staff Management (Vendor)

Vendors can add sub-employees or technicians to their organization.

* **Add Staff**: `POST /api/v1/vendor/add-staff`
  * Payload: `business_id`, `first_name`, `last_name`, `email`, `phone`, `date_of_joining`, `documents` (array of identity documents).
  * Validates and saves files in `vendor/staff_documents`.
* **Verification**: Requires back-office admin approval of documents before staff state goes active.

---

## 5. QR Code & Emblem Systems

### A. QR Code Scanner
Every verified business profile generates a unique QR code.
* **Get QR Code Asset**: `GET /api/v1/vendor/qr` -> Returns a vector/PNG QR code containing the verification URL.
* **Verify QR Scans**: `GET /verify-business/{code}` -> Executed when a customer scans the QR code. Validates vendor business legitimacy and returns their compliance verification status.
* **Scan Analytics**: `GET /api/v1/vendor/qr/analytics` -> Returns scan counts, dates, and client-agent telemetry (tracked via `Jenssegers Agent`).

### B. Emblem Generation
* **Trigger Generation**: `POST /api/v1/vendor/generate-emblem/{businessId}` -> Generates a custom visual trust stamp/emblem overlay including reviews and tier status.
* **Fetch Emblem**: `GET /api/v1/vendor/business/{id}/emblem`

---

## 6. Codebase Reference Map

* **Controllers**:
  * [CustomerController](file:///d:/WHIZZACT/bharatseva_backend/app/Http/Controllers/Api/Customer/CustomerController.php) — Processes customer discovery, bookings, reviews, and quotation acceptances.
  * [VendorBusinessController](file:///d:/WHIZZACT/bharatseva_backend/app/Http/Controllers/Api/VendorBusiness/VendorBusinessController.php) — Processes lead responses, start/complete triggers, quotation submissions, and staff registries.
  * [QrController](file:///d:/WHIZZACT/bharatseva_backend/app/Http/Controllers/Api/QR/QrController.php) — Serves QR images, scans, and user-agent analytics.
  * [ProductDetailController](file:///d:/WHIZZACT/bharatseva_backend/app/Http/Controllers/Api/VendorBusiness/ProductDetailController.php) — Controls product listings.
  * [ProductBulkUploadController](file:///d:/WHIZZACT/bharatseva_backend/app/ProductBulkUploadController.php) — Bulk uploads via Excel sheets.
  * [EmblemController](file:///d:/WHIZZACT/bharatseva_backend/app/Http/Controllers/Api/EmblemController.php) — Manages emblem generation.
* **Models**:
  * [Lead](file:///d:/WHIZZACT/bharatseva_backend/app/Models/Lead.php) — Stores overall booking state (`pending`, `accepted`, `quotation_pending`, `in_progress`, `completed`, `cancelled`).
  * [LeadVendor](file:///d:/WHIZZACT/bharatseva_backend/app/Models/LeadVendor.php) — Maps broadcast bids.
  * [LeadQuotation](file:///d:/WHIZZACT/bharatseva_backend/app/Models/LeadQuotation.php) — Stores Quotation details, prices, and scheduled dates.
  * [ProductDetail](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/ProductDetails/ProductDetail.php)
  * [BusinessStaffDetail](file:///d:/WHIZZACT/bharatseva_backend/app/Models/VendorBusiness/BusinessStaffDetail.php)
