TASKS_API_README.md

# Tasks API Documentation

## Overview
The Tasks API allows employees to fetch their assigned tasks/visits for the day.

## Database Setup

### Option 1: Using Python Migration Script
```bash
python migrate_tasks.py
```

### Option 2: Using SQL Script
```bash
psql -U postgres -d cuatrolabs -f create_tasks_table.sql
```

## API Endpoint

### GET /tracker/tasks/today
Fetch all tasks assigned to the authenticated employee for today.

**Authentication:** Required (JWT Bearer token)

**Response:**
```json
{
  "success": true,
  "tasks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Visit Customer ABC",
      "description": "Deliver products and collect payment",
      "status": "not_started",
      "lat": 19.0760,
      "lon": 72.8777,
      "address": "123 Main St, Mumbai",
      "scheduledAt": "2024-02-17T10:00:00"
    }
  ],
  "count": 1
}
```

**Task Status Values:**
- `not_started` - Task has not been started yet
- `in_progress` - Task is currently being worked on
- `completed` - Task has been completed

**Example Request:**
```bash
curl -X GET "http://localhost:8003/tracker/tasks/today" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

---

### PATCH /tracker/tasks/{task_id}/status
Update the status of a task with location and timestamp tracking.

**Authentication:** Required (JWT Bearer token)

**Path Parameters:**
- `task_id` - UUID of the task to update

**Request Body:**
```json
{
  "status": "in_progress",
  "timestamp": 1708156800000,
  "latitude": 19.0760,
  "longitude": 72.8777
}
```

**Response:**
```json
{
  "success": true,
  "message": "Task status updated successfully"
}
```

**Status Transition Rules:**
- `not_started` → `in_progress` (captures started_at timestamp)
- `not_started` → `completed` (direct completion allowed)
- `in_progress` → `completed` (captures completed_at timestamp)
- `in_progress` → `not_started` (revert allowed)
- `completed` → `in_progress` (reopening allowed)

**Validation Rules:**
- Location (latitude/longitude) is mandatory
- Timestamp must be Unix milliseconds (positive integer)
- Latitude must be between -90 and 90
- Longitude must be between -180 and 180
- Only assigned employee can update the task
- Invalid status transitions return 400 error
- Task not found or unauthorized returns 404 error

**Example Request:**
```bash
curl -X PATCH "http://localhost:8003/tracker/tasks/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "timestamp": 1708156800000,
    "latitude": 19.0760,
    "longitude": 72.8777
  }'
```

**Error Responses:**

400 Bad Request - Invalid status transition:
```json
{
  "success": false,
  "error": "Cannot transition from 'completed' to 'not_started'",
  "detail": "Cannot transition from 'completed' to 'not_started'"
}
```

404 Not Found - Task not found or unauthorized:
```json
{
  "success": false,
  "error": "Task with ID {task_id} not found",
  "detail": "Task with ID {task_id} not found"
}
```

## Database Schema

### Table: trans.scm_tasks
```sql
CREATE TABLE trans.scm_tasks (
    id UUID PRIMARY KEY,
    merchant_id UUID NOT NULL,
    assigned_to UUID NOT NULL,
    title TEXT NOT NULL,
    description TEXT,
    status TEXT DEFAULT 'not_started',
    latitude DOUBLE PRECISION,
    longitude DOUBLE PRECISION,
    address TEXT,
    scheduled_at TIMESTAMP,
    started_at BIGINT,
    completed_at BIGINT,
    created_at TIMESTAMP DEFAULT now(),
    updated_at TIMESTAMP DEFAULT now()
);
```

### Indexes
- `idx_scm_tasks_assigned_date` - Optimizes queries by assigned_to and scheduled_at
- `idx_scm_tasks_merchant_status` - Optimizes queries by merchant_id and status
- `idx_scm_tasks_status_scheduled` - Optimizes queries by status and scheduled_at

## Testing

### 1. Run the migration
```bash
python migrate_tasks.py
```

### 2. Insert test data
```sql
INSERT INTO trans.scm_tasks (
    id, merchant_id, assigned_to, title, description, 
    status, latitude, longitude, address, scheduled_at
) VALUES (
    gen_random_uuid(),
    'YOUR_MERCHANT_ID'::uuid,
    'YOUR_EMPLOYEE_ID'::uuid,
    'Visit Customer ABC',
    'Deliver products and collect payment',
    'not_started',
    19.0760,
    72.8777,
    '123 Main St, Mumbai',
    CURRENT_DATE + INTERVAL '10 hours'
);
```

### 3. Generate test token
```bash
python generate_test_token.py
```

### 4. Test GET today's tasks
```bash
curl -X GET "http://localhost:8003/tracker/tasks/today" \
  -H "Authorization: Bearer $(cat test_token.txt)"
```

### 5. Test PATCH update task status

Get the task ID from the previous response, then:

**Start the task (not_started → in_progress):**
```bash
TASK_ID="your-task-id-here"
curl -X PATCH "http://localhost:8003/tracker/tasks/${TASK_ID}/status" \
  -H "Authorization: Bearer $(cat test_token.txt)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "timestamp": '$(date +%s000)',
    "latitude": 19.0760,
    "longitude": 72.8777
  }'
```

**Complete the task (in_progress → completed):**
```bash
curl -X PATCH "http://localhost:8003/tracker/tasks/${TASK_ID}/status" \
  -H "Authorization: Bearer $(cat test_token.txt)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "timestamp": '$(date +%s000)',
    "latitude": 19.0761,
    "longitude": 72.8778
  }'
```

**Test invalid transition (should fail):**
```bash
curl -X PATCH "http://localhost:8003/tracker/tasks/${TASK_ID}/status" \
  -H "Authorization: Bearer $(cat test_token.txt)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "not_started",
    "timestamp": '$(date +%s000)',
    "latitude": 19.0761,
    "longitude": 72.8778
  }'
```

## Implementation Details

### Files Created/Modified
- `app/tracker/tasks/router.py` - API endpoint handlers (GET today, PATCH status)
- `app/tracker/tasks/service.py` - Business logic with status validation
- `app/tracker/tasks/schemas.py` - Request/response models
- `app/main.py` - Router registration
- `migrate_tasks.py` - Database migration script
- `create_tasks_table.sql` - SQL script for manual setup

### Key Features

**GET /tracker/tasks/today:**
- JWT authentication required
- Filters tasks by authenticated employee
- Returns only today's tasks (based on scheduled_at)
- Tasks ordered by scheduled time
- Includes geolocation data (lat/lon)
- Status tracking (not_started, in_progress, completed)

**PATCH /tracker/tasks/{task_id}/status:**
- JWT authentication required
- Authorization checks (task must be assigned to employee)
- Status transition validation
- Location tracking on every update
- Timestamp tracking (started_at, completed_at)
- Idempotent updates (same status allowed)
- Comprehensive error handling with appropriate HTTP status codes

### Status Transition Logic
The service validates all status transitions to maintain data integrity:
- Prevents invalid transitions (e.g., completed → not_started requires going through in_progress)
- Allows reopening completed tasks
- Allows reverting in-progress tasks
- Captures timestamps at key milestones (started_at, completed_at)

### Security Features
- JWT token validation on all endpoints
- Employee authorization (can only update own tasks)
- Merchant validation (task must belong to employee's merchant)
- Task existence verification
- Returns 404 for unauthorized access (doesn't reveal task existence)

## API Documentation
Once the server is running, visit:
- Swagger UI: http://localhost:8003/docs
- ReDoc: http://localhost:8003/redoc