citrus-cms/resources/views/guide/weld-log-triggers-migration.md

# WeldLog Triggers System - Migration Guide

## Quick Reference

**Old System**: Single 2,435-line file (`weld_logs.php`)  
**New System**: 13 modular trigger classes + core infrastructure  
**Migration Time**: 30-60 minutes  
**Downtime Required**: No (can test alongside old system)

---

## Pre-Migration Checklist

### ✅ Before You Begin

- [ ] Backup current `weld_logs.php` file
- [ ] Backup database (full backup recommended)
- [ ] Verify all new trigger files exist
- [ ] Review trigger execution order
- [ ] Ensure development environment is ready for testing
- [ ] Review logs to understand current trigger behavior
- [ ] Document any custom modifications to old trigger file

### 📋 System Requirements

- PHP 7.4+ (already met)
- Laravel 8+ (already met)
- Sufficient database connection pool
- Log storage space (triggers generate detailed logs)

---

## Migration Steps

### Step 1: Verify New System Files

Check that all required files exist:

```bash
# Navigate to project root
cd /var/www/html/dev

# Check core files
ls -la app/Services/WeldLogTriggers/Contracts/WeldLogTriggerInterface.php
ls -la app/Services/WeldLogTriggers/Base/BaseTrigger.php
ls -la app/Services/WeldLogTriggers/WeldLogTriggerRegistry.php
ls -la app/Services/WeldLogTriggers/WeldLogTriggerManager.php

# Check all 13 trigger files
ls -la app/Services/WeldLogTriggers/Triggers/*.php | wc -l
# Should output: 13

# Check new entry point
ls -la app/Http/Controllers/SaveTrigger/weld_logs_new.php
```

**Expected Output**:
```
All files should exist with no errors
Total of 13 trigger files in Triggers directory
```

---

### Step 2: Backup Current System

```bash
# Backup old trigger file
cp app/Http/Controllers/SaveTrigger/weld_logs.php \
   app/Http/Controllers/SaveTrigger/weld_logs_BACKUP_$(date +%Y%m%d_%H%M%S).php

# Backup database (adjust credentials)
mysqldump -u your_user -p your_database > backup_$(date +%Y%m%d_%H%M%S).sql

# Verify backup
ls -lh app/Http/Controllers/SaveTrigger/weld_logs_BACKUP_*.php
ls -lh backup_*.sql
```

---

### Step 3: Test New System (Without Switching)

#### Option A: Parallel Testing (Recommended)

Create a test script to call new system alongside old:

```php
// app/Http/Controllers/SaveTrigger/weld_logs_test.php
<?php
// Include new system
require_once __DIR__ . '/weld_logs_new.php';

// Log comparison results
Log::info("=== TRIGGER COMPARISON TEST ===", [
    'weld_log_id' => $id,
    'timestamp' => now()
]);
```

Run manual tests:
1. Create a new weld log record
2. Update various fields
3. Check logs for both systems
4. Compare database states

#### Option B: Feature Flag

Add a setting to switch between systems:

```php
// In weld_logs.php (temporarily)
if (setting('use_new_trigger_system')) {
    require_once __DIR__ . '/weld_logs_new.php';
    return;
}

// ... existing old code ...
```

---

### Step 4: Review Migration Differences

#### Logic Changes to Verify

| Area | Old System | New System | Verification |
|------|-----------|------------|--------------|
| Execution Order | Implicit | Explicit (1-13) | Check logs for order |
| Error Handling | Mixed | Standardized | Test error scenarios |
| Logging | Inconsistent | Standardized | Compare log formats |
| Performance | N/A | Tracked per trigger | Review timing logs |
| Field Detection | Manual | Automatic | Verify `shouldRun()` |

#### Known Differences

1. **Logging Format**: New system uses standardized log format
   - **Old**: Various formats
   - **New**: Consistent structure with trigger names and orders

2. **Error Handling**: New system has better error isolation
   - **Old**: One trigger error could affect others
   - **New**: Each trigger error is isolated

