kodeva/PLAN.md

PLAN.md — Rencana Pengembangan Kodeva

Rencana eksekusi untuk membangun Kodeva (Sistem Manajemen Kursus Coding). Dokumen pendamping: AGENTS.md (engineering), DESIGN.md (UI/UX), seed.example.ts (contoh data). Status: Draft v1.0 · Estimasi total 8–10 minggu (1 full-stack dev + AI agent).

---

1. Tujuan & Kriteria Sukses

Tujuan: Aplikasi web internal untuk mengelola siklus siswa kursus coding — dari calon siswa, follow up, enrollment, kehadiran, pembayaran prorata, jurnal, raport, hingga placement test.

Kriteria sukses (v1.0):

1. Admin bisa CRUD siswa + follow up dan mengubah status CALON_STUDENT → STUDENT → EX_STUDENT tanpa Excel.
2. Dashboard menampilkan angka perlu follow up & ex student serta 3 grafik (siswa aktif, kehadiran, sumber lead) di right rail.
3. Pembayaran prorata per pertemuan (contoh Rp 2.000.000/10 → Rp 200.000/pertemuan) dengan metode Cash/Transfer/QRIS.
4. Guru bisa input kehadiran, jurnal+foto, dan raport per siswa.
5. Kelas dapat dikonfigurasi (nama, level, guru, jumlah pertemuan, harga, kapasitas, jadwal).
6. Hasil placement test tampil di detail siswa.
7. Semua role & data terlindungi RBAC; tidak ada payment gateway.
8. Lulus e2e flow utama + lint/typecheck/test hijau.

---

2. Ruang Lingkup

2.1 In Scope (v1.0)

• Auth & RBAC (Admin, Teacher)
• Shell layout: left nav + main + right rail
• CRUD Siswa (field lengkap + foto profil + status + sumber lead)
• Follow Up pipeline (kanban) + aktivitas + jadwal due
• CRUD Kelas + Enrollment + generate Session
• Kehadiran per pertemuan (bulk)
• Pembayaran prorata + metode + bukti
• Jurnal aktivitas + upload multi-foto
• Raport (aspek penilaian + publish)
• Placement Test (skor kategori + level + rekomendasi)
• Dashboard + grafik right rail
• Seed contoh data

2.2 Out of Scope (ditunda)

• Payment gateway / auto-reconciliation
• Notifikasi WhatsApp otomatis (v1.1, integrasi API)
• Portal/login untuk orang tua & siswa
• Multi-cabang / multi-tenant
• Mobile app native
• Absensi QR / face recognition
• Sertifikat otomatis (v1.1)
• Akuntansi/laporan keuangan lengkap

---

3. Asumsi, Tim & Kapasitas

Item	Asumsi
Tim	1 full-stack developer + AI agent (pair)
Desainer	1 part-time (audit visual di M1 & M7)
Stack	Sesuai AGENTS.md §2 (Next.js 15 + Prisma + Postgres)
Kapasitas	~5 hari kerja/minggu, ~6 jam efektif/hari
Lingkungan	Dev lokal + 1 staging (Vercel + Neon/Supabase)
Bahasa	UI Bahasa Indonesia
Data	Mulai dari seed.example.ts, direset tiap sprint

Definition of Ready (DoR): task punya deskripsi, acceptance criteria, dan file/lokasi yang dituju. Definition of Done (DoD): kode + test + lint/typecheck hijau, UI sesuai DESIGN.md, 4 state (loading/empty/error/success), sudah di-review agent/manusia.

---

4. Ringkasan Timeline

Minggu   1     2     3     4     5     6     7     8     9    10
M0 Setup ██
M1 Fondasi    ████
M2 Siswa &        ████
   Follow Up
M3 Kelas &             ████
   Kehadiran
M4 Pembayaran              ████
M5 Jurnal                       ████
M6 Raport &                          ████
   Placement
M7 Dashboard &                            ████
   Right Rail
M8 Hardening                                   ████
M9 UAT & Launch                                     ████

Milestone	Nama	Estimasi	Dependency	Requirement
M0	Setup & Scaffolding	3–4 hari	—	—
M1	Fondasi: Auth + Shell + Schema + Seed	1 minggu	M0	—
M2	Siswa & Follow Up	1,5 minggu	M1	#1, #7
M3	Kelas, Enrollment & Kehadiran	1,5 minggu	M1, M2	#5, #4
M4	Pembayaran Prorata	1 minggu	M3	#3
M5	Jurnal Aktivitas + Upload Foto	1 minggu	M3	#6
M6	Raport & Placement Test	1 minggu	M3	#4, #8
M7	Dashboard & Right Rail	1 minggu	M2–M6	#2, #7
M8	Hardening, QA & Polish	1 minggu	M0–M7	—
M9	UAT & Launch	1 minggu	M8	semua

