TASK_STATUS_UPDATE_GUIDE.md

# Task Status Update API - Quick Reference

## Endpoint
```
PATCH /tracker/tasks/{task_id}/status
```

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

## Status Values
- `not_started` - Initial state
- `in_progress` - Task is being worked on
- `completed` - Task is finished

## Valid Status Transitions

### From: not_started
✅ `not_started` → `in_progress` (captures started_at)
✅ `not_started` → `completed` (direct completion)

### From: in_progress
✅ `in_progress` → `completed` (captures completed_at)
✅ `in_progress` → `not_started` (revert)

### From: completed
✅ `completed` → `in_progress` (reopen)
❌ `completed` → `not_started` (must go through in_progress)

## Validation Rules

### Required Fields
- `status` - Must be one of: not_started, in_progress, completed
- `timestamp` - Unix timestamp in milliseconds (positive integer)
- `latitude` - Must be between -90 and 90
- `longitude` - Must be between -180 and 180

### Authorization
- Must be authenticated (JWT token required)
- Task must be assigned to the authenticated employee
- Task must belong to employee's merchant

## Response Codes

### 200 OK - Success
```json
{
  "success": true,
  "message": "Task status updated successfully"
}
```

### 400 Bad Request - Invalid 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"
}
```

### 422 Unprocessable Entity - Validation Error
```json
{
  "success": false,
  "error": "Validation Error",
  "errors": [
    {
      "field": "body -> latitude",
      "message": "ensure this value is greater than or equal to -90",
      "type": "value_error.number.not_ge"
    }
  ]
}
```

## Timestamp Tracking

### started_at
- Set when status changes to `in_progress`
- Stored as Unix timestamp in milliseconds (BIGINT)
- Captured from request payload

### completed_at
- Set when status changes to `completed`
- Stored as Unix timestamp in milliseconds (BIGINT)
- Captured from request payload

### updated_at
- Set on every status update
- Stored as PostgreSQL TIMESTAMP
- Automatically set by database

## Location Tracking

Every status update captures the employee's location:
- `latitude` - Updated on every status change
- `longitude` - Updated on every status change

This allows tracking where the employee was when they:
- Started the task
- Completed the task
- Made any status changes

## Example Usage

### Start a task
```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
  }'
```

### Complete a task
```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": "completed",
    "timestamp": 1708160400000,
    "latitude": 19.0761,
    "longitude": 72.8778
  }'
```

### Reopen a completed task
```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": 1708164000000,
    "latitude": 19.0762,
    "longitude": 72.8779
  }'
```

## Testing

Run the comprehensive test suite:
```bash
python test_tasks_api.py
```

This will:
1. Create a test task
2. Test GET /tasks/today
3. Test all valid status transitions
4. Test invalid transitions (should fail)
5. Test with invalid task ID (should fail)

## Database Schema

The status update modifies these columns in `trans.scm_tasks`:
- `status` - Updated to new status
- `started_at` - Set when transitioning to in_progress
- `completed_at` - Set when transitioning to completed
- `latitude` - Updated on every change
- `longitude` - Updated on every change
- `updated_at` - Automatically updated by database

## Security Features

1. **Authentication** - JWT token required
2. **Authorization** - Only assigned employee can update
3. **Merchant Validation** - Task must belong to employee's merchant
4. **Privacy** - Returns 404 for unauthorized access (doesn't reveal task existence)
5. **Validation** - All inputs validated before processing
6. **Idempotency** - Same status updates are allowed (no error)

## Best Practices

1. **Always capture current location** - Don't reuse old coordinates
2. **Use server time** - Generate timestamp on client but validate on server
3. **Handle errors gracefully** - Check response status and show appropriate messages
4. **Validate before sending** - Check coordinates and timestamp format
5. **Retry on network errors** - But not on 400/404 errors
6. **Log status changes** - For audit trail and debugging