Markas Latihan
Web app latihan soal pilihan ganda untuk anak SD–SMA. Spesifikasi lengkap ada di docs/brief.md, prototipe di docs/prototype.html.
Keputusan (bagian 13 brief)
| Topik | Keputusan |
|---|
| Model akun | Satu akun orang tua (login Google) dengan profil anak. HP mengingat profil terakhir. "Ganti pemain" tanpa kunci tambahan |
| Auth + database | Firebase (project baru markas-latihan): Auth dengan Google, Firestore. Semua baca/tulis data lewat server Next.js (Admin SDK). Security Rules menolak akses langsung dari browser |
| Kunci jawaban | Diperiksa di server. Browser hanya menerima soal tanpa kunci |
| Batas AI harian | 20 paket per anak, 60 per akun. Merapikan soal admin 30 per akun. Bisa diatur lewat env |
| Model AI | claude-sonnet-5-5 (effort medium, server-side fallback aktif) untuk membuat soal, claude-haiku-5-5 untuk merapikan. Bisa diatur lewat env. Perkiraan ± USD 0,03 per paket 5 soal; biaya tercatat per permintaan di families/{uid}/logAi |
| Sesi ditinggal | Hadiah dihitung sebagian: tiap jawaban benar langsung disimpan saat dicek di server |
| Admin | PIN 4 angka di-hash di server, 5 percobaan lalu jeda 5 menit, reset lewat login orang tua |
| Hosting | Vercel, subdomain *.vercel.app dulu |
Menjalankan
npm install
npm run dev # butuh FIREBASE_SERVICE_ACCOUNT di .env.local
Tanpa kredensial, pakai Firebase Emulator (butuh Java):
npm run emulators # terminal 1
npm run dev:emu # terminal 2
Katalog komponen: /katalog.
Variabel wajib di Vercel
Semua bertipe Secret, dicentang untuk Production dan Preview. Variabel baru hanya terbaca oleh deploy berikutnya.
| Nama | Isi |
|---|
FIREBASE_SERVICE_ACCOUNT | Seluruh isi file JSON service account Firebase |
ANTHROPIC_API_KEY | Kunci Claude API (sk-ant-…) dari Claude Console |
Cek dengan membuka /sehat di alamat deploy: harus tampil "Beres!" dan "Kunci Claude API: terpasang".
Opsional (punya nilai bawaan):
| Nama | Bawaan | Isi |
|---|
AI_LIMIT_PER_PLAYER / AI_LIMIT_PER_FAMILY | 20 / 60 | Jatah paket soal AI per anak / per keluarga per hari (WIB) |
AI_LIMIT_RAPIKAN | 30 | Jatah "Rapikan soal" + baca foto per keluarga per hari |
AI_LIMIT_ESAI | 100 | Pemeriksaan jawaban esai per anak per hari |
AI_MODEL_SOAL | claude-sonnet-5-5 | Model pembuat soal & soal mirip |
AI_MODEL_RAPIKAN | claude-haiku-5-5 | Model merapikan teks soal admin |
AI_MODEL_ESAI | claude-haiku-5-5 | Model memeriksa jawaban esai per poin |
AI_MODEL_BACA_FOTO | claude-sonnet-5-5 | Model membaca foto soal |
Firebase
- Konfigurasi web ada di
lib/firebase/config.ts (publik).
FIREBASE_SERVICE_ACCOUNT (JSON service account, satu baris) wajib di server: .env.local dan Vercel → Settings → Environment Variables.- Aturan Firestore di
firestore.rules: semua akses langsung dari browser ditolak. Data hanya lewat route app/api/* yang memeriksa token login orang tua.
- Setiap domain tempat app dibuka harus ada di Firebase → Authentication → Settings → Authorized domains. Alamat
*.vercel.app tidak otomatis diizinkan: alamat preview dan alamat produksi masing-masing harus ditambahkan.
Struktur data (Firestore)
families/{uid} createdAt, adminPinHash (scrypt), pinGagal, pinKunciSampai
families/{uid}/players/{id} name, kelas, theme, academicYear, rewards, createdAt
families/{uid}/players/{id}/sesi/{sesiId} paket soal lengkap dengan kunci (tidak pernah dikirim ke browser sebelum dijawab), jawaban
families/{uid}/players/{id}/attempts/{sesiId} riwayat latihan selesai: mapel, topik, level, sumber, skor, jawaban per soal (esai: teks anak, hasil per poin, hadiah, koreksi)
families/{uid}/players/{id}/topikStat/{hash} statistik topik per level (best, last, tries) untuk saran
families/{uid}/soalPilihan/{id} soal pilihan orang tua (judul, kelas, mapel, teks asli, soal, saklar acak pilihan)
families/{uid}/gambarSoal/{id} potongan gambar soal (JPEG base64 ±≤ 180 KB, setId paket); foto halaman utuh tidak disimpan
families/{uid}/adminSesi/{sha256} sesi mode admin (60 menit)
families/{uid}/pemakaian/{YYYY-MM-DD} jatah AI harian (WIB): total, perPemain, rapikan, esai.{pemainId}
families/{uid}/logAi/{id} model, token masuk/keluar, hasil per permintaan AI (tanpa isi foto)
