docs/dev/project_roles_simplification.md

# Project Roles Simplification - Payment Structure Update

**Date**: December 11, 2024  
**Status**: Ready for Implementation  
**Migration**: `20251211_add_simple_compensation_fields.sql`

## Problem Statement

The original compensation structure was too complex for the Kenyan context where most workers are paid:
- Per day worked (e.g., 1000 KES/day)
- Per week (e.g., 7000 KES/week)
- Per work completed (e.g., 500 KES/ticket)

The old system used percentages, commissions, and bonuses which confused users during payment setup.

## Solution

Add three new simple compensation types with clear cash-based fields:

### New Compensation Types

1. **`per_day`** - Daily Rate
   - Field: `daily_rate`
   - Example: 1000 KES per day worked
   - Use case: Casual workers, helpers, daily laborers

2. **`per_week`** - Weekly Rate
   - Field: `weekly_rate`
   - Example: 7000 KES per week
   - Use case: Regular workers, supervisors

3. **`per_ticket`** - Per Work Done
   - Field: `per_ticket_rate`
   - Example: 500 KES per ticket completed
   - Use case: Technicians, field agents paid per job

### Backward Compatibility

All old fields remain unchanged:
- `flat_rate_amount` (legacy weekly rate)
- `commission_percentage`
- `base_amount`
- `bonus_percentage`
- `hourly_rate`

Old compensation types still work:
- `flat_rate`
- `commission`
- `hybrid`
- `hourly`
- `custom`

## Database Changes

```sql
-- New fields added
daily_rate NUMERIC(12,2)
weekly_rate NUMERIC(12,2)
per_ticket_rate NUMERIC(12,2)

-- New enum values added
'per_day'
'per_week'
'per_ticket'
```

## Usage Examples

### Example 1: Daily Worker (Helper)
```json
{
  "role_name": "Helper",
  "compensation_type": "per_day",
  "daily_rate": 800.00,
  "description": "General helper for installations"
}
```

**Payroll Calculation**:
- Monday-Friday worked = 5 days
- Weekly pay = 5 × 800 = 4,000 KES

### Example 2: Ticket-Based Technician
```json
{
  "role_name": "Technician",
  "compensation_type": "per_ticket",
  "per_ticket_rate": 600.00,
  "description": "FTTH installation technician"
}
```

**Payroll Calculation**:
- Completed 8 tickets this week
- Weekly pay = 8 × 600 = 4,800 KES

### Example 3: Weekly Supervisor
```json
{
  "role_name": "Supervisor",
  "compensation_type": "per_week",
  "weekly_rate": 7000.00,
  "description": "Site supervisor"
}
```

**Payroll Calculation**:
- Fixed weekly pay = 7,000 KES

## Migration Steps

1. **Run SQL Migration**
   ```bash
   # In Supabase SQL Editor
   # Execute: supabase/migrations/20251211_add_simple_compensation_fields.sql
   ```

2. **Update Python Code** (Already done)
   - ✅ Models updated (`src/app/models/project.py`)
   - ✅ Enums updated (`src/app/models/enums.py`)
   - ✅ Schemas updated (`src/app/schemas/project.py`)

3. **Update Frontend** (TODO)
   - Show simple types first (per_day, per_week, per_ticket)
   - Move complex types to "Advanced" section
   - Add clear labels in Swahili/English

4. **Update Payroll Service** (TODO)
   - Add calculation logic for new types
   - Handle daily_rate: days_worked × daily_rate
   - Handle weekly_rate: fixed amount
   - Handle per_ticket_rate: tickets_closed × per_ticket_rate

## Payroll Service Updates Needed

```python
# In user_payroll calculation
if role.compensation_type == "per_day":
    earnings = days_worked * role.daily_rate
elif role.compensation_type == "per_week":
    earnings = role.weekly_rate
elif role.compensation_type == "per_ticket":
    earnings = tickets_closed * role.per_ticket_rate
# ... existing logic for old types
```

## Benefits

1. **Clarity**: "1000 KES per day" is immediately clear
2. **Simplicity**: No percentages or complex calculations
3. **Kenyan Context**: Matches how people actually get paid
4. **Backward Compatible**: Existing roles continue working
5. **Flexible**: Can still use advanced types when needed

## Next Steps

1. ✅ Create migration file
2. ✅ Update Python models/schemas
3. ⏳ Run migration in Supabase
4. ⏳ Update payroll calculation service
5. ⏳ Update frontend UI
6. ⏳ Test with real data
7. ⏳ Update documentation

## Notes

- No min/max limits added (keeping it simple)
- No per_hour type added (hourly already exists)
- All changes are additive (no deletions)
- Zero breaking changes to existing code