# Implementation Guide for Missing API Endpoints

This guide provides step-by-step instructions for implementing the missing API endpoints requested by the mobile development team.

---

## Files Created

The following files have been created with complete implementation code:

### 1. New Controller Files

| File | Purpose | Status |
|------|---------|--------|
| `app/Http/Controllers/Api/V2/BatchStudentController.php` | Manage students in batches | ✅ Ready to use |
| `app/Http/Controllers/Api/V2/CategoryController.php` | List categories with filtering | ✅ Ready to use |

### 2. Extension Files (Code to Add)

| File | Purpose | Target File |
|------|---------|-------------|
| `QUESTION_BANK_EXTENSION.php` | Add list & search methods | `app/Http/Controllers/Api/V2/QuestionBankController.php` |
| `TUTOR_CONTROLLER_EXTENSION.php` | Add test results & scheduling methods | `app/Http/Controllers/Api/V2/TutorController.php` |
| `ROUTES_TO_ADD.php` | Routes to add | `routes/api.php` |

### 3. Documentation Files

| File | Purpose |
|------|---------|
| `API_ENDPOINT_REVIEW.md` | Comprehensive endpoint analysis |
| `IMPLEMENTATION_GUIDE.md` | This file |

---

## Step-by-Step Implementation

### Step 1: Review the Analysis

1. Open `API_ENDPOINT_REVIEW.md`
2. Review the status of all endpoints
3. Identify which endpoints are critical for your mobile app

**Key Findings:**
- ✅ 48 endpoints fully implemented
- ⚠️ 8 endpoints partially implemented (minor path differences)
- ❌ 4 endpoints missing (need implementation)

---

### Step 2: Add New Controller Files

The new controller files are already created and ready to use:

#### 2.1 BatchStudentController
**File:** `app/Http/Controllers/Api/V2/BatchStudentController.php`

**Provides:**
- `GET /v2/tutor/batches/{batchId}/students` - List students in a batch
- `POST /v2/tutor/batches/{batchId}/students/bulk` - Bulk import students
- `DELETE /v2/tutor/batches/{batchId}/students/{studentId}` - Remove student

**Action Required:** ✅ File already created, no action needed

#### 2.2 CategoryController
**File:** `app/Http/Controllers/Api/V2/CategoryController.php`

**Provides:**
- `GET /v2/tutor/categories` - Get all categories
- `GET /v2/tutor/categories?type=subject&parent_id=1` - Get subjects for class 1
- `GET /v2/tutor/categories?type=topic&parent_id=5` - Get topics for subject 5

**Action Required:** ✅ File already created, no action needed

---

### Step 3: Extend Existing Controllers

#### 3.1 Extend QuestionBankController

**File to Edit:** `app/Http/Controllers/Api/V2/QuestionBankController.php`

**Steps:**
1. Open `QUESTION_BANK_EXTENSION.php`
2. Copy the two methods:
   - `index()` - List questions with filtering
   - `search()` - Search questions by keyword
3. Add them to `QuestionBankController.php` before the closing brace
4. Make sure to add the required imports at the top if not already present

**Code to Add:**
```php
// Add these imports at the top if missing
use Illuminate\Support\Facades\Validator;

// Then add the two methods from QUESTION_BANK_EXTENSION.php
```

#### 3.2 Extend TutorController

**File to Edit:** `app/Http/Controllers/Api/V2/TutorController.php`

**Steps:**
1. Open `TUTOR_CONTROLLER_EXTENSION.php`
2. Copy all four methods:
   - `getTestResults()` - Get test results
   - `scheduleTest()` - Schedule a test
   - `unassignBatch()` - Unassign batch from test
   - `previewTest()` - Preview test questions
   - `formatTime()` - Helper method
3. Add them to `TutorController.php` before the closing brace

**Code to Add:**
```php
// Add these imports at the top if missing
use App\Models\TestResult;
use App\Models\GroupTestSeries;

// Then add all methods from TUTOR_CONTROLLER_EXTENSION.php
```

---

### Step 4: Add Routes

**File to Edit:** `routes/api.php`

**Steps:**
1. Open `ROUTES_TO_ADD.php`
2. Locate the section in `routes/api.php` that starts with:
   ```php
   Route::prefix('v2')->group(function () {
       Route::prefix('tutor')->group(function () {
   ```
3. Add the routes from `ROUTES_TO_ADD.php` to this section

**Important:** Make sure to add the routes **inside** the existing `v2/tutor` prefix group, not create a new one.

---

### Step 5: Add Required Imports to api.php

At the top of `routes/api.php`, add these controller imports if not already present:

```php
use App\Http\Controllers\Api\V2\BatchStudentController;
use App\Http\Controllers\Api\V2\CategoryController;
```

---

### Step 6: Verify Database Models

Ensure these models exist and have the required relationships:

#### Required Models:
- `Group` (groups table)
- `GroupUser` (group_users table)
- `User` (users table)
- `TestSeries` (testseries table)
- `TestResult` (test_results table)
- `GroupTestSeries` (group_testseries table)
- `Question` (questions table)
- `QuestionTranslation` (question_translations table)
- `ClassModel` (classes table)
- `Subject` (lk_category table, filtered by type)
- `Topic` (lk_category table, filtered by type)

---

### Step 7: Test the Endpoints

Use Postman or similar tool to test each new endpoint:

#### 7.1 Test Batch Student Management

