# Education Module API Documentation

## Overview

The Education Module API provides comprehensive functionality for educational institutions including student management, class scheduling, enrollment, and Malaysian education system compliance.

## Students

### Create Student
```http
POST /api/v1/education/students/
```

**Request Body:**
```json
{
  "first_name": "Ahmad",
  "last_name": "Bin Hassan",
  "ic_number": "080101-01-1234",
  "date_of_birth": "2008-01-01",
  "gender": "male",
  "email": "ahmad.hassan@student.edu.my",
  "phone_number": "+60123456789",
  "address": {
    "street": "123 Student Street",
    "city": "Kuala Lumpur",
    "state": "Wilayah Persekutuan",
    "postal_code": "50050",
    "country": "Malaysia"
  },
  "parent_guardian": {
    "name": "Hassan Bin Ibrahim",
    "relationship": "father",
    "phone_number": "+60123456788",
    "email": "hassan.ibrahim@example.com",
    "occupation": "Engineer"
  },
  "emergency_contact": {
    "name": "Siti Aminah",
    "relationship": "mother",
    "phone_number": "+60123456787"
  },
  "previous_school": "SK Taman Desa",
  "previous_grade": "Standard 5",
  "admission_date": "2024-01-01",
  "current_grade": "Standard 6",
  "stream": "academic",
  "subjects": ["mathematics", "science", "english", "bahasa_malaysia"],
  "special_needs": [],
  "medical_conditions": ["asthma"],
  "allergies": ["peanuts"],
  "blood_type": "O+",
  "religion": "islam",
  "nationality": "malaysian",
  "scholarship_info": {
    "has_scholarship": false,
    "scholarship_name": null,
    "scholarship_percentage": 0
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "stu_123456",
    "first_name": "Ahmad",
    "last_name": "Bin Hassan",
    "ic_number": "080101-01-1234",
    "date_of_birth": "2008-01-01",
    "gender": "male",
    "email": "ahmad.hassan@student.edu.my",
    "phone_number": "+60123456789",
    "address": {
      "street": "123 Student Street",
      "city": "Kuala Lumpur",
      "state": "Wilayah Persekutuan",
      "postal_code": "50050",
      "country": "Malaysia"
    },
    "parent_guardian": {
      "name": "Hassan Bin Ibrahim",
      "relationship": "father",
      "phone_number": "+60123456788",
      "email": "hassan.ibrahim@example.com",
      "occupation": "Engineer"
    },
    "emergency_contact": {
      "name": "Siti Aminah",
      "relationship": "mother",
      "phone_number": "+60123456787"
    },
    "previous_school": "SK Taman Desa",
    "previous_grade": "Standard 5",
    "admission_date": "2024-01-01",
    "current_grade": "Standard 6",
    "stream": "academic",
    "subjects": ["mathematics", "science", "english", "bahasa_malaysia"],
    "special_needs": [],
    "medical_conditions": ["asthma"],
    "allergies": ["peanuts"],
    "blood_type": "O+",
    "religion": "islam",
    "nationality": "malaysian",
    "scholarship_info": {
      "has_scholarship": false,
      "scholarship_name": null,
      "scholarship_percentage": 0
    },
    "pdpa_consent": true,
    "pdpa_consent_date": "2024-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Student
```http
GET /api/v1/education/students/{student_id}/
```

### Update Student
```http
PUT /api/v1/education/students/{student_id}/
```

### List Students
```http
GET /api/v1/education/students/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `current_grade` - Filter by current grade
- `stream` - Filter by stream (academic, vocational, technical)
- `search` - Search in name, IC number, email
- `gender` - Filter by gender
- `religion` - Filter by religion
- `nationality` - Filter by nationality
- `has_scholarship` - Filter by scholarship status

### Delete Student
```http
DELETE /api/v1/education/students/{student_id}/
```

### Get Student Academic Record
```http
GET /api/v1/education/students/{student_id}/academic-record/
```

## Classes

### Create Class
```http
POST /api/v1/education/classes/
```

