# YSP Notification System - Enhanced Implementation

This document describes the enhanced YSP notification system that addresses all feedback requirements for professional, robust notification handling.

## 🚀 Key Improvements

### 1. **Retry Logic with 3 Attempts**
- Exponential backoff retry mechanism
- Configurable retry intervals (default: 30 seconds)
- Automatic retry scheduling with increasing delays
- Maximum 3 attempts before marking as failed

### 2. **Merchant-wise Batch Number Management**
- Automatic batch number generation per merchant per day
- Format: 6-digit zero-padded (000001, 000002, etc.)
- Thread-safe implementation with database constraints
- Resets daily for each merchant

### 3. **Database Notification Status Tracking**
- Complete audit trail of all notification attempts
- Status tracking: `pending`, `success`, `failed`, `max_attempts_reached`
- HTTP response logging for debugging
- Retry scheduling with timestamps

### 4. **Configuration Management**
- Merchant-specific configuration support
- Fallback to default configuration
- Database-driven configuration (no hardcoded values)
- Easy configuration updates via database

### 5. **Professional Code Organization**
- Dedicated service module: `YspNotificationService`
- Separation of concerns and clean architecture
- Comprehensive error handling and logging
- Async processing to avoid blocking main flow

## 📊 Database Schema

### `ysp_notification_logs` Table
Tracks all notification attempts with detailed status information:

```sql
- id: Primary key
- transaction_id: Reference to transactions table
- payment_id: Payment reference ID
- notification_url: Target webhook URL
- payload: Complete JSON payload sent
- attempt_number: Current attempt (1-3)
- max_attempts: Maximum retry attempts
- status: Current status (pending/success/failed/max_attempts_reached)
- http_status_code: HTTP response code
- response_body: Server response
- error_message: Error details for failed attempts
- next_retry_at: Scheduled retry timestamp
- completed_at: Completion timestamp
```

### `batch_numbers` Table
Manages merchant-wise batch number generation:

```sql
- id: Primary key
- merchant_id: Merchant identifier
- batch_number: Current batch number (6-digit padded)
- date: Date for this batch
- transaction_count: Number of transactions
- last_used_at: Last usage timestamp
```

### `ysp_configurations` Table
Stores merchant-specific notification configurations:

```sql
- id: Primary key
- merchant_id: Merchant identifier (or "default")
- notification_url: Target webhook URL
- merchant_tag: Merchant tag for payload
- bank_user_id: Bank user identifier
- terminal_id: Terminal identifier
- shop_id: Shop identifier
- cash_desk_id: Cash desk identifier
- max_retry_attempts: Maximum retry attempts (default: 3)
- retry_interval_seconds: Base retry interval (default: 30)
- is_active: Configuration active status
```

## 🔧 Configuration

### Application Configuration
```elixir
# config/config.exs
config :da_product_app, :ysp_notification, %{
  default_url: "http://testapp.ariticapp.com/prasanna/raqmiyatresponse.php",
  default_merchant_tag: "UB776WH",
  default_bank_user_id: "MERCURY_ALIPAY123",
  default_shop_id: "SHOP001",
  default_terminal_id: "900890089008900",
  max_retry_attempts: 3,
  retry_interval_seconds: 30
}
```

### Database Configuration
Default configuration is automatically created during migration:

```sql
INSERT INTO ysp_configurations (
  merchant_id, notification_url, merchant_tag, bank_user_id,
  terminal_id, shop_id, cash_desk_id, max_retry_attempts,
  retry_interval_seconds, is_active
) VALUES (
  'default', 'http://testapp.ariticapp.com/prasanna/raqmiyatresponse.php',
  'UB776WH', 'MERCURY_ALIPAY123', '900890089008900',
  'SHOP001', 'DEV00010002', 3, 30, TRUE
);
```

## 📝 Service Usage

### Basic Notification (Webhook)
```elixir
# In AlipayWebhookController
YspNotificationService.send_notification(payment_id, params)
```

### Polling Notification
```elixir
# In QRMiddleLayerController
YspNotificationService.send_notification_from_polling(m_ref_num, inquiry_response, payment_result)
```

### Merchant Configuration
```elixir
# Get configuration for specific merchant
config = YspConfiguration.get_config_for_merchant("merchant_123")

# Create new merchant configuration
attrs = %{
  merchant_id: "new_merchant",
  notification_url: "https://merchant.example.com/webhook",
  merchant_tag: "CUSTOM_TAG",
  bank_user_id: "CUSTOM_BANK_ID",
  max_retry_attempts: 5,
  retry_interval_seconds: 60
}
YspConfiguration.changeset(%YspConfiguration{}, attrs) |> Repo.insert()
```

### Batch Number Management
```elixir
# Get or create batch number for merchant
{:ok, batch_number} = BatchNumber.get_or_create_batch_number("merchant_123")
# Returns "000001" for first transaction of the day, "000002" for second, etc.
```

## 🔄 Retry Logic Flow

1. **Initial Attempt**: Immediate notification attempt
2. **First Retry**: After 30 seconds (base interval)
3. **Second Retry**: After 60 seconds (2x base interval)
4. **Final Status**: Success or max_attempts_reached

## 📊 Monitoring and Debugging

### Notification Status Query
```sql
-- Check notification status for a specific payment
SELECT 
  nl.payment_id,
  nl.attempt_number,
  nl.max_attempts,
  nl.status,
  nl.http_status_code,
  nl.error_message,
  nl.next_retry_at,
  nl.completed_at
FROM ysp_notification_logs nl
WHERE nl.payment_id = 'PAYMENT_ID_HERE';
```

### Failed Notifications Report
```sql
-- Get all failed notifications
SELECT 
  nl.payment_id,
  nl.attempt_number,
  nl.error_message,
  nl.completed_at,
  t.merchant_id
FROM ysp_notification_logs nl
JOIN transactions t ON nl.transaction_id = t.id
WHERE nl.status IN ('failed', 'max_attempts_reached')
ORDER BY nl.completed_at DESC;
```

### Batch Number Status
```sql
-- Check batch numbers for a merchant
SELECT 
  merchant_id,
  date,
  batch_number,
  transaction_count,
  last_used_at
FROM batch_numbers
WHERE merchant_id = 'MERCHANT_ID_HERE'
ORDER BY date DESC;
```

## ✅ Benefits of Enhanced Implementation

1. **Reliability**: Retry logic ensures notifications are delivered even during temporary outages
2. **Traceability**: Complete audit trail of all notification attempts
3. **Flexibility**: Merchant-specific configuration allows customization
4. **Maintainability**: Clean service-based architecture
5. **Monitoring**: Comprehensive logging and status tracking
6. **Scalability**: Async processing and database-driven configuration
7. **Professional**: Follows best practices for enterprise-grade systems

## 🧪 Testing

The implementation includes comprehensive tests covering:
- Successful notification scenarios
- Retry logic validation
- Batch number generation
- Configuration management
- Error handling
- Edge cases

Run tests with:
```bash
mix test test/da_product_app/services/ysp_notification_service_test.exs
mix test test/da_product_app_web/controllers/alipay_webhook_controller_test.exs
```

## 🔮 Future Enhancements

1. **Admin Dashboard**: Web interface for managing configurations
2. **Webhook Validation**: Signature verification for incoming webhooks
3. **Rate Limiting**: Prevent notification flooding
4. **Performance Metrics**: Response time tracking and analytics
5. **Dead Letter Queue**: Handle permanently failed notifications
6. **Batch Processing**: Bulk notification processing for high volume