# SYLLABUS PLANNER MODULE - API DOCUMENTATION

## Week 10: Complete Implementation

This document provides comprehensive API documentation and Postman cURL examples for the Syllabus Planner module.

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Day 1-2: Syllabus CRUD APIs](#day-1-2-syllabus-crud-apis)
3. [Day 3: Auto-Distribution Algorithm](#day-3-auto-distribution-algorithm)
4. [Day 4: Weekly Schedule View](#day-4-weekly-schedule-view)
5. [Day 5: Topic Completion Tracking](#day-5-topic-completion-tracking)
6. [Database Schema](#database-schema)
7. [Migration Instructions](#migration-instructions)

---

## Prerequisites

### Authentication
All endpoints require authentication using Laravel Sanctum.

Include the token in the `Authorization` header:
```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Base URL
```
http://your-domain.com/api/v2/tutor
```

---

## Day 1-2: Syllabus CRUD APIs

### 1. Create Syllabus

**Endpoint:** `POST /api/v2/tutor/syllabus`

**Description:** Create a new syllabus with automatic topic distribution across the date range.

**Request Body:**
```json
{
  "batch_id": 5,
  "title": "Class 10 Math - Term 1",
  "start_date": "2025-01-15",
  "end_date": "2025-04-15",
  "topic_ids": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
}
```

**cURL Example:**
```bash
curl --location 'http://localhost:8000/api/v2/tutor/syllabus' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "batch_id": 5,
  "title": "Class 10 Math - Term 1",
  "start_date": "2025-01-15",
  "end_date": "2025-04-15",
  "topic_ids": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
}'
```

**Success Response (201):**
```json
{
  "status": true,
  "message": "Syllabus created successfully",
  "data": {
    "syllabus": {
      "id": 1,
      "batch_id": 5,
      "title": "Class 10 Math - Term 1",
      "start_date": "2025-01-15",
      "end_date": "2025-04-15",
      "total_weeks": 13
    },
    "distribution": [
      {
        "topic_id": 1,
        "week_number": 1,
        "scheduled_date": "2025-01-15"
      },
      {
        "topic_id": 2,
        "week_number": 2,
        "scheduled_date": "2025-01-22"
      }
      // ... more topics
    ],
    "summary": {
      "total_topics": 10,
      "total_weeks": 13,
      "topics_per_week": 0.77
    }
  }
}
```

**Validation Rules:**
- `batch_id`: Required, must exist in groups table and be active
- `title`: Required, 3-255 characters
- `start_date`: Required, must be today or future date
- `end_date`: Required, must be after start_date
- `topic_ids`: Required, array of 1-100 topic IDs (must exist in lk_category)
- Date range: Minimum 1 week, maximum 2 years

---

### 2. List All Syllabi

**Endpoint:** `GET /api/v2/tutor/syllabus`

**Description:** Get all syllabi for the authenticated teacher (paginated).

**Query Parameters:**
- `batch_id` (optional): Filter by batch ID
- `sort_by` (optional): Sort column (default: created_at)
- `sort_order` (optional): asc or desc (default: desc)
- `per_page` (optional): Items per page (default: 15)

**cURL Example:**
```bash
curl --location 'http://localhost:8000/api/v2/tutor/syllabus?batch_id=5&per_page=10' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Syllabi retrieved successfully",
  "data": [
    {
      "id": 1,
      "batch_id": 5,
      "batch_name": "Class 10 - Science Batch",
      "title": "Class 10 Math - Term 1",
      "start_date": "2025-01-15",
      "end_date": "2025-04-15",
      "total_weeks": 13,
      "completion_percentage": 30.0,
      "total_topics": 10,
      "completed_topics": 3,
      "is_active": true,
      "has_started": true,
      "has_ended": false,
      "current_week": 5,
      "created_by": {
        "id": 2,
        "name": "John Teacher"
      },
      "created_at": "2025-01-10 10:30:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 15,
    "total": 5,
    "last_page": 1
  }
}
```

---

### 3. Get Single Syllabus

**Endpoint:** `GET /api/v2/tutor/syllabus/{id}`

**Description:** Get detailed information about a specific syllabus including all topics.

**cURL Example:**
```bash
curl --location 'http://localhost:8000/api/v2/tutor/syllabus/1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Syllabus retrieved successfully",
  "data": {
    "id": 1,
    "batch_id": 5,
    "batch_name": "Class 10 - Science Batch",
    "title": "Class 10 Math - Term 1",
    "start_date": "2025-01-15",
    "end_date": "2025-04-15",
    "total_weeks": 13,
    "completion_percentage": 30.0,
    "total_topics": 10,
    "completed_topics": 3,
    "pending_topics": 7,
    "is_active": true,
    "has_started": true,
    "has_ended": false,
    "current_week": 5,
    "created_by": {
      "id": 2,
      "name": "John Teacher"
    },
    "created_at": "2025-01-10 10:30:00",
    "updated_at": "2025-01-10 10:30:00",
    "topics": [
      {
        "syllabus_topic_id": 1,
        "topic_id": 101,
        "topic_name": "Algebra Basics",
        "topic_title": "Introduction to Algebra",
        "week_number": 1,
        "scheduled_date": "2025-01-15",
        "is_completed": true,
        "completed_at": "2025-01-16 14:30:00",
        "test_generated": false,
        "is_overdue": false,
        "is_today": false,
        "is_upcoming": false
      },
      {
        "syllabus_topic_id": 2,
        "topic_id": 102,
        "topic_name": "Linear Equations",
        "topic_title": "Solving Linear Equations",
        "week_number": 2,
        "scheduled_date": "2025-01-22",
        "is_completed": false,
        "completed_at": null,
        "test_generated": false,
        "is_overdue": true,
        "is_today": false,
        "is_upcoming": false
      }
    ]
  }
}
```

---

### 4. Update Syllabus

**Endpoint:** `PUT /api/v2/tutor/syllabus/{id}`

**Description:** Update an existing syllabus. If dates or topics are changed, the distribution is recalculated automatically.

**Request Body (all fields optional):**
```json
{
  "batch_id": 6,
  "title": "Class 10 Math - Term 1 (Updated)",
  "start_date": "2025-01-20",
  "end_date": "2025-05-15",
  "topic_ids": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
}
```

**cURL Example:**
```bash
curl --location --request PUT 'http://localhost:8000/api/v2/tutor/syllabus/1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "title": "Class 10 Math - Term 1 (Updated)",
  "end_date": "2025-05-15"
}'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Syllabus updated successfully",
  "data": {
    "id": 1,
    "batch_id": 5,
    "title": "Class 10 Math - Term 1 (Updated)",
    "start_date": "2025-01-15",
    "end_date": "2025-05-15",
    "total_weeks": 17,
    "total_topics": 10
  }
}
```

---

### 5. Delete Syllabus

**Endpoint:** `DELETE /api/v2/tutor/syllabus/{id}`

**Description:** Soft delete a syllabus (can be restored later).

**cURL Example:**
```bash
curl --location --request DELETE 'http://localhost:8000/api/v2/tutor/syllabus/1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Syllabus deleted successfully"
}
```

---

## Day 3: Auto-Distribution Algorithm

### How It Works

The `TopicDistributionService` automatically distributes topics across the syllabus date range:

1. **Calculate Total Weeks:** Based on start_date and end_date
2. **Even Distribution:**
   - If topics ≤ weeks: Spread topics evenly (some weeks will have no topics)
   - If topics > weeks: Multiple topics per week
3. **Weekday Preference:** Topics are scheduled on weekdays (Monday-Friday)
4. **Avoid Conflicts:** Each topic gets a unique date when possible

### Distribution Examples

**Example 1: 10 topics, 13 weeks**
- Distribution: 1 topic every ~1.3 weeks
- Topics spread evenly across the date range

**Example 2: 20 topics, 13 weeks**
- Distribution: ~1-2 topics per week
- Multiple topics scheduled in same week on different days

**Example 3: 5 topics, 16 weeks**
- Distribution: 1 topic every ~3 weeks
- Large gaps between topics

The algorithm runs automatically when you create or update a syllabus.

---

## Day 4: Weekly Schedule View

### 1. Get Weekly View

**Endpoint:** `GET /api/v2/tutor/syllabus/{id}/weekly`

**Description:** Get topics scheduled for a specific week with navigation.

**Query Parameters:**
- `week` (optional): Week number (default: current week)

**cURL Example:**
```bash
curl --location 'http://localhost:8000/api/v2/tutor/syllabus/1/weekly?week=3' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Weekly schedule retrieved successfully",
  "data": {
    "syllabus_id": 1,
    "syllabus_title": "Class 10 Math - Term 1",
    "current_week": 3,
    "total_weeks": 13,
    "week_dates": {
      "start": "2025-01-29",
      "end": "2025-02-04"
    },
    "is_current_week": true,
    "topics": [
      {
        "syllabus_topic_id": 3,
        "topic_id": 103,
        "topic_name": "Quadratic Equations",
        "topic_title": "Solving Quadratic Equations",
        "scheduled_date": "2025-01-29",
        "day_of_week": "Wednesday",
        "is_completed": false,
        "completed_at": null,
        "test_generated": false,
        "is_overdue": false,
        "is_today": true
      }
    ],
    "week_completion_percentage": 0,
    "completed_topics_count": 0,
    "total_topics_count": 1,
    "navigation": {
      "has_previous": true,
      "previous_week": 2,
      "has_next": true,
      "next_week": 4
    },
    "overall_completion_percentage": 20.0
  }
}
```

---

### 2. Get Weeks Overview

**Endpoint:** `GET /api/v2/tutor/syllabus/{id}/weeks-overview`

**Description:** Get summary of all weeks in the syllabus.

**cURL Example:**
```bash
curl --location 'http://localhost:8000/api/v2/tutor/syllabus/1/weeks-overview' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Weeks overview retrieved successfully",
  "data": {
    "syllabus_id": 1,
    "syllabus_title": "Class 10 Math - Term 1",
    "total_weeks": 13,
    "current_week": 5,
    "overall_completion_percentage": 30.0,
    "weeks": [
      {
        "week_number": 1,
        "week_dates": {
          "start": "2025-01-15",
          "end": "2025-01-21"
        },
        "is_current_week": false,
        "total_topics": 1,
        "completed_topics": 1,
        "pending_topics": 0,
        "completion_percentage": 100.0
      },
      {
        "week_number": 2,
        "week_dates": {
          "start": "2025-01-22",
          "end": "2025-01-28"
        },
        "is_current_week": false,
        "total_topics": 1,
        "completed_topics": 1,
        "pending_topics": 0,
        "completion_percentage": 100.0
      },
      {
        "week_number": 3,
        "week_dates": {
          "start": "2025-01-29",
          "end": "2025-02-04"
        },
        "is_current_week": false,
        "total_topics": 1,
        "completed_topics": 1,
        "pending_topics": 0,
        "completion_percentage": 100.0
      },
      {
        "week_number": 4,
        "week_dates": {
          "start": "2025-02-05",
          "end": "2025-02-11"
        },
        "is_current_week": false,
        "total_topics": 0,
        "completed_topics": 0,
        "pending_topics": 0,
        "completion_percentage": 0
      },
      {
        "week_number": 5,
        "week_dates": {
          "start": "2025-02-12",
          "end": "2025-02-18"
        },
        "is_current_week": true,
        "total_topics": 1,
        "completed_topics": 0,
        "pending_topics": 1,
        "completion_percentage": 0
      }
    ]
  }
}
```

---

## Day 5: Topic Completion Tracking

### 1. Mark Topic Complete

**Endpoint:** `POST /api/v2/tutor/syllabus-topics/{id}/complete`

**Description:** Mark a syllabus topic as completed. Automatically updates the syllabus completion percentage.

**cURL Example:**
```bash
curl --location --request POST 'http://localhost:8000/api/v2/tutor/syllabus-topics/3/complete' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Topic marked as completed successfully",
  "data": {
    "syllabus_topic_id": 3,
    "topic_id": 103,
    "topic_name": "Quadratic Equations",
    "is_completed": true,
    "completed_at": "2025-02-12 15:45:30",
    "syllabus_completion_percentage": 40.0
  }
}
```

---

### 2. Mark Topic Incomplete

**Endpoint:** `POST /api/v2/tutor/syllabus-topics/{id}/incomplete`

**Description:** Unmark a completed topic (useful for corrections).

**cURL Example:**
```bash
curl --location --request POST 'http://localhost:8000/api/v2/tutor/syllabus-topics/3/incomplete' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Topic marked as incomplete successfully",
  "data": {
    "syllabus_topic_id": 3,
    "topic_id": 103,
    "topic_name": "Quadratic Equations",
    "is_completed": false,
    "completed_at": null,
    "syllabus_completion_percentage": 30.0
  }
}
```

---

### 3. Bulk Mark Complete

**Endpoint:** `POST /api/v2/tutor/syllabus-topics/bulk-complete`

**Description:** Mark multiple topics as completed in one request.

**Request Body:**
```json
{
  "topic_ids": [1, 2, 3, 4, 5]
}
```

**cURL Example:**
```bash
curl --location 'http://localhost:8000/api/v2/tutor/syllabus-topics/bulk-complete' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "topic_ids": [1, 2, 3]
}'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Bulk completion completed. 3 topics marked as complete.",
  "data": {
    "success_count": 3,
    "failed_count": 0,
    "updated_topics": [
      {
        "syllabus_topic_id": 1,
        "topic_id": 101,
        "topic_name": "Algebra Basics",
        "completed_at": "2025-02-12 16:00:00"
      },
      {
        "syllabus_topic_id": 2,
        "topic_id": 102,
        "topic_name": "Linear Equations",
        "completed_at": "2025-02-12 16:00:00"
      },
      {
        "syllabus_topic_id": 3,
        "topic_id": 103,
        "topic_name": "Quadratic Equations",
        "completed_at": "2025-02-12 16:00:00"
      }
    ],
    "failed_topics": []
  }
}
```

**Validation Rules:**
- `topic_ids`: Required, array of 1-50 syllabus topic IDs
- Maximum 50 topics can be marked at once

---

### 4. Get Syllabus Progress

**Endpoint:** `GET /api/v2/tutor/syllabus/{id}/progress`

**Description:** Get comprehensive progress information for a syllabus.

**cURL Example:**
```bash
curl --location 'http://localhost:8000/api/v2/tutor/syllabus/1/progress' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

