# Troubleshooting Guide

## Quick Diagnosis

### Step 1: Run Installation Checker
Upload `check-installation.php` to your server and visit:
```
https://yoursite.com/wp-content/plugins/woonoow/check-installation.php
```

This will show you exactly what's wrong.

---

## Common Issues

### Issue 1: Blank Page in WP-Admin

**Symptoms:**
- Blank white page when visiting `/wp-admin/admin.php?page=woonoow`
- Or shows "Please Configure Marketing Setup first"
- No SPA loads

**Diagnosis:**
1. Open browser console (F12)
2. Check Network tab
3. Look for `app.js` and `app.css`

**Possible Causes & Solutions:**

#### A. Files Not Found (404)
```
❌ admin-spa/dist/app.js → 404 Not Found
❌ admin-spa/dist/app.css → 404 Not Found
```

**Solution:**
```bash
# The dist files are missing!
# Re-extract the zip file:
cd /path/to/wp-content/plugins
rm -rf woonoow
unzip woonoow.zip

# Verify files exist:
ls -la woonoow/admin-spa/dist/
# Should show: app.js (2.4MB) and app.css (70KB)
```

#### B. Wrong Extraction Path
If you extracted into `plugins/woonoow/woonoow/`, the paths will be wrong.

**Solution:**
```bash
# Correct structure:
wp-content/plugins/woonoow/woonoow.php ✓
wp-content/plugins/woonoow/admin-spa/dist/app.js ✓

# Wrong structure:
wp-content/plugins/woonoow/woonoow/woonoow.php ✗
wp-content/plugins/woonoow/woonoow/admin-spa/dist/app.js ✗

# Fix:
cd /path/to/wp-content/plugins
rm -rf woonoow
unzip woonoow.zip
# This creates: plugins/woonoow/ (correct!)
```

#### C. Dev Mode Enabled
```
❌ Trying to load from localhost:5173
```

**Solution:**
Edit `wp-config.php` and remove or set to false:
```php
// Remove this line:
define('WOONOOW_ADMIN_DEV', true);

// Or set to false:
define('WOONOOW_ADMIN_DEV', false);
```

Then clear caches:
```bash
php -r "opcache_reset();"
wp cache flush
```

---

### Issue 2: API 500 Errors

**Symptoms:**
- All API endpoints return 500
- Console shows: "Internal Server Error"
- Error log: `Class "WooNooWAPIPaymentsController" not found`

**Cause:**
Namespace case mismatch (old code)

**Solution:**
```bash
# Check if you have the fix:
grep "use WooNooW" includes/Api/Routes.php

# Should show (lowercase 'i'):
# use WooNooW\Api\PaymentsController;

# If it shows (uppercase 'I'):
# use WooNooW\API\PaymentsController;
# Then you need to update!

# Update:
git pull origin main
# Or re-upload the latest zip

# Clear caches:
php -r "opcache_reset();"
wp cache flush
```

---

### Issue 3: WordPress Media Not Loading (Standalone)

**Symptoms:**
- Error: "WordPress Media library is not loaded"
- "Choose from Media Library" button doesn't work
- Only in standalone mode (`/admin`)

**Cause:**
Missing wp.media scripts

**Solution:**
Already fixed in latest code. Update:
```bash
git pull origin main
# Or re-upload the latest zip

php -r "opcache_reset();"
```

---

### Issue 4: Changes Not Reflecting

**Symptoms:**
- Uploaded new code but still seeing old errors
- Fixed files but issues persist

**Cause:**
Multiple cache layers

**Solution:**
```bash
# 1. Clear PHP OPcache (MOST IMPORTANT!)
php -r "opcache_reset();"

# Or visit:
# https://yoursite.com/wp-content/plugins/woonoow/check-installation.php?action=clear_opcache

# 2. Clear WordPress object cache
wp cache flush

# 3. Restart PHP-FPM (if above doesn't work)
sudo systemctl restart php8.1-fpm
# or
sudo systemctl restart php-fpm

# 4. Clear browser cache
# Hard refresh: Ctrl+Shift+R (Windows/Linux)
# Hard refresh: Cmd+Shift+R (Mac)
```

