# Dokumentasi Fitur Mutasi Siswa

## Deskripsi
Fitur mutasi siswa adalah modul untuk mengelola perubahan status dan kelas siswa dalam sistem SISADIK. Fitur ini terdiri dari tiga fungsi utama:

1. **Keluar/Tamat Siswa** - Mengubah status siswa menjadi tidak aktif
2. **Naik Kelas** - Memindahkan siswa ke kelas yang lebih tinggi
3. **Siswa Baru** - Import data siswa baru melalui file Excel

## Struktur File

```
src/app/(main)/dashboard/mutasi-siswa/
├── page.tsx                           # Halaman utama dengan tabs
├── _components/
│   ├── siswa-keluar-form.tsx         # Form untuk keluar/tamat siswa
│   ├── siswa-naik-kelas-form.tsx     # Form untuk naik kelas
│   └── siswa-baru.tsx                # Form untuk import siswa baru
├── _hooks/
│   └── use-kelas.ts                  # Hook untuk mengambil data kelas
└── README.md                         # Dokumentasi ini

src/app/api/
├── siswa/mutasi/route.ts             # API untuk mutasi siswa
└── kelas/route.ts                    # API untuk mengambil daftar kelas
```

## Database Schema

### Model MutasiSiswa
```prisma
model MutasiSiswa {
  id        String      @id @default(cuid())
  siswaId   String
  type      MutasiType
  alasan    String
  tanggal   DateTime    @default(now())
  dariKelas String?
  keKelas   String?
  
  siswa     User        @relation(fields: [siswaId], references: [id])
  
  createdAt DateTime    @default(now())
  updatedAt DateTime    @updatedAt
}

enum MutasiType {
  KELUAR
  TAMAT
  NAIK_KELAS
  PINDAH_KELAS
}

enum UserStatus {
  AKTIF
  KELUAR
  TAMAT
  NONAKTIF
}
```

### Update Model User
Model User telah diupdate dengan field:
- `name` - Nama lengkap user
- `nisn` - NISN untuk siswa
- `kelas` - Kelas siswa
- `status` - Status user (AKTIF, KELUAR, TAMAT, NONAKTIF)
- `jurusanId` - ID Jurusan

## API Endpoints

### 1. GET /api/siswa/mutasi
Mengambil daftar siswa berdasarkan kelas untuk proses mutasi.

**Query Parameters:**
- `kelas` (required) - Nama kelas yang ingin diambil datanya

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": "user_id",
      "name": "Nama Siswa",
      "email": "email@domain.com",
      "nisn": "1234567890",
      "kelas": "X-1",
      "jurusan": {
        "namaJurusan": "Teknik Informatika"
      }
    }
  ],
  "count": 25
}
```

### 2. POST /api/siswa/mutasi
Memproses mutasi siswa (keluar/tamat atau naik kelas).

**Request Body untuk Keluar/Tamat:**
```json
{
  "type": "keluar", // atau "tamat"
  "siswaIds": ["user_id1", "user_id2"],
  "alasan": "Lulus",
  "dariKelas": "XII-1"
}
```

**Request Body untuk Naik Kelas:**
```json
{
  "type": "naik_kelas",
  "siswaIds": ["user_id1", "user_id2"],
  "dariKelas": "X-1",
  "keKelas": "XI-1"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Berhasil memproses 15 siswa",
  "processedCount": 15
}
```

### 3. GET /api/kelas
Mengambil daftar kelas yang tersedia beserta jumlah siswa aktif.

**Query Parameters:** Tidak ada

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "kelas": "X-1",
      "jumlahSiswa": 32
    },
    {
      "kelas": "X-2", 
      "jumlahSiswa": 30
    }
  ]
}
```

**Catatan:** API ini mengambil data kelas yang memiliki siswa aktif dari database, bukan data statis.

## Fitur dan Fungsi

### 1. Keluar/Tamat Siswa
- **Tujuan**: Mengubah status siswa yang keluar atau tamat menjadi tidak aktif
- **Input**:
  - Tipe (Keluar atau Tamat)
  - Kelas asal siswa
  - Alasan keluar/tamat
  - Pilihan siswa yang akan diproses
- **Proses**:
  - Mengubah status user menjadi KELUAR atau TAMAT
  - Menyimpan log mutasi ke tabel MutasiSiswa
  - Siswa tidak akan muncul lagi di pencarian siswa aktif

### 2. Naik Kelas
- **Tujuan**: Memindahkan siswa dari satu kelas ke kelas lain
- **Input**:
  - Kelas asal
  - Kelas tujuan
  - Pilihan siswa yang akan naik kelas
- **Proses**:
  - Mengubah field kelas pada user
  - Menyimpan log mutasi dengan detail perpindahan
  - Siswa akan muncul di kelas baru

### 3. Siswa Baru (Import)
- **Tujuan**: Menambahkan siswa baru melalui file Excel
- **Format File**: 
  - username (wajib, unik)
  - password (wajib)
  - name (wajib)
  - nisn (wajib, unik)
  - kelas (wajib)
  - email (opsional)
  - jurusanId (opsional)
- **Proses**:
  - Validasi format file dan data
  - Hash password secara otomatis
  - Generate email default jika tidak diisi
  - Buat user baru dengan status AKTIF

## Validasi dan Error Handling

### Validasi Input
1. **Kelas**: Harus dipilih sebelum mencari siswa
2. **Siswa**: Minimal satu siswa harus dipilih
3. **Alasan**: Wajib untuk keluar/tamat
4. **Kelas Tujuan**: Wajib untuk naik kelas, tidak boleh sama dengan kelas asal

### Error Handling
- Validasi duplikasi username dan NISN
- Handling file Excel yang corrupt atau format salah
- Rollback otomatis jika terjadi error dalam batch processing
- Pesan error yang informatif untuk user

## Keamanan
- Validasi input di frontend dan backend
- Sanitasi data Excel sebelum processing
- Hash password dengan bcrypt
- Logging semua aktivitas mutasi

## Penggunaan

### Akses Menu
Fitur dapat diakses melalui sidebar: **Mutasi Siswa**

### Workflow Keluar/Tamat:
1. Pilih tipe (Keluar atau Tamat)
2. Pilih kelas
3. Pilih alasan
4. Klik "Cari Siswa"
5. Pilih siswa yang akan diproses
6. Klik "Proses Keluar/Tamat"

### Workflow Naik Kelas:
1. Pilih kelas asal
2. Pilih kelas tujuan
3. Klik "Cari Siswa"
4. Pilih siswa yang akan naik kelas
5. Klik "Proses Naik Kelas"

### Workflow Siswa Baru:
1. Download template Excel
2. Isi data siswa sesuai format
3. Upload file Excel
4. Sistem akan memproses dan memberikan feedback

## Monitoring dan Audit
- Semua mutasi siswa tercatat dalam tabel MutasiSiswa
- Timestamp otomatis untuk setiap transaksi
- Detail lengkap termasuk kelas asal dan tujuan
- Dapat digunakan untuk laporan dan audit

## Tips Penggunaan
1. Backup database sebelum melakukan mutasi massal
2. Validasi data Excel sebelum upload untuk siswa baru
3. Gunakan fitur "Pilih Semua" untuk efisiensi
4. Periksa kembali kelas tujuan sebelum proses naik kelas
5. Dokumentasikan alasan keluar/tamat dengan jelas