3. **Performance Tracking**: New system tracks each trigger separately
   - **Old**: Overall time only
   - **New**: Per-trigger timing + overall time

---

### Step 5: Switch to New System

#### Production Switch (Zero Downtime)

```bash
# Navigate to SaveTrigger directory
cd app/Http/Controllers/SaveTrigger

# Step 5.1: Rename old file (keep as backup)
mv weld_logs.php weld_logs_old_system.php

# Step 5.2: Activate new file
mv weld_logs_new.php weld_logs.php

# Step 5.3: Verify file is active
ls -la weld_logs.php
# Should show weld_logs.php (was weld_logs_new.php)

# Step 5.4: Clear any caches
php artisan cache:clear
php artisan config:clear
php artisan view:clear
```

#### Verify Switch

```bash
# Check file content
head -20 app/Http/Controllers/SaveTrigger/weld_logs.php
# Should show new system comments at top

# Test with a weld log update
# Check logs for new system format
tail -f storage/logs/laravel.log
```

---

### Step 6: Monitor After Migration

#### First Hour Monitoring

Monitor these metrics:

```bash
# Watch logs in real-time
tail -f storage/logs/laravel.log | grep "WELD LOG SAVE TRIGGER"

# Check for errors
grep "ERROR" storage/logs/laravel.log | grep "WeldLog Trigger"

# Check trigger execution counts
grep "executed\|skipped\|failed" storage/logs/laravel.log | tail -50
```

#### Metrics to Track

1. **Execution Time**
   - Old system average: ~2-5 seconds
   - New system should be similar or faster
   - Check logs for "total_execution_time_sec"

2. **Error Rate**
   - Should be 0% for critical triggers
   - Non-critical triggers can fail gracefully

3. **Database Impact**
   - Monitor slow query log
   - Check for deadlocks
   - Verify transaction counts

4. **Memory Usage**
   - Check "memory_usage_start" and "peak_memory_usage_mb" in logs
   - Should not exceed 2GB limit

#### Log Examples to Look For

**✅ Good - Successful Execution**:
```
[2025-10-30 10:15:23] local.INFO: === WELD LOG SAVE TRIGGER STARTED ===
[2025-10-30 10:15:23] local.INFO: WeldLog Trigger [1/13] Spool Status Changer - STARTED
[2025-10-30 10:15:23] local.INFO: WeldLog Trigger [1/13] Spool Status Changer - COMPLETED {"duration_ms":45.23}
...
[2025-10-30 10:15:28] local.INFO: === WELD LOG SAVE TRIGGER COMPLETED === {"statistics":{"executed":10,"skipped":3}}
```

**❌ Bad - Errors**:
```
[2025-10-30 10:15:23] local.ERROR: Trigger execution failed: NDE Matrix Update
```

**⚠️ Warning - Slow Execution**:
```
[2025-10-30 10:15:28] local.INFO: WeldLog Trigger [7/13] Test Package Operations - COMPLETED {"duration_ms":5234.56}
// If duration > 3000ms, investigate
```

---

### Step 7: Validate Data Integrity

#### Database Validation Queries

Run these queries to verify data consistency:

```sql
-- Check spool statuses were updated
SELECT COUNT(*) 
FROM weld_logs 
WHERE updated_at > DATE_SUB(NOW(), INTERVAL 1 HOUR)
AND spool_status IS NOT NULL;

-- Check NDE Matrix records
SELECT COUNT(*) 
FROM nde_matrices 
WHERE updated_at > DATE_SUB(NOW(), INTERVAL 1 HOUR);

-- Check test package updates
SELECT COUNT(*) 
FROM test_packages 
WHERE updated_at > DATE_SUB(NOW(), INTERVAL 1 HOUR);

-- Check paint follow up records
SELECT COUNT(*) 
FROM paint_follow_ups 
WHERE updated_at > DATE_SUB(NOW(), INTERVAL 1 HOUR);

-- Check for any null values that shouldn't be null
SELECT COUNT(*) 
FROM weld_logs 
WHERE line_number IS NOT NULL 
AND fluid_code IS NULL 
AND type_of_welds IS NOT NULL;
```

