İşlem Geçmişi (Audit Log)

Bu Proje Nedir?

ERP, muhasebe ve yönetim panellerinde en çok istenen özellik "işlem geçmişi"dir. İnternette bulacağınız örneklerin çoğu ise şunu yapar: bir logs tablosu açar, içine "Ahmet ürünü güncelledi" gibi bir cümle yazar ve biter.

O cümle üç soruyu da cevapsız bırakır: hangi alan değişti, neydi, ne oldu? Üstelik o tabloya DELETE atmanın önünde hiçbir engel yoktur — yani "bu fiyatı kim değiştirdi?" sorusunun cevabı, o cevabı vermek istemeyen kişi tarafından silinebilir. Böyle bir kayıt denetim değil, süstür.

Bu proje o üç soruyu da cevaplayan bir denetim katmanının nasıl kurulacağını gösteriyor: audit_log tablosu append-only'dir (uygulamada o tabloya UPDATE/DELETE yapan hiçbir yol yoktur), kayıt alan bazlı diff tutar, hassas alanlar loga yazılmadan önce maskelenir ve veri ile kaydı aynı transaction içinde yazılır — biri başarısız olursa ikisi de geri alınır.

Kimler için uygun?

• Kendi projesine denetim / işlem geçmişi katmanı ekleyecekler
• "Bu kaydı kim değiştirdi?" sorusunu üretimde cevaplamak zorunda kalanlar
• PHP + AJAX + DataTables üçlüsünü doğru öğrenmek isteyenler
• Bootstrap 5 üzerine kurulu, tekrar kullanılabilir bir tasarım kalıbı arayanlar

Klonla, cy_audit.sql'i içe aktar, çalıştır. Başka hiçbir kurulum adımı yok. Composer yok, npm yok, internet bağlantısı bile gerekmiyor — tüm kütüphaneler proje içinde.

Bu proje, Çılgın Yazılım Kütüphanesi altında yayınlanan açıklamalı, üretime hazır örneklerden biridir.

---

Üç Kritik Karar

1) Tek yazma noktası — audit()

Denetim kaydı, her işleyicinin kendi başına yazdığı bir şey olsaydı, yarın eklenen bir işleyici onu yazmayı unuturdu ve kimse fark etmezdi. Bu yüzden tek bir fonksiyon vardır:

audit($db, 'update', 'product', $id, $old, $new);
//     ^     ^         ^          ^     ^     ^
//     |     |         |          |     |     └─ işlemden SONRAKİ değerler
//     |     |         |          |     └─────── işlemden ÖNCEKİ değerler
//     |     |         |          └───────────── kayıt id'si
//     |     |         └──────────────────────── mantıksal varlık türü
//     |     └────────────────────────────────── create | update | delete
//     └──────────────────────────────────────── PDO bağlantısı

Yeni bir varlık denetlemek istediğinizde yazacağınız kod tek satırdır. Diff üretimi, maskeleme ve INSERT bu fonksiyonun içindedir.

2) Veri ve kaydı aynı transaction'da yazmak

audit() herhangi bir sebeple patlarsa (bozuk kodlama, disk dolu, kilit zaman aşımı) ürün satırı çoktan kaydedilmiş olurdu ve ortada izi olmayan bir kayıt kalırdı. Bir denetim sisteminde bu, sessizce oluşan en tehlikeli durumdur: tabloya bakan kişi hiçbir eksik görmez.

$db->beginTransaction();
try {
    $stmt->execute([...]);                       // veri
    audit($db, 'create', 'product', $newId, null, $data);   // kayıt
    $db->commit();                               // ya ikisi de…
} catch (PDOException $e) {
    $db->rollBack();                             // …ya hiçbiri
    throw $e;
}

InnoDB kullanmamızın somut karşılığı budur.

3) Append-only — kaydın kendisi de korunmalı

