# Indicator Module Installation & Setup Guide

## Installation

1. **Add to composer.json** (in main NGauge_Base project):
```json
"require": {
    "portalpeople/ngauge-indicator": "v1.0.0"
}
```

2. **Update composer dependencies**:
```bash
composer update portalpeople/ngauge-indicator
```

3. **Configure the module** in `params-local.php`:
```php
'plugins' => [
    'indicator' => [
        'protocol' => 'sftp',                    // 'ftp' or 'sftp'
        'host' => 'sftp.example.com',            // SFTP/FTP server hostname
        'port' => 22,                            // 22 for SFTP, 21 for FTP
        'user' => 'username',                    // SFTP/FTP username
        'password' => 'password',                // SFTP/FTP password (encrypted in web UI)
        'path' => '/incoming',                   // Remote directory containing XML files
        'delete_after_download' => false,        // Delete files after download
        'download_interval' => 3600,             // Seconds between file downloads (1 hour)
        'process_interval' => 7200,              // Seconds between order processing (2 hours)
        'summary_email' => 'admin@example.com',  // Email for import summaries (optional)
        'passive_mode' => true,                  // FTP passive mode (ignored for SFTP)
    ]
]
```

4. **Bootstrap the module** in your app config (`config/main.php`):
```php
'modules' => [
    'indicator' => [
        'class' => 'PortalPeople\indicator\Module',
    ],
],

'bootstrap' => ['indicator'],
```

## Configuration via Web UI

1. Navigate to `/indicator/config` (must be logged in as admin)
2. Enter FTP/SFTP connection details
3. Click **Test Connection** to verify connectivity
4. Set download and process intervals (in seconds)
5. Optionally enter email address for import summaries
6. Click **Save Configuration**

## Manual Testing

### Test FTP Connection
```bash
./yii indicator/test
```

### Download Files (one-time)
```bash
./yii indicator/download --delete=1
```

### Process Downloaded Files (one-time)
```bash
./yii indicator/process
```

## Recurring Job Setup

The module uses two recurring background jobs:

1. **DownloadFilesJob**: Fetches XML files from FTP/SFTP server
2. **ProcessFilesJob**: Converts downloaded XML files to orders

Both jobs are automatically registered and will execute at the configured intervals via your queue system (typically `yii\queue\redis\Queue` or `yii\queue\file\Queue`).

### Verify Jobs are Running

Check your queue/job logs:
```bash
tail -f runtime/logs/app.log | grep indicator
```

## Data Flow

```
FTP/SFTP Server
       ↓
   DownloadFilesJob (every 1 hour)
       ↓
@runtime/indicator/inbox/ (raw XML files)
       ↓
   ProcessFilesJob (every 2 hours)
       ↓
Parse XML → Normalize to Order Structure → Create Cart + Cartlines
       ↓
Processed files moved to @runtime/indicator/processed/
Failed files moved to @runtime/indicator/failed/
       ↓
Email summary sent (if configured)
```

## XML File Format

The module expects XML files with the following structure:

```xml
<?xml version="1.0"?>
<orders>
    <order>
        <order_number>ORD-12345</order_number>
        <customer_name>John Doe</customer_name>
        <customer_email>john@example.com</customer_email>
        <delivery_address>123 Main St</delivery_address>
        <postcode>ABC123</postcode>
        <telephone>01234567890</telephone>
        <shipping_method>Standard</shipping_method>
        <notes>Special instructions here</notes>
        <items>
            <item>
                <product_name>Widget A</product_name>
                <quantity>2</quantity>
                <price>19.99</price>
            </item>
            <item>
                <product_name>Widget B</product_name>
                <quantity>1</quantity>
                <price>29.99</price>
            </item>
        </items>
    </order>
</orders>
```

**Supported XML tag variations:**
- `ordernumber`, `order_number`, `ref` → order ID
- `customer_name`, `name` → customer name
- `customer_email`, `email` → customer email
- `delivery_address`, `address` → delivery address
- `postcode`, `zip` → postcode
- `quantity`, `qty` → line quantity
- `product_name`, `description` → item description
- `unit_price`, `price` → item price

## Troubleshooting

### Connection Fails
- Verify FTP/SFTP credentials in configuration
- Check firewall allows outbound connections to FTP/SFTP server
- Test with: `./yii indicator/test`

### No Files Downloaded
- Verify XML files exist on the SFTP/FTP server
- Check file permissions on remote server
- Verify remote path is correct in configuration
- Ensure files have `.xml` extension

### Orders Not Creating
- Check `runtime/logs/app.log` for Indicator errors
- Verify XML file format matches expected structure
- Check backend database connectivity
- Review `@runtime/indicator/failed/` directory for files with issues

### Email Summaries Not Sent
- Verify summary email is configured in params
- Check Yii mailer component is configured
- Verify `summary_email` is a valid email address
- Check application logs for mail errors

## Debugging

Enable debug mode for detailed logging:
```php
// In console.php or main.php
'components' => [
    'log' => [
        'targets' => [
            [
                'class' => 'yii\log\FileTarget',
                'levels' => ['error', 'warning', 'info'],
                'logFile' => '@runtime/logs/indicator.log',
                'categories' => ['indicator.*'],
            ],
        ],
    ],
],
```

Then check logs:
```bash
tail -f runtime/logs/indicator.log
```

## Module Architecture

- **Module.php**: Bootstrap configuration, service factory methods
- **services/FtpDownloadService.php**: FTP/SFTP connection & file download
- **services/ProcessFilesService.php**: XML parsing & order creation
- **jobs/DownloadFilesJob.php**: Recurring download job
- **jobs/ProcessFilesJob.php**: Recurring process job
- **models/Cart.php**: Custom Cart model extending Cartsbe
- **models/ConfigForm.php**: Configuration form with encryption
- **controllers/ConfigController.php**: Web UI for configuration
- **commands/IndicatorController.php**: Console commands for manual testing
