Spaces:
Sleeping
Sleeping
File size: 4,282 Bytes
c43adb1 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 |
# 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
|