# Sıra Diyagramları — Kalyon PV MES-PLC Entegrasyonu

Referans: TEK-SA | Kalyon PV MES ve Otomasyon Entegrasyon Blueprint rev 0.2, §5/§6.
Bu diyagramlar `src/integration-service`, `src/mes-simulator`, `src/plc-simulator`
kodunun **gerçek davranışını** anlatır — kod ile diyagram arasında sürüklenme
olmaması için her diyagramın altında ilgili kaynak dosya/fonksiyon işaretlenmiştir.

## 1. Normal Çevrim (Blueprint §5)

```mermaid
sequenceDiagram
    participant MES
    participant ENT as Entegrasyon Servisi
    participant PLC

    MES->>ENT: POST /api/job-orders {txn_id, serial_no}
    ENT-->>MES: 200 {accepted:true, duplicate:false}
    ENT->>PLC: POST /api/execute {txn_id, ...}
    PLC-->>ENT: 202 {accepted:true}
    Note over PLC: cevrim yurutulur (400-1200ms)
    PLC->>ENT: POST /api/job-results {txn_id, result:OK, cycle_time_ms}
    Note over ENT: TEK DB islemi: status=RESULT_QUEUED + outbox INSERT
    ENT-->>PLC: 200 {accepted:true, duplicate:false}
    ENT->>MES: POST /api/results {txn_id, result}
    MES-->>ENT: 200 {ack:true, duplicate:false, mes_record_id}
    Note over ENT: status=CLOSED, outbox.delivered_at set
```

Kaynak: `integration-service/index.ts` → `app.post('/api/job-orders', ...)`,
`app.post('/api/job-results', ...)`, `relayTick()`.

## 2. Sonuç Gönderilmeden Önce Bağlantı Kaybı (Blueprint §6.1)

```mermaid
sequenceDiagram
    participant MES
    participant ENT as Entegrasyon Servisi
    participant PLC

    Note over MES: MES erisilemez hale gelir
    PLC->>ENT: POST /api/job-results {txn_id, result:OK}
    Note over ENT: outbox INSERT, status=RESULT_QUEUED
    loop her RETRY_INTERVAL_MS
        ENT--xMES: POST /api/results (basarisiz / atlanir)
        Note over ENT: status=RESULT_BUFFERED, attempts++, backoff
    end
    Note over MES: MES geri gelir
    ENT->>MES: POST /api/results {txn_id, result} (AYNI txn_id)
    MES-->>ENT: 200 {ack:true, duplicate:false}
    Note over ENT: status=CLOSED
```

Kaynak: `integration-service/index.ts` → `relayTick()` (chaos: `mesChaosDownOverride`
veya MES simülatörünün `/api/chaos/down` bayrağı).

## 3. Entegrasyon Servisi Çökmesi + Kurtarma (Blueprint §6.3)

```mermaid
sequenceDiagram
    participant PLC
    participant ENT as Entegrasyon Servisi
    participant DB as SQLite (WAL, disk)
    participant MES

    PLC->>ENT: POST /api/job-results {txn_id}
    ENT->>DB: BEGIN IMMEDIATE; INSERT outbox; UPDATE status; COMMIT
    Note over ENT: SIGKILL / process.exit(1)
    destroy ENT
    Note over DB: outbox satırı DİSKTE kalıcı, kaybolmadı
    Note over ENT: supervisor (pm2/systemd) yeniden başlatır
    create participant ENT2 as Entegrasyon Servisi (yeniden başladı)
    ENT2->>DB: ayni dosyayi ac, relayTick() devam eder
    ENT2->>MES: POST /api/results {txn_id} (AYNI txn_id, hic degismedi)
    MES-->>ENT2: 200 {ack:true}
    Note over ENT2: status=CLOSED
```

Kaynak: `src/test/run-fat-scenarios.ts` → `scenarioCrashRecovery()` (gerçek
`SIGKILL` + aynı `DB_PATH` ile yeniden spawn); canlı ortamda
`POST /api/chaos/self-destruct` + pm2 `autorestart`.

## 4. Mükerrer Teslim / Idempotent Consumer (Blueprint §6.2)

```mermaid
sequenceDiagram
    participant ENT as Entegrasyon Servisi
    participant MES

    ENT->>MES: POST /api/results {txn_id: T1}
    Note over MES: received_results tablosunda T1 YOK
    MES->>MES: INSERT received_results(T1, mes_record_id=R1)
    MES-->>ENT: 200 {ack:true, duplicate:false, mes_record_id:R1}

    Note over ENT: ayni sonuc tekrar gonderilir (retry/replay)
    ENT->>MES: POST /api/results {txn_id: T1} (AYNI T1)
    Note over MES: received_results'ta T1 VAR
    MES-->>ENT: 200 {ack:true, duplicate:true, mes_record_id:R1}
    Note over MES,ENT: REJECTED DONMEZ - ikinci uretim kaydi ACILMAZ
```

Kaynak: `mes-simulator/index.ts` → `app.post('/api/results', ...)`,
`received_results` tablosu `txn_id PRIMARY KEY`.

---

**Sürüm yönetimi kuralı**: `txn_id`, `serial_no` ve durum makinesi (`RECEIVED →
SENT_TO_PLC → RESULT_QUEUED → SENDING_TO_MES → (RESULT_BUFFERED ↺) → CLOSED`)
bu spesifikasyonun **kırılamaz çekirdeğidir**. Yeni alan eklemek geriye uyumludur;
mevcut alanların anlamını değiştirmek veya durum makinesini değiştirmek sürüm
numarasını (şu an 0.2.0) yükseltmeyi ve Kalyon MES sağlayıcısıyla ortak onayı
gerektirir (Blueprint §11 "Arayüzün dondurulması").