# Agent Location Tracking API

## Endpoints

### 1. Track Location (Agent)
`POST /track_location`

### 2. Add Location Log (Admin)
`POST /admin/agent-location-log`

## Description
These endpoints allow tracking agent locations without requiring a receipt_id. Location logs can be added anytime for tracking agent movements, check-ins, check-outs, travel, or other activities.

## Authentication
- Agent endpoint: Requires agent authentication
- Admin endpoint: Requires admin authentication

## Request Body Parameters

### Required:
- `latitude` (decimal): GPS latitude coordinate
- `longitude` (decimal): GPS longitude coordinate

### Optional:
- `accuracy` (decimal): Location accuracy in meters
- `altitude` (decimal): Altitude in meters
- `altitude_accuracy` (decimal): Altitude accuracy
- `heading` (decimal): Direction of travel in degrees
- `speed` (decimal): Speed in m/s
- `address` (string): Human-readable address
- `activity_type` (enum): Type of activity - `collection`, `travel`, `check_in`, `check_out`, `other` (default: `other`)
- `receipt_id` (integer): Optional - Link to a receipt if this location is related to a collection
- `loan_id` (string): Optional - Loan ID if related to a specific loan
- `remark` (string): Optional - Additional notes

### Admin Endpoint Additional Required:
- `agent_id` (integer): ID of the agent to track (admin can track any agent)

## cURL Examples

### Agent Tracking Own Location (without receipt)
```bash
curl -X POST "http://192.168.1.3:3000/track_location" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AGENT_JWT_TOKEN" \
  -d '{
    "latitude": 11.3410,
    "longitude": 77.7172,
    "accuracy": 10.5,
    "address": "Erode, Tamil Nadu, India",
    "activity_type": "check_in",
    "remark": "Agent check-in at office"
  }'
```

### Agent Tracking Location with Receipt
```bash
curl -X POST "http://192.168.1.3:3000/track_location" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AGENT_JWT_TOKEN" \
  -d '{
    "latitude": 11.3410,
    "longitude": 77.7172,
    "accuracy": 10.5,
    "address": "Customer location, Erode",
    "activity_type": "collection",
    "receipt_id": 56,
    "loan_id": "DL2025001",
    "remark": "Collection at customer location"
  }'
```

### Agent Tracking Travel Location
```bash
curl -X POST "http://192.168.1.3:3000/track_location" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AGENT_JWT_TOKEN" \
  -d '{
    "latitude": 11.3500,
    "longitude": 77.7200,
    "accuracy": 15.0,
    "speed": 8.5,
    "heading": 45.0,
    "activity_type": "travel",
    "remark": "Traveling to next customer"
  }'
```

### Admin Adding Location Log for Agent
```bash
curl -X POST "http://192.168.1.3:3000/admin/agent-location-log" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
  -d '{
    "agent_id": 5,
    "latitude": 11.3410,
    "longitude": 77.7172,
    "accuracy": 10.5,
    "address": "Erode, Tamil Nadu, India",
    "activity_type": "check_in",
    "remark": "Manual location entry by admin"
  }'
```

### PowerShell Example (Agent)
```powershell
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.UserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1"

Invoke-WebRequest -UseBasicParsing -Uri "http://192.168.1.3:3000/track_location" `
-Method "POST" `
-WebSession $session `
-Headers @{
  "Accept"="application/json"
  "Authorization"="Bearer YOUR_AGENT_JWT_TOKEN"
  "Content-Type"="application/json"
} `
-Body '{
  "latitude": 11.3410,
  "longitude": 77.7172,
  "accuracy": 10.5,
  "address": "Erode, Tamil Nadu, India",
  "activity_type": "check_in",
  "remark": "Agent check-in"
}'
```

## Response Format

### Success Response (200 OK)
```json
{
  "status": "success",
  "message": "Location tracked successfully",
  "data": {
    "location_track_id": 1234,
    "agent_id": 5,
    "agent_name": "Raja",
    "latitude": 11.3410,
    "longitude": 77.7172,
    "accuracy": 10.5,
    "address": "Erode, Tamil Nadu, India",
    "activity_type": "check_in",
    "receipt_id": null,
    "loan_id": null,
    "remark": "Agent check-in at office",
    "created_at": "2025-12-06T10:30:00.000Z"
  }
}
```

### Error Response (400 Bad Request)
```json
{
  "status": "error",
  "message": "Missing required fields: latitude, longitude"
}
```

### Error Response (401 Unauthorized)
```json
{
  "status": "error",
  "message": "Not authenticated"
}
```

## Activity Types

- `collection`: Location related to collecting a receipt/payment
- `travel`: Agent is traveling between locations
- `check_in`: Agent checking in (e.g., at office, start of day)
- `check_out`: Agent checking out (e.g., end of day)
- `other`: General location tracking (default)

## Notes

1. **receipt_id is Optional**: You can track locations without linking to any receipt. Just omit `receipt_id` from the request.

2. **Default Activity Type**: If `activity_type` is not provided, it defaults to `other`.

3. **Agent Endpoint**: Agent can only track their own location (uses authenticated agent's ID).

4. **Admin Endpoint**: Admin can add location logs for any agent in their company by specifying `agent_id`.

5. **Location Data**: 
   - `latitude` and `longitude` are required
   - All other location fields (accuracy, altitude, speed, etc.) are optional
   - `address` can be reverse-geocoded or provided manually

6. **Use Cases**:
   - Track agent movements throughout the day
   - Record check-in/check-out times
   - Track travel routes
   - Link locations to specific receipts (optional)
   - Manual location entry by admin

## Example Use Cases

### 1. Agent Check-In (Start of Day)
```json
{
  "latitude": 11.3410,
  "longitude": 77.7172,
  "activity_type": "check_in",
  "remark": "Start of work day"
}
```

### 2. Agent Check-Out (End of Day)
```json
{
  "latitude": 11.3410,
  "longitude": 77.7172,
  "activity_type": "check_out",
  "remark": "End of work day"
}
```

### 3. Travel Between Locations
```json
{
  "latitude": 11.3500,
  "longitude": 77.7200,
  "activity_type": "travel",
  "speed": 8.5,
  "heading": 45.0,
  "remark": "Traveling to next customer"
}
```

### 4. Collection with Receipt Link
```json
{
  "latitude": 11.3450,
  "longitude": 77.7150,
  "activity_type": "collection",
  "receipt_id": 56,
  "loan_id": "DL2025001",
  "remark": "Collection at customer location"
}
```