# PRD — Web App Presensi & Payroll

**Versi:** 1.0  
**Tanggal:** 29 Agustus 2026  
**Platform:** Web Application  
**Target:** HR / perusahaan / multi-cabang  
**Metode Presensi:** Geo-location + Face Recognition

---

## 1. Product Overview

Aplikasi ini merupakan platform **HR Attendance & Payroll** yang digunakan perusahaan untuk mengelola:

- Data karyawan
- Struktur organisasi
- Presensi
- Lokasi kerja
- Face recognition
- Shift dan jadwal kerja
- Cuti dan izin
- Lembur
- Komponen gaji
- Payroll
- Slip gaji
- Reimbursement
- Kasbon
- Laporan HR

Sistem dirancang agar dapat digunakan oleh perusahaan dengan **satu atau banyak cabang/lokasi kerja**.

---

## 2. Tujuan Produk

### Primary Goal

1. Mencatat kehadiran karyawan secara akurat.
2. Memastikan karyawan melakukan presensi dari lokasi yang diizinkan.
3. Memastikan identitas karyawan melalui face recognition.
4. Menghitung keterlambatan, ketidakhadiran dan lembur.
5. Menghasilkan payroll berdasarkan data aktual.
6. Mengurangi pekerjaan administratif HR.
7. Menyediakan Employee Self Service.

---

## 3. User Roles

### 3.1 Super Admin

Mengelola keseluruhan sistem:

- Company
- Branch
- Users
- Roles
- System Settings
- Subscription

### 3.2 Company Admin / HR

Mengelola:

- Employee
- Attendance
- Leave
- Overtime
- Payroll
- Organization
- Reports

### 3.3 Manager / Supervisor

Mengelola approval bawahan:

- Leave
- Permission
- Overtime
- Attendance correction
- Reimbursement

### 3.4 Finance

Mengelola:

- Payroll
- Reimbursement
- Loan
- Payroll payment
- Payroll report

### 3.5 Employee

Employee Self Service:

- Clock In
- Clock Out
- View attendance
- Leave request
- Permission
- Overtime request
- Reimbursement
- View payslip
- View salary

---

## 4. Organization Structure

```text
Company
   │
   ├── Branch
   │
   └── Division
          │
          └── Department
                 │
                 └── Position
                        │
                        └── Employee
```

### Master

- Company
- Branch
- Division
- Department
- Position
- Job Level
- Employee

---

## 5. Employee Management

HR dapat mengelola data karyawan.

### Data Utama

- Employee ID
- NIK
- Nama
- Foto
- Email
- No. Handphone
- Jenis Kelamin
- Tanggal Lahir
- Alamat
- Tanggal Masuk
- Tanggal Keluar
- Status
- Branch
- Department
- Position
- Manager

Dokumen employee yang diunggah disimpan pada storage aplikasi sebagai file
tervalidasi dengan nama berbasis jenis dokumen dan nomor dokumen
(`jenis-dokumen-document-number.ext`); database menyimpan metadata dan relative
path file tersebut.

### Employment Status

- Probation
- Contract
- Permanent
- Freelance
- Part Time
- Resigned
- Terminated

---

## 6. Face Recognition

Face recognition digunakan sebagai salah satu validasi ketika melakukan presensi.

### 6.1 Face Enrollment

Sebelum dapat melakukan presensi, karyawan harus melakukan registrasi wajah.

```text
Employee
   ↓
Open Face Registration
   ↓
Camera
   ↓
Capture Face
   ↓
Face Quality Check
   ↓
Generate Face Embedding
   ↓
Save Face Template
```

Sistem sebaiknya tidak menyimpan foto wajah mentah sebagai satu-satunya sumber identifikasi.

```text
Face Image
   ↓
Face Detection
   ↓
Face Embedding
   ↓
Encrypted Face Template
```

### 6.2 Face Verification

Saat presensi:

