# Penalty System - Quick Reference Card

## For Administrators

### Viewing Penalties

1. **On Loan Detail Page**
   - Scroll to "Penalty Charges" section
   - See total penalties, penalty rate, and frequency
   - View list of all penalties (automatic and manual)

2. **Penalty Indicators**
   - 🤖 **Auto** badge = Automatically applied by system
   - 👤 **Manual** badge = Applied by staff member
   - 🟢 **Automatic** mode = System applies penalties daily
   - 🟡 **Manual** mode = Staff must apply penalties

### Applying Manual Penalties

1. Navigate to overdue loan
2. Click **"Apply Penalty"** button
3. Enter penalty amount (suggested amount is pre-filled)
4. Enter reason for penalty
5. Click **"Apply Penalty"** to confirm

**Note:** You can only apply penalties to overdue loans.

### Deleting Penalties

- Only **manual penalties** can be deleted
- Automatic penalties cannot be deleted (audit trail)
- Click the 🗑️ **Delete** button next to manual penalty
- Confirm deletion

### Penalty Calculation

#### Daily Penalties
```
Penalty = Outstanding Amount × Rate% × Days Overdue
Example: KES 10,000 × 2% × 5 days = KES 1,000
```

#### Weekly Penalties
```
Penalty = Outstanding Amount × Rate% × Weeks Overdue
Example: KES 50,000 × 5% × 2 weeks = KES 5,000
```

#### Monthly Penalties
```
Penalty = Outstanding Amount × Rate% × Months Overdue
Example: KES 100,000 × 10% × 2 months = KES 20,000
```

### Penalty Modes by Product

| Product | Mode | Frequency | Rate |
|---------|------|-----------|------|
| Boost | Automatic | Daily | 2.0% |
| Boost Plus | Automatic | Daily | 2.5% |
| Mwamba | Manual | Weekly | 5.0% |
| Imara | Automatic | Monthly | 10.0% |

### Common Tasks

#### Check if Automatic Penalties are Running
```bash
# Check Celery status
celery -A branch_system inspect active

# View recent penalties
# Go to Admin Panel → Penalty Charges
```

#### Manually Run Penalty Application (Testing)
```bash
python manage.py apply_penalties --dry-run
```

#### View Penalty History for a Loan
1. Go to loan detail page
2. Click **"View History"** button in Penalty Charges section

### Troubleshooting

| Issue | Solution |
|-------|----------|
| "Apply Penalty" button not showing | Loan must be overdue and you must be staff |
| Penalties not applying automatically | Check if Celery worker and beat are running |
| Can't delete a penalty | Only manual penalties can be deleted |
| Suggested penalty seems wrong | Check loan product penalty rate and frequency |

### Best Practices

✅ **DO:**
- Review suggested penalty before applying
- Always provide clear reason for manual penalties
- Check penalty history before applying new penalty
- Monitor automatic penalties regularly

❌ **DON'T:**
- Apply duplicate penalties for same period
- Delete automatic penalties (not allowed anyway)
- Apply penalties to non-overdue loans (not allowed)
- Forget to document reason for manual penalties

### Getting Help

1. Check the full documentation: `PENALTY_SYSTEM_IMPLEMENTATION.md`
2. View audit logs in Admin Panel
3. Contact system administrator
4. Check Celery logs: `/var/log/celery/`

---

## For System Administrators

### Starting the System

```bash
# 1. Start Redis
redis-server

# 2. Start Celery Worker (in one terminal)
celery -A branch_system worker -l info

# 3. Start Celery Beat (in another terminal)
celery -A branch_system beat -l info
```

### Monitoring

```bash
# Check active tasks
celery -A branch_system inspect active

# Check scheduled tasks
celery -A branch_system inspect scheduled

# Check worker stats
celery -A branch_system inspect stats
```

### Configuration Files

- **Celery Config**: `branch_system/celery.py`
- **Tasks**: `loans/tasks.py`
- **Views**: `loans/penalty_views.py`
- **Models**: `loans/models.py` (LoanProduct, PenaltyCharge)
- **URLs**: `loans/urls.py`

### Scheduled Tasks

| Task | Schedule | Description |
|------|----------|-------------|
| apply_automatic_penalties | Daily 1:00 AM | Apply penalties to overdue loans |
| send_penalty_notifications | Daily 9:00 AM | Send SMS notifications |

### Database Tables

- `loan_products` - Penalty configuration per product
- `penalty_charges` - All applied penalties
- `audit_logs` - Penalty application audit trail

### Logs to Monitor

- Celery worker logs
- Celery beat logs
- Django application logs
- Redis logs

---

**Last Updated:** March 2026  
**Version:** 1.0