truncgit/citrus-cms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c510b18f42004c13d8cd08829f35b9e3f6e2a9ba
citrus-cms/resources/views/guide/naks-sync.md
T
Ümit Tunç 37e7296527 ikinci temizlik tamamlandı
2026-04-28 21:15:09 +03:00

17 KiB
Raw Blame History

NAKS Multi-Module Cross-Site Synchronization

English | Türkçe

English

Overview

The NAKS Sync system enables automatic synchronization of all NAKS-related data across multiple project sites. Each site runs this sync process to pull data from other sites, ensuring all sites have the same NAKS data.

Supported Modules

Module Key Name Table Unique Keys PDF Folder
technology NAKS Technology naks_certificates short_number + certificate_no 0000_Naks Technology
welder NAKS Welder naks_welders naks_certificate_no + welder_id 0003_Naks Welder
consumables NAKS Consumables naks_consumables naks_certificate_no + batch_number 0002_Naks Consumables
expert NAKS Expert register_of_experts certificate_no 0004_Naks Expert
equipment NAKS Equipment welding_equipment attestation 0001_Naks Equipment

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Site 101      │     │   Site 102      │     │   Site 104      │
│ (Cherepovets)   │     │ (Viksa OMK)     │     │ (Novokuznetsk)  │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │    API Communication    │
                    │                         │
                    │  For Each Module:       │
                    │  • naks_certificates    │
                    │  • naks_welders         │
                    │  • naks_consumables     │
                    │  • register_of_experts  │
                    │  • welding_equipment    │
                    └─────────────────────────┘

Key Features

  • Multi-Module Support: Sync all 5 NAKS modules in one command
  • Selective Sync: Choose specific module(s) to sync
  • Incremental Sync: Only syncs new/updated records since last sync
  • Conflict Resolution: Uses updated_at timestamp - newer record wins
  • PDF Download: Automatically downloads certificate PDF files
  • Multi-site Support: Works with all registered project sites
  • Dry Run Mode: Test sync without making changes

Installation

1. Environment Configuration

Add the following to your .env file on each site:

# Cross-Site NAKS Sync
SYNC_ADMIN_EMAIL=sync@stellarcons.com
SYNC_ADMIN_PASSWORD=YourSecurePassword

Important

: The same admin credentials must exist on all project sites.

2. Database Migration

Run the migration to create the sync state tracking table:

php artisan migrate

This creates the sync_states table that tracks sync progress for each module and source.

Usage

Command Options

# Sync ALL modules from all projects
php artisan naks:sync

# Sync specific module only
php artisan naks:sync --module=technology
php artisan naks:sync --module=welder
php artisan naks:sync --module=consumables
php artisan naks:sync --module=expert
php artisan naks:sync --module=equipment

# Sync specific project only
php artisan naks:sync --project=101
php artisan naks:sync --project=Cherepovets

# Combine options
php artisan naks:sync --module=welder --project=101

# Test mode (no changes)
php artisan naks:sync --dry-run

# Force sync all records (ignore last sync ID)
php artisan naks:sync --force

# Show sync status
php artisan naks:sync --status
php artisan naks:sync --status --module=welder

# Reset sync state
php artisan naks:sync --reset
php artisan naks:sync --reset --module=welder
php artisan naks:sync --reset --project=101

Example Output

╔════════════════════════════════════════════════════════════╗
║       NAKS Multi-Module Cross-Site Synchronization         ║
╚════════════════════════════════════════════════════════════╝

📦 Available Modules:
+-------------+------------------+---------------------+----------------------------------+
| Key         | Name             | Table               | Unique Keys                      |
+-------------+------------------+---------------------+----------------------------------+
| technology  | NAKS Technology  | naks_certificates   | short_number + certificate_no    |
| welder      | NAKS Welder      | naks_welders        | naks_certificate_no + welder_id  |
| consumables | NAKS Consumables | naks_consumables    | naks_certificate_no + batch_num  |
| expert      | NAKS Expert      | register_of_experts | certificate_no                   |
| equipment   | NAKS Equipment   | welding_equipment   | attestation                      |
+-------------+------------------+---------------------+----------------------------------+

📋 Available Projects:
+---------------------------+-----------------------------------+
| Project Name              | URL                               |
+---------------------------+-----------------------------------+
| 101-Cherepovets           | https://101.qms.stellarcons.com   |
| 102 - VIKSA OMK           | https://viksaqms.stellarcons.com  |
| 104 - Новокузнецк         | https://104.qms.stellarcons.com   |
+---------------------------+-----------------------------------+

🔄 Starting synchronization...

════════════════════════════════════════════════════════════
                      SYNC RESULTS
════════════════════════════════════════════════════════════

+---------------------+-------+
| Metric              | Value |
+---------------------+-------+
| Total Projects      | 5     |
| Successful Projects | 5     |
| Failed Projects     | 0     |
| Duration            | 120s  |
+---------------------+-------+

