6.3 KiB

Raw Blame History

Spesifikasi Teknis — LMS-BGN (Frontend Next.js 14)

Dihasilkan: 2025-11-12 Lintasan: quick-flow Level: 2 (Proyek Menengah) Jenis Bidang: brownfield

Catatan Koreksi (2025-11-12): Backend belum diimplementasikan pada fase ini. Semua rute API di dokumen ini bersifat rencana (non-implementasi). Pengiriman email "kirim ulang sertifikat" akan dilakukan setelah Acceptance Gate backend terpenuhi (PRD & Tech Spec sign-off, skema data final, ENV siap, alokasi waktu dev). Sementara itu, gunakan mock/JSON/Repo untuk data.

1. Tujuan & Ruang Lingkup

Menetapkan arsitektur, kontrak antarmuka, dan strategi implementasi untuk LMS-BGN.
Fokus pada frontend Next.js 14 (App Router) dengan TypeScript, Tailwind, dan modul fitur: kursus & belajar, assessment & sertifikasi, reward (phase-1, flagged), analytics admin, desktop UX, AI assistant (phase-1).

2. Konteks & Asumsi

Codebase frontend telah tersedia; backend penuh belum terintegrasi (gunakan mock/JSON/Repo interfaces sementara).
Pengiriman email “kirim ulang sertifikat” via rute API Next.js menggunakan ENV (Nodemailer).
Target utama: desktop-first; p95 waktu muat halaman utama < 2 detik.

3. Arsitektur Frontend

Framework: Next.js 14 App Router (src/app/*).
Styling: Tailwind CSS dengan token desain BGN (tailwind.config.js).
State: React Context (AuthContext.tsx, ExamContext.tsx) + hooks util (useExamPersistence, useProgressTracking).
Event bus: src/core/events/SystemEvents.ts untuk event bertipe antar fitur.
Feature flags: src/config/featureFlags.ts untuk modul opsional (reward, AI, dll.).
Modul utama:
- Course & Learning: src/app/course/*, src/components/course/*.
- Assessment & Sertifikasi: src/app/exam-session/*, src/app/exam-summary/*, src/components/admin/CertificatePDF.tsx.
- Reward (Phase-1): src/features/payroll-reward-system/* (dashboard, services, repositories, types).
- Analytics Admin: src/app/admin/analytics/*.
- Desktop UX: polishing lintas halaman learner.
- AI Assistant (Phase-1): src/app/ai-assistant/page.tsx.

4. Kontrak Antarmuka (TypeScript)

Contoh tipe terpadu untuk interoperabilitas; simpan di src/types/index.ts (atau modul terkait):

export interface Course {
  id: string;
  title: string;
  description?: string;
  modules: CourseModule[];
}

export interface CourseModule {
  id: string;
  title: string;
  lessons: Lesson[];
}

export interface Lesson {
  id: string;
  type: 'video' | 'text' | 'pdf';
  durationMinutes?: number;
}

export interface ProgressRecord {
  userId: string;
  courseId: string;
  completedLessonIds: string[];
  percent: number; // 0..100
  learningHours?: number;
}

export interface QuizQuestion {
  id: string;
  type: 'single' | 'multiple';
  prompt: string;
  options: { id: string; text: string }[];
  correctOptionIds: string[];
}

export interface ExamSession {
  id: string;
  courseId: string;
  userId: string;
  startedAt: string; // ISO
  expiresAt?: string; // ISO
  answers: Record<string, string | string[]>; // per Question.id
  score?: number;
}

export interface CertificateData {
  id: string;
  userId: string;
  courseId: string;
  issuedAt: string; // ISO
  status: 'issued' | 'pending' | 'revoked';
}

export interface RewardMetrics {
  userId: string;
  learningHours: number;
  lastUpdated: string; // ISO
}

Prinsip: gunakan tipe terpadu di komponen, hooks, repositori layanan agar konsisten.

5. Event Sistem (contoh)

COURSE_COMPLETED (payload: { userId, courseId }) → tingkatkan progres, evaluasi eligibility sertifikat.
EXAM_COMPLETED (payload: { userId, sessionId, score }) → hasil ujian & kelulusan.
CERTIFICATE_ISSUED (payload: { certificateId }) → tampilkan unduh, opsi kirim ulang.
REWARD_UPDATED (payload: { userId, learningHours }) → sinkron dashboard reward.

6. Feature Flags

rewardEnabled: mengaktifkan modul reward (phase-1).
aiAssistantEnabled: mengaktifkan halaman AI assistant (opsional).
certificateEmailResendEnabled: menampilkan aksi kirim ulang sertifikat.

7. Rute API Sertifikat (Resend)

Path: POST /api/certificates/[id]/resend.
Input: id di path; body opsional (mis. email override); validasi sederhana.
ENV: SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASS.
Response: 200 sukses; 400 input invalid; 404 tidak ditemukan; 500 error kirim.

8. Performa & Optimisasi

Target: p95 < 2 detik di halaman utama learner.
Praktik: code-splitting komponen berat (mis. grafik, PDF); lazy-load multimedia; cache data ringan (React Query jika dipakai); minimalkan re-render via memo/useMemo.

9. Keamanan & Privasi

ENV disimpan aman; jangan hardcode kredensial.
Data peserta terbatas pada kebutuhan UI; hindari PII sensitif.
Validasi input form & sanitasi konten yang ditampilkan.

10. Pengujian

Unit: hooks (useExamPersistence, useProgressTracking), util, komponen kritis.
Integrasi: alur learner utama (buka course → lesson → kuis/ujian → sertifikat).
Snapshot/UI: komponen tabel & kartu utama.
Performance smoke: ukur waktu muat utama pada build produk.

11. Implementasi (Quick-Flow)

Sprint 1 (MLP): Course/lesson viewer, progres dasar, kuis interaktif sederhana.
Sprint 2: Ujian terjadwal + ringkasan; sertifikat PDF & unduh.
Sprint 3: Analytics admin ringkas + export CSV; kirim ulang sertifikat via API.
Sprint 4: Desktop UX polishing; reward dashboard (phase-1, flagged); AI assistant (opsional).

12. Risiko & Mitigasi

Konten tidak siap → gunakan template & libatkan trainer sejak awal.
Performa lambat di desktop lama → optimisasi asset, virtualisasi list, audit Tailwind kelas berat.
Email gagal kirim → fallback notifikasi & retry; validasi ENV di startup.

13. Ketergantungan & Konfigurasi

Next.js 14, React 18, TypeScript, Tailwind.
Nodemailer (rute API); html2canvas & jspdf untuk PDF jika diperlukan.
tailwind.config.js: gunakan palet BGN, ukuran font, bayangan untuk konsistensi.

14. Kriteria Selesai (Tech-Spec)

Tipe terpadu tersedia dan dipakai di komponen/fitur utama.
Rute API resend terdokumentasi dengan ENV jelas.
Feature flags terdokumentasi dan aktif sesuai kebutuhan.
Rencana sprint rinci terhubung ke backlog (docs/mbg-lms-backlog.md).

15. Referensi

docs/bmm-index.md, docs/mbg-lms-prd.md, docs/mbg-lms-backlog.md, docs/mbg-lms-epic-plan.md, docs/mbg-lms-codebase-sync.md.

6.3 KiB Raw Blame History