# Epik 1 — Tech Context: Course & Learning Management

status: contexted
phase: backend-planning
note: Non-implementasi — konteks teknis & gating sebelum coding.

## Tujuan
Menetapkan konteks teknis untuk fitur Course & Learning: katalog kursus, detail, modul/lessons, progres, jadwal & penugasan.

## Lingkup Teknis
- Read-only API untuk katalog & detail kursus
- Mekanisme progres belajar per modul (idempotent updates)
- Draft kontrak penugasan (submission) dan jadwal
- Tanpa perubahan UI/DB produksi (non-implementasi)

## Model Konseptual (Outline)
- Course: { id, title, description, category, level, updatedAt }
- Module: { id, courseId, title, order }
- Lesson: { id, moduleId, title, order, duration }
- Progress: { userId, moduleId, totalProgress(0..100), updatedAt }
- Assignment: { id, courseId, title, dueAt }
- Submission: { id, assignmentId, userId, submittedAt, contentRef, metadata }

## Area API Terkait
- GET /api/courses (paging/filter/sorting)
- GET /api/courses/{courseId}
- POST /api/progress/module (idempotency)
- POST /api/assignments/{assignmentId}/submit (audit & metadata)

## Acceptance Gates
- Kontrak API disetujui PM/SM/Architect
- Privacy, rate limiting, akses kontrol disepakati
- Skema progres & aturan idempotency ditetapkan
- Audit trail & retention policy untuk submission disetujui

## Dependencies
- Data sinkron dengan katalog kursus eksisting
- Konsistensi relasi course→module→lesson

## Risiko & Mitigasi
- Risiko data bias/inkonsisten → validasi relasi saat kontrak
- Risiko spam update progres → idempotency key + rate limit

## Contract Principle
- Skema API/model/field mengikuti skema dummy frontend untuk Course & Module.
- Rujukan utama: `src/app/course/[courseId]/page.tsx` (Course & Module fields).
- Nama field dan struktur tidak boleh breaking terhadap frontend; perubahan mayor perlu versioning.
- Field baru ditambahkan sebagai optional; pengetatan dilakukan setelah sinkronisasi UI.

## Catatan
Dokumen ini hanya konteks & kontrak; implementasi backend ditunda sampai gate terpenuhi.

### Out-of-Scope (Eksplisit)
- Perubahan UI/DB produksi
- Integrasi eksternal (email, payment) di luar ruang Epik 1
- Scheduler/background jobs
- Real-time updates (WebSocket)

### NFR Ringkas (Reliability & Observability)
- Logging terstruktur (level, korelasi requestId, userId)
- Metrics: latency, throughput, error rate
- Alerting dasar untuk error ≥ p95
- Audit trail untuk update progres dan submission

### Dependencies (Versi Target)
- Next.js `14.x`, React `18.x`, TypeScript `5.x`, Tailwind `3.x`

### Acceptance Criteria (Atomik & Testable)
- GET `/api/courses` mengembalikan daftar terpaginasikan (default 10 item); mendukung filter `q` substring pada `title`.
- GET `/api/courses/{courseId}` mengembalikan field: `id,title,description,modules[]`.
- POST `/api/progress/module` bersifat idempotent menggunakan `idempotencyKey`; panggilan duplikat ≤ 5 menit mengembalikan hasil yang sama dan tidak menggandakan progres.
- POST `/api/assignments/{assignmentId}/submit` menyimpan `submittedAt`, `contentRef`, `metadata` dan mencatat audit.

### Test Strategy ↔ AC (Ringkas)
- Unit: util idempotency, validator payload submission.
- Integrasi: GET katalog/detail; POST progres (idempotency) dengan cek audit.
- E2E (smoke): alur kursus → modul → update progres → submit tugas.
- Observabilitas: verifikasi log audit muncul untuk progres & submission.

### Traceability Matrix (Ringkas)
| AC ID | Spec Section | Components | Story | Tests |
|------|---------------|-----------|-------|------|
| E1-AC1 | Area API: GET /api/courses | `src/app/courses`, server route | `docs/stories/1-1-course-catalog-read-api.md` | TBD: backend test untuk katalog kursus |
| E1-AC2 | Area API: GET /api/courses/{courseId} | `src/app/course/[courseId]` | `docs/stories/1-2-course-detail-read-api.md` | TBD: backend test untuk detail kursus |
| E1-AC3 | Idempotency progres | `useProgressTracking`, server route | `docs/stories/1-3-module-progress-update-api.md` | TBD: backend test untuk progres idempotent |
| E1-AC4 | Submission audit | `assignments` UI/route | TBD: `docs/stories/1-4-assignment-submit-api.md` | TBD: backend test untuk submission + audit |