citrus-cms/resources/views/guide/isNowAuth-logging-guide.md

isNowAuth Logging System Guide / isNowAuth Loglama Sistemi Kılavuzu

What This Logging System Does / Bu Loglama Sistemi Ne Yapar

English

Purpose and Importance:

This logging system provides complete transparency into the authorization decision-making process for weld log updates. Every step of the validation process is recorded, allowing developers and administrators to:

• Understand Why Updates Are Blocked or Allowed: When a user tries to update a weld log and the system blocks it, logs show exactly which rule prevented the update
• Track User Actions: See who attempted to update what data, when, and what the outcome was
• Debug Authorization Issues: Quickly identify if a problem is related to welder field restrictions, time limits, or user permission levels
• Audit Trail: Maintain a complete history of all authorization checks for compliance and security purposes
• Performance Monitoring: Identify if authorization checks are taking too long or causing bottlenecks

What Gets Logged:

• Every authorization check attempt with request details
• Current database values vs. requested new values
• Field-by-field analysis of what's being updated
• User information (ID, level, permissions)
• Time calculations and limit comparisons
• The final decision (allow/deny) with clear reasoning
• Special cases like real_welder updates and level-based exceptions

Who Should Use These Logs:

• Developers: For debugging authorization logic and understanding system behavior
• System Administrators: For troubleshooting user complaints about blocked updates
• QA Engineers: For verifying that authorization rules work as expected
• Compliance Officers: For auditing data modification attempts
• Support Teams: For explaining to users why their update was rejected

When to Check These Logs:

• When users report they cannot update weld logs
• When investigating suspicious or unauthorized update attempts
• When testing new authorization rules or modifications
• When debugging time limit issues
• When validating that welder field protections are working correctly

---

Türkçe

Amaç ve Önemi:

Bu loglama sistemi, kaynak kaydı güncellemeleri için yetkilendirme karar verme sürecinde tam şeffaflık sağlar. Doğrulama sürecinin her adımı kaydedilir ve geliştiriciler ile yöneticilerin şunları yapmasına olanak tanır:

• Güncellemelerin Neden Engellendiğini veya İzin Verildiğini Anlamak: Bir kullanıcı kaynak kaydını güncellemeye çalıştığında ve sistem engellediğinde, loglar hangi kuralın güncellemeyi engellediğini tam olarak gösterir
• Kullanıcı Eylemlerini Takip Etmek: Kimin, hangi veriyi, ne zaman güncellemeye çalıştığını ve sonucun ne olduğunu görmek
• Yetkilendirme Sorunlarını Gidermek: Bir sorunun kaynakçı alanı kısıtlamaları, zaman limitleri veya kullanıcı yetki seviyeleriyle ilgili olup olmadığını hızlıca belirlemek
• Denetim İzi: Uyumluluk ve güvenlik amaçları için tüm yetkilendirme kontrollerinin tam geçmişini tutmak
• Performans İzleme: Yetkilendirme kontrollerinin çok uzun sürdüğünü veya darboğazlara neden olduğunu tespit etmek

Neler Loglanır:

• Her yetkilendirme kontrol denemesi ile istek detayları
• Mevcut veritabanı değerleri ile istenen yeni değerlerin karşılaştırması
• Neyin güncellendiğinin alan bazında analizi
• Kullanıcı bilgileri (ID, seviye, yetkiler)
• Zaman hesaplamaları ve limit karşılaştırmaları
• Net gerekçesiyle birlikte final karar (izin ver/engelle)
• real_welder güncellemeleri ve seviye bazlı istisnalar gibi özel durumlar

Bu Logları Kimler Kullanmalı:

• Geliştiriciler: Yetkilendirme mantığını debug etmek ve sistem davranışını anlamak için
• Sistem Yöneticileri: Engellenen güncellemeler hakkında kullanıcı şikayetlerini gidermek için
• QA Mühendisleri: Yetkilendirme kurallarının beklendiği gibi çalıştığını doğrulamak için
• Uyumluluk Görevlileri: Veri değiştirme denemelerini denetlemek için
• Destek Ekipleri: Kullanıcılara neden güncellemelerinin reddedildiğini açıklamak için

Bu Loglar Ne Zaman Kontrol Edilmeli:

