Business Logic & Workflows

PPH Score Calculation

Daily WMS Data → pph_daily_raw
        ↓
POST /api/scores/calculate (period)
        ↓
Aggregate: avg_pph, total_penalty, total_bonus, total_recovery
        ↓
Determine pph_level (from pph_threshold_config)
Determine violation_level (from violation_level_config)
        ↓
employee_period_scores (status: draft)
        ↓
Submit → manager_review → hr_approved → final

The score calculation aggregates daily PPH data, violations, bonuses, and recovery points into a single period score per employee.

Score Statuses

Status	Description	Who can advance
draft	Initial calculation	Leader submits
manager_review	Pending manager approval	Manager approves
hr_approved	Manager approved, pending HR	HR finalizes
final	Locked and finalized	—

---

Violation & Recovery Workflow

1. Create violation record (status: pending)
2. Leader CONFIRMS violation
   └─ System checks course_violation_links for violation_type_id
   └─ If course found:
       → Create recovery_records (type: skill_test, course_id, deadline)
       → points_recovered = penalty_points × max_recovery_pct / 100
       → auto_created = 1
   └─ If no course:
       → Create recovery_records (type: training, deadline=7 days)
3. Employee completes course/training
4. Manager APPROVES recovery
   └─ Points recovered credited to employee_period_scores
5. Score recalculated, net_penalty updated

Violation Statuses

Status	Description
pending	Newly created, awaiting confirmation
confirmed	Confirmed by leader, recovery auto-created
appealed	Employee has appealed
waived	Waived by management

Recovery Statuses

Status	Description
pending	Awaiting completion
approved	Manager approved, points recovered
rejected	Manager rejected
expired	Deadline passed without completion

---

13th Month Bonus Calculation

POST /api/benefits/thirteenth-month/calculate
    Parameters: period (year), warehouse_id (optional)
        ↓
For each employee:
    base = contract_salary × (attendance_hours / standard_hours_per_year)
    multiplier = pph_multiplier_config[pph_level]
    bonus = base × multiplier
    violation_deduction = based on violation_level
        ↓
13th month bonus records (status: draft)
        ↓
Individual or bulk approve

---

Benefit Eligibility

POST /api/benefits/calculate (period)
    ↓
For each employee in period:
    pph_level ← employee_period_scores
    violation_level ← employee_period_scores
    
    For each benefit_rule_config:
        eligible = pph_level >= required_pph_level
                AND violation_level <= required_violation_level
    ↓
benefit_eligibility records created/updated

Benefit Types

Type	Description
attendance_bonus	Monthly attendance bonus
competition	Competition/event awards
compensation	Damage compensation support
13th_month	Year-end 13th month bonus
health_insurance	Health insurance eligibility