Lampiran¶

Referensi & troubleshooting umum.

A. Referensi Formula DSL¶

Konstanta (8 builtin)¶

Pakai syntax [KODE] di expression. Daftar konstanta yang tersedia (lookup juga di Master Data → Penggajian → tab Formula → toolbar Konstanta):

Kategori	Kode	Tipe	Sumber Data	Penjelasan
Karyawan	`[GP]`	DECIMAL	`karyawan_payroll_setting.gaji_pokok`	Gaji pokok dari Setting Karyawan
Karyawan	`[JD_MONTH]`	INTEGER	`karyawan.tanggal_bergabung`	Bulan join (1-12)
Karyawan	`[JD_YEAR]`	INTEGER	`karyawan.tanggal_bergabung`	Tahun join (4 digit)
Waktu Kerja	`[WH]`	DECIMAL	`evaluasi_excess_working_hours.total_menit_excess ÷ 60`	Excess working hours periode aktif (jam, signed: + lebih, − kurang)
Waktu Kerja	`[LMB]`	DECIMAL	`evaluasi_akumulasi_lembur.total_durasi_menit ÷ 60`	Total lembur DISETUJUI periode aktif (jam)
Waktu Kerja	`[CD_MONTH]`	INTEGER	`periode.tanggal_mulai.month`	Bulan periode aktif (1-12)
Waktu Kerja	`[CD_YEAR]`	INTEGER	`periode.tanggal_mulai.year`	Tahun periode aktif
Lainnya	`[YOS]`	INTEGER	computed	Years of Service: tahun penuh dari tanggal_bergabung ke periode aktif (anniversary-aware)

Operator¶

Kategori	Operator	Penjelasan
Aritmatika	`+ - * / %`	Tambah, kurang, kali, bagi, modulo
Perbandingan	`== != < > <= >=`	Hasil 0 (false) / 1 (true)
Logika	`AND OR NOT`	Boolean operations (untuk kondisi `IF`)
Pengelompokan	`( )`	Tanda kurung

Fungsi¶

Fungsi	Signature	Penjelasan
`IF(cond, a, b)`	3 arg	Kembalikan `a` jika `cond` true, `b` jika false
`MIN(a, b, ...)`	≥ 1 arg	Nilai terkecil dari semua argumen
`MAX(a, b, ...)`	≥ 1 arg	Nilai terbesar
`ROUND(x, n)`	2 arg	Pembulatan `x` ke `n` desimal
`MOD(a, b)`	2 arg	Sisa pembagian `a mod b`
`ABS(x)`	1 arg	Nilai absolut
`FLOOR(x)`	1 arg	Pembulatan ke bawah (lantai)
`CEIL(x)`	1 arg	Pembulatan ke atas (langit)

Contoh Real¶

[GP]                                                                              # Gaji pokok langsung
[GP] * [WH] * 8 / 173                                                             # Kelebihan Hari Kerja (jam excess × hourly rate)
[GP] * [LMB] / 173                                                                # Uang Lembur (jam lembur × hourly rate)
ROUND([GP] / 173, 2)                                                              # Tarif per jam pembulatan 2 desimal
IF([WH] > 0, [GP] * [WH] / 173, 0)                                                # Bayar lembur kalau excess > 0
IF(MOD([YOS], 5) == 0 AND [YOS] > 0 AND [JD_MONTH] == [CD_MONTH], [GP] * 3, 0)    # Cuti besar (anniversary 5 tahun + bulan match)
MIN(MAX([GP] * 0.05, 100000), 500000)                                             # Bonus 5% dari GP, min 100rb max 500rb

Validasi & Error¶

Saat simpan formula: - FORMULA_SYNTAX_ERROR — parser tolak karena tanda kurung tidak match, operator tidak dikenal, dll - FORMULA_UNKNOWN_CONSTANT — [KODE] tidak terdaftar di registry. Cek typo (case-insensitive) - FORMULA_UNKNOWN_FUNCTION — fungsi tidak ada (mis. SUM(...) — bukan fungsi yang didukung) - FORMULA_RUNTIME_ERROR — error saat evaluasi (mis. division by zero, type mismatch)

Live validation badge muncul di builder saat Anda mengetik. ✓ Valid (hijau) atau ✗ Error (merah) dengan pesan parser.

Preview di Builder¶

Tombol Preview di Formula builder: 1. Pilih karyawan (search NIK/nama) 2. Pilih periode (default: aktif) 3. Klik Hitung 4. Tampilkan hasil + breakdown nilai konstanta:

Hasil: Rp 5.000.000
Breakdown Konstanta:
  [GP]   = 5000000
  [WH]   = 12.50

B. Glosarium Lengkap¶

Domain HR¶

