# Guide Case Payroll: Kontrak & Komponen Tengah Bulan

## Tujuan
Panduan ini menjelaskan aturan bisnis dan cara hitung payroll saat:
- ada kontrak baru,
- ada update kontrak di tengah bulan,
- ada perubahan nominal komponen pendapatan/potongan di tengah bulan.

## Prinsip Utama
- Jangan overwrite data historis.
- Semua perubahan pakai tanggal efektif (`effective_start`).
- Periode payroll yang sudah `closed` tidak boleh diubah langsung.
- Perubahan setelah `closed` masuk sebagai `adjustment` di periode berikutnya.

## 1) Case Kontrak Baru
### Skenario
Karyawan mendapat kontrak baru per tanggal tertentu.

### Aturan
1. Tutup kontrak lama di `effective_start - 1 hari`.
2. Buat kontrak baru dengan `effective_start` baru.
3. Payroll periode berjalan dihitung prorata jika kontrak aktif berubah di tengah periode.

## 2) Case Update Kontrak Tengah Bulan
### Skenario
Jenis/nominal kontrak berubah pada tanggal 15.

### Aturan Hitung
1. Pecah periode payroll menjadi segmen:
- Segmen A: awal periode s/d 14
- Segmen B: 15 s/d akhir periode
2. Hitung prorata per segmen:

`nilai_segmen = nilai_bulanan x (hari_segmen / total_hari_periode)`

3. Total payroll komponen = jumlah semua segmen.

### Contoh
- Periode: Februari 2026 (28 hari)
- Gaji lama: Rp5.000.000 (1-14)
- Gaji baru: Rp6.000.000 (15-28)

Perhitungan:
- `5.000.000 x 14/28 = 2.500.000`
- `6.000.000 x 14/28 = 3.000.000`
- Total = `Rp5.500.000`

## 3) Case Perubahan Nominal Komponen Tengah Bulan
### Skenario
Tunjangan transport berubah pada tanggal 20.

### Aturan
1. Simpan versi komponen baru sebagai record baru (history).
2. Record lama ditutup pada H-1 dari tanggal efektif baru.
3. Hitung prorata per segmen tanggal seperti aturan kontrak.

### Contoh
- Periode: Januari 2026 (31 hari)
- Tunjangan lama: Rp1.000.000 (1-19)
- Tunjangan baru: Rp1.300.000 (20-31)

Perhitungan:
- `1.000.000 x 19/31 = 612.903`
- `1.300.000 x 12/31 = 503.226`
- Total = `Rp1.116.129`

## 4) Hak Cuti Tahunan
### Aturan Rekomendasi
- Hak cuti tahunan aktif jika:
1. `contract_completed = true`
2. `contract_no >= leave_eligible_contract_no` (dari profil bulan)

## 5) THR Proporsional
### Aturan Umum
`THR = basis_THR x (masa_kerja_bulan / 12)`

### Catatan
- Jika ada perubahan kontrak tengah bulan, gunakan kebijakan perusahaan:
1. mode detail: segmentasi prorata,
2. mode sederhana: pakai kontrak aktif terakhir.

## 6) Lock Periode & Adjustment
### Aturan
1. Jika periode `open`: perubahan boleh langsung dihitung ulang.
2. Jika periode `closed`: tidak boleh edit transaksi payroll lama.
3. Buat `adjustment` ke periode berikutnya dengan referensi periode asal.

## 7) Data Minimum yang Wajib Disimpan
- Header periode payroll: tanggal awal, tanggal akhir, tutup buku, status.
- Riwayat kontrak: `contract_no`, `effective_start`, `effective_end`, status.
- Riwayat komponen: kode komponen, nominal, `effective_start`, `effective_end`, alasan perubahan.
- Audit: `updated_by`, `updated_at`, catatan perubahan.

## 8) Checklist Implementasi
- Tabel history kontrak karyawan berbasis effective date.
- Tabel history nominal komponen berbasis effective date.
- Engine perhitungan segmentasi prorata harian.
- Validasi overlap tanggal agar tidak bentrok.
- Mekanisme lock periode closed + adjustment.
- Log audit perubahan.

## 9) Catatan Komponen Payroll (Per Karyawan)
Beberapa komponen bersifat sangat personal, jadi sumber datanya harus per orang:
- `T. Jabatan` dan `T. Keahlian` dibaca dari override karyawan di profil bulan atau field master karyawan.
- Jika belum diisi pada karyawan, komponen tersebut dianggap `0` (tidak memakai nilai default global profil gaji).

Tujuannya:
- mencegah tunjangan “ikut rata” ke semua karyawan,
- menghindari nilai tunjangan membengkak karena salah set default profil.

## 10) Catatan Perhitungan HK Basis (21 HK)
Jika profil bulan menggunakan basis HK tetap (mis. `21`) dan jam per hari (mis. `8`), maka:
- `Basis Jam = HK Basis x Jam/Hari` (contoh: `21 x 8 = 168`)
- `Jam Tdk. Masuk = max(0, Basis Jam - SUM(Jam Efektif))`
- `HK Masuk (hari) = Jam Masuk Normal / Jam/Hari`

Catatan:
- `Jam Efektif` = jam normal (bukan lembur), jadi lembur tidak menutup kekurangan HK.