```text
Open Camera
   ↓
Detect Face
   ↓
Liveness Check
   ↓
Generate Embedding
   ↓
Compare Employee Face
   ↓
Match?
 ┌───┴───┐
YES      NO
 ↓        ↓
Continue Reject
```

### Validasi

- Face detected
- Face confidence
- Face similarity
- Liveness detection
- One face only
- Camera permission

---

## 7. Anti-Spoofing / Liveness

Face recognition harus mengantisipasi:

- Foto dari HP
- Screenshot
- Video
- Foto cetak

Contoh active liveness:

```text
Look straight
      ↓
Turn left
      ↓
Turn right
      ↓
Blink
```

Untuk MVP, dapat menggunakan passive atau active liveness tergantung library/provider yang digunakan.

---

## 8. Geo Location Attendance

Konfigurasi lokasi presensi dikelola langsung pada data Branch. Tidak ada
menu konfigurasi Geo Location terpisah pada MVP.

Presensi harus memvalidasi lokasi karyawan.

Setiap branch memiliki lokasi:

```text
Branch
Latitude
Longitude
Radius

Latitude, longitude, dan batas akurasi GPS wajib diisi agar branch dapat
digunakan sebagai geofence presensi. Radius juga wajib berupa nilai positif.
```

Contoh:

```text
PT ABC Bandung

Latitude  : -6.xxxxx
Longitude : 107.xxxxx
Radius    : 100 meter
```

Ketika presensi:

```text
Employee GPS
      ↓
Calculate Distance
      ↓
Inside Radius?
   ┌───┴───┐
 YES       NO
  ↓         ↓
Continue   Reject
```

---

## 9. Attendance Flow

### 9.1 Clock In

```text
Employee
   ↓
Open Attendance
   ↓
Request GPS
   ↓
Validate Location
   ↓
Open Camera
   ↓
Face Detection
   ↓
Liveness
   ↓
Face Verification
   ↓
Validate Schedule
   ↓
Clock In
```

Jika semua valid:

```text
Attendance = PRESENT
```

### 9.2 Clock Out

```text
Open Attendance
      ↓
Get GPS
      ↓
Validate Location
      ↓
Face Verification
      ↓
Clock Out
```

Sistem menghitung:

- Clock In
- Clock Out
- Working Duration
- Late Duration
- Early Leave
- Overtime

---

## 10. Attendance Status

Status yang tersedia:

- `PRESENT`
- `LATE`
- `ABSENT`
- `LEAVE`
- `SICK`
- `PERMISSION`
- `HOLIDAY`
- `DAY_OFF`
- `BUSINESS_TRIP`
- `WFH`

---

## 11. Attendance Record

Contoh:

```text
Date        : 29 Aug 2026
Employee    : EMP-001
Schedule    : 08:00 - 17:00

Clock In    : 08:13
Clock Out   : 17:05

Late        : 13 minutes
Work        : 7h 52m
Overtime    : 5 minutes

Location    : Branch Bandung
GPS Accuracy: 8 meter

Face Match  : 98.2%
```

Sistem menyimpan metadata audit:

- Latitude
- Longitude
- GPS accuracy
- Distance from branch
- Face verification result
- Face confidence/similarity
- Device/browser information
- Timestamp
- IP address

---

## 12. Shift Management

HR dapat membuat shift.

### Shift Pagi

```text
Start       08:00
End         17:00
Break       12:00 - 13:00
Late After  08:01
```

### Shift Siang

```text
Start       13:00
End         22:00
Break       17:00 - 18:00
```

### Shift Malam

```text
Start       22:00
End         07:00
Break       02:00 - 03:00
```

Sistem harus mendukung **overnight shift**.

---

## 13. Work Schedule

HR dapat menentukan jadwal karyawan.

```text
Employee: Budi

Mon   Shift Pagi
Tue   Shift Pagi
Wed   Shift Pagi
Thu   Shift Pagi
Fri   Shift Pagi
Sat   OFF
Sun   OFF
```

