citrus-cms/app/Services/WeldLogTriggers/README.md

# WeldLog Triggers System

## 🎯 Overview

Modular, service-based trigger system for WeldLog save operations. Replaces the monolithic 2,435-line trigger file with 12 separate, maintainable trigger classes.

## 📊 Quick Stats

- **Original**: 1 file, 2,435 lines
- **New System**: 16 files, ~3,600 lines (better organized)
- **Triggers**: 12 independent operations
- **Execution Order**: 1-12 (explicit ordering)
- **Test Coverage**: Ready for unit testing

## 🗂️ Structure

```
app/Services/WeldLogTriggers/
├── Contracts/
│   └── WeldLogTriggerInterface.php      # Interface
├── Base/
│   └── BaseTrigger.php                   # Base class
├── Triggers/
│   ├── SpoolStatusChangerTrigger.php           # Order 1
│   ├── LineListsUpdateTrigger.php              # Order 2
│   ├── NdeMatrixUpdateTrigger.php              # Order 3
│   ├── RequestDateOperationsTrigger.php        # Order 4
│   ├── RepairLogsUpdateTrigger.php             # Order 5
│   ├── NdeProjectUpdateTrigger.php             # Order 6
│   ├── TestPackageOperationsTrigger.php        # Order 7
│   ├── ConstructionPaintLogsTrigger.php        # Order 8
│   ├── TestPackBaseStatusChangerTrigger.php    # Order 9
│   ├── PaintFollowUpsSyncTrigger.php           # Order 10
│   ├── HandoversSyncTrigger.php                # Order 11
│   └── TestPackCleanupTrigger.php              # Order 12
├── WeldLogTriggerRegistry.php            # Central registry
├── WeldLogTriggerManager.php             # Execution manager
└── README.md                             # This file
```

## 🚀 Quick Start

### Basic Usage

```php
use App\Services\WeldLogTriggers\WeldLogTriggerManager;
use App\Services\WeldLogTriggers\WeldLogTriggerRegistry;

// Initialize
$registry = new WeldLogTriggerRegistry();
$manager = new WeldLogTriggerManager($registry);

// Execute all triggers
$results = $manager->executeTriggers(
    $weldLogData,      // Current data
    $beforeData,       // Previous data (null for new)
    $changedFields,    // Array of changed field names
    $isNewRecord       // Boolean
);
```

### Adding a New Trigger

1. Create trigger class in `Triggers/` directory
2. Extend `BaseTrigger`
3. Implement required methods
4. Register in `WeldLogTriggerRegistry.php`

```php
class MyNewTrigger extends BaseTrigger
{
    public function getName(): string { return 'My New Trigger'; }
    public function getOrder(): int { return 14; }
    public function getDependentFields(): array { return ['field1', 'field2']; }
    
    protected function process($data, $beforeData, array $context): array
    {
        // Your logic here
        return ['success' => true];
    }
}
```

## ✨ Key Features

### 1. Modular Design
Each trigger is a separate, focused class with single responsibility.

### 2. Automatic Change Detection
System automatically detects which fields changed and runs only relevant triggers.

### 3. Standardized Logging
All triggers use consistent log format with timing information.

### 4. Error Isolation
One trigger's error doesn't affect others (except critical triggers).

### 5. Performance Tracking
Each trigger's execution time is measured and logged separately.

### 6. Future-Ready
Built-in support for async execution (to be implemented).

## 📚 Documentation

### Complete Documentation
See [resources/views/guide/weld-log-triggers-system.md](../../../resources/views/guide/weld-log-triggers-system.md) for:
- Detailed architecture
- Complete trigger descriptions
- API documentation
- Best practices
- Troubleshooting guide

### Migration Guide
See [resources/views/guide/weld-log-triggers-migration.md](../../../resources/views/guide/weld-log-triggers-migration.md) for:
- Step-by-step migration
- Rollback procedures
- Validation checklist
- Common issues and solutions

## 🔍 How It Works

```
1. WeldLog saved in database
   ↓
2. SaveTrigger called (weld_logs.php)
   ↓
3. Detect changed fields
   ↓
4. Initialize Registry & Manager
   ↓
5. For each trigger (1-12):
   - Check if should run (based on changed fields)
   - Execute if needed
   - Log results
   ↓
6. Return consolidated results
```

