๐ข Sistem HR (Human Resource Management System)
Aplikasi manajemen SDM berbasis web yang dirancang untuk mempermudah pekerjaan sehari-hari tim HR โ mulai dari mengelola data karyawan, mencatat kehadiran, sampai memproses pengajuan cuti. Dibangun dengan arsitektur modern yang memisahkan backend (Laravel) dan frontend (React), sehingga mudah dikembangkan dan di-maintain ke depannya.
๐ Daftar Isi
- Gambaran Umum
- Fitur Utama
- Tech Stack
- Struktur Proyek
- Prasyarat
- Instalasi & Setup
- Menjalankan Aplikasi
- Akun Demo
- Panduan Penggunaan
- API Reference
- Database Schema
- Troubleshooting
๐ฏ Gambaran Umum
Sistem HR ini punya dua tipe pengguna dengan peran berbeda:
Admin HR โ orang yang mengelola seluruh data perusahaan. Bisa menambah/edit/hapus karyawan, mengatur jabatan & departemen, melihat rekap absensi semua orang, dan menyetujui atau menolak pengajuan cuti.
Karyawan โ pengguna biasa yang bisa melakukan check-in/check-out harian, mengajukan cuti, serta melihat riwayat kehadiran dan status cuti mereka sendiri.
Kedua peran ini masuk lewat halaman login yang sama โ sistem akan otomatis mengarahkan ke dashboard yang sesuai berdasarkan role masing-masing.
โจ Fitur Utama
Untuk Admin HR
| Fitur | Keterangan |
|---|---|
| Dashboard | Ringkasan statistik: total karyawan, karyawan aktif, absensi hari ini, dan cuti yang menunggu persetujuan |
| Manajemen Karyawan | CRUD lengkap dengan upload foto, filter berdasarkan departemen/jabatan/status, dan pagination |
| Jabatan | Kelola daftar jabatan (Manager, Staff, Senior Staff, dll.) dengan dialog form yang praktis |
| Departemen | Kelola departemen beserta kode uniknya (HR, IT, FIN, dll.) |
| Absensi | Lihat seluruh riwayat absensi karyawan, input manual, dan rekap bulanan per orang |
| Persetujuan Cuti | Review pengajuan cuti dari karyawan, setujui atau tolak dengan catatan |
| Export CSV | Export data karyawan, absensi, dan rekap absensi/cuti ke file CSV (siap buka di Excel) |
Untuk Karyawan
| Fitur | Keterangan |
|---|---|
| Dashboard | Info pribadi, sisa cuti, status absensi hari ini, dan riwayat cuti terakhir |
| Absensi | Check-in dan check-out dengan jam real-time, riwayat absensi per bulan |
| Pengajuan Cuti | Form pengajuan cuti dengan kalkulasi otomatis jumlah hari, pilih jenis cuti |
| Profil | Lihat data diri lengkap dan ubah password |
Keamanan, Akses & Real-Time
| Fitur | Keterangan |
|---|---|
| Role-Based Access | Admin dan Karyawan memiliki hak akses berbeda, dijaga di route & API |
| Token Auth | Sanctum Bearer Token โ otomatis logout jika token tidak valid (401) |
| Halaman 403 | Tampilan informatif jika user mencoba akses halaman yang bukan haknya |
| Halaman 404 | Halaman tidak ditemukan yang friendly |
| Laravel Reverb | Mengirim Notifikasi Status & Pengajuan Cuti secara Real-Time via Websockets |
๐ Tech Stack
Backend
| Komponen | Teknologi | Versi |
|---|---|---|
| Framework | Laravel | 12.x |
| Bahasa | PHP | โฅ 8.2 |
| Database | MySQL | 8.x |
| Autentikasi | Laravel Sanctum | 4.x |
| API | RESTful JSON API | โ |
Frontend
| Komponen | Teknologi | Versi |
|---|---|---|
| Library | React | 19.x |
| Build Tool | Vite | 8.x |
| CSS | Tailwind CSS | 4.x |
| UI Components | shadcn/ui (Radix) | terbaru |
| HTTP Client | Axios | 1.x |
| Routing | React Router | 7.x |
| Icons | Lucide React | 1.x |
| Date Utility | date-fns | 4.x |
| Toast | Sonner | 2.x |
๐ Struktur Proyek
cbi-test/
โโโ backend/ # Laravel API
โ โโโ app/
โ โ โโโ Enums/ # Enum classes (Gender, UserRole, LeaveType, dll.)
โ โ โโโ Http/
โ โ โ โโโ Controllers/Api/ # 7 controller RESTful
โ โ โ โโโ Middleware/ # RoleMiddleware untuk proteksi akses
โ โ โ โโโ Requests/ # Form Request validation per fitur
โ โ โ โโโ Resources/ # API Resource transformers
โ โ โโโ Models/ # Eloquent models (User, Position, Department, dll.)
โ โ โโโ Traits/ # ApiResponse trait untuk format JSON konsisten
โ โโโ database/
โ โ โโโ migrations/ # 9 file migrasi
โ โ โโโ seeders/ # Data awal lengkap (admin, 10 karyawan, absensi, cuti)
โ โโโ routes/
โ โ โโโ api.php # 35 endpoint API
โ โโโ .env # Konfigurasi environment
โ
โโโ frontend/ # React SPA
โ โโโ src/
โ โ โโโ components/
โ โ โ โโโ layout/ # AppLayout (sidebar + navbar responsif)
โ โ โ โโโ ui/ # Komponen shadcn/ui (button, dialog, table, dll.)
โ โ โโโ contexts/ # AuthContext untuk state management
โ โ โโโ lib/ # Utilities (cn, exportCsv)
โ โ โโโ pages/
โ โ โ โโโ LoginPage.jsx # Halaman login
โ โ โ โโโ ForbiddenPage.jsx # Halaman 403 akses ditolak
โ โ โ โโโ NotFoundPage.jsx # Halaman 404
โ โ โ โโโ admin/ # 7 halaman admin (dashboard, employees, dll.)
โ โ โ โโโ employee/ # 4 halaman karyawan (dashboard, attendance, dll.)
โ โ โโโ router/ # Route guards (ProtectedRoute, GuestRoute)
โ โ โโโ services/ # 8 service modules (Axios API calls)
โ โ โโโ App.jsx # Router utama
โ โโโ .env # VITE_API_URL
โ
โโโ README.md # Dokumentasi ini
๐ฆ Prasyarat
Sebelum mulai, pastikan kamu sudah punya ini di komputermu:
- PHP โฅ 8.2 โ Cek dengan
php -v - Composer โ Package manager PHP. Cek dengan
composer -V - Node.js โฅ 18 โ Cek dengan
node -v - npm โ Biasanya sudah bundled sama Node.js. Cek dengan
npm -v - MySQL 8.x โ Database server. Bisa pakai XAMPP, Laragon, atau install mandiri
- Git โ Untuk clone repository (opsional kalau sudah punya file-nya)
๐ก Tips: Kalau pakai Windows, Laragon adalah cara paling gampang untuk setup PHP + MySQL + Composer sekaligus.
๐ Instalasi & Setup
Langkah 1: Siapkan Database
Buka MySQL client kamu (phpMyAdmin, MySQL Workbench, atau terminal) lalu buat database baru:
CREATE DATABASE hris CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Langkah 2: Setup Backend (Laravel)
# Masuk ke folder backend
cd backend
# Install dependency PHP
composer install
# Salin file environment (kalau belum ada)
cp .env.example .env
# Di Windows: copy .env.example .env
# Generate application key
php artisan key:generate
Sekarang buka file .env dan sesuaikan konfigurasi database:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=hris
DB_USERNAME=root
DB_PASSWORD=
FRONTEND_URL=http://localhost:5173
Sesuaikan
DB_USERNAMEdanDB_PASSWORDdengan setup MySQL kamu. Kalau pakai Laragon/XAMPP default, biasanya usernameroottanpa password.
Lanjut jalankan migrasi dan seeder:
# Buat tabel-tabel di database
php artisan migrate
# Isi data awal (admin, karyawan, absensi, cuti)
php artisan db:seed
# Buat symlink untuk akses file upload (foto profil)
php artisan storage:link
Kalau semua lancar, kamu akan punya:
- 1 akun Admin HR
- 10 akun Karyawan
- Data absensi 7 hari terakhir
- 3 contoh pengajuan cuti (pending, approved, rejected)
Langkah 3: Setup Frontend (React)
# Masuk ke folder frontend
cd frontend
# Install dependency Node.js
npm install
Pastikan file .env di folder hr-frontend isinya:
VITE_API_URL=http://localhost:8000/api
Selesai! Aplikasi siap dijalankan. ๐
โถ Menjalankan Aplikasi
Kamu perlu membuka 3 terminal secara bersamaan โ dua untuk backend (Server + Websocket), dan satu untuk frontend.
Terminal 1: Backend (Laravel)
cd backend
php artisan serve
Backend akan berjalan di: http://localhost:8000
Terminal 2: Frontend (React)
cd frontend
npm run dev
Frontend akan berjalan di: http://localhost:5173
Terminal 3: Server WebSocket (Laravel Reverb)
cd backend
php artisan reverb:start
Server Reverb akan meng-handle semua koneksi real-time antara Node.js Frontend dan Laravel App.
Buka browser dan akses http://localhost:5173 โ kamu akan langsung diarahkan ke halaman login.
โ ๏ธ Penting: Backend dan Reverb harus jalan duluan sebelum frontend.
๐ Akun Demo
Setelah menjalankan php artisan db:seed, kamu bisa login dengan akun-akun berikut:
Admin HR
| Field | Nilai |
|---|---|
[email protected] |
|
| Password | password |
Karyawan (contoh beberapa)
| Nama | Password | |
|---|---|---|
| Budi Santoso | [email protected] |
password |
| Siti Rahayu | [email protected] |
password |
| Ahmad Fauzi | [email protected] |
password |
| Dewi Lestari | [email protected] |
password |
| Rizki Pratama | [email protected] |
password |
| Ani Wijayanti | [email protected] |
password |
| Eko Purnomo | [email protected] |
password |
| Rina Susanti | [email protected] |
password |
| Hendra Kurnia | [email protected] |
password |
| Maya Indah | [email protected] |
password |
Semua password karyawan sama:
password. Ini hanya untuk demo, jangan dipakai di production ya!
๐ Panduan Penggunaan
Login
- Buka http://localhost:5173
- Masukkan email dan password
- Sistem akan otomatis mengarahkan ke dashboard sesuai role:
- Admin โ
/admin/dashboard - Karyawan โ
/employee/dashboard
- Admin โ
Sebagai Admin HR
Dashboard
Begitu login, kamu langsung melihat ringkasan perusahaan:
- Total karyawan dan yang aktif
- Jumlah yang hadir hari ini
- Pengajuan cuti yang menunggu persetujuan
- Grafik komposisi departemen
Mengelola Karyawan
- Klik menu Karyawan di sidebar
- Gunakan kolom pencarian untuk cari berdasarkan nama, NIP, atau email
- Filter berdasarkan departemen atau status (aktif/non-aktif)
- Klik tombol Tambah Karyawan untuk membuat data baru
- Isi form lengkap: data pribadi, info pekerjaan, upload foto, dan set password
- Klik ikon pensil (โ๏ธ) untuk edit, atau ikon tempat sampah (๐๏ธ) untuk hapus
Mengelola Jabatan & Departemen
- Klik menu Jabatan atau Departemen di sidebar
- Klik Tambah โ muncul dialog form
- Isi data lalu klik Simpan
- Untuk edit, klik ikon pensil di baris yang diinginkan
Melihat Absensi
- Klik menu Absensi di sidebar
- Tab Daftar Absensi: lihat semua record absensi, filter berdasarkan status atau rentang tanggal
- Tab Rekap Bulanan: lihat ringkasan per karyawan (berapa kali hadir, sakit, izin, alpha)
- Klik Input Absensi Manual untuk menambah record absensi secara manual
Memproses Cuti
- Klik menu Cuti di sidebar
- Tab Menunggu: lihat pengajuan yang belum diproses
- Klik baris untuk lihat detail (siapa yang mengajukan, tanggal, alasan)
- Tambahkan catatan admin (opsional)
- Klik Setujui atau Tolak
Sebagai Karyawan
Dashboard
Melihat informasi pribadi, sisa jatah cuti, status absensi hari ini, dan riwayat cuti terbaru.
Check-in & Check-out
- Klik menu Absensi di sidebar
- Di bagian atas ada jam real-time โ klik Check In di pagi hari
- Sore hari, klik Check Out
- Di bawahnya ada riwayat absensi per bulan, bisa difilter
Mengajukan Cuti
- Klik menu Cuti di sidebar
- Lihat sisa jatah cuti di bagian atas
- Klik Ajukan Cuti
- Pilih jenis cuti (Tahunan, Sakit, Melahirkan, Lainnya)
- Tentukan tanggal mulai dan selesai โ jumlah hari otomatis terhitung
- Tulis alasan, lalu klik Kirim Pengajuan
- Lihat status di tabel riwayat: Menunggu โ Disetujui / Ditolak
Profil
- Klik menu Profil atau klik avatar di navbar
- Lihat data diri lengkap
- Bisa mengubah password di bagian bawah
๐ก API Reference
Semua endpoint menggunakan prefix /api dan mengembalikan format JSON yang konsisten:
{
"success": true,
"message": "Pesan deskriptif",
"data": { ... }
}
Untuk endpoint yang butuh autentikasi, sertakan header:
Authorization: Bearer {token}
Autentikasi
| Method | Endpoint | Deskripsi | Auth |
|---|---|---|---|
| POST | /api/auth/login |
Login, mendapatkan token | โ |
| POST | /api/auth/logout |
Logout, hapus token | โ |
| GET | /api/auth/me |
Data user yang sedang login | โ |
| POST | /api/auth/change-password |
Ubah password user aktif | โ |
Dashboard
| Method | Endpoint | Deskripsi | Role |
|---|---|---|---|
| GET | /api/dashboard/admin |
Statistik untuk Admin HR | Admin |
| GET | /api/dashboard/employee |
Ringkasan untuk Karyawan | Employee |
Karyawan
| Method | Endpoint | Deskripsi | Role |
|---|---|---|---|
| GET | /api/employees |
Daftar karyawan (paginasi, filter, search) | Admin |
| POST | /api/employees |
Tambah karyawan baru | Admin |
| GET | /api/employees/{id} |
Detail satu karyawan | Admin |
| PUT | /api/employees/{id} |
Update data karyawan | Admin |
| DELETE | /api/employees/{id} |
Hapus karyawan | Admin |
Query parameters untuk GET /api/employees:
searchโ Cari nama, NIP, atau emaildepartment_idโ Filter per departemenposition_idโ Filter per jabatanstatusโ Filter:activeatauinactiveper_pageโ Jumlah per halaman (default: 15)pageโ Nomor halaman
Jabatan
| Method | Endpoint | Deskripsi | Role |
|---|---|---|---|
| GET | /api/positions |
Daftar jabatan (paginasi) | Admin |
| GET | /api/positions/all |
Semua jabatan aktif (tanpa paginasi) | Admin |
| POST | /api/positions |
Tambah jabatan | Admin |
| GET | /api/positions/{id} |
Detail jabatan | Admin |
| PUT | /api/positions/{id} |
Update jabatan | Admin |
| DELETE | /api/positions/{id} |
Hapus jabatan | Admin |
Departemen
| Method | Endpoint | Deskripsi | Role |
|---|---|---|---|
| GET | /api/departments |
Daftar departemen (paginasi) | Admin |
| GET | /api/departments/all |
Semua departemen aktif (tanpa paginasi) | Admin |
| POST | /api/departments |
Tambah departemen | Admin |
| GET | /api/departments/{id} |
Detail departemen | Admin |
| PUT | /api/departments/{id} |
Update departemen | Admin |
| DELETE | /api/departments/{id} |
Hapus departemen | Admin |
Absensi
| Method | Endpoint | Deskripsi | Role |
|---|---|---|---|
| GET | /api/attendances |
Riwayat absensi (shared) | Semua |
| GET | /api/attendances/today |
Status absensi hari ini | Semua |
| POST | /api/attendances |
Input absensi manual | Admin |
| GET | /api/attendances/recap |
Rekap bulanan per karyawan | Admin |
| POST | /api/attendances/check-in |
Check-in hari ini | Employee |
| PUT | /api/attendances/check-out |
Check-out hari ini | Employee |
Cuti
| Method | Endpoint | Deskripsi | Role |
|---|---|---|---|
| GET | /api/leaves |
Daftar cuti (shared) | Semua |
| GET | /api/leaves/{id} |
Detail pengajuan cuti | Semua |
| POST | /api/leaves |
Ajukan cuti baru | Employee |
| PUT | /api/leaves/{id}/approve |
Setujui cuti | Admin |
| PUT | /api/leaves/{id}/reject |
Tolak cuti | Admin |
Lookup Data
| Method | Endpoint | Deskripsi | Auth |
|---|---|---|---|
| GET | /api/positions/all |
Semua jabatan aktif (tanpa paginasi) | โ |
| GET | /api/departments/all |
Semua departemen aktif (tanpa paginasi) | โ |
Catatan RBAC: Endpoint dengan role
Adminakan mengembalikan403 Forbiddenjika diakses oleh karyawan, dan sebaliknya.
๐ Database Schema
Aplikasi ini menggunakan 6 tabel utama:
users
Tabel utama untuk semua pengguna (admin maupun karyawan), dibedakan oleh kolom role.
| Kolom | Tipe | Keterangan |
|---|---|---|
| id | bigint (PK) | Auto increment |
| nip | varchar | Nomor Induk Pegawai, unique |
| name | varchar | Nama lengkap |
| varchar | Email, unique | |
| password | varchar | Password (hashed) |
| phone | varchar | Nomor telepon |
| address | text | Alamat |
| birth_date | date | Tanggal lahir |
| gender | enum | male, female |
| position_id | bigint (FK) | Referensi ke positions |
| department_id | bigint (FK) | Referensi ke departments |
| join_date | date | Tanggal bergabung |
| status | enum | active, inactive |
| photo | varchar | Path file foto |
| leave_quota | integer | Sisa jatah cuti (default: 12) |
| role | enum | admin, employee |
positions
| Kolom | Tipe | Keterangan |
|---|---|---|
| id | bigint (PK) | Auto increment |
| name | varchar | Nama jabatan |
| description | text | Deskripsi jabatan |
| status | enum | active, inactive |
departments
| Kolom | Tipe | Keterangan |
|---|---|---|
| id | bigint (PK) | Auto increment |
| name | varchar | Nama departemen |
| code | varchar | Kode singkat (HR, IT, FIN) |
| description | text | Deskripsi departemen |
| status | enum | active, inactive |
attendances
| Kolom | Tipe | Keterangan |
|---|---|---|
| id | bigint (PK) | Auto increment |
| user_id | bigint (FK) | Referensi ke users |
| date | date | Tanggal absensi |
| check_in | time | Jam masuk |
| check_out | time | Jam keluar |
| status | enum | present, sick, permit, absent |
| notes | text | Catatan tambahan |
leaves
| Kolom | Tipe | Keterangan |
|---|---|---|
| id | bigint (PK) | Auto increment |
| user_id | bigint (FK) | Karyawan yang mengajukan |
| type | enum | annual, sick, maternity, other |
| start_date | date | Tanggal mulai cuti |
| end_date | date | Tanggal selesai cuti |
| total_days | integer | Total hari cuti |
| reason | text | Alasan pengajuan |
| status | enum | pending, approved, rejected |
| admin_notes | text | Catatan dari admin saat approve/reject |
| approved_by | bigint (FK) | Admin yang memproses |
| processed_at | timestamp | Waktu diproses |
personal_access_tokens
Tabel bawaan Laravel Sanctum untuk menyimpan token autentikasi. Tidak perlu dikelola manual.
๐ง Troubleshooting
Backend tidak bisa connect ke database
SQLSTATE[HY000] [2002] Connection refused
- Pastikan MySQL sudah berjalan
- Cek konfigurasi
DB_HOST,DB_PORT,DB_DATABASE,DB_USERNAME,DB_PASSWORDdi file.env - Jalankan
php artisan config:clearsetelah mengubah.env
Frontend error CORS
Access to XMLHttpRequest at 'http://localhost:8000/api/...' has been blocked by CORS policy
- Pastikan
FRONTEND_URL=http://localhost:5173di file.envbackend - Jalankan
php artisan config:clear - Restart
php artisan serve
Frontend CSS error "@import must precede all other statements"
- Pastikan di file
src/index.css, baris@import url(...)untuk Google Fonts berada paling atas, sebelum@import "tailwindcss"dan lainnya
Halaman blank setelah login
- Buka DevTools browser (F12) โ tab Console, lihat error
- Pastikan backend sudah berjalan di port 8000
- Pastikan
VITE_API_URL=http://localhost:8000/apidi.envfrontend
Foto tidak muncul
- Jalankan
php artisan storage:linkdi folder backend - Pastikan folder
storage/app/public/photosbisa ditulis
WebSockets (Reverb) atau Notifikasi Cuti Tidak Merespon Real-Time
- Pastikan kamu menjalankan
php artisan reverb:startdi terminal backend terpisah (Terminal 3). - Pastikan variabel
VITE_REVERB_...sudah terdaftar di.envfrontend. - Kalau baru menempelkan variabel lingkungan (
.env), pastikan matikan layanan Vite lalu hidupkan ulangnpm run dev.
Mau reset semua data dari awal
cd backend
php artisan migrate:fresh --seed
Hati-hati, perintah ini menghapus semua tabel dan membuat ulang dari awal.
Cara Export CSV
- Login sebagai Admin HR
- Pergi ke halaman Karyawan, Absensi, atau Cuti
- Gunakan filter yang diinginkan (opsional)
- Klik tombol Export CSV di pojok kanan atas
- File
karyawan_YYYY-MM-DD.csv(atauabsensi_.../cuti_...) akan otomatis terunduh - Buka dengan Microsoft Excel, Google Sheets, atau aplikasi spreadsheet lainnya
File CSV menggunakan UTF-8 BOM agar karakter Indonesia (รก, รฉ, dll.) tampil dengan benar di Excel.
๐ Lisensi
Proyek ini dibuat untuk keperluan tugas/assessment dan bersifat open-source.
Dibuat dengan โ dan sedikit debugging.