# Phase 4 User Portal - Testing Guide

## 🚀 Quick Start

The user portal is now fully implemented with repayment payments and loan applications. Follow these steps to test all features.

## 📋 Pre-Requisites

1. Ensure MySQL is running (XAMPP)
2. Run migrations: `composer dev` or `php artisan migrate`
3. Seed data: `php artisan db:seed` or `php artisan seed:run`
4. Create test admin and user accounts if not present:
   - Admin: `email: admin@lendcore.test`, `password: password`
   - User: `email: user@lendcore.test`, `password: password`

## ✅ Testing Checklist

### 1. User Authentication
- [ ] Navigate to `/login`
- [ ] See updated login form with admin-style UI (gray background, indigo buttons)
- [ ] Login with user credentials: `user@lendcore.test` / `password`
- [ ] Successfully redirected to `/dashboard`

### 2. Dashboard & Overview
- [ ] **Dashboard loads** with 4 metric cards:
  - Active Loans (with indigo icon)
  - Outstanding Balance (with red icon)
  - Overdue Payments (with orange icon)
  - Total Fines (with yellow icon)
- [ ] **Loan Status Summary** grid shows: Pending, Active, Completed, Defaulted counts
- [ ] **Quick Links** section visible (View My Loans, Payment Schedule, Apply for Loan)
- [ ] **Upcoming Repayments** table shows next 5 due payments with status badges
- [ ] **Pay** button visible on overdue/pending repayments

### 3. Loan Application System
- [ ] Click **"Apply for Loan"** button from dashboard/loans list
- [ ] **Application Form** displays with:
  - Tier dropdown showing tiers with amount ranges
  - Amount input field
  - Live preview section
- [ ] **Select a tier** and **enter an amount**:
  - Preview updates with: Interest Rate (%), Duration (weeks), Weekly Installment (KSh)
  - Calculations are correct
- [ ] **Submit application**:
  - Loan created with status='pending'
  - Redirected to loan details page
  - Success message shows
- [ ] **New loan appears in "My Loans"** list

### 4. My Loans View
- [ ] Navigate to `/loans`
- [ ] **Loans display in card layout** with:
  - Tier name and Loan ID
  - Status badge (green for active, yellow for pending)
  - 4 metric columns: Amount, Duration, Weekly Payment, Outstanding
  - Payment progress bar with percentage
  - "View Details" and "Pay Now" buttons
- [ ] **Payment progress bar** shows correct percentage
- [ ] **Click "View Details"** → navigates to loan details

### 5. Loan Details View
- [ ] Loan details show with:
  - **Summary Section**: Amount, Interest, LAF Fee, Registration Fee, Total Payable
  - **Quick Info**: Duration (weeks), Weekly Installment, Interest Rate
  - **4 Metric Cards**: Total Due, Total Paid, Outstanding Balance, Completion Rate %
  - **Repayment Status**: Pending count, Overdue count, Paid count
  - **Repayment Schedule Table**: All installments with Due Date, Amount Due, Paid, Balance, Status
  - **Pay** button on each repayment row

### 6. Repayment Payment System
- [ ] Navigate to `/repayments`
- [ ] **Repayments table** displays with:
  - Loan name, Due Date, Amount Due, Paid, Balance
  - Status badges (green=paid, yellow=pending, red=overdue)
  - Fine amount (if applicable) with red badge
  - "Pay" action button on pending/overdue
- [ ] **Summary stats** at bottom show: Total Due, Total Paid, Outstanding Balance
- [ ] **Click "Pay" button** on any repayment
- [ ] **Payment Form** displays with:
  - Repayment details card (tier, due date, amounts)
  - Fine display if applicable
  - Amount input (max set to balance)
  - Process Payment button
- [ ] **Enter amount** ≤ outstanding balance
- [ ] **Submit payment**:
  - Payment recorded successfully
  - Redirected to repayments list
  - Success message shows
  - Balance updated correctly
  - Status updated to 'paid' if balance = 0

### 7. UI/UX Verification
- [ ] **Color Scheme**: Gray backgrounds, indigo buttons, colored metric cards
- [ ] **Icons**: Visible in metric cards with appropriate colors
- [ ] **Status Badges**: Green/yellow/red colors match status
- [ ] **Responsive Design**: 
  - Mobile view stacks cards vertically
  - Tablet view shows 2-column layouts
  - Desktop view shows full layouts
- [ ] **Hover Effects**: Cards and buttons have transitions
- [ ] **Typography**: Consistent font sizes and weights

### 8. Authorization Tests
- [ ] Login as one user
- [ ] Try to access another user's loan: `/loans/999` → should 403 error
- [ ] Try to access another user's repayment payment form: `/repayments/999/pay` → should 403 error
- [ ] Logout and try to access `/dashboard` → redirected to login

### 9. Validation Tests
- [ ] **Loan Application**:
  - Submit without selecting tier → error shown
  - Submit without amount → error shown
  - Submit amount below min_amount → error shown
  - Submit amount above max_amount → error shown
  - Submit valid form → success
- [ ] **Repayment Payment**:
  - Submit amount > balance → error shown ("Payment exceeds due amount")
  - Submit amount = 0 → error shown
  - Submit valid amount → success

### 10. Data Integrity Tests
- [ ] After payment:
  - Repayment `amount_paid` increases by payment amount
  - Repayment `balance` decreases correctly
  - Status changes to 'paid' when balance = 0
  - Transaction record created (check in transactions table)
- [ ] After loan application:
  - Loan created with correct amount and tier_id
  - Status = 'pending' (awaiting admin approval)
  - Loan appears in user's loan list

## 🔍 Advanced Testing

### Admin Approval Workflow
1. Login as admin
2. Go to admin dashboard
3. Find pending loan application
4. Click **Approve** → status changes to 'approved'
5. Click **Disburse** → status changes to 'active', repayment schedule generated
6. Login as user
7. Verify repayments appear in repayment list
8. Test payment workflow

### Payment Flow
1. Apply for and get loan approved/disbursed
2. View upcoming repayments
3. Make multiple partial payments on same repayment
4. Verify balance updates correctly each time
5. Make final payment to complete repayment
6. Verify status changes to 'paid'
7. Verify no "Pay" button appears for paid repayments

### Fine Calculation
1. Ensure admin has marked a repayment as overdue
2. Fine should be auto-calculated and shown
3. Payment form should show fine amount
4. Payment should reduce balance including fine

## 📊 Expected Data Behavior

### New Loan Application
- Creates Loan record with:
  - `status = 'pending'`
  - `amount = entered amount`
  - `interest = calculated`
  - `laf_fee = calculated (2% of amount)`
  - `registration_fee = 500`
  - `total_payable = amount + interest + fees`
  - `weekly_installment = total_payable / duration_weeks`

### Repayment Payment
- Updates Repayment record:
  - `amount_paid += payment_amount`
  - `balance = amount_due - amount_paid`
  - `status = 'pending'` or `'paid'` (if balance = 0)
- Creates Transaction record with type='payment'

## 🎯 Success Criteria

✅ All tests in the checklist pass
✅ No console errors or PHP warnings
✅ Database data persists correctly
✅ Authorization working (users can't access other users' data)
✅ UI styling matches admin dashboard
✅ All form validations working
✅ All calculations correct

## 📝 Notes

- Tier data must exist in database for application form to show options
- Admin must approve and disburse loans for repayments to be created
- Repayment payment records transactions automatically
- All money fields use KSh currency with 2 decimal places
- Duration shown in weeks (from database), not months