📦 Module Results:
+------------------+--------+----------+---------+---------+------+
| Module           | Synced | Inserted | Updated | Skipped | PDFs |
+------------------+--------+----------+---------+---------+------+
| NAKS Technology  | 150    | 45       | 30      | 75      | 12   |
| NAKS Welder      | 200    | 80       | 40      | 80      | 25   |
| NAKS Consumables | 100    | 30       | 20      | 50      | 5    |
| NAKS Expert      | 50     | 15       | 10      | 25      | 8    |
| NAKS Equipment   | 75     | 25       | 15      | 35      | 10   |
| ─────────        | ─────  | ────────  | ───────  | ───────  | ──── |
| TOTAL            | 575    | 195      | 115     | 265     | 60   |
+------------------+--------+----------+---------+---------+------+

✅ Synchronization completed successfully!

Cron Schedule

The sync runs automatically every day at 02:00 AM. Configuration in app/Console/Kernel.php:

$schedule->command('naks:sync --module=all')
         ->daily()
         ->at('02:00')
         ->withoutOverlapping(120)
         ->appendOutputTo(storage_path('logs/naks-sync.log'));

Sync Logic

  1. Get Project List: Fetches available projects from /api/project-app-urls
  2. Authenticate: Logs in to each remote site once to get Bearer token
  3. For Each Module:
    • Get last synced ID from sync_states table
    • Fetch records with ID > last_synced_id
    • For each record:
      • If not exists locally (by unique keys) → INSERT
      • If exists and remote is newer → UPDATE
      • If exists and local is newer → SKIP
    • Download PDF if available
    • Update sync state

Module Details

NAKS Technology (technology)

  • Table: naks_certificates
  • Unique Key: short_number + certificate_no
  • Example: АЦСТ-149 + 00036
  • PDF Path: storage/documents/003_Welding_Database/0000_Naks Technology/

NAKS Welder (welder)

  • Table: naks_welders
  • Unique Key: naks_certificate_no + welder_id
  • PDF Path: storage/documents/003_Welding_Database/0003_Naks Welder/

NAKS Consumables (consumables)

  • Table: naks_consumables
  • Unique Key: naks_certificate_no + batch_number
  • PDF Path: storage/documents/003_Welding_Database/0002_Naks Consumables/

NAKS Expert (expert)

  • Table: register_of_experts
  • Unique Key: certificate_no
  • PDF Path: storage/documents/003_Welding_Database/0004_Naks Expert/

NAKS Equipment (equipment)

  • Table: welding_equipment
  • Unique Key: attestation
  • PDF Path: storage/documents/003_Welding_Database/0001_Naks Equipment/

Troubleshooting

Issue Solution
Authentication failed Check SYNC_ADMIN_EMAIL/PASSWORD in .env
No projects found Verify /api/project-app-urls endpoint
PDFs not downloading Check storage permissions
Sync stuck Run with --reset to clear state
Module not syncing Check if table exists and has data

Log Files

  • Cron Output: storage/logs/naks-sync.log
  • Application Log: storage/logs/laravel.log

Türkçe

Genel Bakış

NAKS Sync sistemi, tüm NAKS ile ilgili verilerin birden fazla proje şantiyesi arasında otomatik senkronizasyonunu sağlar. Her şantiye bu sync işlemini çalıştırarak diğer şantiyelerden veri çeker ve tüm şantiyelerin aynı NAKS verisine sahip olmasını sağlar.

Desteklenen Modüller

Modül Key İsim Tablo Benzersiz Anahtar PDF Klasörü
technology NAKS Teknoloji naks_certificates short_number + certificate_no 0000_Naks Technology
welder NAKS Kaynakçı naks_welders naks_certificate_no + welder_id 0003_Naks Welder
consumables NAKS Sarf Malzeme naks_consumables naks_certificate_no + batch_number 0002_Naks Consumables
expert NAKS Uzman register_of_experts certificate_no 0004_Naks Expert
equipment NAKS Ekipman welding_equipment attestation 0001_Naks Equipment

Mimari

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Şantiye 101   │     │   Şantiye 102   │     │   Şantiye 104   │
│ (Cherepovets)   │     │ (Viksa OMK)     │     │ (Novokuznetsk)  │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │    API İletişimi        │
                    │                         │
                    │  Her Modül İçin:        │
                    │  • naks_certificates    │
                    │  • naks_welders         │
                    │  • naks_consumables     │
                    │  • register_of_experts  │
                    │  • welding_equipment    │
                    └─────────────────────────┘

Temel Özellikler

  • Çoklu Modül Desteği: Tek komutla 5 NAKS modülünü sync et
  • Seçici Sync: Belirli modül(ler)i sync et
  • Artımlı Sync: Sadece son sync'ten sonra eklenen/güncellenen kayıtları senkronize eder
  • Çakışma Çözümü: updated_at zaman damgası kullanır - yeni olan kazanır
  • PDF İndirme: Sertifika PDF dosyalarını otomatik indirir
  • Çoklu Şantiye Desteği: Tüm kayıtlı proje şantiyeleriyle çalışır
  • Deneme Modu: Değişiklik yapmadan sync'i test et

