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

python migrate_tasks.py

Option 2: Using SQL Script

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:

{
  "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:

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:

{
  "status": "in_progress",
  "timestamp": 1708156800000,
  "latitude": 19.0760,
  "longitude": 72.8777
}

Response:

{
  "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:

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:

{
  "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:

{
  "success": false,
  "error": "Task with ID {task_id} not found",
  "detail": "Task with ID {task_id} not found"
}

Database Schema

Table: trans.scm_tasks

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

python migrate_tasks.py

2. Insert test data

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

python generate_test_token.py

4. Test GET today's tasks

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):

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):

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):

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