# `checkins` Class Check-ins

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

Last updated: Apr 24, 2026

Corresponding API docs: [Class Check-in API](../../api/checkins.md)

## `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.