# Payroll Permission Key Cross-Walk

## Purpose

This document maps BuyerKiosk role names to UF group IDs (`uf_authorize_group.group_id`) as used in the
payroll permission migration (`20260522_016_payroll_permission_keys.json`). Future permission changes
should consult this cross-walk rather than reverse-engineering the mapping from migration history.

## BK Role Name → UF Group ID

| BK Role Name | UF `group_id` | Notes |
|---|---|---|
| Employee | 1 | Frontline worker; view-own-earnings + own-PTO-request only |
| Site Admin | 2 | BK-internal admin; gets all Owner-equivalent permissions |
| Manager | 7 | Store manager; submit, view, onboarding, PTO, termination, punch adjustment |
| Shift Lead | 8 | Shift lead; view-only pay runs + own earnings + own PTO requests |
| Owner | 9 | Store owner; all 12 payroll permissions |

**Source:** Derived from `userfrosting/migrations/input/20251220_013_010_schedule_permissions.json`
which uses `(2, 7, 8, 9)` for Admin/Manager/ShiftLead/Owner on scheduling permissions.

**Note on Super Admin:** `g9` serves as both Store Owner and Super Admin in this codebase.
There is no separate Super Admin group ID — the Owner group (g9) holds all permissions.
Site Admin (g2) is BK-internal staff and receives the same permission set as Owner for all
payroll operations.

---

## Permission Key → Granted Groups

| Permission Key | Employee (g1) | Site Admin (g2) | Manager (g7) | Shift Lead (g8) | Owner (g9) |
|---|:---:|:---:|:---:|:---:|:---:|
| `manage_payroll` | — | ✓ | — | — | ✓ |
| `submit_pay_run` | — | ✓ | ✓ | — | ✓ |
| `approve_pay_run` | — | ✓ | — | — | ✓ |
| `approve_pay_run_above_threshold` | — | ✓ | — | — | ✓ |
| `view_pay_run` | — | ✓ | ✓ | ✓ | ✓ |
| `set_pay_rate` | — | ✓ | — | — | ✓ |
| `view_own_earnings` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `kickoff_employee_onboarding` | — | ✓ | ✓ | — | ✓ |
| `approve_pto_request` | — | ✓ | ✓ | — | ✓ |
| `request_pto` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `terminate_employee` | — | ✓ | ✓ | — | ✓ |
| `create_punch_adjustment` | — | ✓ | ✓ | — | ✓ |

---

## Design Rationale

Per PRD Feature 10 (lines 201-206):

- **Owner (g9)** has ALL manage permissions (manage, approve, set rates, etc.)
- **Manager (g7)** has operational permissions: submit pay run, view, onboarding kickoff,
  PTO approve, termination kickoff, punch adjustment
- **Shift Lead (g8)** is view-only: view pay runs, own earnings, own PTO requests
- **Employee (g1)** has only personal permissions: own earnings, own PTO requests
- **Site Admin (g2)** is BK-internal staff equivalent to Owner for all payroll operations

---

## Adding Future Permissions

1. Add an `insert` operation to `20260522_016_payroll_permission_keys.json`
   (or create a new dated migration file for post-Phase-0 additions)
2. Update this cross-walk table
3. Set `check_query` to `SELECT id FROM uf_authorize_group WHERE hook = '<new_key>' LIMIT 1`
4. Use `conditions = 'always()'` per the established BK convention

---

## Related Files

- `userfrosting/migrations/input/20260522_016_payroll_permission_keys.json` — migration that inserts these rows
- `userfrosting/migrations/input/20251220_013_010_schedule_permissions.json` — reference template for permission insert pattern
- `docs/specs/050-everee-payroll-foundations/solution-design.md` §"Permission keys migration" — SDD source for this mapping