.. SPDX-License-Identifier: GPL-3.0-or-later

==================
Class Check-in API
==================

1. Manually Create a Check-in Session
-------------------------------------

.. code:: bash

   POST /api/v1/checkin-sessions

Body:

.. code:: json

   {
     "occurrence_id": 345,
     "remark": "Created before class"
   }

Notes:

-  The course teacher or ``superadmin/secretary/assistant`` may call
   this endpoint.
-  Each call creates one ``CheckinSession`` for a single
   ``CourseOccurrence``.
-  Creating a session repeatedly for the same ``occurrence`` does not
   generate duplicate data. The endpoint returns the existing session
   and marks ``created=false``.

Example response:

.. code:: json

   {
     "code": 0,
     "message": "checkin session created",
     "data": {
       "created": true,
       "session": {
         "id": 101,
         "course_id": 12,
         "occurrence_id": 345,
         "session_date": "2026-03-09",
         "sections": [1, 2],
         "status": "draft"
       }
     }
   }

2. Check-in Session List
------------------------

.. code:: bash

   GET /api/v1/checkin-sessions

Query (optional):

-  ``course_id``
-  ``classroom_id``
-  ``status``
-  ``date`` (single day)
-  ``start_date`` / ``end_date``

Permissions:

-  ``superadmin/secretary/assistant``: view all sessions.
-  Teachers: view only sessions for courses they teach.

3. Get Today’s Check-in Sessions
--------------------------------

.. code:: bash

   GET /api/v1/checkin-sessions/daily

Notes: returns today’s courses and check-in status. Permissions are the
same as the list endpoint.

4. Open a Check-in Session
--------------------------

.. code:: bash

   POST /api/v1/checkin-sessions/{id}/open

Permission: course teacher or ``superadmin/secretary/assistant``.

Notes: changes the session status from ``draft`` to ``open``, allowing
students to check in.

5. Get Roster
-------------

Get the class student roster for a session and each student’s check-in
status.

.. code:: bash

   GET /api/v1/checkin-sessions/{id}/roster

Permission: course teacher or ``superadmin/secretary/assistant``.

Response:

.. code:: json

   {
     "code": 0,
     "message": "success",
     "data": {
       "session": {
         "id": 101,
         "course": {
           "id": 12,
           "name": "Calculus",
           "course_code": "MATH101",
           "teacher": 88,
           "teacher_name": "Jane Miller",
           "class_name": "CS 2024"
         },
         "course_id": 12,
         "occurrence": {
           "id": 345,
           "classroom": {
             "id": 121,
             "room_number": "C317",
             "building": "5A"
           },
           "classroom_id": 121,
           "occurrence_date": "2026-03-09",
           "weekday": "MONDAY",
           "sections": [1, 2],
           "start_time": "08:00",
           "end_time": "09:40",
           "status": "scheduled",
           "source_type": "generated",
           "remark": ""
         },
         "occurrence_id": 345,
         "course_session": {
           "id": 345,
           "classroom": {
             "id": 121,
             "room_number": "C317",
             "building": "5A"
           },
           "classroom_id": 121,
           "occurrence_date": "2026-03-09",
           "weekday": "MONDAY",
           "sections": [1, 2],
           "start_time": "08:00",
           "end_time": "09:40",
           "status": "scheduled",
           "source_type": "generated",
           "remark": ""
         },
         "course_session_id": 345,
         "classroom": {
           "id": 121,
           "building": "5A",
           "room_number": "C317",
           "capacity": 60,
           "equipment": {
             "projector": true
           },
           "status": "available",
           "last_maintenance": null,
           "remark": ""
         },
         "classroom_id": 121,
         "session_date": "2026-03-09",
         "sections": [1, 2],
         "status": "open",
         "session_code": "ABC123",
         "opened_at": "2026-03-09T08:00:00+08:00",
         "closed_at": null,
         "created_by": 88,
         "remark": "Created before class",
         "created_at": "2026-03-09T07:55:00+08:00",
         "updated_at": "2026-03-09T08:00:00+08:00"
       },
       "roster": [
         {
           "student_id": 2001,
           "full_name": "John Smith",
           "user_code": "2024123456",
           "user_code_last4": "3456",
           "student_class": "CS 2024",
           "status": "present",
           "checkin_time": "2026-03-09T08:05:00+08:00",
           "remark": "",
           "record_id": 101
         }
       ]
     }
   }

6. Update Student Check-in Status in Real Time
----------------------------------------------

.. code:: bash

   POST /api/v1/checkin-sessions/{id}/toggle-status

Permission: course teacher or ``superadmin/secretary/assistant``.

Body:

.. code:: json

   {
     "student_id": 2001,
     "status": "present",
     "remark": ""
   }

Notes: ``status`` supports ``present/late/absent/leave``.

7. Check-in Record List
-----------------------

.. code:: bash

   GET /api/v1/checkin-records

Query (optional):

-  ``session_id``
-  ``student_id``
-  ``status``

Permissions:

-  ``superadmin/secretary/assistant``: view all records.
-  Teachers: view only check-in records for courses they teach.
-  Students: view only their own check-in records.

8. Student View of Daily Courses and Check-in Status
----------------------------------------------------

.. code:: bash

   GET /api/v1/checkin-records/my-schedule

Query:

-  ``date`` (required, format ``YYYY-MM-DD``)

Permission: student role.

Response:

.. code:: json

   {
     "code": 0,
     "message": "success",
     "data": {
       "date": "2026-03-09",
       "courses": [
         {
           "session_id": 101,
           "course_name": "Calculus",
           "course_code": "MATH101",
           "classroom": "5A C317",
           "sections": [1, 2],
           "status": "present",
           "checkin_time": "2026-03-09T08:05:00+08:00",
           "session_status": "open"
         }
       ]
     }
   }

9. Manual Check-in by Teacher
-----------------------------

.. code:: bash

   POST /api/v1/checkin-records/manual

Body:

.. code:: json

   {
     "session_id": 101,
     "student_id": 2001,
     "status": "present",
     "remark": ""
   }

Notes:

-  Only the course teacher or ``superadmin/secretary/assistant`` may
   call this endpoint.
-  ``status`` supports ``present/late/absent/leave``.