# CMS Scholatics - School Management & Portal System

CMS Scholatics adalah platform Sistem Informasi Sekolah dan Portal Penerimaan Peserta Didik Baru (PPDB / SPPDB / SPMB) modern berbasis Single Page Application (SPA). Aplikasi ini dibangun dengan menggunakan kombinasi framework backend tangguh **Laravel 12** dan frontend interaktif **Vue 3** yang di-bundle secara efisien menggunakan **Vite** dan **Tailwind CSS**.

---

## 🚀 Fitur Utama

CMS Scholatics dirancang dengan fitur lengkap untuk kebutuhan administrasi portal sekolah, publikasi informasi, dan pengelolaan penerimaan siswa. Semua fitur dilengkapi dengan **Logika Kondisional Modul**, yang memungkinkan Anda mengaktifkan atau menonaktifkan modul tertentu langsung dari panel admin.

### 1. Portal Informasi Publik (Frontend)
- **Beranda (Home)**: Banner dinamis, statistik sekolah, dan modul dinamis.
- **Profil Sekolah**: Informasi struktural, visi, misi, dan identitas sekolah.
- **Berita & Artikel**: Publikasi pengumuman dan agenda akademik dengan URL *SEO-friendly*.
- **Galeri & Media**: Album foto kegiatan sekolah dengan *Lightbox Premium* dan galeri video terintegrasi.
- **Program Keahlian (Jurusan)**: Detail kompetensi keahlian khusus tingkat SMA/SMK/MA.
- **Prestasi & Ekstrakurikuler**: Dokumentasi pencapaian siswa dan pendaftaran kegiatan siswa.
- **Layanan Digital & Pusat Unduhan**: Akses tautan layanan eksternal dan formulir dokumen penting.
- **Progressive Web App (PWA)**: Dukungan instalasi *offline* layaknya aplikasi *native* dengan performa super cepat.
- **Dynamic Theme Color**: Personalisasi warna utama *website* langsung dari dasbor admin yang akan meresap ke seluruh elemen UI.

### 2. Portal PPDB / SPMB (Penerimaan Siswa Baru)
- **Registrasi & Keamanan Berbasis OTP**: Autentikasi pendaftar baru tidak menggunakan kata sandi biasa, melainkan kode OTP (*One-Time Password*) yang dikirim langsung via Email untuk keamanan maksimal.
- **Formulir Pendaftaran Interaktif**: 
  - Dilengkapi deteksi otomatis wilayah seluruh Indonesia secara bertingkat (Provinsi > Kab/Kota > Kecamatan > Desa) via **Emsifa API Wilayah**.
  - Fitur sinkronisasi otomatis satu-klik (Auto-fill) untuk Alamat Domisili yang sama dengan Kartu Keluarga.
- **Cetak Bukti Pendaftaran**: Generasi bukti registrasi dan kelulusan berformat PDF, lengkap dengan *QR Code* pelacakan.
- **Pemantauan Seleksi Real-Time**: Calon siswa dapat melacak status kelulusan mereka secara *live* melalui dasbor pendaftar.

### 3. Panel Administrasi & Sistem (CMS Backend)
- **Role & Permission Management**: Sistem otorisasi akses spesifik (Super Admin, Admin, Panitia, Siswa).
- **Menu Builder Dinamis**: Seret-dan-lepas (*drag-and-drop*) kustomisasi struktur menu navigasi.
- **Audit Logs & Keamanan**: Pencatatan riwayat aksi (*create, update, delete*) setiap pengguna. Sistem akan otomatis mengeluarkan (*logout*) pengguna jika terdeteksi tidak aktif selama 15 menit.
- **Sistem Lisensi**: Aktivasi dan manajemen lisensi terhubung langsung ke server FLYMEMBER.
- **Sistem Pemeliharaan Terpadu**:
  - Pembuatan dan pengunduhan cadangan (*backup*) basis data secara instan (`.sql`/`.sqlite`).
  - Fitur **System Restore** sekali klik.
  - Pembersihan tembolok sistem (*Cache*) langsung dari UI.

---

## 🛠️ Spesifikasi Teknologi (Tech Stack)

### Backend
- **Core Framework**: Laravel 12.x
- **API Authentication**: Laravel Sanctum (Stateful SPA)
- **Authorization**: Spatie Laravel Permission 7.x
- **Activity Tracker**: Spatie Laravel Activitylog 4.x
- **PHP Version**: >= 8.2

