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

===============
Class Check-ins
===============

Author: Zhenyu Yang <yangzhenyu@sust.edu.cn>

Last updated: Apr 24, 2026

Corresponding API docs: `Class Check-in API <../../api/checkins.rst>`__

``checkins`` Code Entry
-----------------------

-  ``backend/apps/checkins/models/__init__.py``
-  ``backend/apps/checkins/views/__init__.py``
-  ``backend/apps/checkins/serializers/__init__.py``
-  ``backend/apps/checkins/services/__init__.py``

``checkins`` Core Data
----------------------

``CheckinSession``
~~~~~~~~~~~~~~~~~~

-  One-to-one optional relationship with ``CourseOccurrence``.
-  Stores the check-in date, class period, status, check-in code,
   open/close times, creator, and remarks.

``CheckinRecord``
~~~~~~~~~~~~~~~~~

-  Stores a student’s check-in status for a given session.
-  ``(session, student)`` has a unique constraint.
-  Recorded fields include ``status``, ``checkin_time``, ``method``,
   ``source``, ``remark``, and ``confidence``.

Permission Model
----------------

-  Admin roles:

   -  ``superadmin``
   -  ``secretary``
   -  ``assistant``

-  Non-admin users may only manage check-in data for their own courses.
-  Students can only view check-in records and ``my-schedule`` related
   to themselves.

Key Actions
-----------

Creating a Check-in Session
~~~~~~~~~~~~~~~~~~~~~~~~~~~

-  Entry: ``CheckinSessionViewSet.create``
-  Anchored by ``occurrence_id``
-  Idempotent: duplicate creation does not produce a second session.

List & Daily View
~~~~~~~~~~~~~~~~~

-  ``list`` supports filtering by course, classroom, status, and date
   range.
-  ``daily`` returns today’s sessions.
-  On ``list``, ``_update_statuses()`` is called to automatically
   refresh the status of today’s sessions:

   -  30 minutes before class starts until class ends: ``draft -> open``
   -  After class ends: ``draft/open -> closed``

Roster & Check-in
~~~~~~~~~~~~~~~~~

-  ``roster`` assembles the roster by matching
   ``Course.class_name == User.student_class``.
-  ``toggle-status`` is designed for real-time roll call; defaults to
   ``method="manual"``, ``source="miniapp"``.
-  ``manual`` is an alternative manual check-in entry; defaults to
   ``method="manual"``, ``source="web"``.

Student View
~~~~~~~~~~~~

-  ``CheckinRecordViewSet.my_schedule``

   -  View courses and check-in status for the student’s class on a
      given date.

Current Implementation Boundaries
---------------------------------

-  Check-in is still teacher-driven; sessions are not opened
   automatically.
-  Signage devices are not integrated into the check-in write flow.
-  Face recognition check-in fields have been reserved in the data
   model, but they currently serve as placeholders for future expansion.