# RBAC Quick Start Testing Guide

## Setup (5 minutes)

### Step 1: Create Test Company
```php
php artisan tinker
>>> $company = \App\Models\Company::create(['name' => 'Test Company', 'currency_code' => 'USD']);
```

### Step 2: Create Test Users (all 5 roles)

```php
# Super Admin
$super = \App\Models\User::create([
    'name' => 'Super Admin',
    'email' => 'super@test.com',
    'password' => bcrypt('password'),
    'email_verified_at' => now(),
    'role_id' => 1,
]);

# Company Admin
$admin = \App\Models\User::create([
    'name' => 'Admin',
    'email' => 'admin@test.com',
    'password' => bcrypt('password'),
    'email_verified_at' => now(),
    'role_id' => 2,
    'company_id' => $company->id,
]);

# Cashier
$cashier = \App\Models\User::create([
    'name' => 'Cashier',
    'email' => 'cashier@test.com',
    'password' => bcrypt('password'),
    'email_verified_at' => now(),
    'role_id' => 3,
    'company_id' => $company->id,
]);

# Meter Reader
$reader = \App\Models\User::create([
    'name' => 'Meter Reader',
    'email' => 'reader@test.com',
    'password' => bcrypt('password'),
    'email_verified_at' => now(),
    'role_id' => 4,
    'company_id' => $company->id,
]);

# Customer
$customer = \App\Models\User::create([
    'name' => 'Customer',
    'email' => 'customer@test.com',
    'password' => bcrypt('password'),
    'email_verified_at' => now(),
    'role_id' => 5,
]);

exit
```

---

## Test Cases (20 minutes)

### Test 1: Super Admin Access ✅
```
1. Login: super@test.com / password
2. Visit /dashboard → Should see SYSTEM OVERVIEW
3. Visit /companies → Should see all companies
4. Visit /admin/settings → Should see system settings
5. Visit /users → Should see all users
6. Visit /billings?company_id=1 → Should filter by company
   
Expected: All pages accessible ✅
```

### Test 2: Company Admin Access ✅
```
1. Login: admin@test.com / password
2. Visit /dashboard → Should see COMPANY ADMIN dashboard
3. Visit /clients → Should see only Test Company's clients
4. Visit /billings → Should see only Test Company's billings
5. Visit /company/settings → Should see company settings
6. Try /companies → Should get 403 Forbidden

Expected: Appropriate pages accessible, restricted pages blocked ✅
```

### Test 3: Cashier Access ✅
```
1. Login: cashier@test.com / password
2. Visit /dashboard → Should see CASHIER dashboard with payment stats
3. Visit /billings → Should see only Test Company's billings (read-only feel)
4. Visit /payments → Should see payment recording form
5. Visit /clients → Should see clients for disconnection purposes
6. Try /company/settings → Should get 403 Forbidden
7. Try /tier-groups → Should get 403 Forbidden

Expected: Payment workflow accessible, admin functions blocked ✅
```

### Test 4: Meter Reader Access ✅
```
1. Login: reader@test.com / password
2. Visit /dashboard → Should see METER READER dashboard
3. Visit /record-meter → Should see meter recording form
4. Visit /my-meter-readings → Should show own readings (placeholder)
5. Try /payments → Should get 403 Forbidden
6. Try /billings → Should get 403 Forbidden

Expected: Meter operations only ✅
```

### Test 5: Customer Access ✅
```
1. Login: customer@test.com / password
2. Visit /dashboard → Should see CUSTOMER dashboard
3. Visit /my-billings → Should show personal billings (placeholder)
4. Visit /my-payments → Should show payment history (placeholder)
5. Try /clients → Should get 403 Forbidden
6. Try /payments → Should get 403 Forbidden

Expected: Personal data only ✅
```

---

## Verification Checks

### Check 1: Middleware Logging
```bash
tail -f storage/logs/laravel.log | grep CheckRole
```
Should see logs for each access attempt with:
- route_name
- user_id
- user_role
- allowed_roles
- Access GRANTED or DENIED message