**Success Response (200):**
```json
{
  "status": true,
  "message": "Syllabus progress retrieved successfully",
  "data": {
    "syllabus_id": 1,
    "syllabus_title": "Class 10 Math - Term 1",
    "completion_percentage": 30.0,
    "total_topics": 10,
    "completed_topics": 3,
    "pending_topics": 7,
    "overdue_topics_count": 2,
    "upcoming_topics_count": 1,
    "current_week": 5,
    "total_weeks": 13,
    "completion_timeline": [
      {
        "topic_id": 101,
        "topic_name": "Algebra Basics",
        "scheduled_date": "2025-01-15",
        "completed_at": "2025-01-16 14:30:00",
        "week_number": 1
      },
      {
        "topic_id": 102,
        "topic_name": "Linear Equations",
        "scheduled_date": "2025-01-22",
        "completed_at": "2025-01-24 10:15:00",
        "week_number": 2
      },
      {
        "topic_id": 103,
        "topic_name": "Quadratic Equations",
        "scheduled_date": "2025-01-29",
        "completed_at": "2025-02-01 09:45:00",
        "week_number": 3
      }
    ],
    "overdue_topics": [
      {
        "syllabus_topic_id": 4,
        "topic_id": 104,
        "topic_name": "Polynomials",
        "scheduled_date": "2025-02-05",
        "week_number": 4,
        "days_overdue": 7
      },
      {
        "syllabus_topic_id": 5,
        "topic_id": 105,
        "topic_name": "Trigonometry Basics",
        "scheduled_date": "2025-02-12",
        "week_number": 5,
        "days_overdue": 0
      }
    ],
    "upcoming_topics": [
      {
        "syllabus_topic_id": 6,
        "topic_id": 106,
        "topic_name": "Statistics",
        "scheduled_date": "2025-02-19",
        "week_number": 6,
        "days_until": 7
      }
    ]
  }
}
```