---

5. Detail Per Milestone

M0 — Setup & Scaffolding (3–4 hari)

Goal: Repo siap dibangun, konvensi & CI berjalan.

Tasks

• Init Next.js 15 (App Router, TS strict) + pnpm + folder sesuai AGENTS.md §4
• Tailwind v4 + CSS tokens DESIGN.md §13 + font (Plus Jakarta Sans, Inter, Sora, JetBrains Mono)
• shadcn/ui + lucide-react + Recharts + TanStack Table + dnd-kit
• ESLint + Prettier + Husky + lint-staged
• .env.example, lib/utils.ts (cn, formatIDR, formatDateID)
• Prisma init + Postgres lokal (Docker) + script db:push/db:seed
• CI dasar (lint + typecheck + test)
• Halaman /health verifikasi deploy

Deliverable: pnpm dev jalan, tokens tampil di halaman contoh, CI hijau. Acceptance: pnpm lint && pnpm typecheck && pnpm test hijau.

---

M1 — Fondasi: Auth + Shell + Schema + Seed (1 minggu)

Goal: Shell 3 kolom + login + database + data contoh.

Tasks

• Finalisasi prisma/schema.prisma (AGENTS.md §6) + db:push
• Salin seed.example.ts → prisma/seed.ts, verifikasi output seed
• Auth.js v5 Credentials + session + hashPassword/verify
• Middleware proteksi route + withAuth + src/lib/rbac.ts
• AppShell: AppSidebar (248px, item aktif pill gradient, badge follow up), Topbar (breadcrumb, search, aksi, notif, avatar), RightRail (sticky, toggle)
• Komponen UI dasar: Button, Card, StatCard, Badge, Chip, Input, Segmented, Dropdown, Modal, Skeleton, EmptyState
• Halaman /login, redirect per role
• Audit visual desainer (palet, kontras, spacing)

Deliverable: Login berfungsi, shell responsif 3 breakpoint, halaman kosong per menu. Acceptance: login admin/teacher sukses; route terproteksi menolak tanpa sesi; nav highlight benar; skeleton tampil.

---

M2 — Siswa & Follow Up (1,5 minggu) → Req #1, #7

Goal: CRUD siswa lengkap + pipeline follow up.

Tasks

• lib/validators/student.ts (Zod) + followUp.ts
• API: /api/students (GET/POST), /api/students/[id] (GET/PATCH/DELETE/archive)
• Halaman /students: tabel + filter status/sumber/kelas + search + toggle tabel⇄kartu
• Form tambah/edit: foto (dropzone), nama, telepon, email, orang tua, sumber lead (segmented), status (segmented), multi-kelas
• Detail siswa: header profil + tab Ringkasan / Kelas / Pembayaran / Placement / Raport / Jurnal (tab diisi bertahap)
• StudentCard, StatusBadge, SourceChip
• Follow Up: /follow-up kanban (dnd-kit) 6 kolom + drag ubah status
• FollowUpActivity timeline + set nextFollowUpAt + PIC
• lib/follow-up.ts: query due (status ∉ ENROLLED/LOST && nextFollowUpAt ≤ endOfToday)
• Aksi "Enroll": ubah status → STUDENT, buat Enrollment (validasi kapasitas), arahkan ke pembayaran
• Tombol WhatsApp/Call (deep link wa.me, tel:)

Acceptance:

• CRUD siswa bertahan setelah refresh; foto terupload.
• Kanban drag mengubah status & tersimpan.
• followUpDue benar sesuai seed (2 due).
• Status siswa berubah otomatis saat enroll.
• Unit test follow-up.ts hijau.

---

M3 — Kelas, Enrollment & Kehadiran (1,5 minggu) → Req #5, #4

Goal: Konfigurasi kelas + pertemuan + absensi.

Tasks

• API /api/classes (CRUD) + /api/classes/[id]/sessions
• Halaman /classes: grid kartu (strip warna, progress kapasitas, jadwal)
• Form kelas: nama, kode unik, level, guru, totalMeetings, packagePrice, pricePerMeeting (auto-preview Rp/pertemuan), kapasitas, jadwal, warna, status
• Detail kelas: roster siswa, daftar sesi, tab jurnal
• Generate Session otomatis (weekly) saat kelas diaktifkan; opsi edit/hapus
• API /api/attendance (GET per sesi, bulk upsert)
• Halaman /attendance: pilih kelas → pertemuan → grid siswa + segmented H/T/I/S/A + "Hadir Semua" + progress 12/12 terisi
• lib/attendance.ts: attendanceRate
• Unit test validasi kapasitas & generate sesi