**Request Body:**
```json
{
  "name": "6 Bestari",
  "grade_level": "Standard 6",
  "stream": "academic",
  "academic_year": "2024",
  "room_number": "A-101",
  "capacity": 30,
  "current_enrollment": 28,
  "teacher_id": "tch_123456",
  "assistant_teacher_id": "tch_789012",
  "schedule": {
    "monday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
    "tuesday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
    "wednesday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
    "thursday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
    "friday": ["08:00-09:30", "10:00-11:30", "12:30-13:30"]
  },
  "subjects": [
    {
      "name": "Mathematics",
      "teacher_id": "tch_123456",
      "hours_per_week": 5
    },
    {
      "name": "Science",
      "teacher_id": "tch_345678",
      "hours_per_week": 3
    }
  ],
  "special_requirements": ["air_conditioned", "projector"],
  "notes": "Advanced mathematics class"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "cls_123456",
    "name": "6 Bestari",
    "grade_level": "Standard 6",
    "stream": "academic",
    "academic_year": "2024",
    "room_number": "A-101",
    "capacity": 30,
    "current_enrollment": 28,
    "teacher_id": "tch_123456",
    "assistant_teacher_id": "tch_789012",
    "schedule": {
      "monday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
      "tuesday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
      "wednesday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
      "thursday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
      "friday": ["08:00-09:30", "10:00-11:30", "12:30-13:30"]
    },
    "subjects": [
      {
        "name": "Mathematics",
        "teacher_id": "tch_123456",
        "hours_per_week": 5
      },
      {
        "name": "Science",
        "teacher_id": "tch_345678",
        "hours_per_week": 3
      }
    ],
    "special_requirements": ["air_conditioned", "projector"],
    "notes": "Advanced mathematics class",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Class
```http
GET /api/v1/education/classes/{class_id}/
```

### Update Class
```http
PUT /api/v1/education/classes/{class_id}/
```

### List Classes
```http
GET /api/v1/education/classes/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `grade_level` - Filter by grade level
- `stream` - Filter by stream
- `academic_year` - Filter by academic year
- `teacher_id` - Filter by teacher
- `has_space` - Filter by available space (true/false)

### Delete Class
```http
DELETE /api/v1/education/classes/{class_id}/
```

### Get Class Students
```http
GET /api/v1/education/classes/{class_id}/students/
```

### Get Class Schedule
```http
GET /api/v1/education/classes/{class_id}/schedule/
```

## Enrollment

### Enroll Student
```http
POST /api/v1/education/enrollment/
```

**Request Body:**
```json
{
  "student_id": "stu_123456",
  "class_id": "cls_123456",
  "enrollment_date": "2024-01-01",
  "enrollment_type": "new",
  "fees": {
    "tuition_fee": 1200.00,
    "registration_fee": 100.00,
    "material_fee": 200.00,
    "total_fee": 1500.00,
    "payment_plan": "full_payment"
  },
  "scholarship_info": {
    "has_scholarship": false,
    "scholarship_amount": 0.00
  },
  "previous_results": {
    "upsr_result": "5A",
    "previous_school": "SK Taman Desa"
  },
  "documents": [
    {
      "type": "birth_certificate",
      "file_id": "doc_123456"
    },
    {
      "type": "ic_copy",
      "file_id": "doc_789012"
    }
  ],
  "notes": "Excellent mathematics student"
}
```

### Get Enrollment
```http
GET /api/v1/education/enrollment/{enrollment_id}/
```

### Update Enrollment
```http
PUT /api/v1/education/enrollment/{enrollment_id}/
```

### List Enrollments
```http
GET /api/v1/education/enrollment/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `student_id` - Filter by student
- `class_id` - Filter by class
- `enrollment_type` - Filter by enrollment type (new, transfer, returning)
- `status` - Filter by status (active, inactive, graduated)
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)

### Withdraw Student
```http
POST /api/v1/education/enrollment/{enrollment_id}/withdraw/
```

**Request Body:**
```json
{
  "withdrawal_date": "2024-06-01",
  "reason": "Family relocation",
  "destination_school": "SK Putrajaya",
  "refund_amount": 750.00,
  "notes": "Student family moving to Putrajaya"
}
```

## Attendance

### Record Attendance
```http
POST /api/v1/education/attendance/
```

**Request Body:**
```json
{
  "student_id": "stu_123456",
  "class_id": "cls_123456",
  "date": "2024-01-15",
  "status": "present",
  "time_in": "08:00:00",
  "time_out": "14:00:00",
  "remarks": "Student present and on time",
  "recorded_by": "tch_123456"
}
```

### Get Attendance Record
```http
GET /api/v1/education/attendance/{attendance_id}/
```

### Update Attendance
```http
PUT /api/v1/education/attendance/{attendance_id}/
```

### List Attendance
```http
GET /api/v1/education/attendance/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `student_id` - Filter by student
- `class_id` - Filter by class
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `status` - Filter by status (present, absent, late, excused)

### Get Student Attendance Summary
```http
GET /api/v1/education/students/{student_id}/attendance-summary/
```

**Query Parameters:**
- `start_date` - Start date (YYYY-MM-DD)
- `end_date` - End date (YYYY-MM-DD)

## Grades and Assessments

### Record Grade
```http
POST /api/v1/education/grades/
```

