# Gradebooks API

The Gradebooks module manages student grades, report cards, and academic progress.

## Models

### Gradebook

Main gradebook record linking student to academic period:

```json
{
  "id": "uuid",
  "student_id": "student-uuid",
  "student": {...},
  "academic_session_id": "session-uuid",
  "semester_id": "semester-uuid",
  "class_id": "class-uuid",
  "status": "active",
  "overall_grade": "A",
  "overall_score": 92.5,
  "team_id": "team-uuid"
}
```

### GradebookCourse

Per-course grades within a gradebook:

```json
{
  "id": "uuid",
  "gradebook_id": "gradebook-uuid",
  "student_id": "student-uuid",
  "course_id": "course-uuid",
  "final_score": 88.5,
  "final_grade": "B+",
  "subject_id": "subject-uuid"
}
```

### Assessment

Individual assignments/tests:

```json
{
  "id": "uuid",
  "name": "Midterm Exam",
  "course_id": "course-uuid",
  "max_score": 100,
  "weight": 30,
  "due_date": "2024-03-15",
  "category_id": "category-uuid"
}
```

### AssessmentResult

Student scores on assessments:

```json
{
  "id": "uuid",
  "assessment_id": "assessment-uuid",
  "student_id": "student-uuid",
  "score": 85,
  "grade": "B",
  "submitted_at": "2024-03-14T10:00:00Z"
}
```

## Endpoints

### Gradebook CRUD

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/gradebooks/list` | List gradebooks |
| GET | `/api/gradebooks/:id` | Get gradebook |
| POST | `/api/gradebooks` | Create gradebook |
| PUT | `/api/gradebooks/:id` | Update gradebook |

### Student Reports

**Get Student Report:**

`GET /api/gradebooks/student/:student_id/report`

**Response:**
```json
{
  "student": {...},
  "academic_session": {...},
  "subjects": [
    {
      "subject": "Mathematics",
      "course_grade": "A",
      "assessments": [
        {"name": "Quiz 1", "score": 95, "max": 100},
        {"name": "Midterm", "score": 88, "max": 100}
      ]
    }
  ],
  "overall_gpa": 3.8
}
```

### Class Summary

**Get Class Summary:**

`GET /api/gradebooks/class/:class_id/summary`

### Subject Statistics

**Get Subject Statistics:**

`GET /api/gradebooks/subject/:subject_id/statistics`

## Report Cards

### Generate Report Card

**Endpoint:** `POST /api/gradebooks/:id/report-card/generate`

Triggers async report card generation.

### Check Generation Status

**Endpoint:** `GET /api/gradebooks/:id/report-card/status`

### Download Report Card

**Endpoint:** `GET /api/gradebooks/:id/report-card`

Returns PDF report card.

## Assessment Results

### List Results for Assessment

`GET /api/assessment_results/assessment/:assessment_id`

### Get Statistics

`GET /api/assessment_results/assessment/:assessment_id/stats`

**Response:**
```json
{
  "assessment": {...},
  "statistics": {
    "count": 30,
    "average": 78.5,
    "median": 80,
    "min": 45,
    "max": 98,
    "std_dev": 12.3
  }
}
```

### Student Course Results

`GET /api/assessment_results/student/:student_id/course/:course_id`

## Grade Calculation

### Calculate Course Grade

`POST /api/gradebook_courses/calculate`

Recalculates grades based on assessments and weights.

### Recalculate Student Grades

`POST /api/gradebook_courses/student/:student_id/recalculate`

## Grade Scales

Define grading scales:

```json
{
  "id": "uuid",
  "name": "Standard Scale",
  "ranges": [
    {"min": 90, "max": 100, "grade": "A", "gpa": 4.0},
    {"min": 80, "max": 89, "grade": "B", "gpa": 3.0},
    {"min": 70, "max": 79, "grade": "C", "gpa": 2.0}
  ]
}
```