📊 BÖLÜM 1: YÖNETİCİ ÖZETİ

1.1 Proje Başarı Metrikleri — Ölçülebilir Sonuçlar

Bu proje, tasarımdan üretime kadar tek elden yönetilmiş olup, aşağıdaki ölçülebilir iş sonuçlarını üretmektedir:

1.2 Başarı Alanları Detay Tablosu

1.3 Projenin Teknik Karmaşıklık Seviyesi

Kapsanan Teknik Disiplinler:

🎯 BÖLÜM 2: PROJENİN GERÇEK AMACI & STRATEJİK DEĞER

2.1 Net Tanım — Problem Statement

Bu sistemin tek ana amacı:
WAPIM sisteminde günlük datalar adımında, yani WhatsApp kanalından gelen dataları DUPLICATE OLUŞTURMADAN, doğru kurallarla CREATE veya UPDATE ederek, asenkron ve izlenebilir şekilde işlemek.

İş Problemi:

WhatsApp üzerinden gelen lead verileri, CRM sistemine aktarılırken:

2.2 Sistem Kimliği — Bu Sistem Ne ve Ne DEĞİL

🏛️ BÖLÜM 3: SİSTEM MİMARİSİ & KATMANLI TASARIM

3.1 Mimari Büyük Resim — High-Level Architecture

3.2 Katman Sorumlulukları — Separation of Concerns

Bu mimari, Separation of Concerns prensibine sıkı sıkıya bağlıdır:

3.3 Mimari Kararların Gerekçeleri

🖥️ BÖLÜM 4: WEB ARAYÜZÜ & KULLANICI DENEYİMİ TASARIMI

4.1 Kullanıcı Giriş Alanları

4.2 Buton Davranışları — İki Aşamalı Güvenlik Tasarımı

Sistem, yanlışlıkla CRM'e veri gönderilmesini engelleyen iki aşamalı bir güvenlik mekanizması içerir:

📦 BÖLÜM 5: JOB & QUEUE MEKANİZMASI

5.1 Neden Queue Gerekli? — Problem Analizi

ÇÖZÜM MİMARİSİ: İşi hemen yapmaya çalışma. Kuyruğa koy, arka planda güvenle işle.
Bu pattern'in adı: Asynchronous Job Processing — enterprise sistemlerin standart yaklaşımı.

5.2 jobs Tablosu — Ana İş Kaydı

CREATE TABLE jobs (
    id          INT AUTO_INCREMENT PRIMARY KEY,
    status      ENUM('NEW', 'RUNNING', 'DONE', 'FAILED'),
    total       INT          COMMENT 'Toplam kayıt sayısı',
    done        INT DEFAULT 0 COMMENT 'İşlenen kayıt sayısı',
    created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
);

5.3 job_items Tablosu — Satır Bazlı İş Detayı

CREATE TABLE job_items (
    id           INT AUTO_INCREMENT PRIMARY KEY,
    job_id       INT          COMMENT 'Foreign Key → jobs',
    phone        VARCHAR(20)  COMMENT 'Telefon numarası',
    payload      JSON         COMMENT 'Lead verisi (tüm alanlar)',
    status       ENUM('PENDING','PROCESSING','CREATED','UPDATED','FAILED'),
    crm_response JSON         COMMENT 'CRM API yanıtı (audit için)',
    FOREIGN KEY (job_id) REFERENCES jobs(id)
);

5.4 Status Durumları — Yaşam Döngüsü

⚙️ BÖLÜM 6: WORKER ENGINE — SİSTEMİN BEYNİ

6.1 Worker Nedir?

⚙️ worker.php = DAEMON PROCESS
Bu, sistemin kalbidir. Sürekli çalışır, kuyruktaki işleri alır, CRM ile konuşur ve sonuçları kaydeder.

6.2 Worker Yaşam Döngüsü

Worker'ın Kritik Sorumlulukları:

🧠 BÖLÜM 7: CREATE vs UPDATE — EN KRİTİK KARAR MEKANİZMASI

7.1 Temel Kural — Create-First Strategy

Neden Create-First?

Create-First'ün Üstünlükleri:

7.2 CREATE Akışı

// 1. Adım: Her zaman önce CREATE dene
$createRes = $crmClient->createRecord($payload);

if ($createRes['IsOk'] === true) {
    // ✅ CREATED — Yeni kayıt başarıyla oluşturuldu
    $this->markAsCreated($jobItem, $createRes);
}

7.3 CREATE Başarısız Olursa?

🔍 BÖLÜM 8: CRM'DE KAYIT BULMA STRATEJİSİ

8.1 Kritik Teknik Zorluk

Problem: SETCRM API'si multi-field search desteklemiyor. Telefon numarası CRM'de 3 farklı alanda olabilir.
Çözüm: Sıralı (cascading) arama stratejisi tasarlandı.

CRM'de arama yalnızca FIELD ID ile yapılabilir:

GET RecordByUniqueField?customObjectId=...&id=FIELD_ID&value=PHONE

8.2 Unique Phone Fields Konfigürasyonu

// app.php — Merkezi konfigürasyon
'unique_phone_fields' => [
    'Mobile',        // Öncelik 1 — En sık kullanılan
    'Other Phone',   // Öncelik 2 — Alternatif telefon
    'Other Phone 2'  // Öncelik 3 — İkincil alternatif
]