• Kullanıcılar kaynak kayıtlarını güncelleyemediklerini bildirdiğinde
• Şüpheli veya yetkisiz güncelleme denemelerini araştırırken
• Yeni yetkilendirme kurallarını veya değişiklikleri test ederken
• Zaman limiti sorunlarını debug ederken
• Kaynakçı alanı korumalarının doğru çalıştığını doğrularken

---

English Version

Overview

The isNowAuth function in AdminController.php is responsible for authorization checks when updating weld log records. This guide explains the comprehensive logging system implemented for debugging and monitoring purposes.

Log Key Structure

All logs follow a standardized key format:

{function_name}.{section}.{detail}

This hierarchical structure makes it easy to filter and trace specific operations.

Main Functions and Their Logs

1. isNowAuth Function

The primary authorization function that checks various conditions before allowing weld log updates.

Log Keys:

isNowAuth.start

• Purpose: Log the initial request parameters
• Data Logged:
  • table_name: The target table name
  • request_key: The primary key of the record being updated
  • request_values: The new values to be updated
• When: At the very beginning of the function
• Example:

{
  "table_name": "weld_logs",
  "request_key": {"id": 123},
  "request_values": {"welder_1": "JOHN", "welder_2": "MIKE"}
}

isNowAuth.query.result

• Purpose: Log the database query result
• Data Logged:
  • query_found: Boolean indicating if record was found
  • query_id: The ID of the found record
• When: After querying the database for the existing record

isNowAuth.welder_check.existing_values

• Purpose: Log current welder field values from database
• Data Logged:
  • welder_1: Current welder_1 value
  • welder_2: Current welder_2 value
  • welder_1_empty: Boolean check if welder_1 is empty
  • welder_2_empty: Boolean check if welder_2 is empty
• When: When checking welder fields in existing record

isNowAuth.welder_check.new_values

• Purpose: Log the new welder values from the update request
• Data Logged:
  • welder_1_isset: Boolean check if welder_1 is in update
  • welder_2_isset: Boolean check if welder_2 is in update
  • welder_1: New welder_1 value (if any)
  • welder_2: New welder_2 value (if any)
• When: When processing new values from the request

isNowAuth.welder_check.blocked

• Purpose: Log when a welder field update is blocked
• Data Logged:
  • reason: Why it was blocked (e.g., "welder_1_already_filled")
  • existing_value: The current value in database
  • new_value: The attempted new value
• When: When trying to update a welder field that's already filled
• Action: Returns false (blocks the update)

isNowAuth.real_welder_check.status

• Purpose: Log whether only real_welder fields are being updated
• Data Logged:
  • is_only_real_welder_update: Boolean result
• When: After checking if the update is only for real_welder_1 or real_welder_2

isNowAuth.real_welder_check.welder_status

• Purpose: Log welder field status for real_welder updates
• Data Logged:
  • welder_1_value: Current welder_1 value
  • welder_2_value: Current welder_2 value
  • welder_fields_filled: Boolean if any welder field is filled
• When: During real_welder update validation

isNowAuth.real_welder_check.decision

• Purpose: Log the decision for real_welder updates
• Data Logged:
  • action: "allow_without_time_limit" or "continue_to_time_check"
  • reason: "welder_fields_empty" or "welder_fields_filled"
• When: After deciding whether to bypass time limit for real_welder updates

isNowAuth.level_check.status

• Purpose: Log user level check status
• Data Logged:
  • user_id: Current user's ID
  • user_level: Current user's level
  • allowed_levels: Array of levels that bypass time limit
  • level_in_allowed: Boolean if user is in exception list
• When: Checking if user level has special privileges

isNowAuth.level_check.decision

• Purpose: Log decision based on user level
• Data Logged:
  • action: "allow"
  • reason: "user_level_in_exception_list"
  • user_level: The user's level
• When: When user level grants exception from time limit
• Action: Returns true (allows the update)

isNowAuth.time_limit_check.initiating

• Purpose: Log when time limit check is about to be performed
• Data Logged:
  • user_level: User's level
  • welding_date: The welding date from record
  • created_at: Record creation timestamp
• When: Before calling checkWeldLogTimeLimit function

isNowAuth.decision