## 🎨 Design Patterns

- **Strategy Pattern**: Each trigger is a strategy
- **Registry Pattern**: Central trigger registry
- **Template Method**: BaseTrigger defines execution template
- **Chain of Responsibility**: Triggers execute in sequence

## 📋 Trigger List

| # | Trigger | Purpose | Avg Time |
|---|---------|---------|----------|
| 1 | Spool Status Changer | Updates spool statuses | 50-100ms |
| 2 | Line Lists Update | Syncs line lists data | 100-200ms |
| 3 | NDE Matrix Update | Manages NDE matrices | 200-500ms |
| 4 | Request Date Operations | Generates request numbers | 100-300ms |
| 5 | Repair Logs Update | Updates repair statuses | 50-100ms |
| 6 | NDE Project Update | Updates project fields | 50-100ms |
| 7 | Test Package Operations | Complex test package logic | 500-2000ms |
| 8 | Construction Paint Logs | Construction paint sync | 200-400ms |
| 9 | Test Pack Base Status | Updates base statuses | 300-600ms |
| 10 | Paint Follow Ups Sync | Comprehensive paint sync | 250-450ms |
| 11 | Handovers Sync | Syncs handover data | 100-200ms |
| 12 | Test Pack Cleanup | Cleans orphaned records | 50-100ms |

**Total**: 2-4 seconds average

## ⚡ Performance

### Optimization Features
- Chunk processing for large datasets
- Transaction retry logic for deadlocks
- Configurable delays between chunks
- Memory management
- Database timeout settings

### Monitoring
Check logs for performance metrics:
```bash
tail -f storage/logs/laravel.log | grep "WeldLog Trigger"
```

Look for:
- `duration_ms`: Execution time per trigger
- `total_execution_time_sec`: Overall time
- `peak_memory_usage_mb`: Memory usage

## 🧪 Testing

### Manual Testing
```php
// Test with real weld log
$weldLog = WeldLog::find(1);
$beforeData = clone $weldLog;
$weldLog->spool_number = 'NEW-SPOOL';
$weldLog->save();

// Check logs for trigger execution
```

### Unit Testing (Future)
Each trigger can be unit tested independently:
```php
$trigger = new SpoolStatusChangerTrigger();
$result = $trigger->execute($data, $beforeData, []);
$this->assertTrue($result['success']);
```

## 🐛 Troubleshooting

### Common Issues

**Trigger not executing?**
- Check `getDependentFields()` includes changed field
- Check logs for "Skipping trigger" messages
- Verify trigger is registered in Registry

**Performance slow?**
- Check chunk sizes in TransactionHelper calls
- Add database indexes
- Monitor slow query log

**Deadlock errors?**
- Ensure queries ordered by 'id ASC'
- Use TransactionHelper with retry logic
- Increase delays between chunks

### Debug Mode
Enable detailed logging:
```php
Log::setDefaultDriver('daily');
Log::info("Debug info", ['data' => $data]);
```

## 📝 Changelog

### Version 1.1.0 (2025-11-15)
- ✅ Consolidated paint follow-up logic (LineList parity)
- ✅ Removed legacy PaintFollowUpTrigger
- ✅ Added cleanup + protection to construction paint sync
- ✅ Updated docs and registry ordering

## 🤝 Contributing

### Adding New Triggers
1. Create class in `Triggers/` directory
2. Extend `BaseTrigger`
3. Implement all required methods
4. Add to Registry
5. Update documentation
6. Test thoroughly

### Code Style
- Follow PSR-12 standards
- Use type hints
- Add PHPDoc comments
- Keep methods focused (single responsibility)
- Log important operations

## 📖 Additional Resources

- [Main Documentation](../../../resources/views/guide/weld-log-triggers-system.md)
- [Migration Guide](../../../resources/views/guide/weld-log-triggers-migration.md)
- [DevQMS Documentation](../../../resources/views/guide/)

## 🔐 Security

- All triggers use prepared statements
- Transaction safety ensured
- Input validation in place
- Error messages don't expose sensitive data

## 📞 Support

For issues or questions:
1. Check documentation
2. Review logs
3. Contact development team

---

**Version**: 1.0.0  
**Status**: Production Ready ✅  
**Last Updated**: October 30, 2025  
**Maintainer**: DevQMS Development Team