Acceptance:

• Kelas baru muncul & bisa dipilih di form siswa.
• Siswa ke-13 ditolak saat kapasitas 12 (pesan jelas).
• Kehadiran tersimpan per sesi & bisa diedit; rate benar.

---

M4 — Pembayaran Prorata (1 minggu) → Req #3

Goal: Input pembayaran per pertemuan + rekap.

Tasks

• lib/prorata.ts (PURE): pricePerMeeting, amount, usedMeetings, remainingMeetings, proratedValue, deriveStatus
• Unit test lengkap (batas: totalMeetings=0, bayar > total, parsial, kehadiran > kuota)
• API /api/payments (GET/POST), /api/payments/[id] (PATCH/refund)
• Halaman /payments: tabel invoice (mono), filter siswa/kelas/metode/status
• Form: pilih siswa → kelas (auto harga) → stepper meetingsPaid → kalkulasi prorata live → metode (Cash/Transfer/QRIS) → tanggal → upload bukti
• Nomor invoice otomatis (INV-YYYY-NNNN)
• Kartu ringkasan di detail siswa: Kuota 10 · Terpakai 6 · Sisa 4 · Nilai sisa Rp 800.000
• Badge "Perlu Perpanjang" bila sesi terpakai ≥ kuota

Acceptance:

• Input 10 pertemuan × Rp 200.000 = Rp 2.000.000.
• Sisa kuota & nilai sisa terhitung benar dari kehadiran.
• Metode tampil sebagai chip berwarna (Cash mint, Transfer sky, QRIS violet).
• Semua unit test prorata hijau.

---

M5 — Jurnal Aktivitas + Upload Foto (1 minggu) → Req #6

Goal: Feed aktivitas kelas dengan dokumentasi foto.

Tasks

• API /api/uploads (validasi tipe & ukuran, simpan ke public/uploads / S3)
• API /api/journals (GET feed/POST), /api/journals/[id] (GET/PATCH/DELETE)
• Halaman /journals: feed kartu (cover foto, judul, kelas, tanggal, tag, author, jumlah siswa)
• Form jurnal: multi-foto drag-reorder, judul, deskripsi, kelas, sesi, tag, tandai siswa terlibat
• Lightbox galeri foto
• Jurnal tampil di detail siswa (tab Jurnal) & detail kelas
• Empty/loading state sesuai DESIGN.md §8.7

Acceptance:

• Upload 4 foto berhasil, urutan tersimpan, tampil di feed & detail.
• Validasi tolak file > 5MB / non-gambar.
• Jurnal terkait siswa yang benar.

---

M6 — Raport & Placement Test (1 minggu) → Req #4, #8

Goal: Penilaian siswa + hasil tes penempatan.

Tasks

• API /api/report-cards (GET/POST), .../[id]/publish
• Form raport: aspek (Logika, Computational Thinking, Problem Solving, Kreativitas, Kolaborasi) 0–100 → rata-rata, grade otomatis A/B/C/D, catatan guru, ringkasan kehadiran
• Preview raport bertema (header gradient, tanda tangan guru) + tombol Publish
• Halaman /report-cards (list per kelas/periode)
• API /api/placements (GET/POST)
• Form placement: siswa, tanggal, pemeriksa, skor kategori → level otomatis + rekomendasi kelas
• Kartu Placement Test di detail siswa: level, skor per kategori (bar), rekomendasi, tanggal, pemeriksa, badge di header
• Unit test perhitungan grade & level

Acceptance:

• Raport Andi (seed) tampil dengan grade benar & bisa dipublish.
• Placement Elsa tampil Intermediate + rekomendasi JavaScript Intermediate.
• Badge level muncul di header profil siswa.

---

M7 — Dashboard & Right Rail (1 minggu) → Req #2, #7

Goal: Semua grafik & ringkasan.

Tasks

• API /api/dashboard/summary (paralel: counts + trend + leadSources + attendance)
• Hero sapaan + 4 StatCard besar (Siswa Aktif, Perlu Follow Up, Ex Student, Kehadiran %)
• Right rail widgets (DESIGN.md §9.1): stat stack, donut kehadiran, area tren siswa, bar sumber lead, list follow up hari ini, kelas hari ini
• Chart components (Recharts): ActiveStudentsChart, AttendanceDonut, LeadSourceBar + legend & tooltip Bahasa Indonesia
• Warna chart sesuai mapping DESIGN.md §3.5
• Responsif: rail jadi drawer < 1280px
• Animasi masuk 250ms + chart 400ms, hormati prefers-reduced-motion