Kurulum

1. Ortam Yapılandırması

Her şantiyede .env dosyasına aşağıdakileri ekleyin:

# Şantiyeler Arası NAKS Sync
SYNC_ADMIN_EMAIL=sync@stellarcons.com
SYNC_ADMIN_PASSWORD=GuvenliSifreniz

Önemli: Aynı admin kimlik bilgileri tüm proje şantiyelerinde mevcut olmalıdır.

2. Veritabanı Migrasyonu

Sync durum takip tablosunu oluşturmak için migrasyonu çalıştırın:

php artisan migrate

Kullanım

Komut Seçenekleri

# TÜM modülleri tüm projelerden sync et
php artisan naks:sync

# Sadece belirli modülü sync et
php artisan naks:sync --module=technology
php artisan naks:sync --module=welder
php artisan naks:sync --module=consumables
php artisan naks:sync --module=expert
php artisan naks:sync --module=equipment

# Sadece belirli projeyi sync et
php artisan naks:sync --project=101
php artisan naks:sync --project=Cherepovets

# Seçenekleri birleştir
php artisan naks:sync --module=welder --project=101

# Test modu (değişiklik yapma)
php artisan naks:sync --dry-run

# Tüm kayıtları zorla sync et
php artisan naks:sync --force

# Sync durumunu göster
php artisan naks:sync --status
php artisan naks:sync --status --module=welder

# Sync durumunu sıfırla
php artisan naks:sync --reset
php artisan naks:sync --reset --module=welder

Cron Zamanlaması

Sync her gün sabah 02:00'de otomatik olarak çalışır. app/Console/Kernel.php içindeki yapılandırma:

$schedule->command('naks:sync --module=all')
         ->daily()
         ->at('02:00')
         ->withoutOverlapping(120)
         ->appendOutputTo(storage_path('logs/naks-sync.log'));

Sync Mantığı

  1. Proje Listesi Al: /api/project-app-urls'den mevcut projeleri çeker
  2. Kimlik Doğrula: Bearer token almak için her uzak şantiyeye bir kez giriş yapar
  3. Her Modül İçin:
    • sync_states tablosundan son sync edilen ID'yi al
    • ID > last_synced_id olan kayıtları çek
    • Her kayıt için:
      • Yerel'de yoksa (benzersiz anahtarlara göre) → EKLE
      • Varsa ve uzaktaki daha yeniyse → GÜNCELLE
      • Varsa ve yereldeki daha yeniyse → ATLA
    • PDF varsa indir
    • Sync durumunu güncelle

Modül Detayları

NAKS Teknoloji (technology)

  • Tablo: naks_certificates
  • Benzersiz Anahtar: short_number + certificate_no
  • Örnek: АЦСТ-149 + 00036
  • PDF Yolu: storage/documents/003_Welding_Database/0000_Naks Technology/

NAKS Kaynakçı (welder)

  • Tablo: naks_welders
  • Benzersiz Anahtar: naks_certificate_no + welder_id
  • PDF Yolu: storage/documents/003_Welding_Database/0003_Naks Welder/

NAKS Sarf Malzeme (consumables)

  • Tablo: naks_consumables
  • Benzersiz Anahtar: naks_certificate_no + batch_number
  • PDF Yolu: storage/documents/003_Welding_Database/0002_Naks Consumables/

NAKS Uzman (expert)

  • Tablo: register_of_experts
  • Benzersiz Anahtar: certificate_no
  • PDF Yolu: storage/documents/003_Welding_Database/0004_Naks Expert/

NAKS Ekipman (equipment)

  • Tablo: welding_equipment
  • Benzersiz Anahtar: attestation
  • PDF Yolu: storage/documents/003_Welding_Database/0001_Naks Equipment/

Sorun Giderme

Sorun Çözüm
Kimlik doğrulama başarısız .env'deki SYNC_ADMIN_EMAIL/PASSWORD'ü kontrol edin
Proje bulunamadı /api/project-app-urls endpoint'ini doğrulayın
PDF'ler indirilmiyor Storage izinlerini kontrol edin
Sync takıldı Durumu temizlemek için --reset ile çalıştırın
Modül sync olmuyor Tablonun var olduğunu ve veri içerdiğini kontrol edin

Log Dosyaları

  • Cron Çıktısı: storage/logs/naks-sync.log
  • Uygulama Logu: storage/logs/laravel.log

Files Reference

File Description
app/Console/Commands/NaksSync.php Artisan command
app/Services/NaksSyncService.php Multi-module sync service
database/migrations/2025_01_07_000001_create_sync_states_table.php Migration
app/Console/Kernel.php Cron schedule configuration

API Endpoints Used

Endpoint Method Description
/api/login POST Get Bearer token
/api/project-app-urls GET Get project list
/api/{table}/read GET Fetch records for each module

Last Updated: January 2025

Reference in New Issue View Git Blame Copy Permalink