# Tutor School Students API Documentation

## Endpoint: Get Students in Tutor's Batches for Selected School

### Overview
This API returns a list of all students enrolled in batches where the authenticated tutor is assigned, filtered by the tutor's currently selected school or freelancer context.

### Request Details

**Endpoint:** `GET /api/v2/tutor/school-students`

**Authentication:** Required (Sanctum Token)

**Authorization:** Only Tutors (role_id: 3) and Schools (role_id: 5)

### Query Parameters

| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `page` | Integer | No | Page number for pagination | 1 |
| `per_page` | Integer | No | Items per page | 15 |
| `search` | String | No | Search by student name, email, or mobile number | - |
| `status` | String | No | Filter by enrollment status: `active`, `inactive`, `withdrawn` | - |
| `batch_id` | Integer | No | Filter by specific batch ID (must be one of tutor's batches) | - |

### Request Example

```bash
# Get all students in tutor's batches
curl -X GET "http://api.pathshalaa.in/api/v2/tutor/school-students" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Get with pagination
curl -X GET "http://api.pathshalaa.in/api/v2/tutor/school-students?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Search for specific student
curl -X GET "http://api.pathshalaa.in/api/v2/tutor/school-students?search=john" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by batch
curl -X GET "http://api.pathshalaa.in/api/v2/tutor/school-students?batch_id=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by status
curl -X GET "http://api.pathshalaa.in/api/v2/tutor/school-students?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response - Success (200)

```json
{
  "status": true,
  "message": "Students retrieved successfully",
  "data": {
    "total_students": 45,
    "students": [
      {
        "id": 123,
        "user_id": 123,
        "name": "John Doe",
        "email": "john@example.com",
        "mobile_no": "9876543210",
        "profile_image": "https://cdn.pathshalaa.in/profiles/123.jpg",
        "batches": [
          {
            "batch_id": 5,
            "batch_name": "Class 10 - Science Batch A",
            "class_name": "Class 10",
            "enrollment_status": "active"
          },
          {
            "batch_id": 8,
            "batch_name": "Class 10 - Mathematics Batch",
            "class_name": "Class 10",
            "enrollment_status": "active"
          }
        ]
      },
      {
        "id": 124,
        "user_id": 124,
        "name": "Jane Smith",
        "email": "jane@example.com",
        "mobile_no": "8765432109",
        "profile_image": null,
        "batches": [
          {
            "batch_id": 5,
            "batch_name": "Class 10 - Science Batch A",
            "class_name": "Class 10",
            "enrollment_status": "active"
          }
        ]
      }
    ]
  },
  "pagination": {
    "total": 45,
    "per_page": 15,
    "current_page": 1,
    "last_page": 3
  }
}
```

### Response - No Batches Found (200)

```json
{
  "status": true,
  "message": "No batches found for tutor",
  "data": {
    "total_students": 0,
    "students": []
  },
  "pagination": {
    "total": 0,
    "per_page": 15,
    "current_page": 1,
    "last_page": 1
  }
}
```

### Response - Batch Not Found (404)

```json
{
  "status": false,
  "message": "Batch not found or you do not have access",
  "error_code": "BATCH_NOT_FOUND"
}
```

### Response - Unauthorized (403)

```json
{
  "status": false,
  "message": "Forbidden: only tutor and schools are allowed to perform this action.",
  "error_code": "FORBIDDEN"
}
```

### Response - Unauthenticated (401)

```json
{
  "status": false,
  "message": "Unauthenticated",
  "error_code": "UNAUTHENTICATED"
}
```

### Response - Server Error (500)

```json
{
  "status": false,
  "message": "An unexpected error occurred",
  "error": "Error message details..."
}
```

## How It Works

1. **Authentication Check**: Validates that the request is made by an authenticated user
2. **Authorization Check**: Ensures only tutors (role_id: 3) or schools (role_id: 5) can access
3. **School/Freelancer Context**:
   - **School-based tutors** (school_id != '0'): Gets all batches in their assigned school where they are registered as a teacher
   - **Freelance tutors** (school_id = '0'): Gets all batches they are directly assigned to as a teacher
4. **Student Collection**: Gathers all unique students from those batches
5. **Data Enrichment**: For each student, includes:
   - Basic info (name, email, mobile, profile image)
   - List of all batches they're enrolled in (with batch name, class name, and enrollment status)
6. **Pagination**: Returns results in paginated format (15 per page by default)

## Key Features

- ✅ **School/Freelancer aware**: Works for both school-based and freelance tutors
- ✅ **Duplicate removal**: Each student appears only once even if enrolled in multiple batches
- ✅ **Batch relationship**: Shows which batches each student is enrolled in
- ✅ **Search functionality**: Find students by name, email, or mobile number
- ✅ **Status filtering**: Filter by enrollment status (active, inactive, withdrawn)
- ✅ **Batch filtering**: Get students from a specific batch
- ✅ **Pagination**: Handle large datasets efficiently
- ✅ **Error handling**: Comprehensive error responses with appropriate HTTP status codes

## Use Cases

1. **Tutor Dashboard**: Display all students for teacher overview
2. **Student Management**: Quick access to all students in tutor's school/freelancer context
3. **Assignment**: Bulk operations on students (assign tests, send notifications, etc.)
4. **Analytics**: View student performance across batches
5. **Communication**: Send announcements/messages to students

## Related Endpoints

- `GET /api/v2/tutor/groups` - List all batches/groups
- `GET /api/v2/tutor/batches/{batchId}/students` - Get students in a specific batch
- `GET /api/v2/tutor/enrollment-students` - Get enrollment information
- `POST /api/v2/tutor/add-student-to-batch` - Add student to batch

## Implementation Notes

- The endpoint uses DISTINCT to avoid returning duplicate students if they're enrolled in multiple batches
- Batch information is dynamically fetched for each student to ensure accuracy
- The class name is fetched from the `lk_category` table
- Profile image column is checked for existence before including it in the response
- Empty batch lists return status 200 with empty data (not an error)