#### Comparison Test

If possible, maintain a separate environment with old system:

1. Apply same weld log changes to both
2. Compare resulting database states
3. Verify all related tables updated correctly

---

## Rollback Procedure

If issues occur, follow these steps immediately:

### Emergency Rollback (< 5 minutes)

```bash
# Step 1: Navigate to directory
cd /var/www/html/dev/app/Http/Controllers/SaveTrigger

# Step 2: Deactivate new system
mv weld_logs.php weld_logs_failed.php

# Step 3: Restore old system
mv weld_logs_old_system.php weld_logs.php

# Step 4: Clear caches
php artisan cache:clear
php artisan config:clear

# Step 5: Verify rollback
head -20 weld_logs.php
# Should show old system code

# Step 6: Test with a weld log save
# Check logs for old system format

# Step 7: Notify team
echo "ROLLBACK COMPLETED at $(date)" >> rollback.log
```

### Post-Rollback

1. Document the issue that caused rollback
2. Review logs from failed migration
3. Fix issues in new system
4. Re-test before attempting migration again

---

## Troubleshooting Common Issues

### Issue 1: Trigger Not Found

**Symptom**:
```
PHP Fatal error: Class 'App\Services\WeldLogTriggers\Triggers\SpoolStatusChangerTrigger' not found
```

**Solution**:
```bash
# Regenerate autoload files
composer dump-autoload

# Clear Laravel caches
php artisan cache:clear
php artisan config:clear

# Verify file exists
ls -la app/Services/WeldLogTriggers/Triggers/SpoolStatusChangerTrigger.php
```

---

### Issue 2: Triggers Execute in Wrong Order

**Symptom**: Logs show triggers executing out of order

**Solution**:
1. Check `getOrder()` methods in each trigger
2. Verify Registry registers triggers correctly
3. Check logs for "getTriggersInOrder" output

```php
// Debug in WeldLogTriggerManager
Log::info("Trigger execution order", [
    'order' => array_map(function($t) {
        return $t->getOrder() . ': ' . $t->getName();
    }, $triggers)
]);
```

---

### Issue 3: Performance Degradation

**Symptom**: New system slower than old system

**Solutions**:

1. **Check chunk sizes**:
```php
// In triggers using TransactionHelper
// Increase chunk size if too small
TransactionHelper::chunkTransaction(
    $collection,
    $callback,
    50, // Try 20, 50, 100
    1000 // 1ms delay
);
```

2. **Add database indexes**:
```sql
-- Example indexes
CREATE INDEX idx_line_number ON weld_logs(line_number);
CREATE INDEX idx_test_package ON weld_logs(test_package_no);
CREATE INDEX idx_iso_number ON weld_logs(iso_number);
```

3. **Check database connections**:
```bash
# Monitor active connections
mysql> SHOW PROCESSLIST;

# Check for slow queries
mysql> SHOW FULL PROCESSLIST;
```

---

### Issue 4: Memory Exhaustion

**Symptom**:
```
PHP Fatal error: Allowed memory size of 2147483648 bytes exhausted
```

**Solutions**:

1. **Check chunk processing**:
```php
// Ensure large collections are chunked
Model::chunk(100, function($chunk) {
    // Process
});
```

2. **Unset large variables**:
```php
$largeCollection = Model::all();
// Process...
unset($largeCollection); // Free memory
```

3. **Increase memory limit temporarily**:
```php
ini_set('memory_limit', '4G'); // Only for testing
```

---

### Issue 5: Deadlock Errors

**Symptom**:
```
Deadlock found when trying to get lock; try restarting transaction
```

**Solutions**:

1. **Verify ordering**:
```php
// Always order by id ASC
$query->orderBy('id', 'ASC')->get();
```