### Check 2: Activity Logs
1. Login as super_admin or company_admin
2. Visit `/logs`
3. Should see recent access log entries
4. Verify user_id, email, route_name, timestamp

### Check 3: Unauthorized Access Logging
```bash
grep "Access DENIED" storage/logs/laravel.log
```
Should see 403 attempts in logs (from Test Cases where access was denied)

### Check 4: Dashboard Routing
After login, user should be redirected to role-appropriate dashboard:
- super_admin → System overview
- company_admin → Company statistics
- cashier → Payment collection stats
- meter_reader → Meter operations
- customer → Personal billing

---

## Quick Test (2 minutes)

If short on time, test just the critical paths:

```bash
# 1. Super Admin can see all
Login as super@test.com → /companies ✅

# 2. Company Admin sees only their company
Login as admin@test.com → /clients → count = Test Company only ✅

# 3. Cashier can record payments
Login as cashier@test.com → /payments ✅

# 4. Unauthorized access blocked
Login as cashier@test.com → try /company/settings → 403 ✅
```

---

## Troubleshooting

### Issue: 500 Error on Login
**Check:**
1. Roles table exists: `SELECT * FROM roles;`
2. User's role_id is valid
3. `php artisan cache:clear`

### Issue: 403 Even with Correct Role
**Check:**
1. User role name matches middleware requirement
2. Company_id assigned (if needed)
3. Route middleware includes role

### Issue: Dashboard Not Showing
**Check:**
1. User role_id is correct
2. Dashboard view file exists:
   - `resources/views/dashboards/{role}.blade.php`
3. DashboardController has `{role}Dashboard()` method

### Issue: Company Filtering Not Working
**Check:**
1. User has company_id assigned
2. Query includes `company_id` filter
3. Related models have proper relationships

---

## Expected Results Summary

| Role | Dashboard | Routes Accessible | Routes Blocked |
|------|-----------|------------------|-----------------|
| Super Admin | System overview | /companies, /users, /admin/settings | None (see all) |
| Company Admin | Company mgmt | /clients, /billings, /payments, /staff | /admin/settings, /companies |
| Cashier | Payment stats | /billings, /payments, /clients | /company/settings, /staff |
| Meter Reader | Meter ops | /record-meter | /payments, /billings |
| Customer | Personal | /my-billings, /my-payments | /clients, /payments |

---

## Commands for Testing

### Clear All Caches
```bash
php artisan cache:clear
php artisan route:clear
php artisan view:clear
```

### Check Routes
```bash
php artisan route:list | grep -E "(check.role|dashboard)"
```

### View Activity Logs
```php
php artisan tinker
>>> \App\Models\ActivityLog::latest()->limit(10)->get();
```

### Check User Role
```php
php artisan tinker
>>> $user = \App\Models\User::find(1);
>>> $user->role->name;
```

---

## Performance Notes

- Route cache clear needed if routes modified: `php artisan route:clear`
- Activity logging may slow requests slightly (expected <5ms overhead)
- Company filters use indexed columns for performance
- Middleware checks are minimal overhead (~1-2ms)

---

## Success Criteria

All of these should be true after testing:

- ✅ Each role can access their authorized routes
- ✅ Each role is blocked from unauthorized routes (403)
- ✅ Super admin can access everything
- ✅ Company admin/cashier see only their company's data
- ✅ Dashboards show for each role
- ✅ Activity logs record access attempts
- ✅ Middleware logs show correct role checking
- ✅ No 500 errors during normal operation
- ✅ User can logout and re-login with different accounts

---

## Next Steps After Testing

1. ✅ Testing complete
2. Create production users with real data
3. Set up email notifications for sensitive actions
4. Configure backup strategy for activity logs
5. Train staff on their role capabilities
6. Monitor logs regularly for issues

---

**Status: Ready for Production Testing** 🚀