Files
citrus-cms/resources/views/guide/notifications-guide.md
T
2026-04-28 21:15:09 +03:00

26 KiB
Raw Blame History

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

  1. First run: Scans entire table, collects IDs of all problematic records
  2. Subsequent runs: Checks only new records created after last notification
  3. 5-minute check: If run again within 5 minutes, it's skipped (performance optimization)
  4. 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 timestamp
  • shouldCheckNotification() - Check if 5 minutes have passed
  • getLastCheckTimestamp() - Get last check timestamp (null = first run)
  • isNotificationDuplicate() - Check for duplicate notifications
  • getAlreadyNotifiedIds() - 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

  1. Laravel Scheduler must be running (cron job)
  2. User roles must be assigned in Settings
  3. 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_s table → download field
  • NAKS Welder: naks_welders table → certificate field
  • Welding Equipment: welding_equipment table → download field
  • WPQ Follow-Up: welder_tests table → download field

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:

  1. Go to Settings → Specific Permissions → Notification Settings
  2. Assign roles to "Document Revision Changed"
  3. Open Document Revision module
  4. Change REV number of an existing record (0 → 1)
  5. Check notifications immediately after update

Action:

  • Update pdf_engineering file with new revision
  • Update pdf_spool_iso file 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_1
  • brand_name_1
  • thickness_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_logs table → report_file field
  • RT (Radiographic Testing): radiographic_tests table → report_file field
  • UT (Ultrasonic Testing): ultrasonic_tests table → report_file field
  • PT (Penetrant Testing): p_t_logs table → report_file field
  • MT (Magnetic Testing): magnetic_tests table → report_file field
  • HT (Hardness Testing): hardness_tests table → report_file field
  • PMI (Positive Material Identification): p_m_i_tests table → report_file field
  • PWHT (Post Weld Heat Treatment): p_w_h_t_s table → report_file field
  • Ferrite Testing: ferrits table → report_file field

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 minutes
  • notifications:check-repair-log-new-joint - Every 5 minutes
  • notifications:check-daily-repair-rate - Every 5 minutes
  • notifications:check-line-list-missing-data - Every 5 minutes
  • notifications:check-pdf-documents - Every 5 minutes
  • notifications:check-weldlog-certificate - Every 5 minutes
  • notifications:check-incoming-control-certificate - Every 5 minutes
  • notifications:check-nde-matrix-discrepancies - Every 5 minutes
  • notifications:check-ndt-calculation - Every 5 minutes
  • notifications:check-manage-ndt-unnecessary - Every 5 minutes
  • notifications:check-support-log-weldlog - Every 5 minutes
  • notifications:check-paint-system-values - Every 5 minutes
  • notifications:check-weldlog-test-dates - Every 5 minutes
  • notifications:check-ndt-request-overdue - Every 5 minutes
  • notifications:check-test-log-pdf - Every 5 minutes

🛠️ Troubleshooting

No Notifications Received?

  1. Check Role Assignment:

    Settings → Specific Permissions → Notification Settings
    Verify your role is assigned to the notification type
    
  2. Check Scheduler:

    # Verify cron is running
    ps aux | grep schedule:run
    
    # Check Notification logs
    tail -f storage/logs/notifications-YYYY-MM-DD.log
    
  3. 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-notifications for 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

Helper Functions:

  • app/Functions/notification-state-helper.php - State tracking functions
  • app/Functions/notification-helper.php - Notification sending functions

Commands (All updated for v4):

  • app/Console/Commands/NotificationCheckDeletedJoints.php
  • app/Console/Commands/NotificationCheckRepairLog.php
  • app/Console/Commands/NotificationCheckRepairRate.php
  • app/Console/Commands/NotificationCheckLineList.php
  • app/Console/Commands/NotificationCheckPDFDocuments.php
  • app/Console/Commands/NotificationCheckWeldlogCertificate.php
  • app/Console/Commands/NotificationCheckIncomingControlCertificate.php
  • app/Console/Commands/NotificationCheckNDEMatrixDiscrepancies.php
  • app/Console/Commands/NotificationCheckNDTCalculation.php
  • app/Console/Commands/NotificationCheckManageNDT.php
  • app/Console/Commands/NotificationCheckSupportLogWeldlog.php
  • app/Console/Commands/NotificationCheckPaintSystem.php
  • app/Console/Commands/NotificationCheckWeldlogTestDates.php
  • app/Console/Commands/NotificationCheckNDTRequestOverdue.php
  • app/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.php
  • app/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:

  1. Check Laravel logs: storage/logs/truncgil-**-**.log
  2. Review command output for specific errors
  3. Verify database connectivity and queue worker status
  4. Contact system administrator for permission issues

End of Guide