Istilah	Arti
Tenant	Organisasi/perusahaan yang menyewa aplikasi. Setiap tenant punya data terpisah.
Multi-tenant	Arsitektur 1 instance app melayani banyak tenant.
Biodata	Data identitas seseorang (KTP, alamat, keluarga, pendidikan). 1 biodata bisa jadi karyawan di banyak penempatan (mutasi).
Karyawan	Penempatan biodata pada satu jabatan + kelompok kerja, dengan nomor induk + tanggal bergabung.
Jabatan	Posisi/role di organisasi. Punya hierarki via `parent_id` dan level (golongan 1-20).
Golongan	`jabatan.level` (1-20). Dipakai untuk lookup tarif (fasilitas progressif, komponen perjalanan dinas).
Tipe Penempatan	INISIASI (karyawan baru) / PROMOSI / MUTASI / LAINNYA.
Status Kekaryawanan	Status karyawan (TETAP, KONTRAK, MAGANG, dll) — per tenant, master di Miscellaneous.
PII	Personally Identifiable Information. KTP, NPWP, nama ibu — disimpan terenkripsi.

Domain Waktu Kerja¶

Istilah	Arti
Shift / Waktu Kerja	Definisi 1 shift: jam masuk/pulang + window absensi (toleransi clock-in/clock-out).
Window absensi	Rentang jam yang valid untuk clock-in (`Earliest`-`Latest Clock-In`) atau clock-out.
Cross midnight	Shift yang lintas tengah malam (mis. 22:00-06:00 hari berikutnya).
Jadwal Kerja	Pola mingguan: shift apa di Senin/Selasa/.../Minggu.
Day-slot	1 dari 7 slot per minggu (Senin-Minggu). Bisa shift atau LIBUR.
Kelompok Kerja	Grup karyawan yang dapat assignment jadwal yang sama.
Assignment	Penugasan jadwal kerja ke kelompok kerja untuk rentang tanggal.
Hari Libur	Tanggal libur tenant (`HARI_BESAR` / `CUTI_BERSAMA`).

Domain Pipeline¶

Istilah	Arti
Periode	Periode payroll satu bulanan (mis. "2026-04").
Cut-off	Deadline submit pengajuan setelah `tanggal_selesai` periode.
Pola Periode	Template periode tenant: tanggal mulai-selesai + cut-off. Auto-generate kode.
Jadwal Harian Karyawan	Materialisasi: 1 row per (karyawan × tanggal periode) → `waktu_kerja_id`.
Realisasi	Hasil kalkulasi presensi harian per karyawan.
Status Efektif	Hasil status realisasi: HADIR / IZ (ijin) / AZ (alpa) / CT (cuti) / DN (dinas) / LB (libur).
Tutup Bulan	Snapshot evaluasi periode + bikin periode berikutnya.
Evaluasi	4 tabel snapshot per periode: excess working hours, kelebihan hari kerja, selisih absensi, akumulasi lembur.
Excess Working Hours (WH)	Selisih jam kerja: (jadwal_datang - clock_in) + (clock_out - jadwal_pulang). Signed.
Kelebihan Hari Kerja	Selisih: hadir_seharusnya - hadir_aktual per karyawan.
Akumulasi Lembur	Total durasi lembur DISETUJUI per karyawan periode.
Archive	Pindah data periode tertua ke Elasticsearch (cold storage).

Domain Penggajian¶

Istilah	Arti
Setting Karyawan	Setup payroll per karyawan: gaji_pokok + status_kekaryawanan + bank rekening.
Komponen Gaji	Baris yang muncul di slip gaji. Punya kategori (PENDAPATAN/POTONGAN/BENEFIT) + Model (FORMULA/FASILITAS/UPLOAD/PINJAMAN).
Model komponen	Source nilai komponen — menentukan cara resolve nominal.
Value Reference	Pointer polymorphic dari komponen ke entity sumber (formula.id / fasilitas_id / jenis_pinjaman.id).
Status Berhak (M:N)	List status_kekaryawanan yang berhak dapat komponen tsb.
Perhitungan Pajak	Kategori PPh 21 yang diterapkan saat kalkulasi pajak (8 enum).
Formula	Definisi rumus DSL reusable. Direferensi komponen `model=FORMULA`.
Konstanta Formula	Variabel `[KODE]` yang resolve ke data karyawan/periode/evaluasi runtime.
Fasilitas Progressif	Tunjangan dengan tarif berbeda per golongan jabatan.
Tarif (fasilitas)	Nominal per golongan + satuan periode (HARIAN/BULANAN).
Jenis Pinjaman	Master tipe pinjaman (Kasbon, Koperasi, Bank, dll).
Pinjaman Karyawan	Transaksi pinjaman per karyawan + angsuran flat per bulan.

Domain Proses Gaji¶