Acceptance:

• Angka dashboard cocok dengan seed (4 aktif, 2 ex, 2 due).
• Bar chart sumber lead menampilkan WhatsApp/Referral/Banner/Social dengan angka.
• Rail tetap fungsional di tablet (drawer).

---

M8 — Hardening, QA & Polish (1 minggu)

Goal: Stabil, aman, cepat, aksesibel.

Tasks

• Audit RBAC semua route + test unauthorized
• Validasi Zod di semua boundary; sanitasi upload
• Optimasi query (index, hindari N+1) + loading.tsx/Suspense
• Aksesibilitas: fokus, label, kontras AA, target sentuh 44px
• Audit visual final (desainer) + konsistensi token
• Error boundary + toast + halaman 404/500
• E2E Playwright flow utama
• Dokumentasi singkat (README: setup & peran)

Acceptance:

• pnpm lint && typecheck && test && test:e2e hijau.
• Lighthouse mobile ≥ 90 performance/accessibility untuk dashboard.
• Tidak ada error di console.

---

M9 — UAT & Launch (1 minggu)

Goal: Rilis ke pengguna nyata.

Tasks

• Deploy staging + migrasi data contoh
• Sesi UAT dengan admin & 1 guru (skenario tasks)
• Perbaiki temuan blocker/high
• Backup & restore DB terdokumentasi
• Deploy production + domain + monitoring error (Sentry)
• Pelatihan singkat + panduan penggunaan
• Retrospective & susun backlog v1.1

Acceptance: Admin & guru menyelesaikan 8 skenario UAT tanpa bantuan; data produksi aman.

---

6. Backlog Prioritas (MoSCoW)

Must (v1.0): semua requirement #1–#8, auth/RBAC, seed, deploy. Should: dark mode, export CSV siswa/pembayaran, filter lanjutan, audit log, konfeti enroll. Could: notifikasi WhatsApp otomatis, sertifikat PDF, portal ortu, absensi QR, laporan pendapatan. Won't (kini): payment gateway, multi-cabang, mobile native.

---

7. Risiko & Mitigasi

Risiko	Dampak	Prob.	Mitigasi
Scope melebar (fitur baru saat coding)	Tinggi	Sedang	Kunci v1.0 ke Must; fitur baru masuk backlog v1.1
Logika prorata ambigu (refund/rollover)	Tinggi	Sedang	Kunci aturan di AGENTS.md §7.1 + unit test sebelum UI
Desain tidak konsisten antar halaman	Sedang	Sedang	Wajib pakai token DESIGN.md; audit di M1 & M8
Upload foto besar bikin lambat/biaya	Sedang	Sedang	Batasi 5MB, kompres (sharp), lazy-load
Kapasitas kelas & enrollment bentrok	Sedang	Rendah	Validasi server-side + test
Database drift schema	Sedang	Rendah	Migrasi Prisma, staging sebelum prod
Estimasi molor karena 1 dev	Sedang	Sedang	Prioritaskan Must tiap sprint; cut Should bila perlu

---

8. Tracking & Ritual

• Papan: GitHub Projects / Linear — kolom Backlog · Ready · In Progress · Review · Done.
• Sprint: 1 minggu, demo di akhir sprint (per milestone).
• Definition of Ready/Done: §3.
• Branch: feat/…, fix/…; PR wajib lulus CI + review.
• Commit: Conventional Commits.

---

9. Setelah v1.0 (v1.1+)

1. Notifikasi WhatsApp otomatis (reminder follow up, jadwal, tagihan).
2. Export laporan (CSV/PDF) & sertifikat siswa.
3. Portal orang tua/siswa (lihat raport, jadwal, tagihan).
4. Absensi QR + rekap otomatis.
5. Laporan pendapatan & aging piutang.
6. Multi-cabang + dashboard per cabang.
7. Dark mode & PWA.

---

10. Checklist Ringkas Per Requirement

Req	Fitur	Milestone	Status
1	CRUD follow up siswa baru (field lengkap + status)	M2	⬜
2	Right rail dashboard (siswa aktif, kehadiran, bar sumber lead)	M7	⬜
3	Pembayaran prorata + Cash/Transfer/QRIS	M4	⬜
4	Guru input jurnal, raport, kehadiran	M3, M5, M6	⬜
5	Konfigurasi kelas + pilih kelas saat input siswa	M3	⬜
6	Jurnal aktivitas + upload foto	M5	⬜
7	Dashboard: perlu follow up & ex student	M2, M7	⬜
8	Placement test tampil di info siswa	M6	⬜