citrus-cms/resources/views/guide/NAKS_SYNC_SYSTEM.md

# NAKS Synchronization & Trigger System Documentation

This document explains the technical architecture and workflow of the NAKS multi-project synchronization system. This system ensures that when a NAKS certificate changes its "Source Project" (ownership), all other project sites are notified and updated automatically.

---

# 🇹🇷 Türkçe Dokümantasyon

## 1. Genel Bakış
NAKS Senkronizasyon Sistemi, birden fazla proje sahasında (Web Uygulaması) ortak bir veri havuzunun korunmasını sağlar. Özellikle `naks_certificates` (Technology) modülünde, bir sertifikanın "Source Project" (Kaynak Proje) alanı değiştiğinde, diğer tüm projelerin bu değişikliği anında öğrenmesi ve verilerini güncellemesi gerekir.

Bu sistem, **Event-Driven (Olay Güdümlü)** bir yapı kullanır:
1.  Kullanıcı bir kaydı düzenler.
2.  Sistem değişikliği algılar.
3.  Diğer projelere "Senkronizasyon Yap" emri gönderilir.
4.  Diğer projeler, güncel veriyi çeker.

## 2. Mimari Bileşenler

Sistem 4 ana bileşenden oluşur:

### A. Observer (Gözlemci)
**Dosya:** `app/Observers/NaksCertificateObserver.php`
*   Veritabanındaki `updated` olayını dinler.
*   Eğer `source_project` sütunu değişmişse (örneğin Viksa'dan boş/bu proje'ye geçmişse) tetiklenir.
*   `TriggerNaksSyncJob`'ı kuyruğa (Queue) ekler.

### B. Trigger Job (Tetikleyici İş)
**Dosya:** `app/Jobs/TriggerNaksSyncJob.php`
*   Arka planda (Queue) çalışır.
*   Sistemdeki diğer tüm proje URL'lerini (`api/project-app-urls`) listeler.
*   Kendisi hariç diğer tüm projelere `POST /api/naks/trigger-sync` isteği atar.

### C. Endpoint Controller (Karşılayıcı Uç Nokta)
**Dosya:** `app/Http/Controllers/Api/NaksSyncController.php`
*   Diğer projelerden gelen tetikleme isteklerini karşılar.
*   İstek geldiğinde güvenlik kontrolü yapar.
*   Gelen isteğe göre `NaksSyncService->sync()` metodunu çalıştıracak bir işlemi kuyruğa alır.

### D. Sync Service (Senkronizasyon Servisi)
**Dosya:** `app/Services/NaksSyncService.php`
*   Asıl işi yapan servistir.
*   Karşı projeye bağlanır, token alır ve verileri (`naks_certificates`) indirip yerel veritabanını günceller.
*   Conflict (Çakışma) yönetimi yapar (timestamp kontrolü).

## 3. İş Akışı (Workflow)

1.  **Adım 1:** Kullanıcı A Projesinde bir NAKS sertifikasını düzenler ve `Source Project` alanını değiştirir (örneğin temizler).
2.  **Adım 2:** `NaksCertificateObserver` bu değişikliği yakalar.
3.  **Adım 3:** Observer, `TriggerNaksSyncJob` başlatır.
4.  **Adım 4:** Job, Proje B ve Proje C'ye API isteği gönderir: `POST .../api/naks/trigger-sync`.
5.  **Adım 5:** Proje B isteği alır, doğrular ve kendi kuyruğuna "Senkronizasyon Başlat" emri verir.
6.  **Adım 6:** Proje B, arka planda Proje A'ya bağlanır ve güncellenmiş kaydı kendi veritabanına yazar.

## 4. Kurulum ve Gereksinimler

*   **Queue Worker:** Sistemin çalışması için Laravel Queue Worker (`php artisan queue:work`) sunucuda çalışıyor olmalıdır.
*   **Observer Kaydı:** `AppServiceProvider` içerisinde observer tanımlı olmalıdır.
*   **Yetkilendirme:** `.env` dosyasında `SYNC_ADMIN_EMAIL` ve `SYNC_ADMIN_PASSWORD` tanımlı olmalıdır.

---

# 🇬🇧 English Documentation

## 1. Overview
The NAKS Synchronization System maintains a shared data pool across multiple project sites (Web Applications). Specifically for the `naks_certificates` (Technology) module, when the "Source Project" field of a certificate changes, all other projects must be notified immediately to update their local data.

The system uses an **Event-Driven** architecture:
1.  User updates a record.
2.  System detects the change.
3.  A "Trigger Sync" command is sent to other projects.
4.  Other projects pull the latest data.

## 2. Architecture Components

The system consists of 4 main components:

### A. Observer
**File:** `app/Observers/NaksCertificateObserver.php`
*   Listens for the database `updated` event.
*   Triggers if the `source_project` column has changed (e.g., changed from 'Viksa' to empty/this project).
*   Dispatches `TriggerNaksSyncJob` to the queue.

### B. Trigger Job
**File:** `app/Jobs/TriggerNaksSyncJob.php`
*   Runs in the background (Queue).
*   Lists all other project URLs via (`api/project-app-urls`).
*   Sends a `POST /api/naks/trigger-sync` request to all projects except the current one.

### C. Endpoint Controller
**File:** `app/Http/Controllers/Api/NaksSyncController.php`
*   Receives trigger requests from other projects.
*   Validates the incoming request.
*   Queues a task to run `NaksSyncService->sync()` based on the trigger.

### D. Sync Service
**File:** `app/Services/NaksSyncService.php`
*   The core service that performs logic.
*   Connects to the remote project, authenticates, downloads data (`naks_certificates`), and updates the local database.
*   Handles conflict resolution (via timestamp checks).

## 3. Workflow

1.  **Step 1:** User modifies a NAKS certificate in Project A and changes the `Source Project` field.
2.  **Step 2:** `NaksCertificateObserver` captures this event.
3.  **Step 3:** The Observer dispatches `TriggerNaksSyncJob`.
4.  **Step 4:** The Job sends an API request to Project B and Project C: `POST .../api/naks/trigger-sync`.
5.  **Step 5:** Project B receives the request, validates it, and queues a "Start Sync" command locally.
6.  **Step 6:** Project B connects to Project A in the background and updates its local record with the new data.

## 4. Setup & Requirements

*   **Queue Worker:** A Laravel Queue Worker (`php artisan queue:work`) must be running on the server for asynchronous processing.
*   **Observer Registration:** The observer must be registered in `AppServiceProvider`.
*   **Authentication:** `SYNC_ADMIN_EMAIL` and `SYNC_ADMIN_PASSWORD` must be configured in the `.env` file.