citrus-cms/resources/views/guide/naks-sync.md

# NAKS Multi-Module Cross-Site Synchronization

[English](#english) | [Türkçe](#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:

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

```bash
php artisan migrate
```

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

### Usage

#### Command Options

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

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

```env
# Ş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:

```bash
php artisan migrate
```

### Kullanım

#### Komut Seçenekleri

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

```php
$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*