---

### Issue 5: File Permissions

**Symptoms:**
- 403 Forbidden errors
- Can't access files

**Solution:**
```bash
cd /path/to/wp-content/plugins/woonoow

# Set correct permissions:
find . -type f -exec chmod 644 {} \;
find . -type d -exec chmod 755 {} \;

# Verify:
ls -la admin-spa/dist/
# Should show: -rw-r--r-- (644) for files
```

---

## Verification Steps

After fixing, verify everything works:

### 1. Check Files
```bash
cd /path/to/wp-content/plugins/woonoow

# These files MUST exist:
ls -lh woonoow.php                    # Main plugin file
ls -lh includes/Admin/Assets.php      # Assets handler
ls -lh includes/Api/Routes.php        # API routes
ls -lh admin-spa/dist/app.js          # SPA JS (2.4MB)
ls -lh admin-spa/dist/app.css         # SPA CSS (70KB)
```

### 2. Test API
```bash
curl -I https://yoursite.com/wp-json/woonoow/v1/store/settings

# Should return:
# HTTP/2 200 OK
```

### 3. Test Assets
```bash
curl -I https://yoursite.com/wp-content/plugins/woonoow/admin-spa/dist/app.js

# Should return:
# HTTP/2 200 OK
# Content-Length: 2489867
```

### 4. Test WP-Admin
Visit: `https://yoursite.com/wp-admin/admin.php?page=woonoow`

**Should see:**
- ✓ WooNooW dashboard loads
- ✓ No console errors
- ✓ Navigation works

**Should NOT see:**
- ✗ Blank page
- ✗ "Please Configure Marketing Setup"
- ✗ Errors about localhost:5173

### 5. Test Standalone
Visit: `https://yoursite.com/admin`

**Should see:**
- ✓ Standalone admin loads
- ✓ Login page (if not logged in)
- ✓ Dashboard (if logged in)

---

## Emergency Rollback

If everything breaks:

```bash
# 1. Deactivate plugin
wp plugin deactivate woonoow

# 2. Remove plugin
rm -rf /path/to/wp-content/plugins/woonoow

# 3. Re-upload fresh zip
unzip woonoow.zip -d /path/to/wp-content/plugins/

# 4. Reactivate
wp plugin activate woonoow

# 5. Clear all caches
php -r "opcache_reset();"
wp cache flush
```

---

## Getting Help

If issues persist, gather this info:

1. **Run installation checker:**
   ```
   https://yoursite.com/wp-content/plugins/woonoow/check-installation.php
   ```
   Take screenshot of results

2. **Check error logs:**
   ```bash
   tail -50 /path/to/wp-content/debug.log
   tail -50 /var/log/php-fpm/error.log
   ```

3. **Browser console:**
   - Open DevTools (F12)
   - Go to Console tab
   - Take screenshot of errors

4. **Network tab:**
   - Open DevTools (F12)
   - Go to Network tab
   - Reload page
   - Take screenshot showing failed requests

5. **File structure:**
   ```bash
   ls -la /path/to/wp-content/plugins/woonoow/
   ls -la /path/to/wp-content/plugins/woonoow/admin-spa/dist/
   ```

Send all this info when requesting help.

---

## Prevention

To avoid issues in the future:

1. **Always clear caches after updates:**
   ```bash
   php -r "opcache_reset();"
   wp cache flush
   ```

2. **Verify files after extraction:**
   ```bash
   ls -lh admin-spa/dist/app.js
   # Should be ~2.4MB
   ```

3. **Use installation checker:**
   Run it after every deployment

4. **Keep backups:**
   Before updating, backup the working version

5. **Test in staging first:**
   Don't deploy directly to production