---

## 14. Leave Management

Karyawan dapat mengajukan cuti.

```text
Employee
   ↓
Create Leave Request
   ↓
Select Leave Type
   ↓
Select Date
   ↓
Reason
   ↓
Submit
   ↓
Manager Approval
   ↓
HR Approval
```

### Jenis Cuti

- Annual Leave
- Sick Leave
- Maternity Leave
- Special Leave
- Unpaid Leave
- Company Leave

### Event Balance

Selain saldo cuti berbasis hari, sistem mendukung saldo nominal untuk event
tertentu. `Event` hanya menyimpan master event perusahaan/cabang. Pada saat
mengelola Leave Balance, admin dapat memilih sumber saldo berupa Leave Type atau
Event. Saldo event dimiliki employee tertentu dan menyimpan nominal alokasi,
total pengeluaran, serta saldo tersisa.

Setiap pengeluaran dicatat sebagai Event Balance History dengan tanggal,
nominal, keterangan, saldo sebelum, dan saldo sesudah. History dapat dibuat,
diubah, dan dihapus oleh Web Admin serta disediakan melalui API untuk Web
Customer. Sistem menghitung ulang saldo secara transactional dan menolak
pengeluaran yang melebihi saldo tersedia.

---

## 15. Permission

Jenis izin:

- Telat
- Pulang cepat
- Tidak masuk
- Keperluan pribadi
- WFH
- Dinas luar

---

## 16. Overtime

Flow:

```text
Employee
   ↓
Overtime Request
   ↓
Manager Approval
   ↓
HR
   ↓
Payroll
```

Data:

- Date
- Start Time
- End Time
- Duration
- Reason
- Approval

---

## 17. Payroll

Payroll menggunakan:

```text
Employee
       +
Salary Structure
       +
Attendance
       +
Leave
       +
Overtime
       +
Allowance
       +
Bonus
       +
Deduction
       ↓
Payroll Calculation
       ↓
Net Salary
```

---

## 18. Salary Component

### Earning

- Basic Salary
- Transport Allowance
- Meal Allowance
- Position Allowance
- Attendance Allowance
- Overtime
- Bonus
- Commission

### Deduction

- BPJS
- PPh 21
- Loan
- Kasbon
- Late Penalty
- Absence Deduction
- Other Deduction

---

## 19. Salary Structure

Contoh:

```text
Salary Structure: Staff

Basic Salary       Rp5.000.000
Transport            Rp500.000
Meal                 Rp500.000
Attendance           Rp300.000
```

Salary structure dapat diberikan berdasarkan:

- Position
- Grade
- Employee
- Branch

---

## 20. Payroll Processing

### Payroll Period

```text
September 2026

Period:
01 Sep - 30 Sep

Payment:
30 Sep 2026
```

### Workflow

```text
Draft
 ↓
Calculate
 ↓
Review
 ↓
Approved
 ↓
Paid
 ↓
Closed
```

Setelah **Closed**, data payroll tidak boleh diubah sembarangan.

Jika ingin mengubah:

```text
Closed
 ↓
Request Reopen
 ↓
Authorization
 ↓
Recalculate
```

---

## 21. Payslip

Karyawan dapat melihat slip gaji.

```text
PT ABC

PAYSLIP
September 2026

Employee:
Budi

EARNINGS
Basic Salary       5.000.000
Transport            500.000
Overtime             300.000

DEDUCTION
BPJS                 100.000
PPh 21               150.000

-----------------------------
NET SALARY          5.550.000
```

Output:

- PDF
- Web
- Download
- Employee Portal

---

## 22. Loan / Kasbon

Fitur:

- Loan request
- Approval
- Loan amount
- Tenor
- Installment
- Remaining balance
- Automatic payroll deduction

Contoh:

```text
Loan             Rp6.000.000
Tenor            6 bulan
Installment      Rp1.000.000
```

---

## 23. Reimbursement

