# Financial Forecaster - Testing Guide

## 🎯 Quick Start

The Financial Forecaster is now **65% complete** and ready for testing! You can create forecasts and scenarios through the UI.

---

## 🔐 Step 1: Login

Use one of these CEO/CFO/CTO accounts (these are the only roles with access):

| Role | Email | Password |
|------|-------|----------|
| **CEO** ⭐ | `ceo@company.com` | `password` |
| **CFO** ⭐ | `cfo@company.com` | `password` |
| **CTO** ⭐ | `cto@company.com` | `password` |

---

## 📊 Step 2: Access Forecaster

1. Click **Accounting** in the main menu
2. Scroll down and click **Financial Forecaster** (last item in menu)
3. You'll see the dashboard (currently empty)

---

## ✅ Step 3: Create Your First Forecast

### What You Can Test Now:

1. **Create Forecast** (Click "New Forecast" button)
   - Forecast Name: `2025 Base Forecast`
   - Period Type: **Monthly** or **Quarterly**
   - Start Date: `2025-01-01`
   - End Date: `2025-12-31`
   - Starting Cash: `$100,000.00`
   - Description: Optional
   - Click **Create Forecast**

2. **View Forecast Details**
   - After creation, you'll see:
     - Summary stats (Revenue, Expenses, Cashflow, Ending Cash)
     - **Periods table** - Auto-generated based on your date range!
     - Empty scenarios section
   - All periods start with $0 values (editing periods coming soon)

3. **Create a Scenario**
   - Click "New Scenario" button
   - Scenario Name: `Base Case`
   - Description: `Conservative forecast with bank financing`
   - Click **Create Scenario**

4. **View Scenario Details**
   - See financing instruments section (empty)
   - See investment instruments section (empty)
   - Metrics section shows "not yet calculated" message

5. **Edit Forecast/Scenario**
   - Click "Edit" button
   - Change name or description
   - Toggle active/inactive status

6. **Navigate Back**
   - Use breadcrumbs and "Back" buttons
   - All navigation works properly

---

## 🎨 What You'll See

### Dashboard View
- Card grid showing all forecasts
- Each card shows:
  - Name and status badge
  - Date range
  - Period type (Monthly/Quarterly)
  - Starting cash
  - Number of periods
  - Action buttons (View, Edit, Delete)

### Forecast Details View
- Header with forecast name and key info
- Summary stats cards (4 metrics)
- Scenarios section (empty at first)
- **Periods table** with columns:
  - Period label
  - Start/End dates
  - Revenue, COGS, OpEx, CapEx, Tax
  - Net Cashflow
  - Ending Cash
  - **All auto-calculated** (currently $0 but structure is ready)

### Scenario Details View
- Scenario name and description
- Metrics cards (empty until calculated)
- Financing instruments table (empty)
- Investment instruments table (empty)
- Action buttons (Calculate, Export - placeholders)

---

## 🚧 What's Not Ready Yet

### Cannot Do Yet:
- ❌ Edit period values (Revenue, COGS, etc.) - Coming soon
- ❌ Add financing instruments (loans, bonds)
- ❌ Add investment instruments (treasuries, CDs)
- ❌ Calculate metrics (NPV, IRR, ROI)
- ❌ Compare scenarios side-by-side
- ❌ Export to CSV/Excel
- ❌ Edit rate indices

### You'll See Placeholder Alerts:
- "Add financing instrument form coming soon!"
- "Add investment instrument form coming soon!"
- "Calculate metrics feature coming soon!"
- "Period editing coming soon!"

---

## 🧪 Recommended Test Flow

### Test 1: Basic Forecast Creation
1. Login as CEO
2. Create forecast named "Test Monthly" with monthly periods
3. Verify periods are auto-generated (12 periods for full year)
4. Check that periods table displays correctly

### Test 2: Quarterly Periods
1. Create forecast named "Test Quarterly" with quarterly periods
2. Verify only 4 periods are generated
3. Check period labels (Q1 2025, Q2 2025, etc.)

