# Panduan Lengkap — Pembuat Jadwal Otomatis

> Sistem sekolah digital — Modul Jadwal Otomatis

---

## Gambaran Umum

Sistem ini menghasilkan jadwal pelajaran secara otomatis menggunakan algoritma *constraint-based scheduling* dengan pendekatan block-centric. Engine bekerja dalam 4 fase utama:

1. **Placement Phase** — menempatkan blok dengan 1000 percobaan multi-attempt
2. **Repair Phase** — memperbaiki blok yang gagal (normal → deep → relax HC7 → relax HC6)
3. **Swap Phase** — optimasi hill-climbing untuk distribusi yang lebih merata
4. **Save** — menyimpan hasil ke database

**Target:** 95–100% jam terjadwal otomatis, sisanya bisa diselesaikan manual.

---

## Constraint yang Diterapkan

| Kode | Jenis | Deskripsi |
|------|-------|-----------|
| HC1 | Hard | Guru tidak boleh mengajar 2 kelas di slot yang sama |
| HC2 | Hard | Kelas tidak boleh punya 2 pelajaran di slot yang sama |
| HC3 | Hard | Guru tidak boleh dijadwalkan di slot yang diblokir |
| HC4 | Hard | Slot harus bertipe KBM |
| HC5 | Hard | Blok 2+ jam harus kontigu (berurutan, tidak terpisah) |
| HC6 | **Soft** | Guru tidak melebihi max jam/hari (boleh dilanggar saat last-resort) |
| HC7 | **Soft** | Mapel yang sama tidak 2x sehari per kelas (boleh dilanggar saat last-resort) |
| HC8 | Hard | Blok dari load yang sama tidak boleh di hari yang sama |

---

## Langkah-Langkah Penggunaan

### Langkah 1 — Konfigurasi Slot Waktu `/schedule-timeslot`

1. Buka menu **Slot Waktu**
2. Pilih hari (Senin, Selasa, dst.)
3. Tambahkan slot dengan klik tombol **Tambah Slot**:
   - **Tipe KBM** = jam pelajaran aktif → ini yang diisi generator
   - **Tipe Istirahat/Upacara/Keagamaan** = tidak diisi generator, hanya informatif
4. Isi: Nomor Slot, Label (misal "Jam 1"), Jam Mulai, Jam Selesai
5. Gunakan **Salin ke Hari Lain** agar tidak input ulang per hari
6. Aktifkan/nonaktifkan slot dengan toggle tanpa perlu hapus

**Contoh konfigurasi umum (7 slot KBM per hari):**
```
Slot 0: 07.00–07.45  Upacara (Senin) / KBM 1 (hari lain)
Slot 1: 07.45–08.30  KBM 1
Slot 2: 08.30–09.15  KBM 2
Slot 3: 09.15–10.00  KBM 3
Slot 4: 10.00–10.15  Istirahat
Slot 5: 10.15–11.00  KBM 4
Slot 6: 11.00–11.45  KBM 5
Slot 7: 11.45–12.30  KBM 6
```

---

### Langkah 2 — Input Beban Mengajar `/schedule-load`

1. Buka menu **Beban Mengajar**
2. Pilih guru dari daftar
3. Pilih mata pelajaran yang diajarkan
4. Centang kelas-kelas yang diajar (bisa multi-kelas sekaligus)
5. Isi **Jam/Minggu** (berapa jam per minggu untuk setiap kelas)
6. Atur **Split Config** — cara pemisahan blok jam:
   - `2,2` → jadwalkan sebagai 2 blok × 2 jam di hari berbeda
   - `3,1` → jadwalkan sebagai 1 blok 3 jam + 1 blok 1 jam
   - `2,1,1` → 1 blok 2 jam + 2 blok 1 jam
   - Kosong → jadwalkan sebagai 1 blok utuh
7. Klik **Simpan**

**Tips beban mengajar:**
- Total jam semua kelas tidak boleh > total slot KBM yang tersedia
- Split 2,2 lebih mudah dijadwalkan daripada 3,1
- Hindari split_config yang melebihi 3 blok per load

---

### Langkah 3 — Set Ketersediaan Guru `/schedule-availability`

1. Buka menu **Ketersediaan Guru**
2. Klik nama guru untuk membuka pengaturan
3. **Tab "Batas Jam/Hari"**: Atur maksimal jam mengajar per hari untuk guru ini (default: 6 jam)
4. **Tab "Slot Tidak Tersedia"**: Klik sel slot yang ingin diblokir
   - 🟢 Hijau = tersedia → klik untuk memblokir
   - 🔴 Merah = diblokir → klik untuk membuka kembali
   - ⬜ Abu-abu = non-KBM (tidak perlu diblokir)
5. Gunakan tombol **Blokir Hari** untuk memblokir seluruh hari sekaligus
6. Klik **Simpan Ketersediaan** setelah selesai

**Perhatian:** Jangan blokir lebih dari yang diperlukan. Jika guru punya 20 jam beban tapi blokir banyak slot, generator akan kesulitan.

---

### Langkah 4 — Buat Jadwal Baru `/schedule-generator/create`

