# Suno Step-by-Step Upload Implementation Plan

## Overview
Implement a step-by-step Suno file upload process with detailed logging for debugging and visibility.

## Suno Upload Flow (Based on API Endpoints)
1. **Reserve Upload Slot**: `POST /api/uploads/audio` → returns upload_id and upload URL
2. **Upload File**: PUT/POST file to the provided URL (S3 presigned URL or multipart)
3. **Signal Upload Complete**: `POST /api/uploads/audio/{upload_id}/upload-finish`
4. **Poll Status**: `GET /api/uploads/audio/{upload_id}` until file is processed
5. **Initialize Clip**: `POST /api/uploads/audio/{upload_id}/initialize-clip` → returns clip_id

## Implementation Tasks

### 1. Create suno_step_by_step_utils.py
- [ ] Create individual functions for each step:
  - `step1_reserve_upload_slot(filename, content_type)` → returns upload_id, upload_url, fields
  - `step2_upload_file(upload_url, fields, file_path)` → uploads file to S3
  - `step3_signal_upload_complete(upload_id, upload_key)` → marks upload as finished
  - `step4_poll_upload_status(upload_id)` → polls until processed
  - `step5_initialize_clip(upload_id)` → creates clip, returns clip_id
- [ ] Add detailed logging at each step with timing info
- [ ] Add error handling and retry logic for each step
- [ ] Create a main orchestrator function that runs all steps

### 2. Backend API Endpoint
- [ ] Add new endpoint `/api/suno_upload_steps` that:
  - Accepts a local file path or file upload
  - Runs each step individually with status updates
  - Sends real-time logs via SSE (Server-Sent Events) or WebSocket
  - Returns final clip_id on success
- [ ] Create a status tracking system (job_id → step status)
- [ ] Store logs for each job in storage/{job_id}/suno_upload_log.txt

### 3. Frontend Updates (index.html)
- [ ] Add new section "Suno Step-by-Step Upload Test"
- [ ] Add file input and "Start Upload" button
- [ ] Create real-time log display area (scrollable div)
- [ ] Show current step progress (Step 1/5, Step 2/5, etc.)
- [ ] Display timing for each step
- [ ] Show final result (clip_id) or error message

### 4. Logging Strategy
- [ ] Backend: Log to both console and file with timestamps
- [ ] Frontend: Display logs in real-time using EventSource or polling
- [ ] Include: HTTP requests/responses, timing, file sizes, URLs (sanitized)
- [ ] Format: `[2024-01-01 12:00:00] [STEP 1] [INFO] Starting upload reservation...`

### 5. Testing Plan
- [ ] Test with small WAV file first
- [ ] Test error scenarios (invalid token, network timeout)
- [ ] Verify each step completes successfully
- [ ] Check that logs are comprehensive and helpful

## Success Criteria
- Can upload a WAV file to Suno step-by-step
- Each step is clearly logged with timing
- Frontend shows real-time progress
- Process is resilient to common errors
- Final clip_id is returned and can be used for generation