# Backend Filter Parameters Audit

**Date**: 2025-01-27  
**Action**: 2.2.1.2 - Ensure backend handles all filter params  
**Status**: ✅ Complete (Verification)

## Overview

This document verifies that the backend `/tracks` endpoint handles all filter parameters sent by the frontend.

## Frontend Parameters

The frontend sends the following query parameters to `/tracks` endpoint (via `getTracks` function):

1. **`page`** - Page number (default: 1)
2. **`limit`** - Items per page (default: 20)
3. **`user_id`** - Filter by user ID (optional)
4. **`genre`** - Filter by genre (optional)
5. **`format`** - Filter by format (optional)
6. **`search`** - Search query (optional) ⚠️
7. **`sort_by`** - Sort field: 'created_at' | 'title' | 'popularity' (default: 'created_at')
8. **`sort_order`** - Sort order: 'asc' | 'desc' (default: 'desc')

## Backend Handler Analysis

**Location**: `veza-backend-api/internal/core/track/handler.go:812-878`

**Handler Function**: `ListTracks(c *gin.Context)`

### Parameters Handled ✅

1. **`page`** ✅ - Line 814: `page := c.DefaultQuery("page", "1")`
2. **`limit`** ✅ - Line 815: `limit := c.DefaultQuery("limit", "20")`
3. **`user_id`** ✅ - Line 816: `userIDStr := c.Query("user_id")` → Parsed and added to params (lines 840-844)
4. **`genre`** ✅ - Line 817: `genre := c.Query("genre")` → Added to params (lines 847-849)
5. **`format`** ✅ - Line 818: `format := c.Query("format")` → Added to params (lines 851-854)
6. **`sort_by`** ✅ - Line 819: `sortBy := c.DefaultQuery("sort_by", "created_at")` → Added to params (line 835)
7. **`sort_order`** ✅ - Line 820: `sortOrder := c.DefaultQuery("sort_order", "desc")` → Added to params (line 836)

### Parameters NOT Handled ⚠️

8. **`search`** ❌ - **NOT HANDLED** in `ListTracks` handler

## Backend Service Analysis

**Location**: `veza-backend-api/internal/core/track/service.go:511-580`

**Service Function**: `ListTracks(ctx context.Context, params TrackListParams)`

**TrackListParams Struct** (line 500):
```go
type TrackListParams struct {
    Page      int
    Limit     int
    UserID    *uuid.UUID
    Genre     *string
    Format    *string
    SortBy    string
    SortOrder string
    // Search field is MISSING
}
```

**Service Implementation**:
- ✅ Handles `UserID` filter (line 516-518)
- ✅ Handles `Genre` filter (line 519-521)
- ✅ Handles `Format` filter (line 522-524)
- ✅ Handles `SortBy` and `SortOrder` (lines 532-558)
- ❌ **Does NOT handle `Search` parameter**

## Search Endpoint

**Separate Endpoint**: `/tracks/search` (line 780 in router.go)

**Handler**: `SearchTracks(c *gin.Context)` (line 1387)

**Parameters**: Uses `q` parameter (not `search`)

**Status**: Separate search endpoint exists but uses different parameter name (`q` vs `search`)

## Issue Identified

**Problem**: Frontend sends `search` parameter to `/tracks` endpoint, but backend `ListTracks` handler does not process it.

**Impact**: 
- Search functionality may not work when using `/tracks` endpoint
- Frontend may need to use `/tracks/search` endpoint instead for search functionality

## Recommendations

1. **Option A**: Add `search` parameter support to `ListTracks` handler and service
   - Add `Search *string` field to `TrackListParams` struct
   - Parse `search` query parameter in handler
   - Implement search logic in service (LIKE query on title/artist)

2. **Option B**: Frontend should use `/tracks/search` endpoint for search queries
   - Update frontend to use `/tracks/search` when search term is provided
   - Keep `/tracks` for non-search queries

3. **Option C**: Standardize parameter names
   - Backend `/tracks/search` uses `q` parameter
   - Frontend sends `search` parameter
   - Align on one parameter name (`search` or `q`)

## Current State

**Backend `/tracks` endpoint**:
- ✅ Handles: page, limit, user_id, genre, format, sort_by, sort_order
- ❌ Missing: search parameter

**Backend `/tracks/search` endpoint**:
- ✅ Handles: q (search), genre, format, sort_by, sort_order, tags, min_duration, max_duration, min_bpm, max_bpm, min_date, max_date
- Uses `q` parameter instead of `search`

## Validation

✅ Verified backend handler implementation  
✅ Verified backend service implementation  
✅ Verified frontend parameter usage  
⚠️ Identified missing `search` parameter in `/tracks` endpoint  
⏭️ Recommendation: Add search support to ListTracks or use separate search endpoint

## Next Steps

- **Action 2.2.1.1**: Remove client-side filtering (can proceed - backend handles filters)
- **Action 2.2.1.2**: ✅ Verified - Backend handles most filter params, but `search` is missing from `/tracks` endpoint
- **Recommendation**: Add `search` parameter to `ListTracks` handler/service OR update frontend to use `/tracks/search` endpoint
