# Reality Mode Implementation - Final Specification

## Overview

The AFINET portal operates in **Reality Mode** where all pricing and invoicing is controlled by Odoo, with the portal acting as a customer-facing interface that syncs data from Odoo.

## Pricing Reality

### Only Starlink Has Fixed Pricing

**Starlink** is the ONLY package with predetermined pricing that comes from Odoo product data:
- Monthly price: Retrieved from Odoo product catalog
- Installation fee: Retrieved from Odoo product catalog
- Equipment cost: Retrieved from Odoo product catalog

### All Other Packages Require Custom Pricing

All other packages (Magellan, Shared Broadband, Dedicated Burst, DIA, IP Transit, Dark Fibre, IPLC, InterCity-VPN) require manual pricing by the sales team in Odoo:

| Package | Feasibility Test | Portal Behavior |
|---------|-----------------|-----------------|
| Magellan Metro-VPN | Yes | Portal can calculate estimate, but sales team reviews/adjusts |
| Shared Business Broadband | Yes | Portal can calculate estimate, but sales team reviews/adjusts |
| Dedicated Burst Internet | Yes | Portal can calculate estimate, but sales team reviews/adjusts |
| Dedicated Internet Access | No | Portal creates with $0, sales team prices |
| IP Transit | No | Portal creates with $0, sales team prices |
| Dark Fibre Lease | No | Portal creates with $0, sales team prices |
| IPLC | No | Portal creates with $0, sales team prices |
| InterCity-VPN | No | Portal creates with $0, sales team prices |

**Key Point:** "Feasibility Test: Yes" means portal CAN calculate an estimate, but this is NOT the final price. Sales team ALWAYS reviews and sets final pricing in Odoo.

## Complete Workflow (Reality Mode)

### Step 1: Customer Requests Quotation

**Starlink:**
```
Customer → Portal: Request Starlink quotation
Portal: Retrieves pricing from Odoo product data
Portal: Creates quotation with Odoo pricing
Portal → Odoo: Sends draft quotation (with pricing)
Status: pending_review (awaiting sales team approval)
```

**All Other Packages:**
```
Customer → Portal: Request quotation
Portal: Calculates estimate (if feasibility data available) OR $0
Portal: Creates quotation with estimate/$0
Portal → Odoo: Sends draft quotation (with estimate/$0)
Status: pending_review (awaiting sales team pricing)
```

### Step 2: Sales Team Reviews in Odoo

```
Sales Team in Odoo:
1. Reviews quotation and customer requirements
2. Adds/adjusts products and services
3. Sets final pricing
4. Sends quotation to customer (state: 'sent')
```

### Step 3: Portal Syncs Quotation (Every 5 Minutes)

```
Scheduled Job (every 5 minutes):
→ php artisan sync:data quotations

Portal:
1. Fetches updated quotations from Odoo
2. Updates quotation pricing
3. Updates quotation status to 'sent'
4. Sends email notification to customer
```

**Alternative:** Webhook (if configured)
```
Odoo → Portal Webhook: quotation.updated
Portal: Immediately syncs pricing and notifies customer
```

### Step 4: Customer Reviews and Accepts

```
Customer → Portal: Views quotation with real pricing
Customer → Portal: Accepts quotation
Portal → Odoo: Confirms quotation
Odoo: Converts to sales order (state: 'sale')
```

### Step 5: Portal Syncs Sales Order (Every 5 Minutes)

```
Scheduled Job (every 5 minutes):
→ php artisan sync:data orders

Portal:
1. Fetches new/updated sales orders from Odoo
2. Creates sales order record
3. Links to quotation
4. Updates quotation status to 'accepted'
5. Updates quotation pricing (if changed)
```

**Alternative:** Webhook (if configured)
```
Odoo → Portal Webhook: sale.order.confirmed
Portal: Immediately syncs sales order
```

### Step 6: Sales Team Generates Invoice in Odoo

