# ASTROBİLGE KALICI SİSTEM CHECKPOINT & MASTER MİMARİ BELGESİ
**Tarih:** 04 Eylül 2026  
**Sürüm:** Üretim Seviyesi & Tam Koruma Altında  
**Git Checkpoint Etiketi:** `checkpoint-ai-chat-reasoning-2026-09-04`  
**Önceki Etiket:** `checkpoint-ai-reasoning-library-2026-09-04`  

---

## 1. YÖNETİCİ ÖZETİ VE CHECKPOINT AMACI
Bu doküman; AstroBilge platformunun **Sohbet (Chat) Veritabanı**, **Sohbet Algoritmaları**, **Yapay Zeka (AI/IA) Mantık Yürütme Motoru (Reasoning Engine)**, **Halüsinasyon Önleme Katmanı**, **Tarihsel Korelasyon Veritabanı** ve **1.301 Kitaplık Kütüphane İçe Aktarma Hattının** eksiksiz ve kalıcı bir kontrol noktasını (checkpoint) oluşturmak amacıyla hazırlanmıştır.

Sistem, yapay zekanın uydurma veya ezbere dayalı astroloji yorumları yapmasını engelleyerek, **klasik kurallar, 45.576 doğrulanmış vaka haritası, 70.573 hayat olayı ve 1.301 otorite kitap** üzerinden milisaniyeler içinde kanıt temelli mantık yürütmesini sağlar.

---

## 2. CHAT (SOHBET) VERİTABANI MİMARİSİ

Sohbet sistemi, oturum bazlı çoklu tur (multi-turn) mimarisine ve tam harita anlık görüntüsü (snapshot) saklama yeteneğine sahiptir.

### 2.1. `ai_conversations` Tablosu
Tüm kullanıcı ve yapay zeka mesajlaşmalarını, kullanılan harita anlık verilerini ve oturum durumlarını saklar.
* **`id` (BIGINT, PK):** Otomatik artan kayıt kimliği.
* **`user_id` (BIGINT, FK -> `users.id`, nullable):** Mesajı atan kullanıcı (veya misafir).
* **`role` (VARCHAR(20)):** Mesaj sahibi (`user` veya `assistant`).
* **`message` (LONGTEXT):** Mesajın tam içeriği.
* **`chart_key` (VARCHAR(80)):** Aktif astrolojik harita tipi (`natal`, `synastry`, `transit`, `solar_arc`, `progressed`, `traditional`, `horary` vb.).
* **`chart_title` (VARCHAR(255)):** Haritanın kullanıcı arayüzündeki başlığı.
* **`user_chart_id` (BIGINT, FK -> `user_charts.id`, nullable):** Kullanıcının kayıtlı haritası.
* **`chart_data` (JSON):** Mesaj anındaki tüm gezegen konumları, evler, açılar ve koordinatların dondurulmuş anlık görüntüsü (snapshot).
* **`metadata` (JSON):** İstek bağlamı (sayfa bilgisi, soru tipi, token sayısı, ekol, dilimleme durumu).
* **`turn_uuid` (UUID):** Her soru-cevap turu için tekil kimlik.
* **`session_uuid` (UUID):** Çoklu tur konuşmaları birbirine bağlayan konuşma oturumu kimliği.
* **`reply_to_id` (BIGINT, FK -> `ai_conversations.id`, nullable):** Asistan cevabının referans aldığı kullanıcı sorusu.
* **İndeksler:** `user_id`, `session_uuid`, `turn_uuid`, `chart_key`, `created_at`.

### 2.2. `ai_interpretations` Tablosu
Aynı astrolojik konum ve soru kalıpları için üretilen profesyonel yorumları önbelleğe alarak maliyeti sıfırlar ve anında yanıt üretir.
* **`prompt_hash` (CHAR(64), UNIQUE):** SHA-256 hash anahtarı.
* **`prompt` (TEXT):** Üretilen prompt metni.
* **`content` (LONGTEXT):** Yapay zeka veya kütüphane tarafından üretilmiş doğrulanmış yanıt metni.

### 2.3. `user_ai_usage_logs` Tablosu
Her kullanıcının AI kullanımını, token tüketimini ve paket kotalarını hassas şekilde denetler.
* **`user_id`, `feature_key`, `tokens_prompt`, `tokens_completion`, `tokens_total`, `model_name`, `created_at`.**

