# Session Scheduling

## Purpose

ECOIN treats `course_sessions` as cohorts and `attendance_sessions` as the real class sessions used by attendance, teacher dashboards, student schedule, reminders, and reports.

## Daily Slots

A cohort can now store `daily_slots` with one or two sessions per study day:

- Morning: `09:00 -> 12:00`
- Morning extended: `08:30 -> 12:30`
- Morning + afternoon: `09:00 -> 12:00` and `13:00 -> 16:00`

Each slot may include `label_ar` and `label_fr`.

## Generation Modes

- `sessions_count`: generate from `start_date` until the exact requested number of sessions is reached.
- `date_range`: generate all matching sessions between `start_date` and `end_date`.

The generator uses `Africa/Algiers` and writes `starts_at`, `ends_at`, `session_date`, `start_time`, `end_time`, and `duration_minutes`.

## Safety Rules

- One or two slots per day only.
- Slot duration must be between 30 and 360 minutes.
- `end_time` must be after `start_time`.
- Slots in the same day must not overlap.
- Existing sessions are not replaced unless `replace_existing=true`.
- Replacement cancels safe sessions, but keeps locked sessions and sessions with attendance records.

## Admin Workflow

From cohort edit > `جدول الحصص`:

1. Choose generation mode.
2. Set date range or total sessions count.
3. Pick study days from the scheduling tab.
4. Choose a quick preset or edit daily slots.
5. Preview generated sessions.
6. Generate sessions.
7. Open `/admin/cohorts/{cohort}/sessions` to review the generated timetable.

## Admin Timetable Page

The cohort sessions page shows:

- Total sessions, total hours, scheduled sessions, locked sessions, and cancelled sessions.
- A responsive table with date, time, slot label, status, and actions.
- Safe cancellation for sessions without attendance records.
- Reopen action for cancelled sessions.

Sessions with attendance records or locked status are protected from cancellation.

## Audit Events

Scheduling writes operational audit events when audit logging is enabled:

- `sessions.generated`: new schedule generated for a cohort.
- `sessions.replaced`: existing safe sessions were cancelled and a new schedule was generated.
- `session.cancelled`: one session was cancelled from the admin timetable page.
- `session.reopened`: one cancelled session was reactivated.

## Integration

- Teacher sessions read `attendance_sessions` and support two sessions on the same date.
- Student schedule prefers real generated `attendance_sessions`; if none exist, it falls back to legacy virtual cohort occurrences.
- Cancelled sessions are hidden from the student generated schedule.