```
Sales Team in Odoo:
1. Generates invoice from sales order (manual or automatic)
2. Invoice created in Odoo
```

**IMPORTANT:** Portal does NOT auto-generate invoices. Invoices are ALWAYS created in Odoo.

### Step 7: Portal Syncs Invoice (Every 5 Minutes)

```
Scheduled Job (every 5 minutes):
→ php artisan sync:data invoices

Portal:
1. Fetches new/updated invoices from Odoo
2. Creates invoice record
3. Links to sales order
4. Sends email notification to customer
5. Customer can now pay
```

**Alternative:** Webhook (if configured)
```
Odoo → Portal Webhook: invoice.created
Portal: Immediately syncs invoice and notifies customer
```

### Step 8: Customer Pays Invoice

```
Customer → Portal: Makes payment
Portal → Payment Gateway: Processes payment
Payment Gateway → Portal: Confirmation
Portal → Odoo: Records payment on invoice
Odoo: Marks invoice as paid
```

### Step 9: Portal Syncs Payment Status (Every 5 Minutes)

```
Scheduled Job (every 5 minutes):
→ php artisan sync:data invoices

Portal:
1. Fetches updated invoice status from Odoo
2. Updates invoice status to 'paid'
3. Updates customer balance
```

**Alternative:** Webhook (if configured)
```
Odoo → Portal Webhook: invoice.paid
Portal: Immediately updates invoice status
```

## Scheduled Sync Jobs

**File:** `afinet-portal-backend/routes/console.php`

```php
// Sync quotations every 5 minutes
Schedule::command('sync:data quotations')
    ->everyFiveMinutes()
    ->withoutOverlapping();

// Sync invoices every 5 minutes
Schedule::command('sync:data invoices')
    ->everyFiveMinutes()
    ->withoutOverlapping();

// Sync sales orders every 5 minutes
Schedule::command('sync:data orders')
    ->everyFiveMinutes()
    ->withoutOverlapping();
```

### Running the Scheduler

**Development:**
```bash
php artisan schedule:work
```

**Production (Cron):**
```bash
* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1
```

## Changes Made

### 1. Removed Auto-Invoice Generation

**File:** `afinet-portal-backend/app/Http/Controllers/API/QuotationController.php`

**Before:**
```php
// When customer accepts quotation
$invoiceId = $odooService->generateInvoice($odooOrderId);
// Auto-generated invoice immediately
```

**After:**
```php
// When customer accepts quotation
// NOTE: Invoice generation is handled by sales team in Odoo
// Portal will sync invoices via webhook or scheduled sync job
// Do NOT auto-generate invoices here
```

### 2. Updated Response Message

**Before:**
```php
'next_steps' => 'Invoice generated. Proceed to payment to complete your order.'
```

**After:**
```php
'next_steps' => 'Your order has been confirmed. An invoice will be generated by our team shortly. You will receive an email notification when the invoice is ready for payment.'
```

### 3. Added Scheduled Sync Jobs

**File:** `afinet-portal-backend/routes/console.php`

Added three scheduled jobs that run every 5 minutes:
- Sync quotations from Odoo
- Sync invoices from Odoo
- Sync sales orders from Odoo

## Simulation Mode vs Reality Mode

### Simulation Mode (SIMULATE_PACKAGE_PRICING=true)

**Purpose:** Development, testing, demos ONLY

**Behavior:**
- Portal generates mock pricing for all packages
- Portal auto-generates invoices
- No Odoo dependency
- Fast, automated flow

**Use Cases:**
- Frontend development
- UI testing
- Demo presentations
- Development without Odoo access

### Reality Mode (SIMULATE_PACKAGE_PRICING=false) ✓ CURRENT

**Purpose:** Production use

**Behavior:**
- Only Starlink has fixed pricing from Odoo
- All other packages require sales team pricing
- Invoices ALWAYS come from Odoo
- Portal syncs data every 5 minutes (or via webhooks)
- Full business process enforced

