# Updated Payroll Screen Specifications

**Date:** 2026-06-12 | **Status:** PENDING BACKEND CONFIRMATION (Phase 11)
**Stack:** Laravel 12 Blade + Alpine.js + Tailwind CSS 3.4

---

## 1. PAYROLL PERIODS (ADM-25)

### Payroll Table

```html
<div class="bg-white dark:bg-slate-800 rounded-xl shadow-sm border border-slate-200 dark:border-slate-700">
  <div class="p-6 border-b border-slate-200 dark:border-slate-700">
    <div class="flex items-center justify-between">
      <h2 class="text-lg font-semibold text-slate-900 dark:text-slate-100">Payroll Periods</h2>
      <button class="bg-primary-600 hover:bg-primary-700 text-white text-sm font-semibold py-2 px-4 rounded-lg">+ New Period</button>
    </div>
  </div>
  <div class="overflow-x-auto">
    <table class="min-w-full divide-y divide-slate-200 dark:divide-slate-700">
      <thead class="bg-slate-50 dark:bg-slate-800">
        <tr>
          <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Period</th>
          <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Dates</th>
          <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Teachers</th>
          <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Gross</th>
          <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Net</th>
          <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Status</th>
          <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Actions</th>
        </tr>
      </thead>
      <tbody class="divide-y divide-slate-200 dark:divide-slate-700">
        <tr class="hover:bg-slate-50 dark:hover:bg-slate-800">
          <td class="px-6 py-4 text-sm font-medium text-slate-900 dark:text-slate-100">June 2026</td>
          <td class="px-6 py-4 text-sm text-slate-600">Jun 1–30</td>
          <td class="px-6 py-4 text-sm text-slate-600">15</td>
          <td class="px-6 py-4 text-sm">₵ 18,400</td>
          <td class="px-6 py-4 text-sm font-medium">₵ 15,640</td>
          <td class="px-6 py-4"><span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-green-100 text-green-800">Completed</span></td>
          <td class="px-6 py-4 text-sm">
            <button class="text-primary-600 hover:text-primary-700 font-medium mr-3">View</button>
            <button class="text-slate-500 hover:text-slate-700 font-medium">Export</button>
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</div>
```

### Status Badges

| Status | Tailwind Classes |
|--------|-----------------|
| Draft | `bg-slate-100 text-slate-800` |
| Preview | `bg-blue-100 text-blue-800` |
| Processing | `bg-amber-100 text-amber-800 animate-pulse` |
| Completed | `bg-green-100 text-green-800` |
| Cancelled | `bg-slate-100 text-slate-800 line-through` |

---

## 2. PAYROLL PERIOD DETAIL (ADM-26)

### Payroll Summary

```html
<div class="bg-white dark:bg-slate-800 rounded-xl shadow-sm border border-slate-200 dark:border-slate-700 p-6">
  <h3 class="text-lg font-semibold text-slate-900 dark:text-slate-100 mb-4">Payroll Summary</h3>
  <div class="grid grid-cols-2 lg:grid-cols-4 gap-4">
    <div>
      <p class="text-sm font-medium text-slate-500">Gross Earnings</p>
      <p class="text-2xl font-bold text-slate-900 dark:text-slate-100 mt-1">₵ 18,400</p>
    </div>
    <div>
      <p class="text-sm font-medium text-slate-500">Admin Fees</p>
      <p class="text-2xl font-bold text-red-600 mt-1">₵ 2,760</p>
      <p class="text-xs text-slate-500">15% applied</p>
    </div>
    <div>
      <p class="text-sm font-medium text-slate-500">Adjustments</p>
      <p class="text-2xl font-bold text-slate-900 dark:text-slate-100 mt-1">₵ 0</p>
    </div>
    <div>
      <p class="text-sm font-medium text-slate-500">Net Earnings</p>
      <p class="text-2xl font-bold text-green-600 mt-1">₵ 15,640</p>
    </div>
  </div>
</div>
```

### Teacher Payroll Table

```html
<table class="min-w-full divide-y divide-slate-200 dark:divide-slate-700">
  <thead class="bg-slate-50 dark:bg-slate-800">
    <tr>
      <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Teacher</th>
      <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Sessions</th>
      <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Gross</th>
      <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Admin Fee</th>
      <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Net</th>
      <th class="px-6 py-3 text-left text-xs font-medium text-slate-500 uppercase">Actions</th>
    </tr>
  </thead>
  <tbody class="divide-y divide-slate-200 dark:divide-slate-700">
    <tr class="hover:bg-slate-50 dark:hover:bg-slate-800">
      <td class="px-6 py-4 text-sm font-medium text-slate-900 dark:text-slate-100">Dr. Mensah</td>
      <td class="px-6 py-4 text-sm text-slate-600">24</td>
      <td class="px-6 py-4 text-sm">₵ 2,400</td>
      <td class="px-6 py-4 text-sm text-red-600">-₵ 360</td>
      <td class="px-6 py-4 text-sm font-medium">₵ 2,040</td>
      <td class="px-6 py-4 text-sm">
        <button class="text-primary-600 hover:text-primary-700 font-medium mr-3">Payslip</button>
        <button class="text-slate-500 hover:text-slate-700 font-medium">Adjust</button>
      </td>
    </tr>
  </tbody>
</table>
```

