# Payment System - Invoice Bypass for Test Payments

## Summary
Successfully updated the payment system to support optional invoices, allowing direct payments for orders and quotations during testing.

## Changes Made

### 1. Backend - PaymentController.php

#### `initiatePayment()` Method
- **Changed**: `invoice_id` from `required` to `nullable`
- **Added**: `sales_order_id` (nullable) - for direct order payments
- **Added**: `quotation_id` (nullable) - for direct quotation payments
- **Added**: Validation to ensure at least one ID is provided
- **Added**: Logic to handle all three payment types:
  - Invoice-based payment (production flow with validation)
  - Direct order payment (test mode)
  - Direct quotation payment (test mode)
- **Updated**: Payment reference generation based on type
- **Updated**: Response data to include relevant reference (invoice/order/quotation)

#### `uploadProofOfPayment()` Method
- **Changed**: `invoice_id` from `required` to `nullable`
- **Added**: `sales_order_id` (nullable) - for direct order payments
- **Added**: `quotation_id` (nullable) - for direct quotation payments
- **Added**: Validation to ensure at least one ID is provided
- **Added**: Logic to handle all three payment types
- **Updated**: File naming to use appropriate reference number
- **Updated**: Email sending - only sends emails when invoice exists
- **Added**: Logging for test payments without invoices
- **Updated**: Response data to include relevant reference

### 2. Frontend - unified-payment-modal.js

#### `handlePayment()` Function
- **Updated**: Payload construction to send appropriate ID based on payment type
- **Changed**: From sending `type` and `id` to sending specific field names:
  - `invoice_id` for invoices
  - `sales_order_id` for orders
  - `quotation_id` for quotations

#### `handleBankTransferSubmit()` Function
- **Removed**: Invoice-only validation
- **Updated**: FormData construction to send appropriate ID based on payment type
- **Changed**: Now supports all three payment types for bank transfer

### 3. Frontend - use-payment.js Hook

#### `initiatePayment` Mutation
- **Simplified**: Now accepts raw payload instead of type/id structure
- **Updated**: Directly sends payload to backend API
- **Added**: Invalidation for orders and quotations queries
- **Removed**: Type detection logic (now handled by backend)

## Usage Examples

### 1. Invoice Payment (Production Flow)
```javascript
// Pesepay
const payload = {
  invoice_id: 123,
  amount: 100.00,
  payment_method: 'pesepay'
};

// Bank Transfer
const formData = new FormData();
formData.append('invoice_id', 123);
formData.append('amount', 100.00);
formData.append('payment_reference', 'BANK-REF-123');
formData.append('payment_date', '2026-02-18');
formData.append('proof_file', file);
```

### 2. Direct Order Payment (Test Mode)
```javascript
// Pesepay
const payload = {
  sales_order_id: 456,
  amount: 150.00,
  payment_method: 'pesepay'
};

// Bank Transfer
const formData = new FormData();
formData.append('sales_order_id', 456);
formData.append('amount', 150.00);
formData.append('payment_reference', 'BANK-REF-456');
formData.append('payment_date', '2026-02-18');
formData.append('proof_file', file);
```

### 3. Direct Quotation Payment (Test Mode)
```javascript
// Pesepay
const payload = {
  quotation_id: 789,
  amount: 200.00,
  payment_method: 'pesepay'
};

// Bank Transfer
const formData = new FormData();
formData.append('quotation_id', 789);
formData.append('amount', 200.00);
formData.append('payment_reference', 'BANK-REF-789');
formData.append('payment_date', '2026-02-18');
formData.append('proof_file', file);
```

## Payment Modal Usage

The unified payment modal automatically handles all payment types:

```javascript
// Invoice payment
setPaymentData({
  type: 'invoice',
  id: 123,
  amount: 100.00,
  reference: 'INV-001',
  description: 'Payment for Invoice #INV-001'
});

// Order payment (test)
setPaymentData({
  type: 'order',
  id: 456,
  amount: 150.00,
  reference: 'ORD-002',
  description: 'Payment for Order #ORD-002'
});

// Quotation payment (test)
setPaymentData({
  type: 'quotation',
  id: 789,
  amount: 200.00,
  reference: 'QUO-003',
  description: 'Payment for Quotation #QUO-003'
});

setPaymentModalOpen(true);
```

## Important Notes

### Production vs Test Mode

1. **Invoice Payments (Production)**:
   - Full validation (amount must match invoice)
   - Status checks (paid/cancelled)
   - Odoo integration (file upload)
   - Email notifications (finance team + customer)
   - Invoice status updates

2. **Direct Order/Quotation Payments (Test)**:
   - No amount validation
   - No status checks
   - No Odoo integration
   - No email notifications
   - Logged for tracking only

### Email Behavior

- **With Invoice**: Sends emails to finance team and customer with full details
- **Without Invoice**: Only logs the payment, no emails sent

### Odoo Integration

- **With Invoice**: Uploads proof of payment to Odoo as attachment
- **Without Invoice**: Skips Odoo upload

## Backward Compatibility

✅ All existing invoice-based payment flows continue to work
✅ No breaking changes to existing API contracts
✅ Frontend components handle both old and new payment types

## Testing

To test direct order/quotation payments:

1. Create an order or quotation
2. Open payment modal with order/quotation data
3. Select payment method (Pesepay or Bank Transfer)
4. Complete payment
5. Check logs for payment record creation
6. Verify no emails are sent (test mode)

## Files Modified

### Backend
- `afinet-portal-backend/app/Http/Controllers/API/PaymentController.php`

### Frontend
- `afinet-portal/src/components/modals/unified-payment-modal.js`
- `afinet-portal/src/hooks/use-payment.js`

## Next Steps

If you want to enable full production features for order/quotation payments:
1. Add amount validation
2. Add status checks
3. Enable Odoo integration
4. Create email templates for order/quotation payments
5. Add order/quotation status updates after payment