26 KiB
🔔 Notification System Guide
Version: 4.0 (Real-Time System)
Last Updated: December 11, 2025
Branch: feature-notification-log-11122025
🆕 Version 4 - Real-Time Notification System
New Features (v4 - 2025-12-06):
- ✅ Real-time notifications: Runs every 5 minutes (maximum 5 minutes delay)
- ✅ Duplicate prevention: Same issue won't trigger duplicate notifications
- ✅ Incremental checking: First run scans all records, subsequent runs check only new records
- ✅ 90%+ performance improvement: Only new records are checked
- ✅ Synchronous execution: Compatible with cronjob
How It Works:
- First run: Scans entire table, collects IDs of all problematic records
- Subsequent runs: Checks only new records created after last notification
- 5-minute check: If run again within 5 minutes, it's skipped (performance optimization)
- Duplicate check: If notification exists for same issue and no new records, it's skipped
Helper Functions: app/Functions/notification-state-helper.php
getLastNotificationTime()- Get last notification timestampshouldCheckNotification()- Check if 5 minutes have passedgetLastCheckTimestamp()- Get last check timestamp (null = first run)isNotificationDuplicate()- Check for duplicate notificationsgetAlreadyNotifiedIds()- Get already notified record IDs
Performance:
| Scenario | Duration | Description |
|---|---|---|
| First run | 2-10 seconds | Entire table scanned |
| Within 5 min | < 0.1 seconds | Skip (no query) |
| After 5 min (no new) | 0.1-0.5 seconds | Only new records checked |
| New records exist | 0.1-1 seconds | Only new records checked |
📋 Quick Reference
| # | Notification Type | Trigger | Schedule | Permission Code |
|---|---|---|---|---|
| 1 | Deleted Joints Missing Comments | Scheduled | Every 5 min | notification_deleted_joint_missing_comment |
| 2 | Repair Logs Missing New Joint Number | Scheduled | Every 5 min | notification_repair_log_missing_new_joint |
| 3 | Daily Repair Rate Exceeds 12% | Scheduled | Every 5 min | notification_daily_repair_rate_high |
| 4 | Line List Missing Required Data | Scheduled | Every 5 min | notification_line_list_missing_data |
| 5 | WPS PDF Document Missing | Scheduled | Every 5 min | notification_wps_pdf_missing |
| 6 | NAKS Welder Certificate Missing | Scheduled | Every 5 min | notification_naks_welder_cert_missing |
| 7 | Welding Equipment PDF Missing | Scheduled | Every 5 min | notification_welding_equipment_pdf_missing |
| 8 | WPQR PDF Missing | Scheduled | Every 5 min | notification_wpq_followup_pdf_missing |
| 9 | Certificate Number 1-2 Missing | Scheduled | Every 5 min | notification_weldlog_certificate_missing |
| 10 | Incoming Control Certificate Missing | Scheduled | Every 5 min | notification_incoming_control_cert_missing |
| 11 | Welder ID Card Created | Event (Insert) | Immediate | notification_welder_id_card_created |
| 12 | Document Revision Changed | Event (Update) | Immediate | notification_document_revision_changed |
| 13 | NDE Matrix Not in Weldlog | Scheduled | Every 5 min | notification_nde_matrix_not_in_weldlog |
| 14 | Weldlog Not in Line List | Scheduled | Every 5 min | notification_weldlog_not_in_line_list |
| 15 | Line List NDT Missing | Scheduled | Every 5 min | notification_line_list_ndt_missing |
| 16 | NDT PMI Test Missing | Scheduled | Every 5 min | notification_ndt_pmi_missing |
| 17 | NDT FN Test Missing | Scheduled | Every 5 min | notification_ndt_fn_missing |
| 18 | Unnecessary NDT Requests | Scheduled | Every 5 min | notification_manage_ndt_unnecessary |
| 19 | Support Log Missing in Weldlog | Scheduled | Every 5 min | notification_support_log_missing_in_weldlog |
| 20 | Paint System Missing | Scheduled | Every 5 min | notification_paint_system_incomplete |
| 21 | Overall Repair Rate Exceeds 5% | Scheduled | Every 5 min | notification_overall_repair_rate_high |
| 22 | Weldlog Test Date Before Welding Date | Scheduled | Every 5 min | notification_weldlog_test_date_invalid |
| 23 | NDE Matrix Empty Row - NDT Assignment Required | Scheduled | Every 5 min | notification_nde_matrix_empty_row |
| 24 | NDT Request Overdue (10+ Days) | Scheduled | Every 5 min | notification_ndt_request_overdue |
| 25 | VT Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_vt |
| 26 | RT Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_rt |
| 27 | UT Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_ut |
| 28 | PT Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_pt |
| 29 | MT Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_mt |
| 30 | HT Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_ht |
| 31 | PMI Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_pmi |
| 32 | PWHT Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_pwht |
| 33 | Ferrite Test - PDF Report Missing | Scheduled | Every 5 min | notification_test_log_pdf_missing_ferrite |
🚀 Getting Started
Prerequisites
- Laravel Scheduler must be running (cron job)
- User roles must be assigned in Settings
- Helper functions loaded (
app/Functions/notification-state-helper.php)
System Status
- ✅ Real-time notifications (every 5 minutes)
- ✅ Duplicate prevention active
- ✅ Incremental checking (only new records)
- ✅ First run scans all records, subsequent runs check only new data
Testing Notifications
Step 1: Configure Permissions
Navigate to: Settings → Specific Permissions → Notification Settings
Assign your role (e.g., QC Manager) to the notification types you want to receive
Step 2: Trigger Manually (for testing)
# Test a specific notification
php artisan notifications:check-deleted-joints
# Test all NDT reminders
php artisan notifications:check-ndt
# Test repair rate check
php artisan notifications:check-daily-repair-rate
Step 3: Check Results
- Click the bell icon (🔔) in the header
- Or visit:
/admin/types/my-notifications
📦 Notification Types (Detailed)
1️⃣ Deleted Joints Missing Comments
When: Joints are deleted without explanation
Why: Quality tracking requires deletion reasons
Command: notifications:check-deleted-joints
What to check:
SELECT * FROM deleted_joints
WHERE (comment IS NULL OR comment = '')
LIMIT 50
Message Example:
Deleted joint W-123 (Spool: SP-001, ISO: ISO-456) has no comment.
Please add deletion reason.
Fix: Add a comment in the Deleted Joints page explaining why it was removed.
2️⃣ Repair Logs Missing New Joint Number
When: Repairs completed but new joint number not assigned
Why: Tracking requires new joint identification after repair
Command: notifications:check-repair-log-new-joint
What to check:
SELECT * FROM repair_logs
WHERE (new_joint_no IS NULL OR new_joint_no = '')
LIMIT 50
Message Example:
Repair log for joint W-OLD (Spool: SP-002, ISO: ISO-789) has no new joint number assigned.
Fix: Assign the new joint number in Repair Log module.
3️⃣ Daily Repair Rate Exceeds 12%
When: Daily repair rate is too high (quality issue)
Why: Alert QC teams when repair rate exceeds acceptable threshold
Command: notifications:check-daily-repair-rate
Calculation:
Repair Rate = (Today's Repairs / Today's Welds) × 100
Alert if > 12%
Message Example:
Daily repair rate is 15.2% (19 repairs out of 125 welds).
Please investigate quality issues.
Fix: Investigate root cause - check welder qualifications, materials, procedures.
4️⃣ Line List Missing Required Data
When: Line List entries missing critical fields
Why: Incomplete line data causes downstream issues
Command: notifications:check-line-list-missing-data
Required Fields:
- Category/Group
- NDT Ratio
- Pressure
- Temperature
- Test Type
- Test Media
Message Example:
Line ABC-123 (used in weld logs) is missing required data: NDT Ratio, Test Type
Fix: Complete the missing fields in Line List module.
5️⃣-8️⃣ PDF Documents Missing
When: Required PDFs not uploaded
Why: Documentation compliance
Command: notifications:check-pdf-documents
Checks:
- WPS:
w_p_stable →downloadfield - NAKS Welder:
naks_welderstable →certificatefield - Welding Equipment:
welding_equipmenttable →downloadfield - WPQ Follow-Up:
welder_teststable →downloadfield
Message Example:
WPS WPS-001 is missing PDF document. Please upload procedure file.
Fix: Upload the missing PDF in respective module.
9️⃣ Certificate Number 1-2 Missing
When: Welding completed but certificates not recorded
Why: Certificate tracking for quality assurance
Command: notifications:check-weldlog-certificate
Condition:
welding_date is filled
AND (certificate_number_of_1 is empty OR certificate_number_of_2 is empty)
Message Example:
Weldlog joint W-456 is missing: Certificate No 1, Certificate No 2
(welded on 2025-12-06)
Fix: Add certificate numbers in Weldlog module.
🔟 Incoming Control Certificate Missing
When: Materials received but certificates not logged
Why: Material traceability requirement
Command: notifications:check-incoming-control-certificate
Condition:
Record exists (created_at is not null)
AND certificate_no is empty
Message Example:
Incoming Control record MAT-789 is missing Certificate No
Fix: Add certificate number in Incoming Control module.
1️⃣1️⃣ Welder ID Card Created (Event-Based)
When: New welder added to NAKS Welder database
Why: Informational - notify teams about new qualified welder
Trigger: Automatic on insert to naks_welders table
Message Example:
New Welder ID Card created for John Smith (Welder ID: W-1234)
Action: Review the Welder ID Card page to verify information.
1️⃣2️⃣ Document Revision Changed (Event-Based)
When: REV number is updated in Document Revision module
Why: PDF files must be updated when revision changes
Trigger: Automatic on update to document_revisions table
Condition:
revision_no field changed (e.g., "0" → "1")
AND oldValue is not empty (not initial creation)
Message Example:
Document Revision REV changed from 0 to 1 for Drawing ABC-123.
Please update PDF files.
Link: /admin/types/document-revision?id={id}
How to Test:
- Go to Settings → Specific Permissions → Notification Settings
- Assign roles to "Document Revision Changed"
- Open Document Revision module
- Change REV number of an existing record (0 → 1)
- Check notifications immediately after update
Action:
- Update
pdf_engineeringfile with new revision - Update
pdf_spool_isofile if applicable - Ensure all PDF files reflect the new REV number
1️⃣3️⃣ NDE Matrix Not in Weldlog
When: NDE Matrix contains line numbers not found in Weldlog
Why: Data consistency - NDE Matrix should reflect actual welding work
Command: notifications:check-nde-matrix-discrepancies
Check:
NDE Matrix has line number
BUT
Weldlog does NOT have matching line_number
Message Example:
NDE Matrix line "ABC-123" (Project: P001, Joint Type: BW) not found in Weldlog
Link: /admin/types/nde-matrix?line={line}
1️⃣4️⃣ Weldlog Not in Line List
When: Welding performed on lines not defined in Line List
Why: All welded lines must be predefined in Line List
Command: notifications:check-nde-matrix-discrepancies
Check:
Weldlog has line_number (with welding_date filled)
BUT
Line List does NOT have matching line_no
Message Example:
Weldlog line "DEF-456" (Project: P002, ISO: ISO-789) not found in Line List
Link: /admin/types/weldlog?line_number={line_number}
Action: Add the line to Line List module with complete specifications.
1️⃣5️⃣ Line List NDT Missing
When: Line List entry lacks NDT ratio but is used in welding
Why: NDT ratio must be defined before welding begins
Command: notifications:check-nde-matrix-discrepancies
Check:
Line List entry exists
AND used in Weldlog (welding_date is not null)
BUT
Line List.ndt is empty or 0
Message Example:
Line List entry "GHI-789" is missing NDT ratio (used in Weldlog)
Link: /admin/types/line-list?line_no={line_no}
Action: Update Line List with correct NDT percentage.
1️⃣6️⃣ NDT PMI Test Missing
When: SS or CS+SS materials but PMI test request not created
Why: PMI (Positive Material Identification) required for stainless steel materials
Command: notifications:check-ndt-calculation
Condition:
welding_date is filled
AND (Material Grade 1 or 2 = SS (11, 8, 9) OR CS+SS combination)
AND pmi_request_no is empty
Message Example:
Joint W-123 (ISO: ISO-456) has SS material but PMI test request not created
Link: /admin/types/weldlog?id={id}
Action: Create PMI test request in Weldlog module.
1️⃣7️⃣ NDT FN Test Missing
When: SS materials but FN (Ferrite) test request not created
Why: Ferrite number testing required for stainless steel welds
Command: notifications:check-ndt-calculation
Condition:
welding_date is filled
AND (Material Grade 1 or 2 = SS (11, 8, 9))
AND ferrite_request_no is empty
Message Example:
Joint W-456 (ISO: ISO-789) has SS material but FN (Ferrite) test request not created
Link: /admin/types/weldlog?id={id}
Action: Create FN (Ferrite) test request in Weldlog module.
1️⃣8️⃣ Manage NDT Unnecessary Request
When: Manual NDT request created but NDE Matrix shows 0% ratio
Why: Prevent unnecessary testing costs and time
Command: notifications:check-manage-ndt-unnecessary
Condition:
welding_date is filled
AND test_request_no is filled (RT/UT/PT/MT)
AND (
NDE Matrix ratio for that test type = 0% OR NULL
OR NDE Matrix entry doesn't exist for line/joint type
)
Message Example:
Unnecessary RT test request for Joint W-987 (ISO: ISO-901, Line: ABC-123, Request: RT-000244)
- NDE Matrix ratio is 0%
Link: /admin/types/weldlog?id={id}
Action:
- Review NDE Matrix to verify if test is actually needed
- If ratio should be > 0%, update NDE Matrix
- If test is unnecessary, cancel the request in Manage NDT
- This helps avoid wasting resources on unneeded tests
Test Types Checked:
- RT (Radiographic Testing)
- UT (Ultrasonic Testing)
- PT (Penetrant Testing)
- MT (Magnetic Testing)
1️⃣9️⃣ Support Log Missing in Weldlog
When: Support Log entry marked as welded but not found in Weldlog
Why: Ensure all welded supports are properly recorded in Weldlog
Command: notifications:check-support-log-weldlog
Condition:
Support Log weld_or_assembled_date is filled (not NULL, not empty, not 0000-00-00)
AND support_code is not empty
AND support_code NOT found in Weldlog (element_code_1 OR element_code_2)
Message Example:
Support Code FE11-A-1028 (Line: ABC-123, Materials: Ст3пс, Weld Date: 2024-09-11) is welded
in Support Log but not found in Weldlog (ID Code 1 or ID Code 2). Please add to Weldlog.
Link: /admin/types/support?id={id}
Action:
- Verify if the support was actually welded
- If welded, add the corresponding entry to Weldlog with the Support Code
- If not welded yet, update Support Log status
- This ensures accurate tracking of welded supports
Fields Checked in Weldlog:
element_code_1(ID Code 1)element_code_2(ID Code 2)
2️⃣0️⃣ Paint System Missing
When: Paint System exists but customer-agreed paint values are missing
Why: Complete paint specifications required for Line List entries
Command: notifications:check-paint-system-values
Condition:
Paint System exists for paint_cycle
AND (
primer_coat_name_1 is empty OR
brand_name_1 is empty OR
thickness_1 is 0 or NULL
)
Message Example:
Paint System "А" (used by Lines: DEF-456, GHI-789...) has missing customer-agreed values:
Primer Coat Name 1, Thickness 1. Please fill in Paint System details.
Link: /admin/types/paint-system?id={id}
Action:
- Fill in the missing paint values in Paint System:
- Primer Coat Name (Layer 1)
- Brand Name (Layer 1)
- Thickness (Layer 1)
- These are customer-agreed values from Line List requirements
Required Fields (Layer 1):
primer_coat_name_1brand_name_1thickness_1
2️⃣1️⃣ Overall Repair Rate Exceeds 5%
When: Overall repair rate is too high (quality issue)
Why: Alert QC teams when overall repair rate exceeds acceptable threshold
Command: notifications:check-daily-repair-rate
Calculation:
Overall Repair Rate = (Total Repairs / Total Welds) × 100
Alert if > 5%
Message Example:
Overall repair rate is 6.8% (150 repairs out of 2200 welds).
Please investigate quality issues.
Fix: Investigate root cause - check welder qualifications, materials, procedures, and overall quality control processes.
2️⃣2️⃣ Weldlog Test Date Before Welding Date
When: Test date is recorded before welding date (logical error)
Why: Tests cannot be performed before welding is completed
Command: notifications:check-weldlog-test-dates
Condition:
welding_date is filled
AND test_date (any test type) < welding_date
Message Example:
Weldlog joint W-789 (ISO: ISO-012) has test date (2025-12-05) before welding date (2025-12-10).
Please verify dates.
Link: /admin/types/weldlog?id={id}
Action:
- Verify and correct test dates
- Ensure test dates are after welding date
- Update test records with correct dates
2️⃣3️⃣ NDE Matrix Empty Row - NDT Assignment Required
When: NDE Matrix has empty rows without NDT assignments
Why: All NDE Matrix rows must have proper NDT assignments
Command: notifications:check-nde-matrix-discrepancies
Condition:
NDE Matrix row exists
AND no NDT test assignments (RT, UT, PT, MT, etc.) are filled
Message Example:
NDE Matrix has empty row for Line ABC-123 (Project: P001, Joint Type: BW).
NDT assignment required.
Link: /admin/types/nde-matrix?line={line}
Action:
- Fill in appropriate NDT test assignments for the row
- Ensure all required tests are assigned based on material and joint type
2️⃣4️⃣ NDT Request Overdue (10+ Days)
When: NDT test request created but not completed within 10 days
Why: Ensure timely completion of NDT tests
Command: notifications:check-ndt-request-overdue
Condition:
test_request_no is filled
AND request_date is filled
AND (test_date is empty OR test_date is NULL)
AND request_date < (NOW() - 10 days)
Message Example:
NDT Request RT-000123 (Joint W-456, ISO: ISO-789) is overdue.
Request date: 2025-11-25 (15 days ago). Please complete the test.
Link: /admin/types/weldlog?id={id}
Action:
- Complete the NDT test and update test_date
- If test is delayed, update request_date or cancel if unnecessary
2️⃣5️⃣-3️⃣3️⃣ Test Log PDF Reports Missing
When: Test completed but PDF report not uploaded
Why: Documentation compliance - all test results must have PDF reports
Command: notifications:check-test-log-pdf
Test Types Checked:
- VT (Visual Testing):
v_t_logstable →report_filefield - RT (Radiographic Testing):
radiographic_teststable →report_filefield - UT (Ultrasonic Testing):
ultrasonic_teststable →report_filefield - PT (Penetrant Testing):
p_t_logstable →report_filefield - MT (Magnetic Testing):
magnetic_teststable →report_filefield - HT (Hardness Testing):
hardness_teststable →report_filefield - PMI (Positive Material Identification):
p_m_i_teststable →report_filefield - PWHT (Post Weld Heat Treatment):
p_w_h_t_stable →report_filefield - Ferrite Testing:
ferritstable →report_filefield
Condition:
Test result is filled (vt_result, rt_result, ut_result, etc.)
AND report_file is empty or NULL
Message Example:
VT Test for Joint W-123 (ISO: ISO-456) is completed but PDF report is missing.
Please upload test report.
Link: /admin/types/{test-type}?id={id}
Action: Upload the PDF test report in the respective test log module.
⏰ Schedule Overview
New System (v4): All notification checks run every 5 minutes.
Features:
- ✅ Real-time notifications (maximum 5 minutes delay)
- ✅ First run scans entire table
- ✅ Subsequent runs check only new records
- ✅ No duplicate notifications
- ✅ 90%+ performance improvement
All Commands:
notifications:check-deleted-joints- Every 5 minutesnotifications:check-repair-log-new-joint- Every 5 minutesnotifications:check-daily-repair-rate- Every 5 minutesnotifications:check-line-list-missing-data- Every 5 minutesnotifications:check-pdf-documents- Every 5 minutesnotifications:check-weldlog-certificate- Every 5 minutesnotifications:check-incoming-control-certificate- Every 5 minutesnotifications:check-nde-matrix-discrepancies- Every 5 minutesnotifications:check-ndt-calculation- Every 5 minutesnotifications:check-manage-ndt-unnecessary- Every 5 minutesnotifications:check-support-log-weldlog- Every 5 minutesnotifications:check-paint-system-values- Every 5 minutesnotifications:check-weldlog-test-dates- Every 5 minutesnotifications:check-ndt-request-overdue- Every 5 minutesnotifications:check-test-log-pdf- Every 5 minutes
🛠️ Troubleshooting
No Notifications Received?
-
Check Role Assignment:
Settings → Specific Permissions → Notification Settings Verify your role is assigned to the notification type -
Check Scheduler:
# Verify cron is running ps aux | grep schedule:run # Check Notification logs tail -f storage/logs/notifications-YYYY-MM-DD.log -
Check Data:
# Manually run command to see results php artisan notifications:check-deleted-joints # Should output: "Sent X notifications..."
Notifications Not Clearing?
- Click on notification to mark as read
- Use "Mark All as Read" button in dropdown
- Visit
/admin/types/my-notificationsfor bulk actions
Duplicate Notifications?
- ✅ No duplicate notifications in new system
- System won't send duplicate notifications for the same issue
- When new records are added, notification is updated (additive approach)
- When issue is resolved, notification automatically stops
📊 Database Schema
notifications table
- id (primary key)
- user_id (foreign key → users)
- code (notification type code)
- title
- message
- link (URL to relevant page)
- is_read (boolean)
- created_at
- updated_at
Indexes
- user_id
- is_read
- created_at
- code
🔗 Related Files
Helper Functions:
app/Functions/notification-state-helper.php- State tracking functionsapp/Functions/notification-helper.php- Notification sending functions
Commands (All updated for v4):
app/Console/Commands/NotificationCheckDeletedJoints.phpapp/Console/Commands/NotificationCheckRepairLog.phpapp/Console/Commands/NotificationCheckRepairRate.phpapp/Console/Commands/NotificationCheckLineList.phpapp/Console/Commands/NotificationCheckPDFDocuments.phpapp/Console/Commands/NotificationCheckWeldlogCertificate.phpapp/Console/Commands/NotificationCheckIncomingControlCertificate.phpapp/Console/Commands/NotificationCheckNDEMatrixDiscrepancies.phpapp/Console/Commands/NotificationCheckNDTCalculation.phpapp/Console/Commands/NotificationCheckManageNDT.phpapp/Console/Commands/NotificationCheckSupportLogWeldlog.phpapp/Console/Commands/NotificationCheckPaintSystem.phpapp/Console/Commands/NotificationCheckWeldlogTestDates.phpapp/Console/Commands/NotificationCheckNDTRequestOverdue.phpapp/Console/Commands/NotificationCheckTestLogPDF.php
Schedule:
app/Console/Kernel.php- All commands run every 5 minutes
Documentation:
notification-testing-guide.md- Testing guide (detailed test scenarios)
Controllers:
app/Http/Controllers/NotificationController.phpapp/Http/Controllers/AdminController.php(line 1236-1244 for Welder ID Card)
Views:
resources/views/admin/master.blade.php(Bell icon UI)resources/views/admin/type/my-notifications.blade.php(Full page)
Config:
app/Console/Kernel.php(Scheduler registration)resources/views/admin/type/settings/specific-permissions.blade.php(Permissions)
📝 Notes
- All notification messages are in English
- Notifications are user-specific based on role assignments
- Notification polling happens every 60 seconds in frontend
- Commands include performance limits (typically 50-100 records per run)
- Caching is used for unread counts to optimize performance
🆘 Support
For technical support or questions:
- Check Laravel logs:
storage/logs/truncgil-**-**.log - Review command output for specific errors
- Verify database connectivity and queue worker status
- Contact system administrator for permission issues
End of Guide