### 2.4. `user_ai_comments` Tablosu
Kullanıcıların yapay zeka yorumlarına verdiği geri bildirimleri (beğeni, puan, detaylı yorum) toplar.

### 2.5. `prompt_settings` Tablosu
Sistem promptlarını, sıcaklık (temperature), model seçimini (GPT-4o, Claude vb.) dinamik olarak yönetir.

---

## 3. CHAT (SOHBET) ALGORİTMASI VE AKIŞI

Chat mimarisi **ince kontrolcü (thin controller) - kalın servis (fat service)** prensibiyle çalışır.

### 3.1. Uç Noktalar (`AIAssistantController`)
* **`POST /ai-assistant/send-message`:** Ana sohbet motoru. SSE (Server-Sent Events) akışı veya JSON formatında yanıt döner.
* **`GET /ai-assistant/strings`:** Çok dilli arayüz metinleri.
* **`GET /ai-assistant/context`:** İstemci tarafında aktif harita verilerini yükler.
* **`GET /ai-assistant/context-aspects`:** Harita açı tablosunu çeker.
* **`GET /ai-assistant/history/sessions`:** Kullanıcının geçmiş konuşma oturumlarını listeler.
* **`GET /ai-assistant/history/sessions/{turnUuid}`:** Belirli bir turun detayını ve harita anlık görüntüsünü getirir.

### 3.2. Akıllı Yanıt Pipeline'ı (`AiService::sendMessage`)
1. **Validasyon ve Güvenlik:** Girdi uzunluğu, oturum UUID ve harita formatları doğrulanır.
2. **Kütüphane Fast-Path (Sıfır Maliyetli Hızlı Yanıt):**
   - Kullanıcı doğrudan astrolojik bir tanım soruyorsa (ör. *"Venüs Satürn karesi ne demek"*, *"Algol nedir"*, *"Güneş Koç ne anlama gelir"*), yapay zeka API'sine gitmeden veritabanından doğrulanmış yorum 1-3 ms içinde döner.
3. **Akıllı Soru Sınıflandırma (`QuestionTopicClassifierService`):**
   - Soru kariyer, ilişki, sağlık, finans, horary, firdaria gibi 12 temel alandan hangisine ait tespit edilir.
4. **Harita Dilimleme (`ChartDataSlicerService`):**
   - Modelin kafasını karıştırmamak ve token tasarrufu sağlamak için sadece ilgili gezegenler ve evler modele aktarılır.
5. **Kesin Matematiksel Doğrulama (`AstrologicalHallucinationGuardService`):**
   - İsviçre Efemerisi (Swetest) ile hesaplanmış gerçek dereceler sistem promptuna "Ground Truth" olarak mühürlenir. Modelin haritada olmayan bir açıyı uydurması imkansız kılınır.
6. **Mantık Yürütme ve Çıkarım Dosyası (`AstrologicalReasoningEngine`):**
   - Haritadaki asaletler, Almuten Figuris, Mısır sınır yöneticileri, dekanlar ve tarihsel 45.576 vaka eşleştirmesi dosyalanır.
7. **Sentez Direktifi (`AstrologicalSynthesizerService`):**
   - Çoklu ajan sentez kuralları eklenir.
8. **Kütüphane ve Kitap Entegrasyonu (`AstrologyLibraryService`):**
   - Sabian sembolleri, Charubel dereceleri ve 1.301 kitaptan ilgili pasajlar çekilir.
9. **Akışlı Yanıt (Streaming SSE):**
   - Kullanıcıya kelime kelime canlı yanıt iletilir, yanıt bittiğinde `ai_conversations` tablosuna otomatik kalıcı kayıt yapılır.

---

## 4. YAPAY ZEKA (IA) VE MANTIK YÜRÜTME ALGORİTMASI (REASONING ENGINE)

Yapay zeka çıkarım motoru `AstrologicalReasoningEngine.php` dosyasında yer alır ve klasik astrolojinin derin mantığını yürütür:

