# 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):

```ts
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`.