1. Buka menu **Jadwal Otomatis**
2. Klik **Buat Jadwal Baru**
3. Isi:
   - **Nama Jadwal** (contoh: "Jadwal Semester Ganjil 2025/2026")
   - **Tahun Ajaran**
   - **Semester** (Ganjil/Genap)
   - **Hari Aktif** — centang hari-hari pembelajaran (biasanya Senin–Jumat)
4. Klik **Simpan & Lanjutkan**

---

### Langkah 5 — Validasi & Generate

1. Buka halaman detail jadwal
2. Klik tab **Validasi** → sistem otomatis cek:
   - ✅ OK: slot KBM ada, beban mengajar ada, tidak overload
   - ⚠️ Peringatan: utilisasi tinggi, guru mepet, duplikasi beban
   - ❌ Error: harus diperbaiki dulu sebelum generate
3. Jika validasi ✅, klik tab **Generate**
4. (Opsional) Centang **"Pertahankan entry terkunci"** jika ingin mempertahankan jadwal yang sudah dikunci
5. Klik **Generate Jadwal**
6. Tunggu 5–60 detik tergantung kompleksitas data

---

### Langkah 6 — Tinjau Hasil

Setelah generate selesai:

1. **Tab Unplaced Lessons** — lihat blok yang gagal:
   - 🔒 `TEACHER_BLOCKED` = guru terlalu banyak diblokir → longgarkan ketersediaan
   - 📅 `NO_SLOT` = tidak ada slot KBM kosong → tambah slot KBM
   - ⚙️ `CONSTRAINT` = konflik constraint lain → coba generate ulang

2. **Lihat Grid** — buka tampilan timetable visual:
   - Mode **Master Timetable** = semua kelas dalam satu tabel
   - Mode **Per Kelas** = detail jadwal satu kelas, dengan drag & drop
   - Mode **Per Guru** = detail jadwal satu guru, dengan drag & drop

3. **Drag & Drop Manual**:
   - Klik dan seret entry ke slot kosong
   - Konfirmasi di dialog yang muncul
   - Sistem validasi constraint sebelum menyimpan
   - Entry yang terkunci 🔒 tidak bisa dipindah

4. **Lock Guru** — kunci jadwal guru yang sudah benar:
   - Buka tab **Lock Guru** di detail jadwal
   - Klik **Kunci Semua** pada baris guru
   - Generate ulang — jadwal guru yang dikunci tidak akan diubah

5. **Iterasi** — ulangi langkah 5–6 hingga semua jam terjadwal

---

### Langkah 7 — Publish & Export

1. Setelah puas dengan hasil, klik **Publish** di halaman detail
2. Jadwal berstatus **Published** dan terlihat oleh guru
3. Buka tab **Export**:
   - **Excel Master** = semua kelas dalam 1 file
   - **Excel Per Kelas** = tiap kelas 1 sheet
   - **Excel Per Guru** = tiap guru 1 sheet
   - **PDF** = format landscape A4, siap cetak

---

## Troubleshooting

### Generate hanya menghasilkan 70–80%

**Penyebab umum:**
- Utilisasi slot terlalu tinggi (>92%)
- Banyak guru dengan jam beban tinggi + sedikit hari tersedia
- Split config yang sulit (banyak blok 3 jam)

**Solusi:**
1. Cek tab Validasi → ikuti saran yang ditampilkan
2. Tambah 1–2 slot KBM
3. Longgarkan ketersediaan guru yang bermasalah
4. Generate ulang (ada faktor acak, hasil bisa berbeda tiap run)
5. Kunci yang sudah benar, generate ulang hanya yang belum

### Generate 100% tapi ada blok yang salah posisi

Gunakan drag & drop di grid untuk memindah manual. Kunci setelah dipindah agar tidak berubah saat generate ulang.

### Error validasi "Guru X diblokir terlalu banyak"

Buka `/schedule-availability`, cari guru tersebut, kurangi blokir slot atau tambah jam/hari maksimal.

### Error validasi "Kelas X melebihi kapasitas"

Beban jam mapel di kelas tersebut terlalu banyak. Buka `/schedule-load`, cek total jam di kelas tersebut vs jumlah slot KBM per minggu.

---

## Pertanyaan Umum

**Q: Berapa lama proses generate?**
A: Biasanya 5–30 detik untuk sekolah dengan 10–20 kelas. Timeout set ke 120 detik.

**Q: Apakah bisa generate untuk sebagian kelas saja?**
A: Tidak langsung. Solusinya: kunci jadwal kelas yang sudah benar, generate ulang — engine akan mengisi yang belum terjadwal.

**Q: Apa itu HC6 soft constraint?**
A: Max jam/hari untuk guru adalah soft constraint. Generator berusaha menghormatinya, tapi jika tidak ada pilihan lain (last resort), boleh melebihi dengan catatan di log. Ini sama dengan pendekatan ASc Timetable.

**Q: Bisa export per kelas tertentu saja?**
A: Saat ini export tersedia untuk: semua kelas (master), per kelas (tiap kelas 1 sheet), per guru. Pilih yang sesuai.

**Q: Jadwal yang sudah di-publish bisa digenerate ulang?**
A: Ya. Publish hanya mengubah status tampilan. Generate ulang tetap bisa dilakukan.

---

*Panduan ini tersedia di dalam aplikasi melalui tombol "Panduan" di halaman Jadwal Otomatis.*
