# 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.