root
/
LMS-BGN
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
LMS-BGN/docs/retrospectives/epic-1-retrospective-2025-1...

10 KiB
Raw Blame History

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.