---

## Database Schema

### `syllabi` Table

| Column | Type | Description |
|--------|------|-------------|
| id | BIGINT UNSIGNED | Primary key |
| batch_id | BIGINT UNSIGNED | Foreign key to groups table |
| title | VARCHAR(255) | Syllabus title |
| start_date | DATE | Start date |
| end_date | DATE | End date |
| total_weeks | INT | Total weeks (auto-calculated) |
| created_by | BIGINT UNSIGNED | Foreign key to users table |
| completion_percentage | DECIMAL(5,2) | Overall completion (0-100) |
| deleted_at | TIMESTAMP | Soft delete timestamp |
| created_at | TIMESTAMP | Creation timestamp |
| updated_at | TIMESTAMP | Last update timestamp |

**Indexes:**
- `idx_syllabi_batch_id` on `batch_id`
- `idx_syllabi_created_by` on `created_by`
- `idx_syllabi_start_date` on `start_date`
- `idx_syllabi_end_date` on `end_date`
- `idx_syllabi_deleted_at` on `deleted_at`

---

### `syllabus_topics` Table

| Column | Type | Description |
|--------|------|-------------|
| id | BIGINT UNSIGNED | Primary key |
| syllabus_id | BIGINT UNSIGNED | Foreign key to syllabi table |
| topic_id | BIGINT UNSIGNED | Foreign key to lk_category table |
| week_number | INT | Week number (1-based) |
| scheduled_date | DATE | Specific date for this topic |
| is_completed | BOOLEAN | Completion status |
| completed_at | TIMESTAMP | When completed |
| test_generated | BOOLEAN | Whether test was generated |
| created_at | TIMESTAMP | Creation timestamp |
| updated_at | TIMESTAMP | Last update timestamp |

