# `classrooms` Classroom Management

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

Last updated: Apr 24, 2026

Corresponding API docs: [Classroom Management API](../../api/classrooms.md)

## `classrooms` Code Entry

- `backend/apps/classrooms/models/__init__.py`
- `backend/apps/classrooms/views/__init__.py`
- `backend/apps/classrooms/services/__init__.py`

## `classrooms` Core Data

### `Classroom`

- Unique key: `building + room_number`
- Key fields:
  - `capacity`
  - `equipment`
  - `status`
  - `last_maintenance`
  - `remark`

## Read Operations

- `list`, `retrieve`, `free`, and `schedule` all require authentication.
- The list supports filtering by `building`, `capacity_min`, and `status`.
- List sorting prioritizes classrooms with missing or unreasonable capacity values, helping operations staff identify records that need data cleanup.

## `classrooms` Permission Boundaries

- Create classroom: `superadmin` only.
- Update / partial update: `superadmin` or `secretary`.
- Delete classroom: `superadmin` only.
- Excel import: `superadmin` / `secretary` / `assistant`.

## Key Business Rules

### Free Classrooms (`free`)

- Excludes two types of conflicts simultaneously:
  - Manual reservations: `status in (pending, approved)` and `source_type=manual`
  - Course occupancy: computed via `courses.services.get_conflicting_classrooms()`

### Classroom Schedule (`schedule`)

- The time range is expanded to full days.
- Two types of occupancy are merged:
  - Manual reservations
  - Course instances (`CourseOccurrence`)
- Idle time blocks are padded so the frontend can directly render the timeline.
- In the current implementation, `pending` manual reservations are also treated as occupied blocks.

## Import

- Entry: `ClassroomViewSet.import_classrooms`
- File requirements: `.xlsx` / `.xls`, max 50MB.
- Import logic lives in `ClassroomImportService`.
- Supports both creation and update; errors are aggregated and returned.

## `classrooms` and Other Modules

- `borrowings`, `repairs`, and `abuse` reference classrooms via foreign keys.
- `courses` uses classrooms to host course instances.
- `signage` binds one-to-one with a classroom via `SignageDevice`.