---

✨ Tentang Proyek

Qurio adalah Learning Management System (LMS) modern dan platform kuis interaktif yang direkayasa untuk evaluasi pendidikan profesional. Platform ini menjembatani kesenjangan antara Instruktur (Author) yang membutuhkan alat pembuat soal dinamis dengan analitik komprehensif, dan Peserta (Participant) yang berhak mendapatkan pengalaman ujian yang mulus, adil, dan transparan.

🎯 Visi

Repositori ini saat ini menampung Backend API dari Qurio. Arsitektur ini lahir dari kebutuhan untuk menciptakan pusat evaluasi online yang berintegritas tinggi dan "Anti-Curang". Baik untuk ujian universitas yang ketat dengan batas waktu, maupun kuis pelatihan kasual, Qurio menyediakan RESTful API terpusat yang aman untuk mengelola seluruh siklus kuis—mulai dari penyusunan draf hingga penilaian otomatis dan analitik mendalam.

🛡️ Arsitektur & Keamanan

Pada intinya, Backend Qurio mengutamakan pendekatan "Keamanan & Konsistensi":

• Kontrol Akses Berbasis Peran (RBAC): Middleware berbasis JWT yang ketat memastikan bahwa peran ADMIN, AUTHOR, dan PARTICIPANT benar-benar terisolasi. Author hanya dapat mengedit kuisnya sendiri, dan Peserta tidak dapat mengakses endpoint analitik.
• Validasi Sisi Server: Untuk mencegah manipulasi dari sisi klien, logika krusial seperti penghitung waktu mundur kuis, validasi tanggal Mulai/Selesai, dan batas maksimal percobaan (Max Attempts) ditegakkan secara absolut oleh server Node.js.
• Integritas Data: Didukung oleh Prisma ORM, skema database menggunakan batasan relasional yang ketat dan penghapusan kaskade (cascading deletes) untuk mencegah data yatim (orphaned data).
• Manajemen Berkas Terorganisir: Menggunakan multer, lampiran gambar untuk soal dan opsi diproses dengan aman dan disimpan secara sistematis di direktori publik yang terisolasi (public/uploads/questions dan public/uploads/options).

---

🚀 Fitur Utama Backend

📝 Manajemen Kuis Tingkat Lanjut

• Konfigurasi Dinamis: Kuis mendukung visibilitas Publik/Privat (via PIN), akses terjadwal (startDate & endDate), dan batas percobaan yang dapat disesuaikan.
• Pembuat Soal Granular: Tambah, perbarui, atau hapus soal dengan berbagai tingkat kesulitan. Mendukung format pilihan ganda dan benar/salah beserta lampiran gambar.
• Sistem Draf: Simpan kuis sebagai DRAFT sebelum secara resmi diubah menjadi PUBLISHED.

🎯 Mesin Pengerjaan Anti-Curang

• Mekanisme Simpan Otomatis: Jawaban disimpan secara bertahap per soal (endpoint /answer), memastikan tidak ada data yang hilang jika peserta kehilangan koneksi.
• Penilaian Otomatis: Sistem langsung menghitung skor saat kuis diserahkan, dengan mempertimbangkan preferensi Instruktur apakah akan menampilkan atau menyembunyikan hasil akhir.
• Sistem Ulasan: Peserta dapat meninjau jawaban benar/salah pasca-ujian, diatur secara ketat oleh pengaturan showScore milik Instruktur.

📈 Analitik Kelas Enterprise

• Dasbor Instruktur: Satu endpoint tangguh yang mengumpulkan total persentase kelulusan, durasi rata-rata, tren pengerjaan 7 hari terakhir, dan kuis dengan performa terbaik.
• Papan Peringkat (Leaderboards): Peringkat peserta secara real-time berdasarkan skor akhir dan kecepatan penyelesaian.
• Inspeksi Pengerjaan Mendalam: Memungkinkan Instruktur memeriksa jawaban individu siswa untuk mengidentifikasi soal yang paling sering dijawab salah.