```bash
# List students in a batch
GET /api/v2/tutor/batches/1/students
Authorization: Bearer {token}

# Bulk import students
POST /api/v2/tutor/batches/1/students/bulk
Authorization: Bearer {token}
Content-Type: application/json

{
  "students": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "mobile": "1234567890"
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "mobile": "0987654321"
    }
  ]
}

# Remove a student
DELETE /api/v2/tutor/batches/1/students/123
Authorization: Bearer {token}
```

#### 7.2 Test Categories

```bash
# Get all classes
GET /api/v2/tutor/categories
Authorization: Bearer {token}

# Get subjects for a class
GET /api/v2/tutor/categories?type=subject&parent_id=1
Authorization: Bearer {token}

# Get topics for a subject
GET /api/v2/tutor/categories?type=topic&parent_id=5
Authorization: Bearer {token}
```

#### 7.3 Test Questions

```bash
# List all questions
GET /api/v2/tutor/questions
Authorization: Bearer {token}

# Filter by category
GET /api/v2/tutor/questions?category_id=5&per_page=20
Authorization: Bearer {token}

# Search questions
GET /api/v2/tutor/questions/search?keyword=algebra
Authorization: Bearer {token}
```

#### 7.4 Test Results & Scheduling

```bash
# Get test results
GET /api/v2/tutor/results/test/123
Authorization: Bearer {token}

# Schedule a test
POST /api/v2/tutor/test-series/123/schedule
Authorization: Bearer {token}
Content-Type: application/json

{
  "start_date": "2025-01-20 09:00:00",
  "end_date": "2025-01-20 11:00:00",
  "group_ids": [1, 2, 3]
}

# Preview test
GET /api/v2/tutor/test-series/123/preview
Authorization: Bearer {token}

# Unassign batch
DELETE /api/v2/tutor/test-series/123/groups/1
Authorization: Bearer {token}
```

---

## Troubleshooting

### Common Issues and Solutions

#### Issue 1: "Class not found" error
**Solution:** Make sure you added the controller imports at the top of `routes/api.php`

#### Issue 2: "Method not found" error
**Solution:** Verify that you added the methods to the correct controller file

#### Issue 3: "Column not found" error
**Solution:** Check that your database has all required columns. Run migrations if needed.

#### Issue 4: "Forbidden" error
**Solution:** Ensure the user has `role_id = 3` (tutor) in the database

#### Issue 5: Pagination not working
**Solution:** Laravel pagination is already implemented. Make sure you're passing `page` and `per_page` parameters correctly.

---

## Database Migration Requirements

If any tables or columns are missing, you may need to create migrations:

### Required Tables:
- `groups` - Batch/group information
- `group_users` - Student enrollment in groups
- `users` - User accounts
- `testseries` - Test series information
- `test_results` - Student test results
- `group_testseries` - Assignment of tests to groups
- `questions` - Question bank
- `question_translations` - Multi-language support
- `classes` - Class/grade levels
- `lk_category` - Categories (subjects, topics)
- `group_activity_logs` - Activity tracking

### Key Columns to Verify:

**groups table:**
- id, name, school_id, class_id, subject_ids, status, enrollment_code, expires_at

**group_users table:**
- id, group_id, user_id, type, status, enrolled_at, enrollment_method

**testseries table:**
- id, name, school_id, added_by, total_marks, duration, status, start_date, end_date, is_scheduled

**test_results table:**
- id, test_series_id, user_id, obtained_marks, total_marks, correct_answers, incorrect_answers, unattempted, time_taken, status, started_at, completed_at

---

## API Documentation for Mobile Team

After implementation, share these endpoint details with your mobile team:

### Base URL
```
https://your-domain.com/api
```

### Authentication
All endpoints require Bearer token authentication:
```
Authorization: Bearer {access_token}
```

### Response Format
All responses follow this structure:
```json
{
  "status": true,
  "message": "Success message",
  "data": { ... },
  "pagination": { ... }  // For list endpoints
}
```

### Error Response Format
```json
{
  "status": false,
  "message": "Error message",
  "error_code": "ERROR_CODE",
  "errors": { ... }  // For validation errors
}
```

---

## Next Steps After Implementation

1. ✅ Complete implementation as described above
2. ✅ Test all endpoints thoroughly
3. ✅ Update API documentation (Swagger/Postman)
4. ✅ Share endpoint details with mobile team
5. ✅ Monitor error logs for any issues
6. ✅ Optimize queries if performance issues arise

---

## Summary of Changes

### New Files Created (2)
1. `app/Http/Controllers/Api/V2/BatchStudentController.php`
2. `app/Http/Controllers/Api/V2/CategoryController.php`

### Files to Modify (3)
1. `app/Http/Controllers/Api/V2/QuestionBankController.php` - Add 2 methods
2. `app/Http/Controllers/Api/V2/TutorController.php` - Add 5 methods
3. `routes/api.php` - Add ~10 routes

### Estimated Implementation Time
- Adding routes: 5 minutes
- Extending controllers: 10 minutes
- Testing all endpoints: 30 minutes
- **Total: ~45 minutes**

---

## Support

If you encounter any issues during implementation:

1. Check the error logs in `storage/logs/laravel.log`
2. Verify database structure matches requirements
3. Ensure all model relationships are properly defined
4. Test with valid authentication token (role_id = 3 for tutor)

---

**Implementation Status:** ✅ Ready for deployment
**Last Updated:** 2025-01-18
**Version:** 1.0