LMS-BGN/docs/epic-3-context.md

Epik 3 — Tech Context: Reward & Payroll Integration (Phase-1)

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

Tujuan

Menetapkan konteks teknis integrasi fase-1 antara reward (hasil pembelajaran) dan payroll: akrual reward, saldo, serta ekspor payload ke penyedia payroll (stub) dengan kontrol, idempoten, dan audit.

Lingkup Teknis

• Akrual reward berbasis event (progress modul selesai, assignment dinilai, lulus ujian)
• Baca saldo reward per karyawan dan per periode
• Referensi siklus payroll (periode, cutoff, status)
• Stub ekspor payroll: hasilkan payload CSV/JSON dengan mapping pay-code; throttle & audit
• Idempotensi job ekspor (job key), retry aman, dan kontrol approval (dual-control)

Model Konseptual (Outline)

• Employee: { id, payrollId, name, department }
• RewardPolicy: { id, code, description, calcType, payCode, limits }
• RewardTransaction: { id, employeeId, policyId, amount, sourceEvent, eventId, createdAt }
• RewardBalance: { employeeId, period, amount }
• PayrollCycle: { id, periodStart, periodEnd, cutoffDate, status }
• PayrollExportJob: { id, cycleId, status, payloadRef, createdAt, submittedAt }
• PayrollExportRecord: { jobId, employeeId, payCode, amount, notes }

Area API Terkait (Draft)

• GET /api/rewards/balance?employeeId&period
• GET /api/rewards/transactions?employeeId&period (read-only audit)
• GET /api/payroll/cycles
• POST /api/payroll/exports (stub; idempotent)
• GET /api/payroll/exports/{jobId}

Acceptance Gates

• Kebijakan reward & mapping pay-code disetujui HR/Finance
• Format ekspor (field, tipe, satuan) disepakati dengan penyedia payroll
• Idempotensi, recon, dan prosedur approval disetujui (dual-control)
• Data privacy (PII), audit trail, dan retensi log sesuai kebijakan

Dependencies

• HRIS/master karyawan & daftar pay-code resmi
• Sumber event dari LMS (progress, assignment, exam)
• Kanal integrasi penyedia payroll (untuk fase-1 hanya stub)

Risiko & Mitigasi

• Salah mapping/pay-code → validasi schema, checklist mapping, simulation/dry-run
• Duplikasi ekspor → idempotent job key, penandaan batch, recon laporan
• Kepatuhan data pribadi → minimisasi PII, akses berbasis peran, audit lengkap

Non-Fungsional

• Performa: batch processing, rate limit untuk export
• Observabilitas: metrics, logs, audit events, runbook untuk insiden
• Keamanan: RBAC untuk akses ekspor, tanda tangan payload jika perlu

Contract Principle

• Skema API/model/field mengikuti skema dummy frontend bila relevan untuk area payroll/reward.
• Perubahan mayor membutuhkan versioning & SOP approval lintas HR/Finance/Engineering.
• Field baru sebagai optional; validasi ketat setelah sinkronisasi.
• Rujukan Payroll: src/app/payroll-demo/page.tsx, src/app/admin/payroll/page.tsx.

Catatan

Dokumen konteks; implementasi backend ditunda sampai acceptance gates terpenuhi dan disetujui lintas HR/Finance/Engineering.