system/ajax.php içinde audit_log tablosuna INSERT dışında bir işlem yapan tek bir uç nokta yoktur. Denetim satırı yalnızca bir CRUD işleminin yan etkisi olarak doğar; arayüzden silinemez, düzenlenemez.

Veritabanı seviyesinde de kilitlemek isterseniz, uygulama kullanıcısına o tabloda yalnızca INSERT ve SELECT yetkisi verin → Canlı Ortama Alırken

---

Neler Var?

Arayüz

• Marka gradyanlı başlık ve modallar
• Sayaç şeridi (toplam / ekleme / güncelleme / silme / son işlem)
• Üç modal (form / silme onayı / işlem detayı)
• Alan bazlı renkli diff tablosu
• İşlem türü, varlık türü ve tarih aralığı filtreleri
• CSV dışa aktarım (ekrandaki filtrelerle birebir aynı)
• Paylaşılabilir kayıt bağlantısı (#islem-42)
• Sağ üstte toast bildirimleri
• Otomatik koyu tema (işletim sistemi ayarını izler)
• Mobil için ayrıca inceltilmiş — yatay kaydırma yok, dokunma hedefleri ≥32px, ARIA etiketli
• Tamamı Türkçe — CDN'siz, çevrimdışı çalışır

Altyapı

• Tek yazma noktası: audit()
• Alan bazlı diff (yalnızca değişen alanlar)
• Hassas alan maskeleme (password, token, cvv …)
• Append-only denetim tablosu
• Veri + kayıt aynı transaction'da
• Sunucu taraflı (server-side) DataTables
• Tek AJAX uç noktası, action tabanlı yönlendirme
• CSRF + hız sınırı (yazma ve dışa aktarım ayrı)
• Alan bazlı hata mesajları (HTTP 422)
• Ortam değişkeni desteği, ortama göre otomatik APP_DEBUG
• Kodun her satırı açıklamalı

---

Güvenlik: Neyi, Nasıl Kapattık?

---

Yapılandırma

Tüm ayarlar system/config.php içinde, açıklamalarıyla birlikte:

AUDIT_MODE: diff mi full mü?

| | diff | full |
|-|--------|--------|
| Yazılan veri | Yalnızca değişen alanlar | Satırın tamamı |
| Tablo boyutu | Küçük | Büyür |
| "O an kayıt neydi?" | Zincirin tamamını okumak gerekir | Tek satırda cevap |
| Uygun olduğu yer | Sık güncellenen tablolar | Yasal saklama, geri alma (rollback) senaryoları |

Bu örnek diff kullanır. full'e geçmek tek satırlık bir değişikliktir; kod yolu ikisini de destekler.

Şifreyi koda yazmayın

Tüm DB_* sabitleri ortam değişkeniyle geçersiz kılınabilir:

# Linux / macOS
export DB_HOST=localhost DB_USER=uygulama DB_PASS='••••••••'

# Windows (PowerShell)
$env:DB_USER = "uygulama"; $env:DB_PASS = "••••••••"

Apache için .htaccess ya da httpd.conf içinde: SetEnv DB_PASS "guclu-sifre"

---

Kendi Projenize Eklemek

Denetim katmanını taşımak için iki dosya yeter: audit_log tablosu ve audit() fonksiyonu.

1 — Tabloyu oluşturun (cy_audit.sql içindeki CREATE TABLE audit_log bloğu)

2 — audit() ve yardımcılarını kopyalayın (system/function.php → BÖLÜM 5)

3 — Her yazma işleminden sonra çağırın:

// EKLEME — old yok
$db->beginTransaction();
$stmt->execute([...]);
$newId = (int) $db->lastInsertId();
audit($db, 'create', 'siparis', $newId, null, $data);
$db->commit();

// GÜNCELLEME — ÖNCE eski satırı okuyun, diff için şart
$old = $db->prepare('SELECT ... WHERE id = ?') /* ... */ ->fetch();
$db->beginTransaction();
$stmt->execute([...]);
audit($db, 'update', 'siparis', $id, $old, $data);
$db->commit();

// SİLME — new yok; old, kaydın son kopyasıdır
audit($db, 'delete', 'siparis', $id, $old, null);

4 — Yeni varlığı tanıtın (system/config.php):

define('AUDIT_ENTITIES', ['product' => 'Ürün', 'siparis' => 'Sipariş']);

5 — Alan etiketlerini ekleyin (system/function.php → FIELD_LABELS) — isteğe bağlıdır; eklemezseniz ham sütun adı gösterilir.

Aktör kim, nereden geliyor?
audit() aktörü $_SESSION['user_id'] ve $_SESSION['user_name'] üzerinden okur. Bu örnekte gerçek giriş olmadığı için system/ajax.php başında sahte bir aktör yazılır. Kendi projenizde o iki satırı silin; oturum zaten giriş sisteminizden gelecektir.

---

Çılgın Yazılım Tasarım Kalıbı

assets/css/cilginyazilim.css dosyası bu projeye değil markaya aittir. Diğer örnek projelerde de aynı görsel dili kullanabilmek için ayrı bir dosya olarak tutulur; bu örneğe özgü her şey (sayaç şeridi, işlem rozetleri, diff tablosu) assets/css/style.css içindedir.

Hazır bileşenler

Bu örneğe özgü (style.css): .cy-stats / .cy-stat, .cy-op--create|update|delete, .cy-diff / .cy-diff__old / .cy-diff__new, .cy-filters, .cy-stock, .cy-sku.

Renkleri değiştirmek

Tüm bileşenler CSS değişkenlerinden beslenir. Tek yeri değiştirmek yeter:

:root {
    --cy-brand-900: #061321;   /* Logodaki en koyu lacivert */
    --cy-brand-600: #0b5cb5;   /* Ana marka mavisi          */
    --cy-accent:    #0ea5e9;   /* Vurgu rengi               */
    --cy-gradient:  linear-gradient(135deg, #061321, #0b5cb5 45%, #0284c7);
}

Koyu tema

Kullanıcının işletim sistemi koyu temadaysa otomatik devreye girer. Zorlamak isterseniz:

<html data-cy-theme="dark">   <!-- veya "light" -->

---

Dosya Yapısı

.
├── index.php                      # Arayüz (sunum katmanı) — veritabanına dokunmaz
├── .env.example                   # Veritabanı bilgileri (isteğe bağlı) — .gitignore içinde
├── cy_audit.sql                   # Şema + 12 ürün + 8 örnek denetim kaydı
├── README.md / README.en.md       # Belgelendirme
├── CHANGELOG.md                   # Sürüm notları
├── LICENSE                        # MIT
├── .htaccess                      # Güvenlik başlıkları, dosya erişim kuralları
├── .gitignore
│
├── docs/
│   └── screenshots/               # README'de kullanılan ekran görüntüleri
│
├── system/
│   ├── config.php                 # Ayarlar, oturum, PDO bağlantısı
│   ├── function.php               # ★ audit() — tek yazma noktası + diff + maskeleme
│   ├── ajax.php                   # AJAX uç noktası / action yönlendiricisi
│   └── .htaccess                  # Bu klasöre doğrudan erişimi kısıtlar
│
└── assets/
    ├── css/
    │   ├── bootstrap.min.css
    │   ├── dataTables.bootstrap5.min.css
    │   ├── cilginyazilim.css      # ★ MARKA TASARIM KALIBI
    │   └── style.css              # Sadece bu sayfaya özel eklemeler
    ├── js/
    │   ├── jquery-3.7.0.js
    │   ├── bootstrap.bundle.js
    │   ├── jquery.dataTables.min.js
    │   ├── dataTables.bootstrap5.min.js
    │   └── audit.js               # ★ Arayüz mantığı
    └── images/logo.png

Yükleme sırası önemlidir:

CSS:  bootstrap → dataTables → cilginyazilim → style
JS:   jQuery → bootstrap.bundle → dataTables → dataTables.bootstrap5 → audit

---

Nasıl Çalışıyor?

┌─────────────────────────────────────────────────────────────────────┐
│  TARAYICI  (index.php + assets/js/audit.js)                         │
│                                                                      │
│  Ürün tablosu ──┐                                                    │
│  Form gönder ───┤                                                    │
│  Filtreler ─────┼──► jQuery AJAX ──► POST { action, csrf_token, … }  │
│  Geçmiş tablosu ┘                            │                       │
│                                              │                       │
│  Yazma bitince refreshAll():                 │                       │
│    ürün tablosu + geçmiş tablosu + sayaçlar  │                       │
└──────────────────────────────────────────────┼───────────────────────┘
                                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│  SUNUCU  (system/ajax.php)                                          │
│                                                                      │
│   1. POST mu?                    → değilse 405                      │
│   2. require_csrf()              → geçersizse 403                   │
│   3. rate_limit()                → aşılırsa 429                     │
│   4. action'a göre dağıt                                            │
│   5. validate_product()          → hatalıysa 422 + errors           │
│                                                                      │
│   6. ┌── BEGIN TRANSACTION ───────────────────────────────┐         │
│      │   INSERT / UPDATE / DELETE  →  products            │         │
│      │   audit()                   →  audit_log           │         │
│      │     ├─ diff_values()  : yalnızca değişen alanlar   │         │
│      │     ├─ redact()       : hassas alanlar → '***'     │         │
│      │     └─ audit_json()   : bozuk bayt → U+FFFD        │         │
│      └── COMMIT  (biri patlarsa ROLLBACK: ikisi de yok)   ┘         │
│                                                                      │
│   7. json_response()             → tek noktadan JSON çıkışı         │
└─────────────────────────────────────────────────────────────────────┘

Sorumluluk dağılımı

---

AJAX API Referansı

Tüm istekler POST ile system/ajax.php adresine yapılır ve geçerli bir csrf_token içermelidir.

action=product_list — Ürün listesi (DataTables)

İstek: draw, start, length, search[value], order[0][column], order[0][dir]

Sıralanabilir sütunlar beyaz listeyle sınırlıdır: 0 → id, 1 → name, 2 → sku, 3 → price, 4 → stock, 5 → updated_at. İşlem sütunu (6) veritabanı sütunu olmadığı için sıralanamaz.

action=product_save — Ekleme / güncelleme

İstek: id (0 veya boş → ekleme), name, sku, price, stock

Başarılı (200):

{ "success": true, "type": "success", "description": "Ürün güncellendi (2 alan).", "id": 5 }

Mesajdaki alan sayısı diff_values() çıktısından gelir. Hiçbir alan değişmediyse "Değişiklik yapılmadı." döner ve denetim kaydı yazılmaz.

Doğrulama hatası (422):

{
  "success": false, "type": "danger",
  "description": "Lütfen formdaki hataları düzeltin.",
  "errors": { "sku": "SKU 2-40 karakter; büyük harf, rakam ve tire." }
}

errors anahtarları form alanlarının name değerleriyle birebir aynıdır. SKU çakışmasında 409 döner, gövde yine errors.sku taşır.

action=product_fetch — Tek ürün (form doldurma)

İstek: id — Hazır HTML değil ham veri döner:

{ "success": true, "product": { "id": 5, "name": "Laptop Soğutucu Stand", "sku": "STND-COOL", "price": "429.90", "stock": 58 } }

action=product_delete — Silme

İstek: id — Ürün silinir, delete denetim kaydı yazılır. old_values kaydın son hâlinin tamamını taşır; bu, silinen kaydın tek kopyasıdır.

action=audit_list — Denetim listesi (salt-okunur)

İstek: DataTables parametreleri + f_action, f_entity, f_from, f_to

Filtreler audit_filters() içinde tek yerden kurulur; audit_export aynı fonksiyonu kullanır, böylece ekrandaki liste ile inen dosya asla ayrışmaz.

action=audit_detail — Alan bazlı diff

İstek: id

{
  "success": true,
  "meta": { "id": 5, "time": "27.08.2026 13:20:38", "actor": "Mehmet YILMAZ",
            "action": "update", "action_tr": "Güncellendi", "entity": "Ürün #5",
            "ip": "10.0.0.12", "user_agent": "Mozilla/5.0 …" },
  "diff": [
    { "field": "price", "label": "Fiyat",      "old": "379.90", "new": "429.90" },
    { "field": "stock", "label": "Stok adedi", "old": 95,       "new": 58 }
  ]
}

field ham sütun adıdır (veritabanına yazılan), label ekranda gösterilen Türkçe etikettir. null = o alan bu işlemde yoktu (create'te old, delete'te new).

action=audit_export — CSV dışa aktarım

İstek: f_action, f_entity, f_from, f_to, search_value

text/csv döner (Content-Disposition: attachment). UTF-8 BOM'lu, ; ayraçlı — Türkçe Excel'de doğrudan açılır. Her değişen alan ayrı satırdır, böylece dosya Excel'de süzülebilir.

action=stats — Sayaç şeridi

{ "success": true, "products": 12, "total": 8, "create": 3, "update": 4, "delete": 1, "last": "30.08.2026 07:20:38" }

Dört sayaç tek sorguda üretilir (SUM(action = '…')), tablo bir kez taranır.

HTTP durum kodları

---

Veritabanı Şeması

CREATE TABLE `audit_log` (
  `id`          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
  `actor_id`    INT UNSIGNED NULL DEFAULT NULL,
  `actor_name`  VARCHAR(150) NOT NULL DEFAULT 'Sistem',
  `action`      ENUM('create','update','delete') NOT NULL,
  `entity_type` VARCHAR(60)  NOT NULL,       -- 'product', 'siparis' …
  `entity_id`   BIGINT UNSIGNED NOT NULL,
  `old_values`  JSON NULL,                   -- create'te NULL
  `new_values`  JSON NULL,                   -- delete'te NULL
  `ip`          VARCHAR(45)  NOT NULL DEFAULT '',
  `user_agent`  VARCHAR(255) NOT NULL DEFAULT '',
  `created_at`  TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_audit_entity`  (`entity_type`, `entity_id`),
  KEY `idx_audit_action`  (`action`),
  KEY `idx_audit_actor`   (`actor_id`),
  KEY `idx_audit_created` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

---

Sık Sorulanlar

Denetim tablosu ne kadar büyür? Ne yapmalıyım?

diff modunda bir güncelleme satırı tipik olarak 150–400 bayt tutar. Günde 10.000 işlem yapan bir sistemde yıllık ~1 GB eder. İki yaygın strateji:

1. Bölümleme (partitioning): created_at üzerinden aylık RANGE bölümleri; eski bölümü tek komutla düşürürsünüz.
2. Arşivleme: N aydan eski satırları soğuk bir tabloya/dosyaya taşıyın. Silmeyin — arşivleyin; denetim kaydını silmek, tuttuğunuz kaydın anlamını zayıflatır.

Neden logs tablosuna cümle yazmıyoruz?

"Ahmet ürünü güncelledi" cümlesi üç soruyu da cevapsız bırakır: hangi alan, neydi, ne oldu? Ayrıca aranamaz, süzülemez ve raporlanamaz. Alan bazlı diff ise "price alanı 429.90'dan 599.90'a çekilmiş" sorusunu SQL ile cevaplayabilir hâle getirir.

audit_log tablosunu veritabanı seviyesinde de kilitleyebilir miyim?

Evet, önerilir. Uygulama kullanıcısına o tabloda yalnızca ekleme ve okuma yetkisi verin:

REVOKE UPDATE, DELETE ON cy_audit.audit_log FROM 'uygulama'@'localhost';
GRANT  INSERT, SELECT ON cy_audit.audit_log TO   'uygulama'@'localhost';

Böylece bir SQL injection açığı bile denetim kaydını değiştiremez.

Hassas alanları maskelemek yerine hiç yazmasam olmaz mı?

Olur ama bilgi kaybedersiniz. *** yazmak "bu alan değişti ama içeriğini saklamıyoruz" der; hiç yazmamak ise "bu alan hiç değişmedi" ile karışır. Denetimde bu ikisi çok farklı iki cümledir.

Denetim kaydını başka bir veritabanına yazabilir miyim?

Yazabilirsiniz ama transaction garantisini kaybedersiniz — bu projedeki en önemli özelliklerden biri budur. Ayrı sunucu gerekiyorsa önce yerel tabloya yazın, sonra bir kuyruk işçisiyle kopyalayın.

Neden hem istemcide hem sunucuda doğrulama var?

İstemci doğrulaması kullanıcı deneyimi içindir; JavaScript kapatılabilir veya istek doğrudan curl ile atılabilir. Gerçek koruma her zaman sunucudadır.

serverSide: true ayarını kapatabilir miyim?

Ürün tablosunda kapatabilirsiniz. Denetim tablosunda kapatmayın: o tablo hızla yüz binlerce satıra ulaşır ve hepsini tarayıcıya indirmek sayfayı dondurur.

---

Canlı Ortama Alırken

• [ ] APP_DEBUG zaten ortamdan türetiliyor — yine de canlıda false olduğunu doğrulayın
• [ ] Veritabanı için root yerine sınırlı yetkili bir kullanıcı oluşturun
• [ ] audit_log tablosunda uygulama kullanıcısından UPDATE ve DELETE yetkisini alın
• [ ] Kimlik bilgilerini ortam değişkeni olarak tanımlayın, koda gömmeyin
• [ ] HTTPS kullanın; session.cookie_secure = 1 ve session.cookie_httponly = 1 ayarlayın
• [ ] Giriş sistemi ekleyin ve system/ajax.php başındaki sahte aktör satırlarını silin
• [ ] Nginx kullanıyorsanız .htaccess çalışmaz; .sql ve .md erişimini sunucu yapılandırmasından kapatın:

```nginx
location ~* \.(sql|log|ini|bak)$ { deny all; }
```

• [ ] Denetim tablosu için arşivleme / bölümleme planı yapın
• [ ] audit_log yedeklerini ana veriyle aynı sıklıkta alın

---

Sorun Giderme

---

Yol Haritası

• [ ] Denetim kaydından geri alma (rollback): old_values ile kaydı eski hâline döndürme
• [ ] full modda satır anlık görüntülerinden zaman çizelgesi görünümü
• [ ] Kullanıcı girişi ve rol tabanlı yetkilendirme (yalnızca yöneticiler geçmişi görsün)
• [ ] Denetim tablosu için otomatik arşivleme / bölümleme betiği
• [ ] Webhook: belirli alanlar değiştiğinde bildirim gönderme
• [ ] Excel (XLSX) ve PDF dışa aktarım
• [ ] PHPUnit ile birim testleri (diff_values, redact, valid_date)
• [ ] Koyu tema için elle açma/kapama düğmesi

---

Katkı

Bu proje herkese açıktır — dilediğiniz geliştirmeyle katkı sağlayabilirsiniz.

📦 Depo: github.com/CilginYazilim/audit-log

Katkı ölçütleri

• Kod açıklamalı olsun. Bu projenin temel amacı öğretmek; yorumsuz kod PR'ı geri döner.
• audit_log tablosuna yazma uç noktası eklemeyin. Append-only olması projenin tezidir.
• Yeni bir yazma işlemi eklerken audit() çağrısını ve transaction'ı unutmayın.
• Tasarım değişikliklerini style.css üzerinden yapın; cilginyazilim.css markaya aittir ve diğer projelerle ortaktır.
• Yeni bir dış kütüphane eklemeden önce issue açıp tartışalım — proje bilinçli olarak bağımlılıksızdır.

---

Lisans

MIT — ticari kullanım dahil serbesttir.