# Indicator Module - Quick Reference

## Installation (5 minutes)

```bash
# 1. Add to main project composer.json
"require": {
    "portalpeople/ngauge-indicator": "v1.0.0"
}

# 2. Update dependencies
composer update

# 3. Configure in params-local.php
'plugins' => [
    'indicator' => [
        'protocol' => 'sftp',
        'host' => 'sftp.example.com',
        'port' => 22,
        'user' => 'username',
        'password' => 'password',
        'path' => '/incoming',
        'download_interval' => 3600,
        'process_interval' => 7200,
        'summary_email' => 'admin@example.com',
    ]
]

# 4. Bootstrap in config/main.php
'modules' => ['indicator' => ['class' => 'PortalPeople\indicator\Module']],
'bootstrap' => ['indicator']
```

## Web Configuration

Navigate to: `http://yourapp.com/indicator/config`

- Enter FTP/SFTP credentials
- Click **Test Connection** to verify
- Set download/process intervals (seconds)
- Optionally add email for summaries
- Click **Save**

## Console Commands

```bash
# Test FTP/SFTP connection
./yii indicator/test

# Download XML files from server (once)
./yii indicator/download --delete=1

# Process downloaded XML files (once)
./yii indicator/process

# View logs
tail -f runtime/logs/app.log | grep indicator
```

## File Locations

| Path | Purpose |
|------|---------|
| `@runtime/indicator/inbox/` | Downloaded XML files waiting to process |
| `@runtime/indicator/processed/` | Successfully processed XML files |
| `@runtime/indicator/failed/` | XML files that failed processing |
| `/indicator/config` | Web configuration interface |

## XML Example

```xml
<?xml version="1.0"?>
<orders>
    <order>
        <order_number>ORD-001</order_number>
        <customer_name>John Doe</customer_name>
        <customer_email>john@example.com</customer_email>
        <delivery_address>123 Main St</delivery_address>
        <postcode>AB12 3CD</postcode>
        <telephone>01234567890</telephone>
        <shipping_method>Standard</shipping_method>
        <items>
            <item>
                <product_name>Widget</product_name>
                <quantity>2</quantity>
                <price>19.99</price>
            </item>
        </items>
    </order>
</orders>
```

## Data Flow

```
SFTP/FTP Server
        ↓
  DownloadFilesJob (every 1 hour)
        ↓
  @runtime/indicator/inbox/
        ↓
  ProcessFilesJob (every 2 hours)
        ↓
  Parse XML → Create Cart + Cartlines
        ↓
  Move to processed/ or failed/
        ↓
  Send email summary (optional)
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Connection fails | Run `./yii indicator/test` or use web UI test button |
| No files downloaded | Check XML files exist on remote, verify path in config |
| Orders not creating | Check `runtime/logs/app.log` for errors, verify XML format |
| Email not sent | Verify Yii mailer configured, check summary_email in config |
| "Module not configured" | Verify params-local.php has `plugins.indicator` config |

## Status Dashboard

Via web UI at `/indicator/config`:
- Shows count of files in inbox (pending)
- Shows count of files in processed (completed)
- Shows count of files in failed (errors)
- Click "Refresh Status" to update counts

## Module Architecture

```
Module.php
  ├─ Bootstrap: Load config, register routes
  ├─ ConfigForm: Handle configuration
  ├─ ConfigController: Web UI
  ├─ DownloadFilesJob: Fetch from FTP
  ├─ ProcessFilesJob: Parse & create orders
  ├─ FtpDownloadService: FTP/SFTP logic
  ├─ ProcessFilesService: XML parsing & DB writes
  └─ Cart, Cartlines, Paymentresponsesbe: Order models
```

## Security

- ✓ Passwords encrypted in database
- ✓ Config controller restricted to admin
- ✓ All input validated via Yii models
- ✓ No sensitive data in logs
- ✓ Path traversal protection

## Performance Tips

- **Adjust intervals** based on data volume:
  - High volume: 600s (10 min) for both jobs
  - Medium volume: 1800s (30 min) for both jobs
  - Low volume: 3600s (1 hour) download, 7200s (2 hours) process

- **Delete files after download** to save server disk space

- **Monitor logs** for failed imports and fix XML structure

## Support

1. Check logs: `tail -f runtime/logs/app.log | grep indicator`
2. Test connection: Visit `/indicator/config` and click "Test Connection"
3. Review INSTALLATION.md for detailed setup
4. Check PROJECT_SUMMARY.md for architecture overview