8.3 getRecordByPhone() Mantığı — Cascading Search

8.4 Performans & Maliyet Analizi

🔀 BÖLÜM 9: ALAN GÜNCELLEME KURALLARI — AKILLI MERGE

9.1 Temel Felsefe

9.2 Interest (İlgi Alanı) — Merge Stratejisi

9.3 Source / CRMID Alanları

9.4 Contact Owner / Pool Mantığı

💡 Bu Tasarımın İş Değeri: Sistem, CRM'deki insan kararlarını EZMİYOR, SAYGI DUYUYOR. Bir satışçı bugün bir müşteriyle görüşmüşse, otomatik sistem o müşteriyi başka birine atamaz. Bu, insan-makine işbirliğinin doğru tasarlanmasıdır.

📅 BÖLÜM 10: TARİH İŞLEME MANTIĞI

10.1 Teknik Zorluk — CRM Tarih Formatı

SETCRM, .NET platformu üzerinde çalıştığı için tarihler Microsoft .NET Date format ile gelir:

\/Date(1768770000000)\/

10.2 Çözüm — dotNetMsToDmy() Format Dönüştürücüsü

// Dönüşüm: .NET milisaniye → PHP DateTime → Türk tarih formatı
function dotNetMsToDmy($dotNetDate) {
    // \/Date(1768770000000)\/ → 1768770000000 → 19.01.2026
    preg_match('/\/Date\((\d+)\)\//', $dotNetDate, $matches);
    $timestamp = $matches[1] / 1000;
    return date('d.m.Y', $timestamp);
}

10.3 Karşılaştırma Mantığı

🛡️ BÖLÜM 11: HATA YÖNETİMİ & SELF-HEALING

11.1 Fail Durumunda Loglanan Bilgiler

11.2 Worker Çökmesi Senaryosu — Self-Healing

📊 BÖLÜM 12: DECISION TABLES

12.1 Status Field Karar Tablosu

Kural Formülü: SET = isPool AND NOT isToday

Kod Karşılığı:

$shouldSetStatus = ($isPool && !$istodaylastfolowupdate);

if ($shouldSetStatus) {
    // Case 2: Pool'da ve bugün follow-up yok → Virgin Lead olarak set et
    $updatePayload[$statusFieldId] = $virginLeadId;
} else {
    // Case 1, 3, 4: Dokunma
    unset($updatePayload[$statusFieldId]);
}

12.2 CRMID ve Source Karar Tablosu

12.3 Interest Merge Karar Tablosu

📐 BÖLÜM 13: FLOWCHARTS

13.1 Yüksek Seviye Akış — CREATE → UPDATE Fallback

13.2 UPDATE Payload Karar Akışı

🏭 BÖLÜM 14: RULE ENGINE TASARIMI

14.1 Mevcut Durum Analizi & Evrim Yol Haritası

14.2 Kural Yapısı — Rule Schema

14.3 Örnek Kurallar

14.4 Context Objesi

$ctx = [
    'isPool'         => $isPool,
    'isToday'        => $istodaylastfolowupdate,
    'isBanned'       => $isBanned,
    'newLeadSource'  => $currentNewLeadSource,
    'sourceWapim'    => $currentSourcewapim,
    'payload'        => $updatePayload,
];

14.5 Minimal Rule Engine İmplementasyonu

$rules = [
    [
        'name'     => 'status_never_set_when_today',
        'priority' => 200,
        'when'     => fn($c) => $c['isToday'] === true,
        'then'     => function (&$c) use ($statusFieldId) {
            unset($c['payload'][$statusFieldId]);
        }
    ],
    [
        'name'     => 'status_set_for_pool_not_today',
        'priority' => 100,
        'when'     => fn($c) => ($c['isPool'] === true && $c['isToday'] === false),
        'then'     => function (&$c) use ($statusFieldId, $virginLeadId) {
            $c['payload'][$statusFieldId] = $virginLeadId;
        }
    ],
];

14.6 Rules Runner — Kural Çalıştırma Motoru

// 1. Kuralları önceliğe göre sırala (yüksek önce = daha baskın)
usort($rules, fn($a, $b) => $b['priority'] - $a['priority']);

// 2. Kuralları sırayla değerlendir
foreach ($rules as $rule) {
    if ($rule['when']($ctx)) {
        $rule['then']($ctx);
        log("Rule '{$rule['name']}' uygulandı (priority: {$rule['priority']})");
        break; // İlk match eden kazanır
    }
}

$updatePayload = $ctx['payload'];

Rule Engine'in Sağladığı Avantajlar:

📈 BÖLÜM 15: SONUÇ, DEĞERLENDİRME & STRATEJİK ETKİ

15.1 Güçlü Yanlar — Teknik Mükemmellik Alanları

15.2 Bilinçli Sınırlamalar — Trade-off Analizi

15.3 Sistemin Stratejik Değeri

Bu sistem:

❌ "Hızlı yazılmış bir script" DEĞİL

✅ CRM davranışlarını, satış süreçlerini ve veri bütünlüğü gereksinimlerini derinlemesine bilen bir mimar tarafından şekillendirilmiş, production-grade bir lead reconciliation sistemidir.

Kapsanan Mühendislik Disiplinleri:

15.4 Dikkat Edilmesi Gerekenler

📋 EK: HIZLI REFERANS KARTI