### 4.1. Asalet ve Güç Analizi (Essential & Accidental Dignities)
* **Yöneticilik (Domicile):** Gezegenin kendi evinde olması (+5 puan).
* **Yücelim (Exaltation):** Gezegenin onurlandırıldığı burçta olması (+4 puan).
* **Üçlü Yöneticiliği (Triplicity):** Dorotheus üçlü yöneticilikleri (+3 puan).
* **Mısır Sınırları (Egyptian Terms/Bounds):** Gezegenin mikro derece yöneticiliği (+2 puan).
* **Dekan / Yüz (Chaldean Faces/Decans):** 10 derecelik mikro yöneticilik (+1 puan).
* **Zarar (Detriment) ve Düşüş (Fall):** -5 ve -4 puanlık zayıflık tespiti.
* **Almuten Figuris:** Haritanın en güçlü ve bilge gezegeninin matematiksel olarak bulunması.

### 4.2. Halüsinasyon Önleme Kalkanı (`AstrologicalHallucinationGuardService`)
* Tolerans (orb) dışındaki hiçbir açıyı yapay zekanın kabul etmesine izin vermez.
* Hangi gezegenin hangi evde olduğu "DEĞİŞTİRİLEMEZ GERÇEK" (GROUND TRUTH) olarak promptun başına kilitlenir.

### 4.3. Çoklu Ajan Sentezi (`AstrologicalSynthesizerService`)
* Soru aşk ise Venüs, Mars, 7. ev yöneticisi ve Ay arasındaki köprüleri sentezler.
* Soru kariyer ise MC (10. ev), Satürn, Güneş ve 2./6. ev yöneticilerini çapraz değerlendirir.

---

## 5. BİLGİ VE DOĞRULAMA VERİTABANI ENVANTERİ

Platform bünyesindeki veritabanı büyüklüğü ve doğrulanmış veri varlıkları:

| Veri Varlığı | Kayıt Sayısı | Açıklama |
| :--- | :--- | :--- |
| `biography_cases` | **45.576** | Solar Fire 9 doğrulanmış harita veritabanı (33.855 AA, 10.796 A, 922 B sınıfı). Çift dilli (TR/EN). |
| `biography_case_events` | **70.573** | Doğrulanmış hayat olayları (tarih, saat, koordinat, olay tipi). |
| `astrology_wiki_articles` | **1.690** | Çift dilli (TR/EN) astroloji ansiklopedisi makaleleri. |
| `astrology_interpretations_library` | **934** | Sabian 360°, Charubel 360°, Vivian Robson 121 sabit yıldız kuralı, Sakoian/Pelletier açı kuralları. |
| `astrology_book_library` | **Büyüyor** (1.301 Kitap) | 1.301 adet Word/PDF kitabın tam metin bölümleri ve MySQL Full-Text indeksi. |
| `user_charts` | **104+** | Kayıtlı kullanıcı doğum haritaları. |

---

## 6. SÜREGELEN ARKA PLAN İŞLEMLERİ (DAEMON)

* **Görev:** `php artisan astro:ingest-all-books --limit=0`
* **Kaynak:** `storage/app/yazarlara_gore.zip` (2.44 GB, 1.301 Kitap).
* **Güvenlik ve Performans Tasarımı:**
  - Disk alanı tükenmesini önlemek için NTFS Hardlink kullanılmıştır (0 bayt ek disk harcar).
  - Kitaplar disk üzerinde toplu olarak açılmaz; zip akışından tek tek okunur, geçici dosya silinir ve RAM korunur.
  - Hata dayanıklılığı: Başlıklar 240 karakter ile güvenli şekilde kırpılır, veritabanı `chapter_title` alanı `TEXT` tipindedir.
  - İlerleme dosyası: `storage/app/astro_books_ingestion_progress.json`.

---

## 7. YEDEK VE KURTARMA (DISASTER RECOVERY)

1. **Git Checkpoint:**
   - Kod tabanındaki tüm geliştirmeler Git sürüm kontrolünde mühürlenmiştir:
   ```bash
   git checkout checkpoint-ai-chat-reasoning-2026-09-04
   ```
2. **Veritabanı Tablolarının Korunması:**
   - `ai_conversations`, `astrology_interpretations_library`, `astrology_book_library`, `biography_cases` tabloları MySQL üzerinde InnoDB motoru ve UTF8MB4 karakter seti ile kalıcı olarak korunmaktadır.