# Payment to Service Activation Flow

## Two Modes: Real vs Simulation

### Real Mode (Production with Odoo)
Manual intervention required at each step.

### Simulation Mode (Testing without Odoo)
Fully automated from payment to activation.

---

## Real Mode Flow (Production)

### Step 1: Order Creation
```
Customer places order → Order created in Odoo
Status: 'pending_payment'
odoo_order_id: Set
```

### Step 2: Payment Received
```
Payment processed → handleSuccessfulPayment()
├─ Invoice marked as 'paid'
├─ Payment recorded in Odoo
├─ Sales order payment_status = 'paid'
└─ Sales order order_status = UNCHANGED (stays 'pending_payment')
```

**Manual Step Required**: Admin must manually approve order in Odoo
- Odoo order status changes from 'draft' to 'sale'
- Webhook syncs status to portal
- Portal order_status updates to 'completed'

### Step 3: Installation Scheduling
```
Manual: Admin schedules installation in Odoo
├─ Installation record created
├─ scheduled_date set
└─ status = 'scheduled'
```

### Step 4: Installation Completion
```
Manual: Technician marks installation as complete in Odoo
├─ Installation status = 'completed'
└─ Webhook syncs to portal
```

### Step 5: Service Activation
```
InstallationObserver triggered
├─ Subscription created
│  ├─ status = 'active'
│  ├─ activation_date = now()
│  └─ monthly_fee calculated
├─ Sales order order_status = 'completed'
└─ actual_installation_date set
```

---

## Simulation Mode Flow (Automated)

### Step 1: Order Creation
```
Customer places order → Order created in portal only
Status: 'pending_payment'
odoo_order_id: NULL
```

### Step 2: Payment Received
```
Payment processed → handleSuccessfulPayment()
├─ Invoice marked as 'paid'
├─ Sales order payment_status = 'paid'
├─ Sales order order_status = 'completed' ✅ AUTO
└─ Installation created
   ├─ status = 'scheduled'
   ├─ scheduled_date calculated
   └─ SIMULATION: Auto-complete installation ✅
      ├─ status = 'completed'
      ├─ actual_date = now()
      └─ handover_completed_at = now()
```

### Step 3: Service Activation (Automatic)
```
InstallationObserver triggered (by status change)
├─ Subscription created ✅ AUTO
│  ├─ status = 'active'
│  ├─ activation_date = now()
│  └─ monthly_fee calculated
├─ Sales order already 'completed'
└─ actual_installation_date set
```

**Result**: Service is fully active immediately after payment!

---

## Code Implementation

### PaymentController::handleSuccessfulPayment()

```php
// 2. UPDATE SALES ORDER
if ($payment->sales_order_id) {
    $salesOrder = SalesOrder::find($payment->sales_order_id);
    if ($salesOrder) {
        // In simulation mode, mark order as completed immediately
        $newOrderStatus = $salesOrder->order_status;
        if (config('app.simulate_package_pricing', false) && !$salesOrder->odoo_order_id) {
            $newOrderStatus = 'completed';
        }
        
        $salesOrder->update([
            'payment_status' => 'paid',
            'order_status' => $newOrderStatus,
            'approved_at' => now(),
        ]);
    }
}

// 5. CREATE INSTALLATION RECORD
if ($payment->sales_order_id) {
    $salesOrder = SalesOrder::with('feasibilityCheck')->find($payment->sales_order_id);
    if ($salesOrder && !$salesOrder->installation) {
        // Calculate scheduled date
        $scheduledDate = now()->addDays(21);
        
        $installation = Installation::create([
            'sales_order_id' => $salesOrder->id,
            'status' => 'scheduled',
            'scheduled_date' => $scheduledDate,
        ]);
        
        // SIMULATION MODE: Auto-complete installation
        if (config('app.simulate_package_pricing', false)) {
            $installation->update([
                'status' => 'completed',
                'actual_date' => now(),
                'actual_time' => now()->format('H:i:s'),
                'handover_completed_at' => now(),
            ]);
        }
    }
}
```

### InstallationObserver::updated()

```php
public function updated(Installation $installation): void
{
    // When installation status changes to 'completed', activate service
    if ($installation->isDirty('status') && $installation->status === 'completed') {
        $this->activateService($installation);
    }
}

protected function activateService(Installation $installation): void
{
    $salesOrder = $installation->salesOrder;
    
    // Create subscription
    $subscription = Subscription::create([
        'customer_id' => $salesOrder->customer_id,
        'sales_order_id' => $salesOrder->id,
        'status' => 'active',
        'activation_date' => now(),
        'monthly_fee' => $monthlyFee,
    ]);
    
    // Update sales order
    $salesOrder->update([
        'order_status' => 'completed',
        'actual_installation_date' => now(),
    ]);
}
```

---

## Status Display Logic

### Orders List
```javascript
const getCustomerStatus = (order) => {
  const hasSubscription = order.subscription || order.subscription_id;
  const paymentStatus = order.payment_status || order.invoice_status;
  
  // Active (subscription exists)
  if (hasSubscription) {
    return { status: 'active', label: 'Active', color: 'green' };
  }
  
  // Completed
  if (status === 'completed') {
    return { status: 'completed', label: 'Completed', color: 'green' };
  }
  
  // Odoo 'sale' - check payment
  if (status === 'sale') {
    if (paymentStatus === 'invoiced' || paymentStatus === 'paid') {
      return { status: 'completed', label: 'Completed', color: 'green' };
    }
    return { status: 'approved', label: 'Approved', color: 'blue' };
  }
  
  // Pending Payment
  if (status === 'pending_payment') {
    return { status: 'pending_payment', label: 'Pending Payment', color: 'yellow' };
  }
};
```

---

## Configuration

Enable simulation mode in `.env`:
```env
SIMULATE_PACKAGE_PRICING=true
```

Check in code:
```php
config('app.simulate_package_pricing', false)
```

---

## Testing Scenarios

### Simulation Mode Test
1. Create order → Status: "Pending Payment"
2. Make payment → Status: "Completed" ✅
3. Check installation → Status: "Completed" ✅
4. Check subscription → Status: "Active" ✅
5. View order → Shows "Active" (green) ✅

### Real Mode Test
1. Create order → Status: "Pending Payment"
2. Make payment → Status: "Approved" (awaiting Odoo)
3. Admin approves in Odoo → Status: "Completed"
4. Admin schedules installation → Installation created
5. Technician completes → Subscription created
6. View order → Shows "Active" (green)

---

## Key Differences Summary

| Aspect | Real Mode | Simulation Mode |
|--------|-----------|-----------------|
| Order Status After Payment | Stays 'pending_payment' | Changes to 'completed' |
| Installation Creation | Manual in Odoo | Auto-created |
| Installation Completion | Manual by technician | Auto-completed |
| Subscription Creation | After manual installation | Immediate (via observer) |
| Time to Activation | Days/weeks | Seconds |
| Odoo Integration | Required | Not used |

---

## Files Modified

1. `app/Http/Controllers/API/PaymentController.php`
   - Updated `handleSuccessfulPayment()` to set order status to 'completed' in simulation mode
   - Installation auto-completion already implemented

2. `app/Observers/InstallationObserver.php`
   - Already creates subscription when installation status changes to 'completed'
   - No changes needed

3. Frontend status display files
   - Already handle both scenarios correctly
   - Check subscription existence for "Active" status
   - Check payment status for Odoo orders

---

## Result

✅ **Simulation Mode**: Payment → Completed → Installation → Subscription → Active (all automatic)

✅ **Real Mode**: Payment → Approved → Manual Steps → Active (requires Odoo intervention)