**Request Body:**
```json
{
  "student_id": "stu_123456",
  "subject_id": "sub_123456",
  "assessment_type": "midterm",
  "assessment_name": "Mathematics Midterm Exam",
  "score": 85.5,
  "max_score": 100.0,
  "grade": "A",
  "remarks": "Excellent performance",
  "teacher_id": "tch_123456",
  "assessment_date": "2024-03-15"
}
```

### Get Grade
```http
GET /api/v1/education/grades/{grade_id}/
```

### Update Grade
```http
PUT /api/v1/education/grades/{grade_id}/
```

### List Grades
```http
GET /api/v1/education/grades/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `student_id` - Filter by student
- `subject_id` - Filter by subject
- `assessment_type` - Filter by assessment type
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)

### Get Student Report Card
```http
GET /api/v1/education/students/{student_id}/report-card/
```

**Query Parameters:**
- `term` - Academic term
- `year` - Academic year

## Fees and Payments

### Create Fee Structure
```http
POST /api/v1/education/fees/
```

**Request Body:**
```json
{
  "grade_level": "Standard 6",
  "fee_type": "tuition",
  "amount": 1200.00,
  "currency": "MYR",
  "payment_frequency": "annually",
  "academic_year": "2024",
  "description": "Annual tuition fee for Standard 6",
  "is_mandatory": true,
  "scholarship_applicable": true
}
```

### Record Payment
```http
POST /api/v1/education/payments/
```

**Request Body:**
```json
{
  "student_id": "stu_123456",
  "fee_id": "fee_123456",
  "amount": 1200.00,
  "payment_method": "bank_transfer",
  "payment_date": "2024-01-15",
  "transaction_id": "TXN123456789",
  "receipt_number": "REC20240001",
  "notes": "Full payment for annual tuition"
}
```

### Get Payment
```http
GET /api/v1/education/payments/{payment_id}/
```

### List Payments
```http
GET /api/v1/education/payments/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `student_id` - Filter by student
- `fee_id` - Filter by fee
- `payment_method` - Filter by payment method
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)

## Reports and Analytics

### Student Performance Report
```http
GET /api/v1/education/reports/student-performance/
```

**Query Parameters:**
- `class_id` - Filter by class
- `subject_id` - Filter by subject
- `assessment_type` - Filter by assessment type
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)
- `format` - Output format (json, csv, pdf)

### Attendance Report
```http
GET /api/v1/education/reports/attendance/
```

**Query Parameters:**
- `class_id` - Filter by class
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)
- `group_by` - Group by (student, class, grade)
- `format` - Output format (json, csv, pdf)

### Financial Report
```http
GET /api/v1/education/reports/financial/
```

**Query Parameters:**
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)
- "report_type" - Report type (revenue, expenses, profit_loss)
- `format` - Output format (json, csv, pdf)

## Malaysian Education Features

### Malaysian Grade System
Support for Malaysian education grade levels:
- Primary: Standard 1-6
- Lower Secondary: Form 1-3
- Upper Secondary: Form 4-5
- Pre-University: Form 6 / Matriculation

### Malaysian Curriculum
Alignment with Malaysian National Curriculum (KSSR/KSSM):
```json
{
  "malaysian_curriculum": {
    "kssr_level": "standard_6",
    "core_subjects": ["bahasa_malaysia", "english", "mathematics", "science"],
    "elective_subjects": ["arabic", "chinese", "tamil"],
    "moral_education": "islamic_education",
    "physical_education": true,
    "arts_education": true
  }
}
```

### Malaysian Assessment System
Support for Malaysian assessment methods:
- UPSR (Primary School Assessment)
- PT3 (Lower Secondary Assessment)
- SPM (Malaysian Certificate of Education)
- STPM (Malaysian Higher School Certificate)

### Malaysian IC Validation
All student IC numbers are validated according to Malaysian format with age verification.

### PDPA Compliance
All student data handling follows Malaysian Personal Data Protection Act 2010.

### Malaysian Education Ministry Integration
Integration with Malaysian Ministry of Education requirements:
- Student registration
- Teacher qualifications
- School accreditation
- Annual reporting

### Malaysian School Calendar
Support for Malaysian school calendar:
- Academic year structure
- School holidays
- Public holidays
- Examination periods

### Malaysian Languages Support
Multi-language support for Malaysian education:
- Bahasa Malaysia
- English
- Chinese (Mandarin)
- Tamil
- Arabic

### Religious Education
Support for religious education requirements:
- Islamic Education for Muslim students
- Moral Education for non-Muslim students
- Religious holiday considerations

### Special Needs Education
Support for Malaysian special education requirements:
- Inclusive education programs
- Special education schools
- Learning disabilities support
- Individualized Education Plans (IEP)