citrus-cms/resources/views/guide/REGISTER_CREATOR_JOBS_README.md

# Register Creator Jobs System - Documentation

## 📋 Overview

New modular, queue-based Register Creator system using Laravel Jobs and Services. This replaces the old cache-based system with a modern, SOLID-principles architecture.

## 🏗️ Architecture

```
Frontend (register-creator-2.blade.php)
    ↓ AJAX Request
Admin-AJAX Endpoint (register-creator-dispatch-jobs.blade.php)
    ↓ Dispatches Jobs
RegisterCreatorJob (Queue)
    ↓ Orchestrates
RegisterCreatorService (Coordinator)
    ↓ Uses
Document Processors (Factory Pattern)
    ├─ QaDocumentProcessor
    ├─ WdbDocumentProcessor
    ├─ TemplateProcessor
    └─ ... (10+ processors)
```

## 📁 File Structure

```
app/
├── Jobs/
│   └── RegisterCreatorJob.php                    # Main job class
├── Services/
│   └── RegisterCreator/
│       ├── RegisterCreatorService.php            # Main coordinator
│       ├── ExcelHandler.php                      # Excel operations
│       ├── PdfConverter.php                      # PDF conversion
│       ├── PlaceholderReplacer.php               # Placeholder handling
│       ├── ProgressTracker.php                   # Progress tracking
│       └── DocumentProcessors/
│           ├── AbstractDocumentProcessor.php     # Base processor
│           ├── DocumentProcessorFactory.php      # Factory pattern
│           ├── QaDocumentProcessor.php
│           ├── WdbDocumentProcessor.php
│           ├── TemplateProcessor.php
│           ├── DrawingsProcessor.php
│           ├── MaterialsProcessor.php
│           ├── IncomingControlProcessor.php
│           ├── PrikazProcessor.php
│           ├── WpsNaksTechnologyProcessor.php
│           ├── NaksConsumablesCertificateProcessor.php
│           ├── NaksConsumablesInspectionProcessor.php
│           ├── DocumentProcedureProcessor.php
│           └── GenericDocumentProcessor.php

resources/views/
├── admin/type/
│   └── register-creator-2.blade.php              # Frontend (updated)
└── admin-ajax/
    └── register-creator-dispatch-jobs.blade.php  # New AJAX endpoint
```

## 🚀 Installation & Setup

### 1. Queue Configuration

Add to `.env`:
```env
QUEUE_CONNECTION=database
```

Run migration for queue table:
```bash
php artisan queue:table
php artisan migrate
```

### 2. Start Queue Worker

**Option A: Supervisor (Production - Recommended)**

Create supervisor config: `/etc/supervisor/conf.d/register-creator.conf`
```ini
[program:register-creator-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/stellar2/artisan queue:work --queue=register-creator --sleep=3 --tries=3 --timeout=3600
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/html/stellar2/storage/logs/queue-worker.log
stopwaitsecs=3600
```

Restart supervisor:
```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start register-creator-worker:*
```

**Option B: Artisan Command (Development)**
```bash
php artisan queue:work --queue=register-creator --tries=3 --timeout=3600
```

### 3. Verify Installation

Check if queue is working:
```bash
php artisan queue:listen --queue=register-creator --timeout=3600
```

## 💡 Usage

### Frontend (Same as Before)

1. Select documents from left panel
2. Select lines from DataGrid
3. Click "Generate Register of Selected"
4. Jobs are dispatched to queue

### Monitoring Jobs

**Check queue status:**
```bash
php artisan queue:work --queue=register-creator --once
```

**Failed jobs:**
```bash
php artisan queue:failed
```

**Retry failed job:**
```bash
php artisan queue:retry <job-id>
```

**Clear failed jobs:**
```bash
php artisan queue:flush
```

## 🔍 How It Works

### 1. Job Dispatch Flow

```php
// User clicks button → AJAX request
$.post("?ajax=register-creator-dispatch-jobs", {
    lines: [...],      // Selected rows
    documents: [...],  // Selected documents
    override: true
})

// Backend dispatches jobs
foreach ($lines as $line) {
    RegisterCreatorJob::dispatch([
        'line_data' => $line,
        'documents' => $documents,
        'settings' => [...]
    ])->onQueue('register-creator');
}
```

### 2. Job Execution

