# Notification System Summary

## Overview
Users receive notifications through three channels:
1. **In-App Notifications** - Displayed in dashboard notifications section
2. **Email** - Sent to user's registered email address
3. **SMS** - Sent to user's phone number (if provided)

## Notification Events

### 1. Withdrawal Request Submitted (User → Admin)

**Trigger:** User submits withdrawal request

**Admin Receives:**
- In-app notification: "John Doe requested withdrawal of ¥100.00. Reference: WTH-XXX"

**User Receives:**
- Email: 
  ```
  Subject: Withdrawal Request Submitted - Flat Line
  
  Your withdrawal request has been submitted successfully.
  
  Amount: ¥100.00
  Reference: WTH-XXX
  Alipay Account: 123456789
  
  Your request will be reviewed by our admin team.
  ```
- SMS: "Flat Line: Your withdrawal request of ¥100.00 (Ref: WTH-XXX) has been submitted. You'll be notified once reviewed."

---

### 2. Withdrawal Approved (Admin → User)

**Trigger:** Admin clicks "Approve" on withdrawal request

**User Receives:**
- In-app notification: "Your withdrawal request of ¥100.00 (Ref: WTH-XXX) has been approved and processed."
- Email:
  ```
  Subject: Withdrawal Approved - Flat Line
  
  Your withdrawal request of ¥100.00 (Ref: WTH-XXX) has been approved and processed. 
  The funds will be transferred to your Alipay account shortly.
  ```
- SMS: "Flat Line: Your withdrawal of ¥100.00 (Ref: WTH-XXX) has been approved."

**Actions:**
- Funds deducted from user wallet
- Transaction status updated to 'completed'

---

### 3. Withdrawal Rejected (Admin → User)

**Trigger:** Admin clicks "Reject" on withdrawal request

**User Receives:**
- In-app notification: "Your withdrawal request of ¥100.00 (Ref: WTH-XXX) has been rejected."
- Email:
  ```
  Subject: Withdrawal Rejected - Flat Line
  
  Your withdrawal request of ¥100.00 (Ref: WTH-XXX) has been rejected. 
  Please contact support for more information.
  ```
- SMS: "Flat Line: Your withdrawal of ¥100.00 (Ref: WTH-XXX) has been rejected. Contact support."

**Actions:**
- Transaction status updated to 'failed'
- No funds deducted

---

### 4. Exchange Order Completed (Admin → User)

**Trigger:** Admin marks exchange order status as "completed"

**User Receives:**
- In-app notification: "Your exchange order #ORD-XXX has been completed. ¥57.00 has been added to your wallet."
- Email:
  ```
  Subject: Exchange Completed - Flat Line
  
  Your exchange order #ORD-XXX has been completed. 
  ¥57.00 has been added to your wallet.
  ```
- SMS: "Flat Line: Your exchange order #ORD-XXX is complete. ¥57.00 added to your wallet."

**Actions:**
- CNY amount added to user wallet
- Wallet transaction created (type: topup, method: exchange)

---

### 5. Wallet Top-Up Successful (Paystack → User)

**Trigger:** Paystack payment verification succeeds

**User Receives:**
- Email:
  ```
  Subject: Top Up Successful - Flat Line
  
  Your wallet top-up of ¥100.00 has been completed successfully. 
  Your new balance is ¥157.00.
  ```
- SMS: "Flat Line: Top-up of ¥100.00 successful. New balance: ¥157.00"
- Dashboard redirect with success message

**Actions:**
- Amount added to user wallet
- Transaction status updated to 'completed'

---

## Notification Channels Configuration

### Email Service
- Uses Laravel's Mail facade
- Configured in `.env` file
- SMTP settings required:
  ```
  MAIL_MAILER=smtp
  MAIL_HOST=smtp.mailtrap.io
  MAIL_PORT=2525
  MAIL_USERNAME=your_username
  MAIL_PASSWORD=your_password
  MAIL_ENCRYPTION=tls
  MAIL_FROM_ADDRESS=noreply@flatline.com
  MAIL_FROM_NAME="Flat Line"
  ```

### SMS Service
- Uses BulkSMSGhana API
- Configured in admin settings
- Required settings:
  - API Key
  - Sender ID (default: "FlatLine")
- Phone number format: +233XXXXXXXXX
- Auto-formats Ghana numbers

### In-App Notifications
- Stored in `notifications` table
- Displayed in dashboard notifications section
- Supports read/unread status
- Pagination (5 per page)
- Filter by: All, Unread, Read

---

## Implementation Details

### Email Service (`app/Services/EmailService.php`)
```php
$emailService = new \App\Services\EmailService();
$emailService->send(
    $user->email,
    'Subject Line',
    'Message body'
);
```

### SMS Service (`app/Services/SmsService.php`)
```php
$smsService = new \App\Services\SmsService();
$smsService->send(
    $user->phone,
    'SMS message (160 chars max recommended)'
);
```

### In-App Notification
```php
\App\Models\Notification::create([
    'user_id' => $user->id,
    'type' => 'EMAIL', // or 'SMS'
    'subject' => 'Notification Subject',
    'message' => 'Notification message',
]);
```

---

## Testing Notifications

### Test Email
1. Configure SMTP settings in `.env`
2. Submit withdrawal request as user
3. Check email inbox for confirmation
4. Admin approves/rejects
5. Check email for approval/rejection notification

### Test SMS
1. Configure BulkSMS API in admin settings
2. Ensure user has phone number
3. Submit withdrawal request
4. Check phone for SMS confirmation
5. Admin approves/rejects
6. Check phone for approval/rejection SMS

### Test In-App
1. Submit withdrawal request
2. Login as admin
3. Check notifications section for new request
4. Approve/reject withdrawal
5. Login as user
6. Check notifications section for approval/rejection

---

## Error Handling

### Email Failures
- Logged to Laravel log file
- Does not block transaction processing
- User still receives in-app notification

### SMS Failures
- Logged to Laravel log file
- Common issues:
  - Invalid API key
  - Insufficient SMS credits
  - Invalid phone number format
- Does not block transaction processing

### Fallback Strategy
- In-app notifications always created
- Email/SMS are supplementary
- Users can always check dashboard for updates

---

## Best Practices

1. **Keep Messages Concise**
   - SMS limited to 160 characters
   - Email should be brief and clear

2. **Include Reference Numbers**
   - Always include transaction reference
   - Helps users track requests

3. **Provide Next Steps**
   - Tell users what to expect
   - Include contact information if needed

4. **Test Regularly**
   - Verify email delivery
   - Check SMS credits
   - Monitor notification logs

5. **User Preferences** (Future Enhancement)
   - Allow users to choose notification channels
   - Opt-in/opt-out for SMS
   - Email vs SMS preference