• Purpose: Log final authorization decisions
• Data Logged:
  • action: "allow" or "deny"
  • reason: Description of why decision was made
• When: Various exit points of the function
• Possible Reasons:
  • "welding_date_empty": No welding date, update allowed
  • "not_weld_logs_table": Different table, no special rules

2. isOnlyRealWelderFieldsUpdate Function

Helper function to determine if only real_welder fields are being updated.

Log Keys:

isOnlyRealWelderFieldsUpdate.analysis

• Purpose: Log detailed analysis of fields being updated
• Data Logged:
  • updating_fields: Array of all fields being updated
  • has_real_welder_update: Boolean if any real_welder field is included
  • other_fields: Array of non-real_welder fields being updated
  • is_only_real_welder_update: Boolean final result
  • real_welder_field_values: Object with real_welder_1 and real_welder_2 values
• When: Every time this function is called
• Example:

{
  "updating_fields": ["real_welder_1", "real_welder_2"],
  "has_real_welder_update": true,
  "other_fields": [],
  "is_only_real_welder_update": true,
  "real_welder_field_values": {
    "real_welder_1": "JOHN",
    "real_welder_2": "MIKE"
  }
}

3. checkWeldLogTimeLimit Function

Validates if the update is within the allowed time limit.

Log Keys:

checkWeldLogTimeLimit.start

• Purpose: Log function initialization
• Data Logged:
  • query_id: Record ID being checked
  • created_at: Record creation timestamp
  • created_at_is_null: Boolean check
• When: At function start

checkWeldLogTimeLimit.calculation

• Purpose: Log time difference calculations
• Data Logged:
  • created_at: Record creation time
  • current_time: Current timestamp
  • allowed_hour_limit: Maximum hours allowed from settings
  • actual_hour_difference: Calculated hour difference
  • within_limit: Boolean if within allowed time
• When: After calculating time differences
• Example:

{
  "created_at": "2024-10-16 08:00:00",
  "current_time": "2024-10-16 10:30:00",
  "allowed_hour_limit": 4,
  "actual_hour_difference": 2.5,
  "within_limit": true
}

checkWeldLogTimeLimit.decision

• Purpose: Log the final time limit decision
• Data Logged:
  • action: "allow" or "deny"
  • reason: Explanation of decision
  • hour_difference: Actual hours passed (for allow)
  • allowed_limit: Maximum allowed hours (for allow)
  • exceeded_by: Hours over the limit (for deny only)
• When: Before returning the decision
• Possible Reasons:
  • "within_time_limit": Update allowed
  • "exceeded_time_limit": Update blocked
  • "created_at_is_null": No creation date, blocked

How to Use These Logs for Debugging

1. Monitor All isNowAuth Operations

tail -f storage/logs/laravel.log | grep "isNowAuth"

2. Track Specific Authorization Failures

tail -f storage/logs/laravel.log | grep "isNowAuth.welder_check.blocked"

3. Monitor Time Limit Violations

tail -f storage/logs/laravel.log | grep "checkWeldLogTimeLimit.decision" | grep "deny"

4. Track Real Welder Updates

tail -f storage/logs/laravel.log | grep "isNowAuth.real_welder_check"

5. Monitor User Level Exceptions

tail -f storage/logs/laravel.log | grep "isNowAuth.level_check"

Common Debugging Scenarios

Scenario 1: Update is Blocked - Find Out Why

1. Search for the record ID in logs:

grep "query_id.*123" storage/logs/laravel.log | grep isNowAuth

2. Look for decision logs:

grep "isNowAuth.decision\|isNowAuth.welder_check.blocked" storage/logs/laravel.log

Scenario 2: Time Limit Issues

1. Check time calculations:

grep "checkWeldLogTimeLimit.calculation" storage/logs/laravel.log | tail -1

2. Review the decision:

grep "checkWeldLogTimeLimit.decision" storage/logs/laravel.log | tail -1

Scenario 3: Real Welder Update Problems

1. Check if it's recognized as real_welder only update:

grep "isOnlyRealWelderFieldsUpdate.analysis" storage/logs/laravel.log | tail -1

2. Check the welder field status:

grep "isNowAuth.real_welder_check.welder_status" storage/logs/laravel.log | tail -1

Log Levels

All logs use Log::debug() which means:

• They appear in the log file only when APP_DEBUG=true in .env
• They don't appear in production by default (for performance)
• They use the "DEBUG" level in log entries

Best Practices

1. Always check logs in sequence: Follow the flow from isNowAuth.start to final decision
2. Use grep with context: Add -A 5 -B 5 to see surrounding logs
3. Filter by timestamp: When debugging specific issues, filter by time range
4. Save important log sections: Export relevant logs for documentation
5. Monitor production carefully: Only enable debug logs temporarily in production

Performance Considerations

• Debug logs are only written when APP_DEBUG=true
• Each authorization check generates 5-15 log entries
• Log file rotation should be configured properly
• Consider using log analysis tools for high-volume systems

---

Türkçe Versiyon

Genel Bakış

AdminController.php dosyasındaki isNowAuth fonksiyonu, kaynak kaydı güncellenirken yetkilendirme kontrollerinden sorumludur. Bu kılavuz, hata ayıklama ve izleme amaçlı olarak uygulanan kapsamlı loglama sistemini açıklar.

Log Anahtar Yapısı

Tüm loglar standart bir anahtar formatı takip eder:

{fonksiyon_adi}.{bolum}.{detay}

Bu hiyerarşik yapı, belirli işlemleri filtrelemeyi ve izlemeyi kolaylaştırır.

Ana Fonksiyonlar ve Logları

1. isNowAuth Fonksiyonu

Kaynak kaydı güncellemelerine izin vermeden önce çeşitli koşulları kontrol eden birincil yetkilendirme fonksiyonu.

Log Anahtarları:

isNowAuth.start

• Amaç: Başlangıç istek parametrelerini logla
• Loglanan Veriler:
  • table_name: Hedef tablo adı
  • request_key: Güncellenen kaydın birincil anahtarı
  • request_values: Güncellenecek yeni değerler
• Ne Zaman: Fonksiyonun en başında
• Örnek:

{
  "table_name": "weld_logs",
  "request_key": {"id": 123},
  "request_values": {"welder_1": "JOHN", "welder_2": "MIKE"}
}

isNowAuth.query.result

• Amaç: Veritabanı sorgu sonucunu logla
• Loglanan Veriler:
  • query_found: Kayıt bulunup bulunmadığını gösteren boolean
  • query_id: Bulunan kaydın ID'si
• Ne Zaman: Mevcut kayıt için veritabanı sorgulandıktan sonra

isNowAuth.welder_check.existing_values

• Amaç: Veritabanındaki mevcut kaynakçı alan değerlerini logla
• Loglanan Veriler:
  • welder_1: Mevcut welder_1 değeri
  • welder_2: Mevcut welder_2 değeri
  • welder_1_empty: welder_1'in boş olup olmadığını gösteren boolean
  • welder_2_empty: welder_2'nin boş olup olmadığını gösteren boolean
• Ne Zaman: Mevcut kayıttaki kaynakçı alanları kontrol edilirken

isNowAuth.welder_check.new_values

• Amaç: Güncelleme isteğindeki yeni kaynakçı değerlerini logla
• Loglanan Veriler:
  • welder_1_isset: welder_1'in güncellemede olup olmadığını gösteren boolean
  • welder_2_isset: welder_2'nin güncellemede olup olmadığını gösteren boolean
  • welder_1: Yeni welder_1 değeri (varsa)
  • welder_2: Yeni welder_2 değeri (varsa)
• Ne Zaman: İstekten yeni değerler işlenirken

isNowAuth.welder_check.blocked

• Amaç: Kaynakçı alanı güncellemesi engellendiğinde logla
• Loglanan Veriler:
  • reason: Neden engellendiği (örn: "welder_1_already_filled")
  • existing_value: Veritabanındaki mevcut değer
  • new_value: Denenen yeni değer
• Ne Zaman: Zaten dolu olan bir kaynakçı alanı güncellenmeye çalışıldığında
• Aksiyon: false döner (güncellemeyi engeller)

isNowAuth.real_welder_check.status

• Amaç: Sadece real_welder alanlarının güncellenip güncellenmediğini logla
• Loglanan Veriler:
  • is_only_real_welder_update: Boolean sonuç
• Ne Zaman: Güncellemenin sadece real_welder_1 veya real_welder_2 için olup olmadığı kontrol edildikten sonra