---

🛠️ Teknologi yang Digunakan

Runtime & Bahasa

Framework & Database

Alat & Infrastruktur

---

📂 Struktur Proyek

qurio-backend/
├── prisma/                 
│   ├── schema.prisma       
│   └── seed.js             
├── public/                 
│   └── uploads/            
│       ├── questions/      
│       └── options/        
├── src/
│   ├── config/             
│   ├── controllers/        
│   ├── middlewares/        
│   ├── routes/             
│   └── server.js           
├── .env                    
└── package.json
└── prisma.config.ts

---

📡 Dokumentasi Endpoint API

Semua endpoint menerima dan menghasilkan application/json kecuali dinyatakan lain. Endpoint yang dilindungi memerlukan JWT yang valid melalui header Authorization: Bearer <token>.

Authentication (/api/auth)

Method	Endpoint	Akses	Body / Params	Deskripsi
POST	/register	Publik	name, username, password, role, phone (opsional)	Mendaftarkan akun pengguna baru.
POST	/login	Publik	username, password	Autentikasi kredensial dan menerima token JWT.

Quiz Management (/api/quizzes)

Method	Endpoint	Akses	Body / Params	Deskripsi
GET	/public	Publik	-	Menampilkan kuis berstatus PUBLISHED tanpa PIN.
GET	/join/:quizCode	Participant	Param: quizCode	Mengambil metadata kuis untuk halaman pra-kuis (Lobby).
POST	/	Author, Admin	title, description, timeLimit, status, pin, startDate, endDate, showScore, randomizeQuestions, maxAttempts	Membuat kuis baru dengan pengaturan akses.
GET	/my-quizzes	Author, Admin	-	Mengambil semua kuis yang dibuat oleh Instruktur terkait.
PUT	/:id	Author, Admin	Param: id Body: Sama seperti POST	Memperbarui konfigurasi kuis.
DELETE	/:id	Author, Admin	Param: id kuis	Menghapus kuis beserta isinya secara kaskade.

Question Engine (/api/questions)

Method	Endpoint	Akses	Body / Params	Deskripsi
POST	/:quizId	Author, Admin	Param: quizId Body: type, content, imageUrl, options	Menambahkan soal baru beserta daftar opsinya.
GET	/quiz/:quizId	Author, Admin	Param: quizId	Mengambil semua soal dalam kuis tertentu.
PUT	/:questionId	Author, Admin	Param: questionId Body: Sama seperti POST	Memperbarui konten soal atau mengganti opsi jawaban.
DELETE	/:questionId	Author, Admin	Param: questionId	Menghapus soal beserta opsi di dalamnya.

Attempt & Scoring (/api/attempts)

Method	Endpoint	Akses	Body / Params	Deskripsi
POST	/start/:quizId	Participant	Param: quizId Body: pin (opsional)	Memulai kuis (Memvalidasi PIN, jadwal, dan max attempts).
POST	/:attemptId/answer	Participant	Param: attemptId Body: questionId, optionId	Simpan otomatis jawaban (Validasi batas waktu dari server).
POST	/:attemptId/finish	Participant	Param: attemptId	Mengakhiri pengerjaan dan memicu perhitungan skor.
GET	/my-history	Participant	-	Melihat riwayat skor pengerjaan kuis pribadi.
GET	/:attemptId/review	Participant	Param: attemptId	Melihat rincian jawaban benar/salah pasca ujian.

Analytics & Files (/api/analytics & /api/uploads)

Method	Endpoint	Akses	Body / Params	Deskripsi
GET	/analytics/author/dashboard	Author, Admin	-	Menarik metrik global, tren, dan grafik performa kuis.
GET	/analytics/quiz/:id	Author, Admin	Param: id kuis	Mengambil statistik kuis spesifik dan Leaderboard.
GET	/analytics/attempt/:id	Author, Admin	Param: id attempt	Memeriksa detail jawaban historis dari satu peserta.
POST	/uploads/question	Author, Admin	Form: image (File)	Mengunggah lampiran gambar untuk ilustrasi soal.
POST	/uploads/option	Author, Admin	Form: image (File)	Mengunggah lampiran gambar untuk opsi jawaban.

