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:

# 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

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

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

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

# 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

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

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

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

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

# 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

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

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

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

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

// Ensure large collections are chunked
Model::chunk(100, function($chunk) {
    // Process
});

2. Unset large variables:

$largeCollection = Model::all();
// Process...
unset($largeCollection); // Free memory

3. Increase memory limit temporarily:

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:

// Always order by id ASC
$query->orderBy('id', 'ASC')->get();

2. Check TransactionHelper usage:

// Use retryTransaction for critical operations
TransactionHelper::retryTransaction(function() {
    // Your query
}, 5); // 5 retries

3. Increase delays:

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

# 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