Employee dapat mengajukan:

- Transport
- Medical
- Internet
- Business expense
- Operational expense

Flow:

```text
Employee
 ↓
Submit
 ↓
Manager
 ↓
Finance
 ↓
Paid
```

---

## 24. Employee Self Service

Dashboard karyawan:

```text
┌──────────────────────────────┐
│ Good Morning, Budi           │
├──────────────────────────────┤
│ Attendance                   │
│ 08:03                        │
│ [ CLOCK OUT ]                │
├──────────────────────────────┤
│ Leave Balance    10 Days     │
│ Overtime          8 Hours    │
├──────────────────────────────┤
│ September Salary             │
│ Rp 5.550.000                 │
└──────────────────────────────┘
```

Fitur:

- Clock in/out
- Pengajuan cuti
- Pengajuan izin
- Pengajuan lembur
- Reimbursement
- Melihat slip gaji
- Melihat histori presensi
- Melihat saldo cuti
- Update profile

---

## 25. HR Dashboard

Dashboard HR menampilkan:

```text
TOTAL EMPLOYEE       125

PRESENT              112
LATE                   8
ABSENT                 3
LEAVE                  2
SICK                   0
```

Chart:

- Attendance trend
- Late trend
- Overtime
- Employee growth
- Payroll expense
- Upcoming company events
- Active company announcements

---

## 26. Reports

### Attendance

- Daily attendance
- Monthly attendance
- Late report
- Absent report
- Early leave
- Overtime

### Leave

- Leave report
- Leave balance
- Leave usage

### Payroll

- Payroll summary
- Salary report
- Deduction
- Overtime payroll
- Payroll by department
- Payroll by branch

### Employee

- Employee list
- Employee status
- Employee turnover

### Operations

- Company announcements: master pengumuman dengan status, waktu publish, dan
  waktu kedaluwarsa.
- Event master: event perusahaan/cabang yang dapat dipilih saat membuat event
  balance pada Leave Balance.
- Event balance history: histori pengeluaran saldo event per employee.

### 5.1 Master Data User Experience

Halaman master data seperti Company, Branch, Department, Division, Position,
Job Level, dan Employee harus menggunakan pola interaksi yang konsisten:

- Daftar data menggunakan tabel dengan nomor urut, search, pilihan jumlah data
  per halaman, informasi rentang data, dan pagination.
- Search, pagination, dan `per_page` diproses server-side agar tetap dapat
  digunakan saat jumlah data besar.
- Form dengan jumlah field sedikit dibuka melalui modal dari tombol aksi utama,
  bukan ditampilkan permanen di halaman.
- Input memiliki placeholder yang membantu dan tanda bintang `*` pada label
  untuk field wajib. Validasi form frontend menggunakan schema Zod; atribut
  HTML `required` tidak digunakan sebagai mekanisme validasi utama.
- Error validasi ditampilkan di bawah field terkait. Backend tetap menjadi
  sumber kebenaran untuk validasi keamanan, aturan bisnis, dan integritas data.
- Notifikasi hasil aksi menggunakan toast. Aksi destruktif menggunakan modal
  confirmation dan tidak menggunakan native browser alert/confirm.
- Implementasi frontend wajib memiliki page entry per module di feature masing-
  masing. Shared component digunakan untuk primitive UI dan pola layout yang
  reusable agar tampilan, spacing, accessibility, loading, empty, error, dan
  responsive state selaras antar-modul; layout, konfigurasi, dan aturan domain
  tetap berada di page module terkait.
- Division menjadi parent Department. Department wajib memilih Division dan
  Position wajib memilih Department; Branch tetap opsional untuk scope lokasi.
  Semua relasi wajib berada dalam company yang sama dan divalidasi ulang di
  backend.