2. **Check TransactionHelper usage**:
```php
// Use retryTransaction for critical operations
TransactionHelper::retryTransaction(function() {
    // Your query
}, 5); // 5 retries
```

3. **Increase delays**:
```php
// In chunk processing
TransactionHelper::chunkTransaction(
    $collection,
    $callback,
    10,
    50000 // Increase to 50ms
);
```

---

## Validation Checklist

After migration, verify these scenarios:

### Scenario 1: New Weld Log Creation

- [ ] All triggers execute (check logs)
- [ ] Spool status set correctly
- [ ] Line lists updated
- [ ] NDE Matrix created
- [ ] Test package created
- [ ] Paint follow ups created
- [ ] No errors in logs

### Scenario 2: Spool Number Change

- [ ] Old spool status updated
- [ ] New spool status updated
- [ ] Both recorded in logs
- [ ] No orphaned records

### Scenario 3: Test Date Addition

- [ ] Request number generated
- [ ] Test table updated
- [ ] Weld log updated
- [ ] Pattern applied correctly
- [ ] Company code correct

### Scenario 4: Type of Joint Change

- [ ] Spool status set to 'Waiting'
- [ ] NDE Matrix updated
- [ ] Old type cleaned up (if applicable)
- [ ] New type created

### Scenario 5: Bulk Updates

- [ ] All records processed
- [ ] No memory issues
- [ ] No timeout errors
- [ ] Reasonable execution time

---

## Post-Migration Tasks

### Week 1: Intensive Monitoring

Daily tasks:
- [ ] Review error logs
- [ ] Check execution times
- [ ] Verify data integrity
- [ ] Monitor database performance
- [ ] Collect user feedback

### Week 2-4: Optimization

Based on week 1 data:
- [ ] Adjust chunk sizes if needed
- [ ] Add indexes for slow queries
- [ ] Optimize slow triggers
- [ ] Fine-tune memory limits
- [ ] Update documentation with findings

### Month 1: Cleanup

- [ ] Remove old system backup if stable
- [ ] Document any customizations
- [ ] Create runbook for common issues
- [ ] Train team on new system
- [ ] Archive migration logs

---

## Success Criteria

Migration is successful when:

✅ All 13 triggers execute correctly  
✅ No increase in error rate  
✅ Performance is equal or better  
✅ Data integrity maintained  
✅ Logs are clear and helpful  
✅ Team understands new system  
✅ No rollback needed after 1 week  

---

## Support and Contacts

### For Issues

1. Check this migration guide
2. Review main documentation: `weld-log-triggers-system.md`
3. Check Laravel logs: `storage/logs/laravel.log`
4. Contact development team

### Useful Commands

```bash
# View recent logs
tail -100 storage/logs/laravel.log

# Search for errors
grep "ERROR" storage/logs/laravel.log | tail -50

# Search for specific trigger
grep "Spool Status Changer" storage/logs/laravel.log

# Monitor in real-time
tail -f storage/logs/laravel.log | grep "WeldLog Trigger"

# Check file sizes
du -sh app/Services/WeldLogTriggers/

# Count lines of code
find app/Services/WeldLogTriggers -name "*.php" -exec wc -l {} + | sort -n
```

---

## Appendix: Line Count Comparison

### Old System
- **weld_logs.php**: 2,435 lines

### New System
- **Interface**: 63 lines
- **BaseTrigger**: 152 lines
- **Registry**: 117 lines
- **Manager**: 227 lines
- **13 Triggers**: ~150-400 lines each (~3,000 total)
- **Entry Point**: 150 lines
- **Total**: ~3,700 lines (more organized, more maintainable)

**Increase in lines**: ~52% more code, but:
- ✅ Much better organized
- ✅ Fully documented
- ✅ Unit testable
- ✅ Reusable
- ✅ Maintainable

---

**Document Version**: 1.0  
**Last Updated**: October 30, 2025  
**Migration Tested**: ✅ Yes (Development)  
**Production Ready**: ✅ Yes