### Payslip Modal

```html
<div class="bg-white dark:bg-slate-800 rounded-xl shadow-sm border border-slate-200 dark:border-slate-700 p-8">
  <div class="text-center mb-6">
    <h3 class="text-xl font-bold text-primary-700">RP Learning Portal</h3>
    <p class="text-sm text-slate-500">PAYSLIP — June 2026</p>
  </div>
  <div class="space-y-4">
    <div class="flex justify-between text-sm">
      <span class="text-slate-500">Teacher</span>
      <span class="font-medium text-slate-900 dark:text-slate-100">Dr. Mensah</span>
    </div>
    <div class="flex justify-between text-sm">
      <span class="text-slate-500">Session Teaching (24 × ₵ 200)</span>
      <span class="text-slate-800 dark:text-slate-200">₵ 4,800</span>
    </div>
    <div class="flex justify-between text-sm">
      <span class="text-slate-500">Private Sessions (4 × ₵ 100)</span>
      <span class="text-slate-800 dark:text-slate-200">₵ 400</span>
    </div>
    <div class="border-t border-slate-200 dark:border-slate-700 pt-4 flex justify-between text-sm font-medium">
      <span class="text-slate-900 dark:text-slate-100">Gross Earnings</span>
      <span class="text-slate-900 dark:text-slate-100">₵ 2,400</span>
    </div>
    <div class="flex justify-between text-sm">
      <span class="text-slate-500">Admin Fee (15%)</span>
      <span class="text-red-600">-₵ 360</span>
    </div>
    <div class="border-t border-slate-200 dark:border-slate-700 pt-4 flex justify-between text-lg font-bold">
      <span class="text-slate-900 dark:text-slate-100">Net Earnings</span>
      <span class="text-green-600">₵ 2,040</span>
    </div>
  </div>
  <div class="mt-6 flex justify-end gap-3">
    <button class="px-4 py-2 text-sm font-medium text-slate-700 bg-slate-100 rounded-lg">Download PDF</button>
    <button class="px-4 py-2 text-sm font-medium text-white bg-primary-600 rounded-lg">Email to Teacher</button>
  </div>
</div>
```

### Processing Animation

```html
<div x-show="processing" class="bg-white dark:bg-slate-800 rounded-xl shadow-sm border border-slate-200 dark:border-slate-700 p-6">
  <p class="text-sm font-medium text-slate-900 dark:text-slate-100 mb-2">⏳ Processing Payroll — June 2026</p>
  <div class="w-full bg-slate-200 dark:bg-slate-700 rounded-full h-3 mb-2">
    <div class="bg-primary-600 h-3 rounded-full transition-all" style="width: 80%"></div>
  </div>
  <p class="text-xs text-slate-500">12/15 teachers processed — Currently: Mrs. Opoku</p>
</div>
```

---

## 3. WORKFLOW

### Processing Steps

```
1. Admin creates period (Draft)
2. Admin clicks [Preview Payroll] → Preview mode
3. Admin reviews calculations + adjustments
4. Admin clicks [Process Payroll] → Confirmation modal
5. Backend processes all teachers → Completed
6. Admin can [Export] or [Send Payslips]
```

---

## 4. CRITICAL BUSINESS RULE

**Admin Fee Snapshot:** The admin fee percentage is captured AT TIME OF PAYROLL EXECUTION and stored in `payroll_calculations.admin_fee_percentage_applied`. Historical payrolls ALWAYS show the rate that was applied, never the current rate.

---

## 5. PENDING BACKEND CONFIRMATION

| Dependency | Status | Required For |
|------------|--------|-------------|
| payroll_periods table | ⏳ PENDING | ADM-25, ADM-26 |
| payroll_calculations table | ⏳ PENDING | ADM-26, CH-06 |
| payroll_transactions table | ⏳ PENDING | ADM-26 |
| payroll_adjustments table | ⏳ PENDING | ADM-26 |
| payroll_audit_logs table | ⏳ PENDING | ADM-30 |
| PayrollCalculatorService | ⏳ PENDING | ADM-25, ADM-26, ADM-30 |
| teacher_compensation_settings | ✅ EXISTS | ADM-30 |