**Use Cases:**
- Production environment
- Real customer transactions
- Actual business operations

## Customer Experience

### Starlink (Fixed Pricing)

```
Timeline: 1-2 days

Day 1:
- Customer requests quotation
- Portal shows Starlink pricing from Odoo
- Status: "Pending Review"
- Customer waits for sales team approval

Day 1-2:
- Sales team reviews and sends quotation in Odoo
- Portal syncs (within 5 minutes)
- Customer receives email: "Your quotation is ready"
- Customer accepts quotation
- Portal confirms in Odoo
- Sales team generates invoice
- Portal syncs invoice (within 5 minutes)
- Customer receives email: "Your invoice is ready"
- Customer pays
```

### All Other Packages (Custom Pricing)

```
Timeline: 1-3 days

Day 1:
- Customer requests quotation
- Portal shows estimate (if feasibility done) or "Pending Pricing"
- Status: "Pending Review"
- Customer waits for sales team pricing

Day 1-2:
- Sales team reviews requirements
- Sales team prices quotation in Odoo
- Sales team sends quotation
- Portal syncs (within 5 minutes)
- Customer receives email: "Your quotation is ready"
- Customer reviews real pricing

Day 2-3:
- Customer accepts quotation
- Portal confirms in Odoo
- Sales team generates invoice
- Portal syncs invoice (within 5 minutes)
- Customer receives email: "Your invoice is ready"
- Customer pays
```

## Testing

### Test Scheduled Sync

```bash
# Run scheduler once (for testing)
php artisan schedule:run

# Run scheduler continuously (for development)
php artisan schedule:work

# Manually sync specific data
php artisan sync:data quotations
php artisan sync:data invoices
php artisan sync:data orders
```

### Test Complete Flow

1. **Create quotation in portal**
   ```bash
   # Customer requests quotation
   # Verify quotation created with estimate/$0
   # Verify sent to Odoo
   ```

2. **Price quotation in Odoo**
   ```bash
   # Sales team adds products and pricing
   # Sales team sends quotation (state: 'sent')
   ```

3. **Wait for sync (max 5 minutes)**
   ```bash
   # Or manually trigger: php artisan sync:data quotations
   # Verify portal updated quotation pricing
   # Verify customer received email
   ```

4. **Accept quotation in portal**
   ```bash
   # Customer accepts
   # Verify Odoo quotation confirmed
   # Verify sales order created in Odoo
   ```

5. **Wait for sync (max 5 minutes)**
   ```bash
   # Or manually trigger: php artisan sync:data orders
   # Verify portal created sales order
   # Verify quotation status updated
   ```

6. **Generate invoice in Odoo**
   ```bash
   # Sales team generates invoice
   ```

7. **Wait for sync (max 5 minutes)**
   ```bash
   # Or manually trigger: php artisan sync:data invoices
   # Verify portal created invoice
   # Verify customer received email
   ```

8. **Pay invoice in portal**
   ```bash
   # Customer makes payment
   # Verify payment recorded in Odoo
   ```

## Production Checklist

✓ `SIMULATE_PACKAGE_PRICING=false` in `.env`
✓ Odoo connection configured and tested
✓ Scheduled sync jobs configured (cron)
✓ Email notifications working
✓ Payment gateway configured
✓ Only Starlink has fixed pricing
✓ All other packages require sales team pricing
✓ Invoices NEVER auto-generated by portal
✓ Portal syncs from Odoo every 5 minutes

## Summary

**Reality Mode enforces the actual business process:**

1. Only Starlink has predetermined pricing
2. All other packages require sales team review and pricing
3. Quotations must be approved by sales team before customer can accept
4. Invoices are ALWAYS generated in Odoo by sales team
5. Portal syncs data from Odoo every 5 minutes (or via webhooks)
6. Customer experience includes waiting periods for sales team actions
7. Full transparency and control for sales team
8. Complete audit trail in Odoo