```php
RegisterCreatorJob::handle()
    → RegisterCreatorService::processLine()
        → Load Excel template
        → Replace placeholders
        → foreach(documents as $document)
            → DocumentProcessorFactory::make($document['type'])
                → Processor::process()
                    → Search files
                    → Add rows to Excel
        → Save Excel
        → Convert to PDF
        → Update progress
```

### 3. Document Type Processing

Each document type has its own processor:

| Type | Processor | Description |
|------|-----------|-------------|
| `qa` | QaDocumentProcessor | NDT reports, procedures |
| `wdb` | WdbDocumentProcessor | WPS, WPQ, Naks certificates |
| `template` | TemplateProcessor | Template documents |
| `drawings` | DrawingsProcessor | Drawing files |
| `materials` | MaterialsProcessor | Material certificates |
| `incoming_control_materials` | IncomingControlProcessor | Incoming control |
| `prikaz` | PrikazProcessor | Work permits |
| `wps_naks_technology` | WpsNaksTechnologyProcessor | WPS Naks certs |
| ... | ... | ... |

## 🎯 Benefits

### ✅ Advantages Over Old System

1. **SOLID Principles**: Each class has single responsibility
2. **Laravel Queue**: Built-in retry, failure handling, monitoring
3. **Parallel Processing**: Multiple workers can run simultaneously
4. **Error Isolation**: One line failure doesn't affect others
5. **Testable**: Each service can be unit tested
6. **Maintainable**: Easy to add new document types
7. **Scalable**: Can add more workers as needed
8. **Progress Tracking**: Real-time progress via Cache
9. **Email Notifications**: Success/failure notifications

### 📊 Performance

- **Old System**: Sequential processing, blocks server
- **New System**: Asynchronous, non-blocking, parallel

## 🐛 Debugging

### Enable Debug Logging

```php
// In RegisterCreatorJob
Log::info("Job started", ['line' => $lineIdentifier]);
```

### Check Logs

```bash
tail -f storage/logs/laravel.log
tail -f storage/logs/queue-worker.log
```

### Progress Tracking

Progress is stored in Cache:
```php
Cache::get("register-creator-progress-{$jobId}")
```

## 🔧 Maintenance

### Add New Document Type

1. Create processor:
```php
// app/Services/RegisterCreator/DocumentProcessors/MyNewProcessor.php
class MyNewProcessor extends AbstractDocumentProcessor {
    public function process(...) {
        // Implementation
    }
}
```

2. Add to factory:
```php
// DocumentProcessorFactory.php
return match($type) {
    'my_new_type' => new MyNewProcessor(),
    // ...
};
```

### Extend Functionality

All processors extend `AbstractDocumentProcessor` which provides:
- File search helper
- Log writing
- Contractor lookup
- Common utilities

## 📝 Configuration

### Settings

- `register_creator_start_row`: Template row in Excel (default: 16)
- `register_creator_column_based`: Column to group by (default: 'line_number')
- `register_creator_path`: Base path for documents

### Job Settings

- **Tries**: 3 (configurable in RegisterCreatorJob)
- **Timeout**: 3600 seconds (1 hour)
- **Queue**: `register-creator`

## 🚨 Troubleshooting

### Jobs Not Processing

```bash
# Check if queue worker is running
ps aux | grep queue:work

# Start manually
php artisan queue:work --queue=register-creator
```

### Memory Issues

```bash
# Increase memory limit in Job
ini_set('memory_limit', '2048M');
```

### Failed Jobs

```bash
# List failed jobs
php artisan queue:failed

# Retry specific job
php artisan queue:retry <job-id>

# Retry all
php artisan queue:retry all
```

## 📞 Support

For issues or questions:
1. Check Laravel logs: `storage/logs/laravel.log`
2. Check queue logs: `storage/logs/queue-worker.log`
3. Check line-specific logs: `storage/documents/{path}/{line}/log.txt`

## 🎓 Best Practices

1. **Always run queue worker** in production
2. **Use Supervisor** for automatic restarts
3. **Monitor failed jobs** regularly
4. **Check memory usage** on long-running jobs
5. **Test with small batches** first
6. **Backup before major updates**

---

**Created**: {{ date('Y-m-d') }}
**Version**: 2.0
**Status**: Production Ready ✅