- Users & Access ditampilkan dalam dua tab: Users dan Roles & Permissions.
  Super Admin dapat membuat, mengubah, menghapus user/role, menetapkan role ke
  user, serta menetapkan permission action ke role. Role `GLOBAL` hanya untuk
  akses platform dan tidak memiliki company; role `COMPANY` dan `BRANCH` wajib
  dimiliki satu company sehingga konfigurasi role dan permission antar-company
  dapat berbeda.

---

## 27. Approval Workflow

Approval dibuat **generic**, bukan hardcode per modul.

### Leave

```text
Employee
   ↓
Supervisor
   ↓
HR
```

### Overtime

```text
Employee
   ↓
Manager
   ↓
HR
```

### Reimbursement

```text
Employee
   ↓
Manager
   ↓
Finance
```

---

## 28. Notification

Notification untuk:

- Clock in reminder
- Clock out reminder
- Late
- Leave approval
- Leave rejection
- Overtime approval
- Payroll generated
- Payslip available
- Reimbursement approval

### Channel

- In-App Notification

Notification ditampilkan di dalam aplikasi melalui notification center, badge jumlah notifikasi belum dibaca, detail notifikasi, serta status read/unread.

Notification dapat mengarahkan user ke halaman atau detail terkait, misalnya detail approval, attendance, payroll, atau payslip.

Push notification tidak termasuk scope MVP.

---

## 29. Geolocation Security

Sistem menyimpan:

```text
latitude
longitude
accuracy
distance
timestamp
```

Jika:

```text
GPS Accuracy > 100m
```

sistem dapat menolak presensi atau meminta user mengulangi.

Sistem juga harus menangani:

- GPS disabled
- Permission denied
- Fake/mock location
- Location unavailable
- Poor GPS accuracy

---

## 30. Face Recognition Security

Face data merupakan data sensitif sehingga arsitektur harus memperhatikan:

- Encryption at rest
- Encryption in transit
- Access control
- Audit log
- Face template tidak dapat diakses sembarang user
- Retention policy
- Penghapusan data ketika employee keluar, sesuai kebijakan perusahaan dan hukum yang berlaku

Idealnya:

```text
Raw Image
   ↓
Face Processing
   ↓
Embedding
   ↓
Encrypt
   ↓
Database
```

Face embedding tidak boleh dikirim atau ditampilkan ke frontend.

---

## 31. Audit Log

Semua aktivitas penting dicatat.

Contoh:

```text
User:
HR Admin

Action:
UPDATE ATTENDANCE

Employee:
EMP-001

Before:
Clock In 08:30

After:
Clock In 08:00

Reason:
Attendance correction

Timestamp:
29 Aug 2026 09:15
```

Audit log juga digunakan untuk:

- Payroll
- Employee
- Salary
- Attendance
- Approval
- Face registration
- Location setting

---

## 32. Non-Functional Requirements

### Security

- HTTPS
- Authentication
- RBAC
- 2FA optional
- Encryption
- Audit log
- Session management
- Rate limiting

### Performance

Target:

```text
Dashboard < 2 seconds
Attendance API < 2 seconds
Payroll calculation < 30 seconds / 1.000 employees
```

### Availability

Target:

```text
99.9% uptime
```

---

## 33. Recommended Architecture

Stack yang direkomendasikan:

```text
Frontend
SvelteKit 5

        ↓ REST API

Backend
Laravel 13

        ↓

MySQL / PostgreSQL

        ↓
Redis
Queue
Cache
```

### Face Recognition

```text
Browser Camera
      ↓
Face Detection
      ↓
Liveness
      ↓
Face Verification Service
      ↓
Laravel API
```

Proses face recognition yang berat sebaiknya dipisahkan sebagai service tersendiri jika membutuhkan model AI yang berat.

---

## 34. High-Level Database

### Core Entity

```text
companies
branches
departments
divisions
positions
employees
employee_documents

users
roles
permissions

shifts
work_schedules
holidays

attendances
attendance_logs
attendance_corrections
attendance_locations
face_templates

leave_types
leave_balances
leave_requests
events
event_balance_histories
announcements
permission_requests

overtime_requests

salary_components
salary_structures
salary_structure_items
employee_salary_structures

payroll_periods
payrolls
payroll_items
payroll_adjustments
payslips

loans
loan_installments

reimbursements

approval_workflows
approval_requests

notifications
audit_logs
```

