# Attendance API

The Attendance module tracks student attendance for classes and courses.

## Model

```json
{
  "id": "uuid",
  "student_id": "student-uuid",
  "student": { "id": "...", "name": "John Doe", "code": "STD001" },
  "class_id": "class-uuid",
  "class": { "id": "...", "name": "Class 10A" },
  "course_id": "course-uuid",
  "course": { "id": "...", "name": "Mathematics" },
  "attendance_date": "2024-01-15",
  "status": "Present",
  "type": "Class",
  "description": "On time",
  "academic_session_id": "session-uuid",
  "timetables_detail_id": "period-uuid",
  "team_id": "team-uuid",
  "created_at": "2024-01-15T08:00:00Z"
}
```

## Status Values

| Status | Description |
|--------|-------------|
| `Present` | Student was present |
| `Late` | Student arrived late |
| `AbsentRequest` | Absent with prior notification |
| `AbsentNoRequest` | Absent without notification |

!!! tip "Frontend Mapping"
    Frontend can use `absent_with_leave` (maps to `AbsentRequest`) and `absent_without_leave` (maps to `AbsentNoRequest`)

## Attendance Types

| Type | Description |
|------|-------------|
| `Class` | Homeroom class attendance |
| `Course` | Subject course attendance |
| `Exam` | Exam attendance |
| `Event` | Event attendance |

## Endpoints

### Standard CRUD Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/attendances` | Create single attendance |
| POST | `/api/attendances/list` | List with pagination |
| GET | `/api/attendances/:id` | Get by ID |
| PUT | `/api/attendances/:id` | Update attendance |
| DELETE | `/api/attendances/:id` | Delete attendance |
| POST | `/api/attendances/export` | Export to Excel |

### Bulk Class Attendance

Create/update attendance for all students in a class.

**Endpoint:** `POST /api/attendances/class-attendance`

**Request:**
```json
{
  "date": "2024-01-15",
  "class_id": "class-uuid",
  "attendances": [
    {
      "student_id": "student-uuid-1",
      "status": "Present",
      "comment": "On time"
    },
    {
      "student_id": "student-uuid-2",
      "status": "Late",
      "comment": "Arrived 10 minutes late"
    },
    {
      "student_id": "student-uuid-3",
      "status": "absent_with_leave",
      "comment": "Sick leave"
    }
  ]
}
```

**Response:**
```json
{
  "success": true,
  "message": "Attendance records created successfully",
  "data": {
    "created": 3,
    "records": [...],
    "duplicates_handled": 0
  }
}
```

### Bulk Course Attendance

Create/update attendance for students in a course.

**Endpoint:** `POST /api/attendances/course-attendance`

**Request:**
```json
{
  "date": "2024-01-15",
  "course_id": "course-uuid",
  "timetables_detail_id": "period-uuid",
  "attendances": [
    {
      "student_id": "student-uuid-1",
      "status": "Present"
    }
  ]
}
```

### Get Student Attendance Details

**Endpoint:** `GET /api/attendances/student/:student_id`

**Query Parameters:**
- `start_date` - Start of date range (YYYY-MM-DD)
- `end_date` - End of date range (YYYY-MM-DD)
- `type` - Filter by attendance type

**Response:**
```json
{
  "success": true,
  "data": {
    "student": { "id": "...", "name": "John Doe" },
    "summary": {
      "total_days": 100,
      "present": 90,
      "late": 5,
      "absent_request": 3,
      "absent_no_request": 2,
      "attendance_rate": 95.0
    },
    "records": [...]
  }
}
```

### Get Attendance Statuses

Get configured attendance statuses for the team.

**Endpoint:** `GET /api/attendances/statuses`

**Response:**
```json
{
  "success": true,
  "data": [
    {"code": "Present", "name": "Present", "color": "#4CAF50"},
    {"code": "Late", "name": "Late", "color": "#FF9800"},
    {"code": "AbsentRequest", "name": "Absent (With Leave)", "color": "#2196F3"},
    {"code": "AbsentNoRequest", "name": "Absent (No Leave)", "color": "#F44336"}
  ]
}
```

