# Runbook: Migrasi Data Legacy ke SIPORA (Lewat Staging)

## Konteks penting

Rebuild SIPORA ini **sengaja tidak pernah terhubung langsung ke sistem lama** — baik ke
database produksinya maupun ke arsitekturnya (lihat aturan dasar proyek). Migrasi data
dilakukan lewat **staging**: data dari sistem lama diekspor & diubah bentuk (di luar SIPORA,
oleh siapa pun yang memahami struktur sistem lama) menjadi file CSV dengan format yang
didokumentasikan di sini, baru kemudian dimuat ke SIPORA lewat `tools/import-legacy.php`.

Tool ini **tidak menangani siswa** — struktur sekolah (sekolah, periode, kelas, guru BK,
admin) dibuat lebih dulu lewat tool ini, baru siswa diimpor per-sekolah lewat fitur impor
CSV/XLSX yang sudah ada di halaman `/school/import` (dibangun sejak Fase 1, sudah lengkap
dengan validasi, deteksi duplikat, dan pengecekan kuota).

## Format file staging

Siapkan satu folder berisi hingga 3 file CSV (header wajib ada di baris pertama, nama kolom
tidak case-sensitive):

### `sekolah.csv` (wajib)

| Kolom | Wajib? | Keterangan |
|---|---|---|
| `kode_sekolah` | Ya | Kode unik sekolah, jadi identifier di file lain |
| `nama_sekolah` | Ya | |
| `timezone` | Tidak | Default `Asia/Jakarta` |
| `nama_periode` | Tidak | Default `Periode Awal` — jadi periode default sekolah ini |
| `tanggal_mulai_periode` | Tidak | Format `YYYY-MM-DD`, default 1 Januari tahun berjalan |
| `tanggal_selesai_periode` | Tidak | Format `YYYY-MM-DD`, default 31 Desember tahun berjalan |
| `kuota_siswa` | Tidak | Jika diisi (>0), langsung menetapkan kuota siswa periode ini |
| `username_admin` | Tidak | Jika diisi bersama `email_admin`, langsung membuat akun Admin Sekolah |
| `email_admin` | Tidak | |

### `kelas.csv` (opsional — lewati bila kelas mau dibuat manual/lewat web nanti)

| Kolom | Wajib? | Keterangan |
|---|---|---|
| `kode_sekolah` | Ya | Harus cocok dengan salah satu baris di `sekolah.csv` |
| `kode_kelas` | Ya | |
| `tingkat` | Ya | |
| `nama_kelas` | Tidak | |

### `guru_bk.csv` (opsional)

| Kolom | Wajib? |
|---|---|
| `kode_sekolah` | Ya |
| `kode_guru` | Ya |
| `nama_guru` | Ya |
| `username` | Ya |
| `email` | Ya |

**Contoh isi (data sintetis, bukan data sungguhan)** ada di `storage/legacy-samples/` — lihat
`storage/legacy-samples/README.md` sebelum memakainya untuk apa pun selain menguji tool ini.

## Cara pakai

```bash
# 1. Selalu mulai dengan pratinjau (dry-run) - TIDAK menulis apa pun ke database.
php tools/import-legacy.php --dir=/path/ke/folder/staging

# 2. Setelah pratinjau terlihat benar, jalankan sungguhan.
php tools/import-legacy.php --dir=/path/ke/folder/staging --commit
```

Urutan pemrosesan selalu: **sekolah → kelas → guru BK** (kelas & guru BK butuh sekolahnya
sudah ada). Setiap baris divalidasi lewat fungsi yang SAMA dipakai form web Super Admin
(`create_school()`, `create_period()`, `create_class()`, `create_staff_user()`,
`create_counselor()`) — bukan `INSERT` mentah — jadi semua aturan validasi & audit log yang
sudah ada di aplikasi otomatis berlaku di sini juga.

## Idempotensi (aman dijalankan ulang)

Baris yang datanya SUDAH ADA (dicocokkan lewat kode sekolah/kelas/guru) otomatis dilewati
("sudah ada, dilewati"), tidak membuat duplikat. Ini membuat tool aman dijalankan ulang bila:

- Ada file staging baru yang menambah sekolah/kelas baru ke folder yang sama.
- Proses sebelumnya terhenti di tengah jalan (error jaringan/database) — jalankan ulang
  perintah yang sama, baris yang sudah berhasil tidak akan diulang.

**Batasan yang perlu diketahui:** bila proses terhenti PERSIS di tengah satu baris sekolah
(sekolah & periode sempat dibuat, tapi admin/kuota belum sempat diproses saat error terjadi),
menjalankan ulang akan melewati sekolah itu sepenuhnya (dianggap "sudah ada") tanpa mencoba
melengkapi admin/kuota yang terlewat. Pada kasus ini periksa manual lewat halaman Super Admin
(`/superadmin/schools/{id}`) apakah sekolah itu sudah punya admin & kuota; lengkapi lewat web
bila belum, tool ini tidak dirancang untuk "melanjutkan" baris yang setengah jadi.

## Akun baru yang dibuat: distribusi link aktivasi

Setiap admin sekolah/guru BK yang berhasil dibuat mendapat akun dengan password acak yang
tidak diketahui siapa pun — pemiliknya mengatur password sendiri lewat link aktivasi
(mekanisme sama dengan lupa password). Setelah `--commit` berhasil, tool menulis satu file
laporan CSV ke `storage/legacy-import-reports/legacy-import-<timestamp>.csv` berisi kolom
`type, kode, nama, username, email, activation_link`.

**File ini berisi link aktivasi SEKALI PAKAI — perlakukan seperti kredensial:**

1. Distribusikan tiap link HANYA ke pemilik akun terkait, lewat kanal yang mereka bisa
   verifikasi (bukan grup/broadcast) — mis. WhatsApp/email langsung ke masing-masing.
2. Setelah semua link terdistribusi, **hapus file laporan ini** dari server
   (`storage/legacy-import-reports/`). Direktori ini sudah di-`.gitignore` sehingga tidak
   akan ter-commit ke git, tapi tetap perlu dibersihkan dari disk server.
3. Link yang tidak sempat dipakai (kedaluwarsa) bisa dibuatkan ulang lewat fitur reset
   password biasa di halaman login — tidak perlu menjalankan ulang tool ini.

## Setelah struktur sekolah selesai: impor siswa

Untuk tiap sekolah yang baru dimigrasi, siapkan CSV siswa sesuai format yang sudah ada
(kolom: `nis`, `nisn`, `nama`, `kelas`, `kode_guru_bk`/`nama_guru_bk` opsional,
`jenis_kelamin` opsional) lalu unggah lewat `/school/import` sebagai Admin Sekolah tersebut
(pakai akun yang baru diaktifkan lewat link di atas). Fitur ini sudah menangani validasi,
deteksi siswa duplikat, dan pengecekan kuota secara otomatis — tidak perlu tool tambahan.

## Menguji dengan data sintetis

```bash
php tools/import-legacy.php --dir=storage/legacy-samples
php tools/import-legacy.php --dir=storage/legacy-samples --commit
```

Setelah selesai menguji, bersihkan data sintetis ini dari database (kode sekolah berprefiks
`CONTOH-`) sebelum memakai lingkungan yang sama untuk data sungguhan — jangan biarkan
tercampur.