isNowAuth.real_welder_check.welder_status

• Amaç: real_welder güncellemeleri için kaynakçı alan durumunu logla
• Loglanan Veriler:
  • welder_1_value: Mevcut welder_1 değeri
  • welder_2_value: Mevcut welder_2 değeri
  • welder_fields_filled: Herhangi bir kaynakçı alanının dolu olup olmadığını gösteren boolean
• Ne Zaman: real_welder güncelleme doğrulaması sırasında

isNowAuth.real_welder_check.decision

• Amaç: real_welder güncellemeleri için kararı logla
• Loglanan Veriler:
  • action: "allow_without_time_limit" veya "continue_to_time_check"
  • reason: "welder_fields_empty" veya "welder_fields_filled"
• Ne Zaman: real_welder güncellemeleri için zaman limitini atlayıp atlamayacağına karar verildikten sonra

isNowAuth.level_check.status

• Amaç: Kullanıcı seviye kontrol durumunu logla
• Loglanan Veriler:
  • user_id: Mevcut kullanıcının ID'si
  • user_level: Mevcut kullanıcının seviyesi
  • allowed_levels: Zaman limitini atlayan seviyelerin dizisi
  • level_in_allowed: Kullanıcının istisna listesinde olup olmadığını gösteren boolean
• Ne Zaman: Kullanıcı seviyesinin özel ayrıcalıklara sahip olup olmadığı kontrol edilirken

isNowAuth.level_check.decision

• Amaç: Kullanıcı seviyesine dayalı kararı logla
• Loglanan Veriler:
  • action: "allow"
  • reason: "user_level_in_exception_list"
  • user_level: Kullanıcının seviyesi
• Ne Zaman: Kullanıcı seviyesi zaman limitinden muafiyet sağladığında
• Aksiyon: true döner (güncellemeye izin verir)

isNowAuth.time_limit_check.initiating

• Amaç: Zaman limiti kontrolü yapılmak üzereyken logla
• Loglanan Veriler:
  • user_level: Kullanıcının seviyesi
  • welding_date: Kayıttaki kaynak tarihi
  • created_at: Kayıt oluşturma zaman damgası
• Ne Zaman: checkWeldLogTimeLimit fonksiyonu çağrılmadan önce

isNowAuth.decision

• Amaç: Final yetkilendirme kararlarını logla
• Loglanan Veriler:
  • action: "allow" veya "deny"
  • reason: Kararın neden alındığının açıklaması
• Ne Zaman: Fonksiyonun çeşitli çıkış noktalarında
• Olası Sebepler:
  • "welding_date_empty": Kaynak tarihi yok, güncellemeye izin verildi
  • "not_weld_logs_table": Farklı tablo, özel kural yok

2. isOnlyRealWelderFieldsUpdate Fonksiyonu

Sadece real_welder alanlarının güncellenip güncellenmediğini belirleyen yardımcı fonksiyon.

Log Anahtarları:

isOnlyRealWelderFieldsUpdate.analysis

• Amaç: Güncellenen alanların detaylı analizini logla
• Loglanan Veriler:
  • updating_fields: Güncellenen tüm alanların dizisi
  • has_real_welder_update: Herhangi bir real_welder alanının dahil olup olmadığını gösteren boolean
  • other_fields: Güncellenen real_welder olmayan alanların dizisi
  • is_only_real_welder_update: Boolean nihai sonuç
  • real_welder_field_values: real_welder_1 ve real_welder_2 değerlerini içeren nesne
• Ne Zaman: Bu fonksiyon her çağrıldığında

3. checkWeldLogTimeLimit Fonksiyonu

Güncellemenin izin verilen zaman limiti içinde olup olmadığını doğrular.

Log Anahtarları:

checkWeldLogTimeLimit.start

• Amaç: Fonksiyon başlangıcını logla
• Loglanan Veriler:
  • query_id: Kontrol edilen kayıt ID'si
  • created_at: Kayıt oluşturma zaman damgası
  • created_at_is_null: Boolean kontrol
• Ne Zaman: Fonksiyon başlangıcında

checkWeldLogTimeLimit.calculation

