sdb2-backend/SCHEDULER_EXAMPLE.md

# Enhanced Scheduler System - Usage Examples

This document demonstrates how to use the new comprehensive scheduled task system.

## Features Overview

### ✨ **Task Types**
- **Credit Recharge**: Automatic or scheduled credit replenishment
- **Play Sound**: Schedule individual sound playback
- **Play Playlist**: Schedule playlist playback with modes

### 🌍 **Timezone Support**
- Full timezone support with automatic UTC conversion
- Specify any IANA timezone (e.g., "America/New_York", "Europe/Paris")

### 🔄 **Scheduling Options**
- **One-shot**: Execute once at specific date/time
- **Recurring**: Hourly, daily, weekly, monthly, yearly intervals
- **Cron**: Custom cron expressions for complex scheduling

## API Usage Examples

### Create a One-Shot Task

```bash
# Schedule a sound to play in 2 hours
curl -X POST "http://localhost:8000/api/v1/scheduler/tasks" \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=YOUR_JWT_TOKEN" \
  -d '{
    "name": "Play Morning Alarm",
    "task_type": "play_sound", 
    "scheduled_at": "2024-01-01T10:00:00",
    "timezone": "America/New_York",
    "parameters": {
      "sound_id": "sound-uuid-here"
    }
  }'
```

### Create a Recurring Task

```bash
# Daily credit recharge at midnight UTC
curl -X POST "http://localhost:8000/api/v1/scheduler/admin/system-tasks" \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=ADMIN_JWT_TOKEN" \
  -d '{
    "name": "Daily Credit Recharge",
    "task_type": "credit_recharge",
    "scheduled_at": "2024-01-01T00:00:00",
    "timezone": "UTC",
    "recurrence_type": "daily",
    "parameters": {}
  }'
```

### Create a Cron-Based Task

```bash
# Play playlist every weekday at 9 AM
curl -X POST "http://localhost:8000/api/v1/scheduler/tasks" \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=YOUR_JWT_TOKEN" \
  -d '{
    "name": "Workday Playlist",
    "task_type": "play_playlist",
    "scheduled_at": "2024-01-01T09:00:00",
    "timezone": "America/New_York", 
    "recurrence_type": "cron",
    "cron_expression": "0 9 * * 1-5",
    "parameters": {
      "playlist_id": "playlist-uuid-here",
      "play_mode": "loop",
      "shuffle": true
    }
  }'
```

## Python Service Usage

```python
from datetime import datetime, timedelta
from app.services.scheduler import SchedulerService
from app.models.scheduled_task import TaskType, RecurrenceType

# Initialize scheduler service
scheduler_service = SchedulerService(db_session_factory, player_service)

# Create a one-shot task
task = await scheduler_service.create_task(
    name="Test Sound",
    task_type=TaskType.PLAY_SOUND,
    scheduled_at=datetime.utcnow() + timedelta(hours=2),
    timezone="America/New_York",
    parameters={"sound_id": "sound-uuid-here"},
    user_id=user.id
)

# Create a recurring task
recurring_task = await scheduler_service.create_task(
    name="Weekly Playlist",
    task_type=TaskType.PLAY_PLAYLIST,
    scheduled_at=datetime.utcnow() + timedelta(days=1),
    recurrence_type=RecurrenceType.WEEKLY,
    recurrence_count=10,  # Run 10 times then stop
    parameters={
        "playlist_id": "playlist-uuid",
        "play_mode": "continuous",
        "shuffle": False
    },
    user_id=user.id
)

# Cancel a task
success = await scheduler_service.cancel_task(task.id)

# Get user's tasks
user_tasks = await scheduler_service.get_user_tasks(
    user_id=user.id,
    status=TaskStatus.PENDING,
    limit=20
)
```

## Task Parameters

### Credit Recharge Parameters
```json
{
  "user_id": "uuid-string-or-null"  // null for all users (system task)
}
```

### Play Sound Parameters
```json
{
  "sound_id": "uuid-string"  // Required: sound to play
}
```

### Play Playlist Parameters
```json
{
  "playlist_id": "uuid-string",        // Required: playlist to play
  "play_mode": "continuous",           // Optional: continuous, loop, loop_one, random, single
  "shuffle": false                     // Optional: shuffle playlist
}
```

## Recurrence Types

| Type | Description | Example |
|------|-------------|---------|
| `none` | One-shot execution | Single alarm |
| `hourly` | Every hour | Hourly reminders |  
| `daily` | Every day | Daily credit recharge |
| `weekly` | Every week | Weekly reports |
| `monthly` | Every month | Monthly maintenance |
| `yearly` | Every year | Annual renewals |
| `cron` | Custom cron expression | Complex schedules |

## Cron Expression Examples

| Expression | Description |
|------------|-------------|
| `0 9 * * *` | Daily at 9 AM |
| `0 9 * * 1-5` | Weekdays at 9 AM |
| `30 14 1 * *` | 1st of month at 2:30 PM |
| `0 0 * * 0` | Every Sunday at midnight |
| `*/15 * * * *` | Every 15 minutes |

## System Tasks vs User Tasks

### System Tasks
- Created by administrators
- No user association (`user_id` is null)  
- Typically for maintenance operations
- Accessible via admin endpoints

### User Tasks
- Created by regular users
- Associated with specific user
- User can only manage their own tasks
- Accessible via regular user endpoints

## Error Handling

The system provides comprehensive error handling:

- **Invalid Parameters**: Validation errors for missing or invalid task parameters
- **Scheduling Conflicts**: Prevention of resource conflicts
- **Timezone Errors**: Invalid timezone specifications handled gracefully  
- **Execution Failures**: Failed tasks marked with error messages and retry logic
- **Expired Tasks**: Automatic cleanup of expired tasks

## Monitoring and Management

### Get Task Status
```bash
curl "http://localhost:8000/api/v1/scheduler/tasks/{task-id}" \
  -H "Cookie: access_token=YOUR_JWT_TOKEN"
```

### List User Tasks
```bash  
curl "http://localhost:8000/api/v1/scheduler/tasks?status=pending&limit=10" \
  -H "Cookie: access_token=YOUR_JWT_TOKEN"
```

### Admin: View All Tasks
```bash
curl "http://localhost:8000/api/v1/scheduler/admin/tasks?limit=50" \
  -H "Cookie: access_token=ADMIN_JWT_TOKEN"
```

### Cancel Task
```bash
curl -X DELETE "http://localhost:8000/api/v1/scheduler/tasks/{task-id}" \
  -H "Cookie: access_token=YOUR_JWT_TOKEN"
```

## Migration from Old Scheduler

The new system automatically:

1. **Creates system tasks**: Daily credit recharge task created on startup
2. **Maintains compatibility**: Existing credit recharge functionality preserved
3. **Enhances functionality**: Adds user tasks and new task types
4. **Improves reliability**: Better error handling and timezone support

The old scheduler is completely replaced - no migration needed for existing functionality.