---

## 35. MVP

Untuk versi pertama, fokus pada modul yang membuat sistem sudah dapat digunakan perusahaan.

### MVP 1

```text
Authentication
    ↓
Company
    ↓
Branch
    ↓
Employee
    ↓
Department
    ↓
Position
    ↓
Shift
    ↓
Work Schedule
    ↓
Face Registration
    ↓
Geo Attendance
    ↓
Attendance Correction
    ↓
Leave
    ↓
Overtime
    ↓
Salary Component
    ↓
Salary Structure
    ↓
Payroll
    ↓
Payslip
    ↓
Report
```

Dengan MVP tersebut, alur utama sudah mencakup:

**Daftar karyawan → jadwal → absen → cuti/izin → lembur → payroll → slip gaji.**

---

## 36. Roadmap

### Phase 1 — Foundation

- Authentication
- RBAC
- Company
- Branch
- Employee
- Department
- Position

### Phase 2 — Attendance

- Shift
- Work Schedule
- Geo-location
- Face enrollment
- Face verification
- Liveness
- Clock In/Out
- Attendance correction

### Phase 3 — HR

- Leave
- Permission
- Holiday
- Overtime
- Approval

### Phase 4 — Payroll

- Salary Component
- Salary Structure
- Payroll Period
- Payroll Calculation
- Deduction
- Allowance
- Payslip

### Phase 5 — Advanced HR

- Loan/Kasbon
- Reimbursement
- Business Trip
- Performance/KPI
- Employee documents

### Phase 6 — Enterprise

- Multi-company
- Multi-branch
- Accounting integration
- Bank payroll
- Mobile application
- Biometric device
- Advanced analytics

### Data access scope

All completed master modules must enforce tenant scope on the backend. `GLOBAL`
roles may access all companies and branches; `COMPANY` roles are limited to
their assigned company; and `BRANCH` roles are limited to their assigned
company and branch. The same scope applies to list queries, form options,
detail access, and create/update/delete authorization.

---

## 37. Domain Architecture

Attendance Engine dan Payroll Engine sebaiknya dibuat sebagai dua domain terpisah.

```text
                 ┌───────────────┐
                 │   Employee    │
                 └───────┬───────┘
                         │
             ┌───────────┴───────────┐
             ↓                       ↓
      ┌─────────────┐        ┌─────────────┐
      │  Attendance │        │    Leave    │
      │ GPS + Face  │        │ Permission  │
      └──────┬──────┘        └──────┬──────┘
             │                      │
             └──────────┬───────────┘
                        ↓
                  ┌───────────┐
                  │  Overtime │
                  └─────┬─────┘
                        │
                        ↓
               ┌─────────────────┐
               │ Payroll Engine  │
               │                 │
               │ Salary          │
               │ Allowance       │
               │ Overtime        │
               │ Deduction       │
               │ Tax/BPJS        │
               └────────┬────────┘
                        ↓
                 ┌─────────────┐
                 │   Payslip   │
                 └─────────────┘
```

Dengan struktur ini, sistem dapat dikembangkan ke:

- Mobile app Flutter
- Mesin fingerprint
- Accounting integration
- Bank payroll
- Multi-company
- Advanced analytics

---

## 38. Future Features (HOLD)

Fitur yang dapat ditambahkan setelah MVP:

- Mobile App
- Push Notification
- Fingerprint Device Integration
- Face Recognition Device
- Advanced Liveness
- PPh 21 otomatis
- BPJS calculation
- Bank transfer payroll
- Accounting integration
- KPI & Performance
- Recruitment
- Training
- Asset Management
- Employee Onboarding/Offboarding
- Multi-company SaaS