**Indexes:**
- `idx_syllabus_topics_syllabus_id` on `syllabus_id`
- `idx_syllabus_topics_topic_id` on `topic_id`
- `idx_syllabus_topics_week_number` on `week_number`
- `idx_syllabus_topics_scheduled_date` on `scheduled_date`
- `idx_syllabus_topics_is_completed` on `is_completed`
- `idx_syllabus_topics_syllabus_week` on `(syllabus_id, week_number)`
- `idx_syllabus_topics_syllabus_completed` on `(syllabus_id, is_completed)`

**Unique Constraints:**
- `unique_syllabus_topic` on `(syllabus_id, topic_id)`

---

## Migration Instructions

### Step 1: Run Migrations

```bash
php artisan migrate
```

This will create the following tables:
- `syllabi`
- `syllabus_topics`

### Step 2: Verify Tables

```bash
php artisan tinker
```

```php
// Check if tables exist
Schema::hasTable('syllabi');
Schema::hasTable('syllabus_topics');

// Check columns
Schema::getColumnListing('syllabi');
Schema::getColumnListing('syllabus_topics');
```

### Step 3: Test API Endpoints

Use the cURL examples above to test each endpoint.

---

## Error Responses

### 400 Bad Request
```json
{
  "status": false,
  "message": "Invalid week number. Must be between 1 and 13"
}
```

