# 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.