Istilah	Arti
Periode Lewat Terakhir	Periode dengan `tanggal_selesai < today()` paling baru — default fixed di sub-menu Proses Gaji.
Replicate Previous	Pattern UI: copy data periode sebelum, replace data periode aktif. Idempotent.
Pengecualian	Override final per (komponen × karyawan × periode). Bypass kalkulasi standar.
Idempotent	Property: re-run = same result, tidak duplikat / accumulate.
All-or-nothing CSV	Validasi upload: bila ada error, reject seluruhnya. Tidak partial-success.
Kalkulasi Idempotent	Tombol Kalkulasi: full DELETE + re-INSERT untuk periode tsb. Predictable.

C. Troubleshooting Umum¶

Masalah	Solusi
Email verifikasi tidak masuk	Cek folder spam. Klik "Kirim ulang verifikasi" di halaman status.
Lupa password	Klik "Lupa password" di login (akan kirim email reset).
"Kode tenant sudah dipakai"	Pilih kode lain. Kode unik global.
Captcha gagal terus	Refresh, pastikan JavaScript & cookies aktif.

Master Data¶

Masalah	Solusi
Tidak bisa hapus jabatan	Ada child aktif atau dipakai karyawan aktif. Pindahkan dulu.
Tidak bisa hapus shift	Dipakai jadwal_kerja aktif. Replace di jadwal dulu.
Kode duplikat saat tambah	Kode unique per tenant — pilih kode lain.
Range golongan tidak boleh?	Cek Profile Organisasi: range level (default 1-10) — sesuaikan bila perlu pakai golongan > 10.

Pengajuan¶

Masalah	Solusi
Approve cuti tapi konflik dengan ijin	Resolver auto-cancel cuti (per precedence). Cek log audit.
Tukar shift gagal: "tidak ada jadwal_harian"	Karyawan B belum punya jadwal_harian di tanggal tsb. Generate jadwal periode dulu.
Lembur slot penuh	Max 2 slot per karyawan per tanggal. Tunggu approve lembur lain dibatalkan.
SPD auto-reject	`today >= tanggal_mulai - 2`. Submit SPD ≥ 2 hari sebelum tanggal mulai.

Pipeline Periode¶

Masalah	Solusi
"Periode overlap" saat tambah	Periode tidak boleh overlap dengan existing. Akhiri periode lama dulu.
Generate jadwal harian: rows_inserted = 0	Cek apakah karyawan punya kelompok_kerja_id + assignment aktif di periode tsb.
Kalkulasi realisasi menghasilkan banyak AZ (alpha)	Cek `presence_capture` — mungkin data biometrik belum import; atau window absensi shift terlalu sempit.
Tutup bulan gagal	Cek error message — biasanya pengajuan PENDING di periode yang harus di-resolve dulu.

Proses Gaji¶

Masalah	Solusi
Banyak karyawan dapat 0 di komponen FORMULA `[GP]`	Setting Karyawan belum lengkap: `gaji_pokok` belum di-isi. Pakai script seed atau isi manual.
Komponen UPLOAD = 0 karyawan	Belum upload CSV / replicate. Aksi di Proses Gaji → Data Upload.
Komponen PINJAMAN = 0	Tidak ada `pinjaman_karyawan` aktif yang overlap periode. Cek tab Data Pinjaman.
Komponen FASILITAS kurang karyawan	Karyawan tidak punya `jabatan.level` valid; atau tarif tidak cover golongan tsb.
Status filter terlalu strict	Buka Komponen Gaji → cek "Status Berhak" — pastikan cover semua status karyawan.
Kalkulasi error / lambat	Cek backend log; untuk tenant besar (1000+ karyawan), kalkulasi bisa beberapa detik.
Kalkulasi tidak update setelah ubah Pengecualian	Manual klik Kalkulasi lagi (idempotent re-run).

Browser / UI¶

Masalah	Solusi
Halaman tidak load setelah login	Hard refresh (Ctrl+Shift+R). Clear cache bila perlu.
Sidebar tidak expand/collapse	Single-open accordion: hanya 1 section terbuka. Klik header lain untuk pindah.
Modal tidak bisa scroll	Modal punya max-height calc viewport; bila konten besar, body sticky scroll.
Logout otomatis	Token JWT expired (default 1 jam). Login ulang.

D. Kontak Bantuan¶

Issue / fitur missing → laporkan ke admin sistem internal organisasi Anda.

Untuk dokumentasi teknis (developer), lihat folder /documentation/ di repository: - api_endpoints.md — daftar 176 endpoint API - penggajian.md — modul payroll detail - proses_gaji.md — modul proses gaji detail - pipeline.md — modul periode + realisasi - waktu-kerja.md — modul jadwal & shift

E. Changelog Manual¶

Versi	Tanggal	Perubahan
1.0	2026-05	Manual awal, cover 7 bab utama (pendaftaran → kalkulasi).