### 401 Unauthorized
```json
{
  "status": false,
  "message": "Unauthenticated."
}
```

### 403 Forbidden
```json
{
  "status": false,
  "message": "Unauthorized. Only teachers and admins can create syllabi."
}
```

### 404 Not Found
```json
{
  "status": false,
  "message": "No query results for model [App\\Models\\Syllabus] 999"
}
```

### 422 Validation Error
```json
{
  "status": false,
  "message": "Validation failed",
  "errors": {
    "title": [
      "Syllabus title is required."
    ],
    "start_date": [
      "Start date must be today or a future date."
    ],
    "topic_ids": [
      "At least one topic must be selected."
    ]
  }
}
```

### 500 Internal Server Error
```json
{
  "status": false,
  "message": "Failed to create syllabus",
  "error": "Database connection error"
}
```

---

## Features Summary

### ✅ Day 1-2: CRUD Operations
- Create syllabus with validation
- List all syllabi (with pagination and filters)
- Get single syllabus with topics
- Update syllabus (recalculates distribution if needed)
- Soft delete syllabus

### ✅ Day 3: Auto-Distribution
- Automatic topic distribution across date range
- Even spacing algorithm
- Weekday preference
- Handles all edge cases (more topics than weeks, fewer topics than weeks)

### ✅ Day 4: Weekly View
- Weekly schedule with navigation
- Current week highlighting
- Week-by-week progress tracking
- Weeks overview for planning

### ✅ Day 5: Completion Tracking
- Mark individual topics complete/incomplete
- Bulk completion
- Automatic completion percentage calculation
- Overdue topic detection
- Upcoming topics preview
- Completion timeline

---

## Next Steps

1. **Run migrations** to create database tables
2. **Test endpoints** using the provided cURL examples
3. **Import into Postman** for easier testing
4. **Integrate with frontend** using the API responses
5. **Add test generation** feature (link completed topics to test creation)

---

## Support

For issues or questions, please contact the development team or create an issue in the project repository.

---

**Version:** 1.0
**Last Updated:** 2025-11-14
**Author:** Claude AI Assistant