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:

QUEUE_CONNECTION=database

Run migration for queue table:

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

[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:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start register-creator-worker:*

Option B: Artisan Command (Development)

php artisan queue:work --queue=register-creator --tries=3 --timeout=3600

3. Verify Installation

Check if queue is working:

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:

php artisan queue:work --queue=register-creator --once

Failed jobs:

php artisan queue:failed

Retry failed job:

php artisan queue:retry <job-id>

Clear failed jobs:

php artisan queue:flush

🔍 How It Works

1. Job Dispatch Flow

// 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

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

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

Check Logs

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

Progress Tracking

Progress is stored in Cache:

Cache::get("register-creator-progress-{$jobId}")

🔧 Maintenance

Add New Document Type

1. Create processor:

// app/Services/RegisterCreator/DocumentProcessors/MyNewProcessor.php
class MyNewProcessor extends AbstractDocumentProcessor {
    public function process(...) {
        // Implementation
    }
}

2. Add to factory:

// 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

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

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

Memory Issues

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

Failed Jobs

# 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 ✅