### Test 3: Multiple Scenarios
1. Create a forecast
2. Add 3 scenarios: "Base Case", "Conservative", "Aggressive"
3. Verify all scenarios appear on forecast detail page
4. Navigate between scenarios

### Test 4: Edit Operations
1. Edit a forecast name
2. Toggle forecast active/inactive
3. Edit a scenario description
4. Delete a scenario (if no instruments - this works)

### Test 5: Navigation
1. Dashboard → Forecast → Scenario → Back to Forecast → Back to Dashboard
2. Verify breadcrumbs work
3. Check all buttons and links

---

## 📝 What to Look For

### Good Signs ✅
- Clean, professional UI matching M1 ERP style
- Fast page loads
- Flash messages appear and dismiss
- Tables render properly
- Dates format correctly
- Numbers format with commas and 2 decimals
- Badges show correct colors (green for active, etc.)
- Responsive layout works on different screen sizes

### Potential Issues 🔍
- Empty periods table (should have auto-generated rows)
- Missing flash messages after create/update
- Broken navigation links
- Permission errors (shouldn't happen for CEO/CFO/CTO)
- Database errors in period generation

---

## 🐛 If You Find Issues

Check these common problems:

1. **Periods not generating**
   - Check database: `SELECT * FROM forecaster_periods WHERE forecast_id = X;`
   - Look for errors in PHP error log

2. **Permission denied**
   - Verify you're logged in as CEO/CFO/CTO
   - Check: `SELECT * FROM role_permissions WHERE role_id IN (108,110,111);`

3. **Blank page**
   - Check PHP error log
   - Verify all model files exist in `/models/`
   - Check controller exists: `/controllers/ForecasterController.php`

4. **404 Not Found**
   - Verify routes exist in `public/index.php`
   - Check URL matches pattern

---

## 📊 Database Quick Checks

```sql
-- Count your forecasts
SELECT COUNT(*) FROM forecaster_forecasts;

-- See all forecasts with periods
SELECT 
    f.name, 
    f.period_type, 
    COUNT(p.id) as period_count
FROM forecaster_forecasts f
LEFT JOIN forecaster_periods p ON f.id = p.forecast_id
GROUP BY f.id;

-- See all scenarios
SELECT 
    s.name, 
    f.name as forecast_name,
    s.is_active
FROM forecaster_scenarios s
JOIN forecaster_forecasts f ON s.forecast_id = f.id;

-- Check permissions
SELECT u.email, r.name as role, COUNT(rp.permission_id) as permissions
FROM users u
JOIN roles r ON u.role_id = r.id
LEFT JOIN role_permissions rp ON r.id = rp.role_id
WHERE r.id IN (108, 110, 111)
GROUP BY u.id;
```

---

## 🎯 Next Development Priority

After you test the current functionality, the next items to build are:

1. **Period Editing** - Form to bulk update revenue/expense values
2. **Financing Instrument Form** - Add loans with amortization
3. **Calculation Engine** - NPV, IRR, amortization schedules
4. **Comparison Dashboard** - Side-by-side with Chart.js graphs
5. **Export Functionality** - CSV/Excel downloads

---

## 💡 Tips

- Use realistic data for testing (e.g., $1M revenue, $500K expenses)
- Test both monthly and quarterly period types
- Create multiple scenarios to test comparison later
- Try edge cases (very large numbers, negative cash, etc.)
- Test with all three roles (CEO, CFO, CTO) to ensure permissions work

---

## ✨ What Makes This Special

Unlike generic forecasting tools, this Forecaster:
- ✅ Auto-generates periods based on date range
- ✅ Supports both monthly and quarterly forecasting
- ✅ Allows unlimited scenarios per forecast
- ✅ Tracks financing instruments (loans, bonds, credit lines)
- ✅ Tracks investment instruments (treasuries, CDs, bonds)
- ✅ Uses real rate indices (SOFR, Prime)
- ✅ Calculates amortization schedules
- ✅ Computes NPV, IRR, ROI metrics
- ✅ Compare multiple scenarios side-by-side
- ✅ Restricted to C-level executives only

---

**Happy Testing! 🚀**

If you encounter any issues or have questions, document them and I can help debug!