157 lines
10 KiB
Markdown
157 lines
10 KiB
Markdown
# Retrospective — Epic 1: Course & Learning (2025-11-12)
|
||
|
||
## Ringkasan
|
||
- Halaman frontend `Courses` dan `Course Detail` telah dibuat dan tampil baik, namun data masih dummy (statik) dan belum terhubung API.
|
||
- Belum ada endpoint untuk `GET /api/courses`, `GET /api/courses/{courseId}`, `POST /api/progress/module`, dan `POST /api/assignments/{assignmentId}/submit` pada stack yang berjalan.
|
||
- Test integrasi untuk area kursus belum tersedia di `backend/tests`.
|
||
- Traceability AC → Spec → Components → Tests ditambahkan, namun sebagian referensi tes masih TBD hingga API dan test disiapkan.
|
||
|
||
## Bukti Implementasi Saat Ini
|
||
- UI kursus: `src/app/courses/page.tsx` (list kursus, progress, status, CTA)
|
||
- UI detail kursus: `src/app/course/[courseId]/page.tsx` (header, modul, progress, CTA)
|
||
- Keduanya menggunakan data dummy lokal (konstanta di file), belum melakukan `fetch` dari API.
|
||
|
||
## Scope yang Sudah Berjalan
|
||
- Tampilan grid kursus dengan statistik ringkas dan progress bar.
|
||
- Tampilan detail kursus dengan daftar modul, status terkunci/selesai, dan CTA navigasi modul.
|
||
- Konsistensi UI/UX dengan `DashboardLayout`, ikon, dan util `cn`.
|
||
|
||
## Gap & Tantangan
|
||
- API belum tersedia untuk katalog/detail kursus, progres modul idempotent, dan submission tugas + audit.
|
||
- Tidak ada test integrasi terkait kursus di `backend/tests`.
|
||
- State management dan idempotency untuk progres belum diikat ke API.
|
||
|
||
## NFR & Observabilitas (Status)
|
||
- Logging, metrics, alerting, audit trail untuk area kursus belum diterapkan; ditargetkan pada pengenalan API.
|
||
|
||
## Dependencies (Rujukan)
|
||
- Frontend: Next.js `14.x`, React `18.x`, TypeScript `5.x`, Tailwind `3.x`.
|
||
- Backend (eksisting untuk Epic 2): Node.js `18.x`, Express `4.x`, Jest `29.x`, Supertest `6.x`.
|
||
|
||
## Acceptance Criteria (AC) Epic 1 (Rujukan)
|
||
- E1-AC1: `GET /api/courses` mengembalikan daftar terpaginasikan; mendukung filter `q` (substring `title`).
|
||
- E1-AC2: `GET /api/courses/{courseId}` mengembalikan `id,title,description,modules[]`.
|
||
- E1-AC3: `POST /api/progress/module` idempotent via `idempotencyKey` (≤ 5 menit).
|
||
- E1-AC4: `POST /api/assignments/{assignmentId}/submit` mencatat audit (`submittedAt`, `contentRef`, `metadata`).
|
||
|
||
## Traceability Matrix (Ringkas)
|
||
| AC ID | Spec Section | Components | Story | Tests |
|
||
|---------|-------------------------------------------------|--------------------------------------------|--------------------------------------------------|-----------------------------------------|
|
||
| E1-AC1 | Area API: GET /api/courses | `src/app/courses`, server route (TBD) | `docs/stories/1-1-course-catalog-read-api.md` | TBD: `backend/tests/courses.test.js` |
|
||
| E1-AC2 | Area API: GET /api/courses/{courseId} | `src/app/course/[courseId]`, server route | `docs/stories/1-2-course-detail-read-api.md` | TBD: `backend/tests/courses.test.js` |
|
||
| E1-AC3 | Idempotency progres | `useProgressTracking`, server route (TBD) | `docs/stories/1-3-module-progress-update-api.md` | TBD: `backend/tests/courses.test.js` |
|
||
| E1-AC4 | Submission audit | `assignments` UI/route (TBD) | TBD: `docs/stories/1-4-assignment-submit-api.md` | TBD: `backend/tests/courses.test.js` |
|
||
|
||
## Keberhasilan
|
||
- UI responsif dan konsisten; struktur halaman jelas dan siap dihubungkan ke API.
|
||
- Desain komponen dan layout memudahkan perluasan fitur (modul, progres, tugas).
|
||
|
||
## Risiko & Mitigasi
|
||
- Risiko keterlambatan karena belum ada API kursus → Mitigasi: buat route handler Next.js sebagai stub minimal lalu integrasi bertahap.
|
||
- Idempotency progres berpotensi kompleks → Mitigasi: util idempotency sederhana dengan penyimpanan in-memory disertai audit.
|
||
|
||
## Follow-up Actions (Prioritas)
|
||
1. Implement Next.js route handler:
|
||
- `src/app/api/courses/route.ts` (GET, pagination + filter `q`).
|
||
- `src/app/api/courses/[courseId]/route.ts` (GET detail + `modules[]`).
|
||
- `src/app/api/progress/module/route.ts` (POST idempotent + audit minimal).
|
||
- `src/app/api/assignments/[assignmentId]/submit/route.ts` (POST + audit minimal).
|
||
2. Ubah `courses/page.tsx` dan `course/[courseId]/page.tsx` untuk `fetch` dari API.
|
||
3. Tambahkan test integrasi `backend/tests/courses.test.js` untuk katalog, detail, progres idempotency, submission audit.
|
||
4. Tambahkan logging terstruktur dan audit trail (minimal) di route handler.
|
||
5. Update traceability: ganti placeholder `TBD` dengan file test dan jalur komponen aktual.
|
||
|
||
## Status Gate
|
||
- Setelah langkah 1–3 selesai dan test hijau, Epic 1 siap integrasi lebih lanjut (auth, persistence, observability).
|
||
|
||
## Tahapan Implementasi & Integrasi (Runbook)
|
||
|
||
### Langkah 0 — Prasyarat & Konfigurasi
|
||
- Pastikan Node.js `>=18`, port backend `8000` tersedia.
|
||
- Tambah `.env.local` di frontend: `NEXT_PUBLIC_API_BASE_URL=http://localhost:8000`.
|
||
- Jika perlu, tambahkan `BACKEND_API_BASE_URL` untuk route API Next (proxy server-side).
|
||
|
||
### Langkah 1 — Menjalankan Backend
|
||
- Dari folder `backend`: `npm install` (sekali), lalu `npm run dev`.
|
||
- Verifikasi: `GET http://localhost:8000/health` → status `ok`.
|
||
|
||
### Langkah 2 — Verifikasi Endpoint Kursus (Backend Express)
|
||
- Katalog: `GET http://localhost:8000/api/courses?page=1&pageSize=20&q=` → `{ items[], total }`.
|
||
- Detail: `GET http://localhost:8000/api/courses/c1` → `{ id, title, modules[] }`.
|
||
- Progress modul (idempotent terima): `POST http://localhost:8000/api/modules/:moduleId/progress` → `202 accepted`.
|
||
|
||
### Langkah 3 — Route API Next.js (Proxy ke Backend)
|
||
- Buat/rapikan `src/app/api/courses/route.ts` → proxy query `page,pageSize,q` ke backend, response normalisasi `{ data, total, page, limit }`.
|
||
- Buat `src/app/api/courses/[courseId]/route.ts` → proxy detail kursus ke backend.
|
||
- Catatan: Gunakan `process.env.BACKEND_API_BASE_URL || process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:8000'` untuk base URL.
|
||
|
||
### Langkah 4 — Integrasi UI
|
||
- `src/app/courses/page.tsx`: ganti sumber `courses[]` dummy menjadi fetch ke `/api/courses?page=1&limit=20&q=` (via Next API).
|
||
- `src/app/course/[courseId]/page.tsx`: ambil detail dari `/api/courses/{courseId}`.
|
||
- Tambah state loading/error sederhana agar UX tetap informatif.
|
||
|
||
### Langkah 5 — Observabilitas & Audit (Minimal)
|
||
- Logging terstruktur di route Next: method, path, durasi, hasil (2xx/4xx/5xx).
|
||
- Audit progres modul: catat `moduleId`, `progressPercent`, `updatedAt` (server-side), idempotency key di backend.
|
||
|
||
### Langkah 6 — Testing & Gate
|
||
- Backend: `npm test` (ada tes untuk `/api/courses` dan detail, progres, dsb.).
|
||
- Tambah `backend/tests/courses.test.js` (follow-up) untuk spesifik katalog/detail jika diperlukan.
|
||
- Gate hijau: halaman UI tidak dummy, data tampil dari backend, tes backend hijau.
|
||
|
||
### Langkah 7 — Dev Server & Preview
|
||
- Frontend (root): `npm run dev` → buka `http://localhost:3000/courses`.
|
||
- Review UI setelah integrasi, pastikan status, progress, dan detail konsisten.
|
||
|
||
|
||
### Traceability Update
|
||
- Hapus `TBD` pada matriks: isi referensi file API Next (`src/app/api/courses/*`), pages (`src/app/courses`, `src/app/course/[courseId]`), dan tes backend (`backend/tests/*`).
|
||
|
||
## Admin — Scope & Alignment (c:/laragon/www/LMS-BGN/src/app/admin/)
|
||
|
||
### Halaman Admin Terkait
|
||
- `admin/analytics` dan `admin/analytics/insights`: ringkasan performa pembelajaran, tren penyelesaian kursus.
|
||
- `admin/analytics/reports`: laporan mendalam (export-ready) untuk progress dan keterlibatan.
|
||
- `admin/analytics/settings`: konfigurasi metrik dan periode pelaporan.
|
||
- `admin/certificates`: daftar sertifikat dan status kelulusan.
|
||
- `admin/exams` (+ `exams/[id]/*`): konfigurasi ujian dan pemantauan.
|
||
- `admin/questions/*` dan `admin/quiz-config`: bank soal dan pengaturan kuis.
|
||
- `admin/users/*`: manajemen pengguna, termasuk status enrollment dan kemajuan kursus.
|
||
- `admin/payroll`: (Terkait Epic 3) sinkronisasi reward/payroll berdasarkan penyelesaian.
|
||
|
||
### Dampak Langsung Epic 1 pada Admin
|
||
- Menyediakan data kursus (katalog, detail, modul) sebagai sumber metrik untuk `analytics` dan `reports`.
|
||
- Menampilkan ringkasan progress per pengguna di `users` (enrollment, % penyelesaian, tanggal mulai/selesai).
|
||
- Menghubungkan kelulusan kursus ke `certificates` (lihat status kelayakan dan penerbitan).
|
||
- Menyelaraskan `exams` dengan modul kursus (mapping modul → ujian) untuk konsistensi alur belajar.
|
||
|
||
### Integrasi Minimal (Tanpa Fallback)
|
||
- Gunakan API Next (proxy) yang sudah ada untuk konsumsi data kursus:
|
||
- `GET /api/courses` dan `GET /api/courses/{courseId}` sebagai data sumber di admin.
|
||
- Jika API gagal, tampilkan pesan error informatif di halaman admin; tidak ada fallback ke data dummy.
|
||
- Normalisasi skema respons agar konsisten (contoh: `{ data, total, page, limit }`).
|
||
|
||
### Rencana Route Admin (TBD, untuk iterasi berikut)
|
||
- `GET /api/admin/analytics/courses` → agregasi: total kursus, rata-rata progress, distribusi status.
|
||
- `GET /api/admin/analytics/users` → progress per pengguna, per kursus.
|
||
- `GET /api/admin/reports/courses/export` → export CSV/XLSX ringkasan progress.
|
||
- `GET /api/admin/certificates` → daftar sertifikat dan status kelayakan.
|
||
- Catatan: sementara, halaman admin dapat mengkonsumsi langsung dari `courses` API untuk metrik dasar.
|
||
|
||
### Observabilitas & Audit (Admin)
|
||
- Logging terstruktur di proxy admin (method, path, durasi, status).
|
||
- Audit view/report generation (timestamp, user admin, filter yang dipakai) untuk compliance.
|
||
|
||
### Traceability (Admin)
|
||
| Area | Halaman | Sumber Data | Status |
|
||
|------|---------|-------------|--------|
|
||
| Analytics (ringkas) | `admin/analytics` | `/api/courses` (aggregasi minimal di FE) | Mulai integrasi |
|
||
| Insights (tren) | `admin/analytics/insights` | `/api/courses` + waktu (TBD) | Rencana |
|
||
| Reports | `admin/analytics/reports` | `/api/courses` (export minimal) | Rencana |
|
||
| Certificates | `admin/certificates` | `/api/certificates` (TBD) | Rencana |
|
||
| Users (progress) | `admin/users` | `/api/courses` + map user (TBD) | Rencana |
|
||
| Exams mapping | `admin/exams` | modul kursus + ujian (TBD) | Rencana |
|
||
|
||
### Gate Admin untuk Epic 1
|
||
- Minimal: halaman `admin/analytics` menampilkan metrik dari data kursus nyata (tanpa dummy), loading/error jelas.
|
||
- Laporan dasar tersedia (tabel ringkas), export dapat menyusul. |