Admin Control (/api/admin)

Method	Endpoint	Akses	Body / Params / Query	Deskripsi
GET	/dashboard	Admin	-	Memantau metrik global (total pengguna, kuis, tren pengerjaan).
GET	/users	Admin	Query: page, limit, q, role	Mendapatkan daftar seluruh pengguna (mendukung paginasi & filter).
PUT	/users/:id	Admin	Param: id Body: name, username, dll.	Memperbarui data pengguna tertentu.
DELETE	/users/:userId	Admin	Param: userId	Menghapus pengguna secara permanen dari sistem.
GET	/quizzes	Admin	Query: page, limit, q, status	Mendapatkan daftar seluruh kuis global (mendukung paginasi).
GET	/quizzes/:slug	Admin	Param: slug	Melihat detail kuis beserta daftar soal untuk inspeksi.
DELETE	/quizzes/:quizId	Admin	Param: quizId	Menghapus paksa kuis beserta data pengerjaannya dari sistem.
GET	/attempts	Admin	Query: page, limit, search, status	Memantau riwayat pengerjaan ujian secara global.
GET	/attempts/:attemptId	Admin	Param: attemptId	Melihat detail lembar jawaban dan skor pengerjaan peserta.
GET	/settings/profile	Admin	-	Mengambil data profil Admin yang sedang login.
PUT	/settings/profile	Admin	Body: name, username	Memperbarui informasi profil Admin.
PUT	/settings/password	Admin	Body: currentPassword, newPassword	Mengubah dan mengamankan password Admin.

---

🌟 FRONTEND: SEGERA HADIR!

Backend yang tangguh dan aman ini hanyalah setengah dari ekosistem Qurio. Kami saat ini sedang aktif mengembangkan Aplikasi Frontend yang akan mendefinisikan ulang cara Anda berinteraksi dengan platform pendidikan.

Dibangun menggunakan kerangka kerja mutakhir Astro untuk pemuatan halaman super cepat (tanpa JS secara bawaan), terintegrasi mulus dengan React (Astro Islands) untuk komponen UI yang sangat interaktif seperti Quiz Builder dinamis dan Mesin Ujian real-time.

Apa yang akan datang:

• ✨ UI Bersih & Glassmorphism: Antarmuka memukau dengan kontras tinggi yang ditenagai oleh Tailwind CSS terbaru. Dirancang untuk mengurangi beban kognitif selama ujian dan terlihat luar biasa premium.

• 📱 Responsivitas Sempurna: Pendekatan mobile-first memastikan platform terlihat dan terasa seperti aplikasi native di ponsel pintar, sekaligus melebar dengan elegan di monitor desktop.

• 📊 Visualisasi Data Interaktif: Grafik indah dan beranimasi yang merender analitik backend Anda secara real-time.

• ⚡ Transisi Tampilan Mulus: Memanfaatkan View Transitions API dari Astro untuk pengalaman navigasi yang mulus dan tanpa hambatan.

Masa depan evaluasi hampir tiba. Tetap pantau!

---

📦 Instalasi

Untuk mendapatkan salinan lokal dan menjalankannya, ikuti langkah-langkah sederhana berikut:

1. Kloning repositori

   git clone https://github.com/nyomangedewisaya/qurio.git
   cd qurio-backend

2. Instal paket NPM

   npm install

3. Konfigurasi Environment & Database
   Buat file .env untuk mengatur koneksi database dan JWT, lalu jalankan perintah inisialisasi database berikut:

   npx prisma db push
   npx prisma generate
   npx prisma db seed

4. Jalankan server backend

   npm run dev
   # atau
   npm start

---

📜 Lisensi

Didistribusikan di bawah Lisensi MIT.

"Memberdayakan pikiran melalui evaluasi yang mulus dan andal."
— Developer Qurio