# ImmigoPro Automatic Installment Charging

## ✅ System Isolation
This charging system is **completely separate** from your existing Subscription Payments:
- Uses `immigo_pro_subscriptions` table (NOT `subscriptions` table)
- Uses `ImmigoProSubscription` model (NOT `Subscription` model)
- Command only queries ImmigoPro records
- **Zero impact** on your existing subscription flow

## 🔄 How It Works

### Flow Overview
1. **Customer purchases** ImmigoPro package with payment plan (e.g., 3-Month Plan)
2. **Upfront payment** charged immediately (e.g., $80)
3. **Payment method stored** in Stripe for future charges
4. **Next charge date** set to 30 days from purchase
5. **Scheduled command** runs daily at 2:00 AM
6. **Finds subscriptions** where `next_charge_date <= today` AND `status = 'active'`
7. **Charges monthly amount** (e.g., $40) using stored payment method
8. **Updates progress**: Increments `paid_installments`, sets new `next_charge_date`
9. **Auto-stops** when all installments paid (status changes to 'completed')

### Example: 3-Month Plan ($200 package)
- **Jan 29**: Purchase → Pay $80 upfront → Store card → Set next charge: Feb 28
- **Feb 28**: Command runs → Charge $40 (1/3) → Set next charge: Mar 28
- **Mar 28**: Command runs → Charge $40 (2/3) → Set next charge: Apr 28
- **Apr 28**: Command runs → Charge $40 (3/3) → Status: completed → STOP

### Auto-Stop Mechanism
The system stops automatically because:
1. When `paid_installments >= installments`, status changes to `'completed'`
2. Command only queries where `status = 'active'`
3. Completed subscriptions are never queried again
4. `next_charge_date` is set to `null` when completed

## 📋 Command Usage

### Manual Testing
```bash
# Test without charging (preview only)
php artisan immigopro:charge-installments --dry-run

# Charge now (for testing purposes)
php artisan immigopro:charge-installments
```

### Automatic Scheduling
The command runs automatically **daily at 2:00 AM** (configured in `routes/console.php`).

To ensure the scheduler runs, you need to add this to your server's crontab:
```bash
* * * * * cd /path-to-your-project/backend && php artisan schedule:run >> /dev/null 2>&1
```

## 🔍 Monitoring

### Check Subscription Status
```bash
cd backend
php check_subscription.php <subscription_id>
```

### Database Query
```sql
SELECT 
    id,
    package_name,
    payment_plan,
    paid_installments,
    installments,
    next_charge_date,
    status
FROM immigo_pro_subscriptions
WHERE status = 'active';
```

## 🚨 Failed Payments

If a payment fails:
- Error is logged in `storage/logs/laravel.log`
- Subscription remains in `active` status
- Next day, command will retry automatically
- TODO: Email notification to user (not implemented yet)

## 📊 Testing Checklist

- [x] Command created: `app/Console/Commands/ChargeImmigoProInstallments.php`
- [x] Scheduler registered: `routes/console.php`
- [x] Database migration: `completed_at` column added
- [x] Model updated: `ImmigoProSubscription` with fillable/casts
- [x] Dry-run tested: No errors
- [ ] Test actual charge with test subscription
- [ ] Verify auto-stop when all installments paid
- [ ] Set up server cron job for production

## 🔒 Security

- Uses off-session payment (no user interaction needed)
- Payment method stored securely in Stripe
- All transactions logged with metadata
- Only processes subscriptions with stored payment methods

## 📝 Database Tables

### Tables Used
- ✅ `immigo_pro_subscriptions` - Installment tracking
- ✅ `immigopro_packages` - Package definitions

### Tables NOT Touched
- ❌ `subscriptions` - Your regular subscriptions (completely separate)
- ❌ Any other payment tables

## 🎯 Next Steps

1. **Test in local**: Update a test subscription's `next_charge_date` to today and run the command
2. **Verify completion**: Ensure status changes to 'completed' after last installment
3. **Production**: Add cron job to run `php artisan schedule:run` every minute
4. **Monitor**: Check logs daily for first week after deployment