### Daily Attendance Status

Get class attendance status for a specific date.

**Endpoint:** `GET /api/attendances/daily-status`

**Query Parameters:**
- `class_id` - Class UUID
- `date` - Date (YYYY-MM-DD)

**Response:**
```json
{
  "success": true,
  "data": {
    "date": "2024-01-15",
    "class": { "id": "...", "name": "Class 10A" },
    "students": [
      {
        "student_id": "...",
        "student_name": "John Doe",
        "student_code": "STD001",
        "status": "Present",
        "attendance_id": "..."
      }
    ],
    "summary": {
      "total": 30,
      "present": 25,
      "late": 2,
      "absent": 3
    }
  }
}
```

### Daily Course Attendance Status

**Endpoint:** `GET /api/attendances/daily-status-course`

**Query Parameters:**
- `course_id` - Course UUID
- `date` - Date (YYYY-MM-DD)

### Attendance Report

Get attendance report for date range.

**Endpoint:** `GET /api/attendances/report`

**Query Parameters:**
- `class_id` or `course_id`
- `start_date`
- `end_date`
- `group_by` - `day`, `week`, `month`

## Attendance Reports

### Courses Without Attendance

Find courses that haven't taken attendance.

**Endpoint:** `GET /api/attendance-reports/missing-attendance`

**Query Parameters:**
- `date` - Date to check
- `academic_session_id` - Academic session

**Response:**
```json
{
  "success": true,
  "data": {
    "courses": [
      {
        "id": "course-uuid",
        "name": "Mathematics 10A",
        "code": "MATH10A",
        "scheduled_periods": 2,
        "attendance_taken": 0
      }
    ],
    "total_missing": 5
  }
}
```

### Export Missing Attendance Report

**Endpoint:** `GET /api/attendance-reports/missing-attendance/export`

Returns Excel file with missing attendance details.

## Filtering

### By Date Range

```json
{
  "filter": {
    "group": "AND",
    "conditions": [
      {"field": "attendance_date", "operator": ">=", "value": "2024-01-01"},
      {"field": "attendance_date", "operator": "<=", "value": "2024-01-31"}
    ]
  }
}
```

### By Status

```json
{
  "filter": {
    "group": "AND",
    "conditions": [
      {"field": "status", "operator": "in", "value": ["AbsentRequest", "AbsentNoRequest"]}
    ]
  }
}
```

### By Class and Date

```json
{
  "filter": {
    "group": "AND",
    "conditions": [
      {"field": "class_id", "operator": "=", "value": "class-uuid"},
      {"field": "attendance_date", "operator": "=", "value": "2024-01-15"}
    ]
  }
}
```

## Duplicate Handling

The API automatically handles duplicates:

1. **Within Request**: Last occurrence wins for duplicate student IDs
2. **Existing Records**: Updates existing attendance for same student/date/class combination

Response indicates duplicates handled:

```json
{
  "data": {
    "created": 25,
    "duplicates_handled": 5,
    "original_count": 30
  }
}
```

## Code Examples

### Take Class Attendance

```javascript
const takeAttendance = async (classId, date, students) => {
  const response = await fetch('/api/attendances/class-attendance', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-Team-ID': teamId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      date: date,
      class_id: classId,
      attendances: students.map(s => ({
        student_id: s.id,
        status: s.status,
        comment: s.comment
      }))
    })
  });

  return response.json();
};
```

### Get Monthly Attendance Summary

```javascript
const getMonthlyAttendance = async (studentId, year, month) => {
  const startDate = `${year}-${month.toString().padStart(2, '0')}-01`;
  const endDate = `${year}-${month.toString().padStart(2, '0')}-31`;

  const response = await fetch(
    `/api/attendances/student/${studentId}?start_date=${startDate}&end_date=${endDate}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'X-Team-ID': teamId
      }
    }
  );

  return response.json();
};
```

## Integration Notes

- Attendance records are automatically linked to the current academic session
- When taking course attendance, the timetable period can be linked for scheduling reference
- Attendance data syncs to Canvas LMS if integration is enabled
- Leave applications can auto-update attendance status when approved