• Amaç: Zaman farkı hesaplamalarını logla
• Loglanan Veriler:
  • created_at: Kayıt oluşturma zamanı
  • current_time: Mevcut zaman damgası
  • allowed_hour_limit: Ayarlardan alınan maksimum izin verilen saat
  • actual_hour_difference: Hesaplanan saat farkı
  • within_limit: İzin verilen zaman içinde olup olmadığını gösteren boolean
• Ne Zaman: Zaman farkları hesaplandıktan sonra

checkWeldLogTimeLimit.decision

• Amaç: Final zaman limiti kararını logla
• Loglanan Veriler:
  • action: "allow" veya "deny"
  • reason: Kararın açıklaması
  • hour_difference: Geçen gerçek saatler (allow için)
  • allowed_limit: İzin verilen maksimum saat (allow için)
  • exceeded_by: Limitin üzerindeki saatler (sadece deny için)
• Ne Zaman: Karar dönmeden önce
• Olası Sebepler:
  • "within_time_limit": Güncellemeye izin verildi
  • "exceeded_time_limit": Güncelleme engellendi
  • "created_at_is_null": Oluşturma tarihi yok, engellendi

Hata Ayıklama için Bu Logları Nasıl Kullanırız

1. Tüm isNowAuth İşlemlerini İzle

tail -f storage/logs/laravel.log | grep "isNowAuth"

2. Belirli Yetkilendirme Hatalarını İzle

tail -f storage/logs/laravel.log | grep "isNowAuth.welder_check.blocked"

3. Zaman Limiti İhlallerini İzle

tail -f storage/logs/laravel.log | grep "checkWeldLogTimeLimit.decision" | grep "deny"

4. Real Welder Güncellemelerini İzle

tail -f storage/logs/laravel.log | grep "isNowAuth.real_welder_check"

5. Kullanıcı Seviye İstisnalarını İzle

tail -f storage/logs/laravel.log | grep "isNowAuth.level_check"

Yaygın Hata Ayıklama Senaryoları

Senaryo 1: Güncelleme Engellendi - Nedenini Bul

1. Loglarda kayıt ID'sini ara:

grep "query_id.*123" storage/logs/laravel.log | grep isNowAuth

2. Karar loglarına bak:

grep "isNowAuth.decision\|isNowAuth.welder_check.blocked" storage/logs/laravel.log

Senaryo 2: Zaman Limiti Sorunları

1. Zaman hesaplamalarını kontrol et:

grep "checkWeldLogTimeLimit.calculation" storage/logs/laravel.log | tail -1

2. Kararı incele:

grep "checkWeldLogTimeLimit.decision" storage/logs/laravel.log | tail -1

Senaryo 3: Real Welder Güncelleme Problemleri

1. Sadece real_welder güncellemesi olarak tanınıp tanınmadığını kontrol et:

grep "isOnlyRealWelderFieldsUpdate.analysis" storage/logs/laravel.log | tail -1

2. Kaynakçı alan durumunu kontrol et:

grep "isNowAuth.real_welder_check.welder_status" storage/logs/laravel.log | tail -1

Log Seviyeleri

Tüm loglar Log::debug() kullanır, bu da şu anlama gelir:

• .env dosyasında APP_DEBUG=true olduğunda log dosyasında görünürler
• Varsayılan olarak production'da görünmezler (performans için)
• Log girdilerinde "DEBUG" seviyesini kullanırlar

En İyi Uygulamalar

1. Logları her zaman sırayla kontrol et: isNowAuth.start'tan final karara kadar akışı takip et
2. Grep'i context ile kullan: Çevresindeki logları görmek için -A 5 -B 5 ekle
3. Zaman damgasına göre filtrele: Belirli sorunları debug ederken zaman aralığına göre filtrele
4. Önemli log bölümlerini kaydet: İlgili logları dokümantasyon için dışa aktar
5. Production'ı dikkatli izle: Production'da debug logları sadece geçici olarak etkinleştir

Performans Değerlendirmeleri

• Debug loglar sadece APP_DEBUG=true olduğunda yazılır
• Her yetkilendirme kontrolü 5-15 log girdisi oluşturur
• Log dosyası rotasyonu düzgün yapılandırılmalıdır
• Yüksek hacimli sistemler için log analiz araçları kullanmayı düşünün