### Frontend
- **Core Library**: Vue 3.x (Composition API)
- **Build Engine**: Vite 7.x
- **State Management**: Pinia 3.x
- **Styling**: Tailwind CSS 4.x
- **PWA Capabilities**: VitePWA (Service Workers & Pre-caching)

---

## 💻 Panduan Instalasi Lokal (Development)

Digunakan untuk mencoba, memodifikasi, dan mengembangkan kode aplikasi di komputer lokal (Windows/Mac/Linux).

### Persyaratan Sistem
- PHP >= 8.2
- Composer >= 2.x
- Node.js >= 18.x & npm
- MySQL / MariaDB (atau SQLite)

### Langkah-Langkah
1. **Clone / Salin Repositori**:
   ```bash
   git clone <repository-url> scholatics
   cd scholatics
   ```
2. **Install Dependensi Backend (Composer)**:
   ```bash
   composer install
   ```
3. **Install Dependensi Frontend (npm)**:
   ```bash
   npm install
   ```
4. **Konfigurasi Environment**:
   Salin `.env.example` ke `.env`. Atur nama database sesuai kebutuhan di file tersebut.
   ```bash
   cp .env.example .env
   ```
5. **Generate Application Key**:
   ```bash
   php artisan key:generate
   ```
6. **Menjalankan Server (Buka 2 Terminal)**:
   - Terminal 1 (Backend): `php artisan serve`
   - Terminal 2 (Frontend): `npm run dev`
7. **Buka Web Installer**:
   Akses `http://127.0.0.1:8000` di browser. Sistem akan otomatis mengarahkan Anda ke halaman **Web Installer** (`/install`).

---

## 🧩 Web Installer (Panduan Instalasi via Browser)

CMS Scholatics dilengkapi **Web Installer** bawaan yang akan secara otomatis aktif saat pertama kali diakses. Installer ini terdiri dari **7 langkah** yang memandu Anda dari awal hingga siap pakai.

### Step 1: System Requirements
Sistem akan memeriksa apakah server Anda memenuhi kebutuhan minimum:
- PHP >= 8.2
- Ekstensi PHP: BCMath, Ctype, cURL, DOM, Fileinfo, JSON, Mbstring, OpenSSL, PDO, Tokenizer, XML

> ⚠️ Jika ada kebutuhan yang belum terpenuhi (ditandai ❌), hubungi penyedia hosting atau aktifkan ekstensi tersebut melalui cPanel > **Select PHP Version**.

### Step 2: Folder Permissions
Sistem memeriksa izin tulis (writable) pada folder kritis:
- `storage/framework/` — ✅ Writable
- `storage/logs/` — ✅ Writable
- `bootstrap/cache/` — ✅ Writable
- `.env` — ✅ Writable

> ⚠️ Jika ada yang belum writable, ubah permission folder menjadi `775` melalui File Manager cPanel atau via SSH: `chmod -R 775 storage bootstrap/cache`

