154 lines
6.3 KiB
Markdown
154 lines
6.3 KiB
Markdown
# 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`. |