### Step 3: License Activation
Masukkan **License Key** yang Anda dapatkan setelah pembelian di [Store Flymotion](https://store.flymotion.my.id).
- Format: `FLYM-XXXX-XXXX-XXXX`
- Sistem akan melakukan validasi real-time ke server **FLYMEMBER**.
- Jika lisensi valid, token akan disimpan sementara dan digunakan di langkah selanjutnya.

> ℹ️ Anda bisa melihat License Key Anda di halaman **My Products** pada akun FLYMEMBER Anda.

### Step 4: Database Configuration
Isi kredensial database MySQL/MariaDB Anda:
- **Nama Aplikasi**: Nama sekolah/institusi Anda
- **Database Host**: `127.0.0.1` (default untuk shared hosting)
- **Database Port**: `3306`
- **Database Name**: Nama database yang sudah dibuat di cPanel
- **Database Username**: Username database dari cPanel
- **Database Password**: Password database dari cPanel

> ⚠️ **Penting**: Database **harus sudah dibuat terlebih dahulu** melalui cPanel > MySQL® Databases, dan user database harus sudah di-*assign* dengan **ALL PRIVILEGES** ke database tersebut.

Sistem akan:
1. Menguji koneksi database secara real-time
2. Menyimpan konfigurasi ke file `.env`
3. Men-generate `APP_KEY` secara otomatis

### Step 5: Database Migration
Klik tombol **Jalankan Migrasi** untuk membuat seluruh struktur tabel database dan mengisi data awal (roles, permissions, konfigurasi modul, dll).

> ⚠️ Proses ini menggunakan `migrate:fresh` — **semua data yang ada di database akan dihapus**. Pastikan database yang digunakan adalah database baru/kosong.

### Step 6: Create Admin Account
Buat akun **Super Admin** pertama Anda:
- **Nama**: Nama lengkap admin
- **Email**: Email untuk login
- **Password**: Minimal 8 karakter (harus dikonfirmasi ulang)

Akun ini secara otomatis mendapat role `super-admin` yang memiliki akses penuh ke seluruh fitur sistem.

### Step 7: Finish!
Instalasi selesai! Sistem menandai instalasi sebagai lengkap dengan membuat file `storage/installed`. Anda akan diarahkan ke halaman login untuk masuk ke Dashboard Admin.

> ℹ️ Setelah instalasi selesai, halaman `/install` akan diblokir otomatis dan tidak bisa diakses kembali. Untuk mengulang instalasi, hapus file `storage/installed` secara manual.

---

## 🌐 Panduan Deployment Produksi (Go-Live)

### 1. Persiapan Build Frontend (Lakukan di Komputer Lokal)
Sebelum mengunggah ke server (terutama *Shared Hosting* yang tidak mendukung Node.js), Anda **WAJIB** melakukan proses *build* di komputer Anda:
```bash
npm run build
```
Proses ini akan mengompilasi kode Vue menjadi aset HTML/CSS/JS statis dan menyimpannya di folder `public/build/`. Pastikan folder `public/build/` ikut terunggah ke server produksi Anda.

### 2. Konfigurasi Penting File `.env` (Wajib di Server)
Ubah konfigurasi berikut pada server produksi Anda agar autentikasi aplikasi satu-halaman (SPA) bekerja tanpa masalah *CORS / Cookie Mismatch*:

```env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://nama-domain-anda.com

# Konfigurasi Database (Sesuaikan dengan kredensial server Anda)
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nama_db_produksi
DB_USERNAME=user_db_produksi
DB_PASSWORD=password_db_produksi

# Penting untuk Keamanan Sesi SPA Sanctum
SANCTUM_STATEFUL_DOMAINS=nama-domain-anda.com,www.nama-domain-anda.com
SESSION_DOMAIN=.nama-domain-anda.com
SESSION_DRIVER=cookie
```
> **Penting**: Jika aplikasi diinstal pada subdomain (misal `panel.sekolah.com`), hilangkan karakter www dan gunakan `SANCTUM_STATEFUL_DOMAINS=panel.sekolah.com`.

---

### 3. Instalasi pada VPS (Ubuntu / Debian - Nginx)
Metode ini sangat disarankan untuk mendapatkan kontrol penuh dan kecepatan akses optimal.

1. Hubungkan domain Anda ke IP VPS.
2. Tempatkan kode sumber (yang sudah Anda `npm run build` sebelumnya) ke `/var/www/scholatics`.
3. Buat file konfigurasi Nginx (`/etc/nginx/sites-available/scholatics.conf`):

```nginx
server {
    listen 80;
    server_name nama-domain-anda.com www.nama-domain-anda.com;
    root /var/www/scholatics/public; # Pastikan berakhiran /public

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;
    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock; # Sesuaikan versi PHP
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}
```
4. Berikan izin akses folder ke pengguna peladen web (Nginx):
```bash
sudo chown -R www-data:www-data /var/www/scholatics
sudo find /var/www/scholatics -type f -exec chmod 644 {} \;
sudo find /var/www/scholatics -type d -exec chmod 755 {} \;
sudo chmod -R 775 /var/www/scholatics/storage /var/www/scholatics/bootstrap/cache
```
5. Aktifkan konfigurasi Nginx dan instal SSL Let's Encrypt (Certbot).
6. Akses domain Anda — Web Installer akan muncul otomatis untuk melanjutkan instalasi via browser.

---

### 4. Instalasi pada Shared Hosting (cPanel)

#### Persiapan di cPanel (SEBELUM Upload)
1. **Buat Database MySQL**: cPanel > MySQL® Databases > Create New Database
2. **Buat User Database**: cPanel > MySQL® Databases > Create New User  
3. **Assign User ke Database**: cPanel > MySQL® Databases > Add User to Database > Centang **ALL PRIVILEGES**

> ⚠️ **PENTING**: Langkah ke-3 sering terlewat! Tanpa assign privilege, aplikasi akan error `Access denied for user`.

#### Langkah Upload dan Konfigurasi
1. Buat direktori baru di luar `public_html` (misal: direktori bernama `scholatics`).
2. Unggah file `scholatics.zip` (source code backend) ke dalam direktori `scholatics` tersebut, lalu **Extract**.
3. Buka **Terminal** di cPanel hosting, lalu jalankan perintah berikut untuk menyalin file konfigurasi `.env`:
   ```bash
   cd scholatics
   cp .env.example .env
   ```
4. Masuk ke direktori tujuan publikasi Anda di dalam direktori `public_html` (misal: `/public_html` jika ditaruh di domain utama, atau `/public_html/foldertujuan` jika di sub-direktori).
5. Unggah file `build.zip` (berisi file *frontend* Vue yang sudah di-build beserta folder *public* Laravel) ke direktori tujuan tersebut, lalu **Extract**.
6. Edit file `index.php` yang ada di dalam `public_html/foldertujuan` tersebut, pastikan baris `require` dan `$app` disesuaikan agar mengarah ke direktori `scholatics` yang berada di luar `public_html`:
   ```php
   require __DIR__.'/../scholatics/vendor/autoload.php';
   $app = require_once __DIR__.'/../scholatics/bootstrap/app.php';
   ```
   *(Sesuaikan `../scholatics` dengan path yang sebenarnya dari `public_html/foldertujuan` Anda mundur ke belakang menuju direktori `scholatics`)*
7. Buat *symlink* untuk folder penyimpanan media (baca bagian Symlink di bawah).

#### Proses Instalasi via Web Installer
Jika seluruh file berhasil diunggah dan dikonfigurasi, akses domain web Anda melalui peramban. Anda akan otomatis diarahkan ke halaman instalasi (`/install`). Berikut adalah rincian proses pada **Installer**:

- **Step 1: System Requirements** - Sistem akan memverifikasi apakah versi PHP dan semua ekstensi PHP yang dibutuhkan server Anda sudah terpenuhi.
- **Step 2: Folder Permissions** - Memeriksa hak akses penulisan (*writable permissions*) pada direktori `storage` dan `bootstrap/cache`.
- **Step 3: License Activation** - Halaman form untuk memasukkan **License Key** FLYMEMBER Anda guna aktivasi kode lisensi.
- **Step 4: Database Configuration** - Mengisikan data kredensial basis data Anda (Nama Database, Username, dan Password yang telah dibuat di langkah persiapan sebelumnya). Sistem akan mengotomatisasi pengisian di file `.env`.
- **Step 5: Database Migration** - Tombol pemicu untuk menjalankan `migrate:fresh` guna membuat seluruh tabel beserta input data bawaan (*seeding*).
- **Step 6: Create Admin Account** - Pengisian form untuk membuat akun pengguna baru sebagai Super Admin (Nama, Email, dan Password baru).
- **Step 7: Finish!** - Konfirmasi akhir bahwa proses instalasi telah tuntas dan file `storage/installed` berhasil ditambahkan untuk mengunci kembali proses installer.

> ℹ️ Sistem akan otomatis mendeteksi lokasi `public_html` dan menyesuaikan *public path* melalui `AppServiceProvider`.

#### Membuat Symlink di Shared Hosting (WAJIB)
Semua aset gambar dan berkas unggahan tersimpan di direktori `/storage`, sehingga harus ditautkan (*symlink*) ke direktori publik. Jika terminal SSH tidak tersedia, buatlah file berekstensi `.php` (misal `symlink.php`) di lokasi folder instalasi publik Anda (di dalam `public_html/foldertujuan`) lalu copas skrip ini:
```php
<?php
// Ganti path direktori sesuai dengan struktur path asli di cPanel hosting Anda!
// $target adalah letak folder origin storage public di source backend (di luar public_html)
$target = '/home/user_cpanel/scholatics/storage/app/public';

// $link adalah tempat terbuatnya shortcut (folder bernama "storage") di folder public web Anda
$link = '/home/user_cpanel/public_html/foldertujuan/storage';

if (symlink($target, $link)) {
    echo "Symlink sukses dibuat!";
} else {
    echo "Gagal membuat symlink.";
}
```
Akses dari peramban (misal `https://domainanda.com/symlink.php`), pastikan muncul pesan konfirmasi keberhasilan, lalu **segera hapus file `symlink.php`** tersebut.

---

## 📋 Checklist Deployment

Gunakan checklist ini untuk memastikan deployment berjalan lancar:

| # | Langkah | Status |
|---|---------|--------|
| 1 | `npm run build` sudah dijalankan di lokal | ☐ |
| 2 | Folder `node_modules` TIDAK ikut diupload | ☐ |
| 3 | File `storage/installed` TIDAK ADA di server | ☐ |
| 4 | Database MySQL sudah dibuat di cPanel | ☐ |
| 5 | User database sudah di-assign dengan ALL PRIVILEGES | ☐ |
| 6 | File `.env` sudah dibuat dengan menyalin `.env.example` | ☐ |
| 7 | Folder `storage/` dan `bootstrap/cache/` writable (775) | ☐ |
| 8 | Symlink storage sudah dibuat | ☐ |
| 9 | Web Installer berhasil diakses di browser | ☐ |
| 10 | 7 langkah instalasi selesai tanpa error | ☐ |
| 11 | `SANCTUM_STATEFUL_DOMAINS` sudah diset sesuai domain | ☐ |
| 12 | `SESSION_DOMAIN` sudah diset dengan awalan titik (`.domain.com`) | ☐ |

---

## 🔒 Solusi Pemeliharaan & Troubleshooting

### Error Umum saat Instalasi

1. **`Access denied for user` (Error 1044)**:
   - User database belum di-assign ke database di cPanel.
   - Solusi: cPanel > MySQL® Databases > Add User To Database > pilih user & database > centang ALL PRIVILEGES.

2. **`Table 'xxx.settings' doesn't exist` (Error 1146)**:
   - Tabel belum dibuat (migrasi belum dijalankan) TAPI file `storage/installed` sudah ada.
   - Solusi: Hapus file `storage/installed` di server, lalu akses ulang domain untuk memulai Web Installer.

3. **Web Installer tidak muncul (langsung error/blank)**:
   - Pastikan file `storage/installed` sudah dihapus.
   - Pastikan folder `storage/` dan `bootstrap/cache/` memiliki permission `775`.
   - Periksa `storage/logs/laravel.log` untuk detail error.

### Error Umum saat Pemakaian

4. **Error 419 (CSRF Token Mismatch) saat Login**:
   - Terjadi karena konfigurasi nama domain pada `SANCTUM_STATEFUL_DOMAINS` atau `SESSION_DOMAIN` di file `.env` salah. 
   - Hapus parameter protokol (`https://`) dari variabel-variabel tersebut (Gunakan murni `domain.com`).
   - Tekan CTRL+F5 atau *Clear Cookies* pada browser Anda.

5. **Gambar Logo/Galeri/Profil Tidak Muncul (Broken Image)**:
   - Jalankan `php artisan storage:link` (atau eksekusi kode *symlink* PHP).
   - Pastikan URL gambar di direktori penyimpanan tidak menggunakan format statis `http://localhost`, melainkan dinamis (`APP_URL`).

6. **Error 402 (Payment Required) pada API**:
   - Lisensi belum aktif atau token lisensi expired.
   - Solusi: Buka menu **Sistem > Aktivasi Lisensi** di Dashboard Admin untuk mengaktifkan ulang lisensi.

7. **Pembersihan Cache Manual (Terminal)**:
   Jika tidak memiliki akses ke panel admin, eksekusi perintah:
   ```bash
   php artisan cache:clear && php artisan config:clear && php artisan route:clear && php artisan view:clear
   ```

### Reset Instalasi (Install Ulang)
Jika Anda ingin mengulang seluruh proses instalasi dari awal:
1. Hapus file `storage/installed`
2. Akses domain Anda — Web Installer akan aktif kembali
3. Pada Step 5 (Database Migration), semua tabel akan di-reset otomatis (`migrate:fresh`)

> ⚠️ **PERHATIAN**: Reset instalasi akan **menghapus semua data** yang ada di database!

---

## 📄 Kredit & Lisensi
- **Developer & Copyright**: [FLYMOTION.MY.ID](https://flymotion.my.id)
- **Kontak Dukungan**:
  - **WhatsApp**: [62822-33000-884](https://wa.me/6282233000884)
  - **Telegram**: [@cs_flymotion](https://t.me/cs_flymotion)