# OpenAI Entegrasyon Detay Raporu

## 1. Amaç ve Kapsam
Bu rapor, projede OpenAI kullanımının:
- nasıl planlandığını,
- backend ve frontend tarafında nasıl entegre edildiğini,
- hangi sayfa/ekranda hangi AI özelliğinin nasıl kurgulandığını
kanıta dayalı şekilde ortaya koyar.

İnceleme, kod ve dokümantasyon birlikte doğrulanarak hazırlanmıştır.

## 2. İnceleme Yöntemi
Çalışma sırasında çoklu alt ajan yaklaşımı kullanıldı:
- Backend akışı (route-controller-service-model-RAG)
- Frontend/sayfa entegrasyonu (widget, context, SSE UX)
- Dokümantasyon ve plan izi (mimari dokümanlar, operasyon notları)

Sonrasında bulgular doğrudan koddan doğrulanmıştır.

## 3. Yönetici Özeti
Projede OpenAI entegrasyonu iki ana hatta ilerliyor:
1. Canlı AI Asistan chat akışı (SSE streaming)
2. Uzun rapor üretimi (Natal, Annual, Relationship)

Bunlara ek olarak RAG/embedding katmanı mevcut ve chat yanıtlarına destekleyici bağlam sağlıyor.

Mimari genel olarak modüler ve temiz:
- Thin controller: [app/Http/Controllers/Frontend/AIAssistantController.php](app/Http/Controllers/Frontend/AIAssistantController.php)
- Orkestrasyon: [app/Services/Ai/AiService.php](app/Services/Ai/AiService.php)
- OpenAI API katmanı: [app/Services/OpenAI/OpenAIServiceRefactored.php](app/Services/OpenAI/OpenAIServiceRefactored.php)
- Prompt kompozisyonu: [app/Services/OpenAI/Prompts/SystemPromptBuilder.php](app/Services/OpenAI/Prompts/SystemPromptBuilder.php)
- Prompt seçimi: [app/Services/OpenAI/PromptSelectorService.php](app/Services/OpenAI/PromptSelectorService.php)

## 4. Planlama ve Mimari Kurgusu

### 4.1 Dokümantasyon temelli plan
Mevcut tasarım dokümanları entegrasyonun niyetini açıkça tarif ediyor:
- Chat mimarisi ve katmanlar: [docs/CHAT-ARCHITECTURE.md](docs/CHAT-ARCHITECTURE.md)
- Context-aware davranış: [docs/CHAT-AI-CONTEXT-AWARE.md](docs/CHAT-AI-CONTEXT-AWARE.md)
- Transit prompt veri akışı: [docs/CHAT-TRANSIT-PROMPT-FLOW.md](docs/CHAT-TRANSIT-PROMPT-FLOW.md)
- Operasyon/timeout: [docs/SERVER_TIMEOUT_NATAL_REPORT.md](docs/SERVER_TIMEOUT_NATAL_REPORT.md)
- Log gözlemleme: [docs/LOG-BAKMA.md](docs/LOG-BAKMA.md)

### 4.2 Kodda gerçekleşen mimari
- OpenAI servis sağlayıcısı DI ile mapper/transformer/prompt/openai servislerini register ediyor:
  [app/Providers/OpenAIServiceProvider.php](app/Providers/OpenAIServiceProvider.php)
- Wrapper yaklaşımıyla eski bağımlılık kırılmadan refactor edilmiş servis kullanılıyor:
  [app/Services/OpenAIService.php](app/Services/OpenAIService.php)

## 5. OpenAI Entegrasyon Katmanları

### 5.1 Endpoint ve route katmanı
Web tarafı:
- GET strings/context/context-aspects
- POST send-message
- POST generate-pdf (auth)
- GET history/sessions + detail (auth)

Kaynak: [routes/web.php](routes/web.php#L72)

API tarafında mobil/harici tüketim için aynı AI endpointleri de açılmış:
Kaynak: [routes/api.php](routes/api.php#L111)

### 5.2 Controller katmanı
AI controller tamamen thin, tüm işi servise delege ediyor:
- strings/context/contextAspects/sendMessage/generatePdf/history

Kaynak: [app/Http/Controllers/Frontend/AIAssistantController.php](app/Http/Controllers/Frontend/AIAssistantController.php)

### 5.3 Servis orkestrasyonu
Ana iş akışı [app/Services/Ai/AiService.php](app/Services/Ai/AiService.php) içinde:
- input validasyon
- panel/chart context toplama
- prompt type çözümleme
- context-aware prompt ekleme
- RAG araması
- SSE stream başlatma
- konuşma kayıtları (user/assistant)
- embedding saklama

Önemli metodlar:
- getContext
- getConversationSessions / getConversationSessionDetail
- sendMessage
- generatePdf
- performRagSearch
- storeConversationMessage
- storeChartEmbeddingIfNeeded

### 5.4 OpenAI HTTP katmanı
[app/Services/OpenAI/OpenAIServiceRefactored.php](app/Services/OpenAI/OpenAIServiceRefactored.php)
- Chat endpoint: https://api.openai.com/v1/chat/completions
- Streaming: stream=true, timeout(0)
- Model: services.openai.model (default gpt-4o-mini)
- Hata sınıflama: quota/rate_limit/api

Embedding tarafı ayrı servis:
[app/Services/EmbeddingService.php](app/Services/EmbeddingService.php)
- Endpoint: /v1/embeddings
- Model: text-embedding-ada-002

## 6. Prompt Mimarisi (Nasıl kurgulanmış?)

### 6.1 Modüler prompt kompozisyonu
[app/Services/OpenAI/Prompts/SystemPromptBuilder.php](app/Services/OpenAI/Prompts/SystemPromptBuilder.php)

Sistem prompt’u çok sayıda modülden inşa ediliyor (Identity, core rules, analysis protocol, data rules, astrology school, chart category, topic uzmanlık modülleri vb.).

Ayrıca PromptSetting üzerinden DB’den aktif custom içerik override edilebiliyor.

### 6.2 Dinamik prompt seçimi
[app/Services/OpenAI/PromptSelectorService.php](app/Services/OpenAI/PromptSelectorService.php)

Akış:
- BASE_KEYS her zaman eklenir
- prompt_type (general/career/strengths/challenges/synastry) varsa doğrudan ilgili key seti seçilir
- yoksa mesajdaki keywordlerle topic key tespiti yapılır
- fallback hesaplama durumunda fallback_warning dahil edilir

### 6.3 Context-aware prompt
[app/Services/AiAsistan/PageContextService.php](app/Services/AiAsistan/PageContextService.php)

Kullanıcı panelde değilse sistem promptuna yönlendirici davranış metni ekleniyor:
- login/register/other (unauth)
- authenticated ama panel dışı

Panelde ise ekstra context prompt eklenmiyor (normal astroloji asistan akışı).

## 7. Harita Verisinin Prompt’a Taşınması

### 7.1 Chart data dönüşümü
[app/Services/OpenAI/Transformers/ChartDataTransformer.php](app/Services/OpenAI/Transformers/ChartDataTransformer.php)

Chart data, AI’nin okuyabileceği yapılandırılmış içerik + JSON protokolüne dönüştürülüyor.

### 7.2 buildSystemContent içine ekleme
[app/Services/OpenAI/OpenAIServiceRefactored.php](app/Services/OpenAI/OpenAIServiceRefactored.php#L1916)

Prompt son yapısı:
- prompt modülleri
- context prompt (varsa)
- AKTİF HARİTA VERİLERİ
- EK REFERANS VERİLER (RAG) (varsa)

## 8. RAG ve Embedding Mimarisi

### 8.1 Arama
[app/Services/VectorSearchService.php](app/Services/VectorSearchService.php)

- Sorgu embedding üretilir
- pgvector varsa cosine similarity ile search
- yoksa text fallback
- preferred chart_key + recency + similarity ile rerank

### 8.2 Saklama
- Embedding tablosu: chart_embeddings
- Migration: [database/migrations/2026_01_23_110320_create_chart_embeddings_table.php](database/migrations/2026_01_23_110320_create_chart_embeddings_table.php)

Not: Migration yorumunda PostgreSQL vector tipe manuel dönüşüm notu mevcut.

## 9. Kalıcılık ve Konuşma Kaydı

### 9.1 AiConversation
Model: [app/Models/AiConversation.php](app/Models/AiConversation.php)

Tablo evrimi:
- temel kayıt: [database/migrations/2026_01_26_181243_create_ai_conversations_table.php](database/migrations/2026_01_26_181243_create_ai_conversations_table.php)
- turn/reply zinciri: [database/migrations/2026_03_11_120000_add_turn_fields_to_ai_conversations_table.php](database/migrations/2026_03_11_120000_add_turn_fields_to_ai_conversations_table.php)
- session_uuid: [database/migrations/2026_03_14_000001_add_session_uuid_to_ai_conversations_table.php](database/migrations/2026_03_14_000001_add_session_uuid_to_ai_conversations_table.php)

### 9.2 AiInterpretation cache
Model: [app/Models/AiInterpretation.php](app/Models/AiInterpretation.php)
Migration: [database/migrations/2026_02_13_120000_create_ai_interpretations_table.php](database/migrations/2026_02_13_120000_create_ai_interpretations_table.php)

Prompt hash bazlı cache yaklaşımı kullanılıyor.

## 10. Sayfa ve Özellik Bazlı Entegrasyon Haritası

### 10.1 Global widget entegrasyonu
Ana layout meta/context ve widget include:
- [resources/views/frontend/main_master.blade.php](resources/views/frontend/main_master.blade.php)

Önemli:
- page-context meta
- user-authenticated meta
- AI widget çoğu sayfada global include
- bazı auth/critical sayfalarda gizleniyor

### 10.2 Widget bileşen yapısı
[resources/views/frontend/ai-assistant/chat-widget.blade.php](resources/views/frontend/ai-assistant/chat-widget.blade.php)

Kurgulanan parçalar:
- floating button
- chat window
- context badge
- history panel
- input + send
- AI_ROUTES + AI_STRINGS bootstrap

### 10.3 Panel sayfası (en yoğun entegrasyon)
[resources/views/frontend/panel/panel.blade.php](resources/views/frontend/panel/panel.blade.php)

OpenAI ile ilişkili panel kurguları:
1. AI widget, right-panel içinde docked başlıyor
2. Yorum Al modalı (natal/relationship/annual)
3. generate-natal-report çağrıları
4. AI generate-pdf çağrısı
5. token/chat_words_remaining güncellemeleri

### 10.4 Home/Login/Register ve context etkisi
- Home context: [resources/views/frontend/index.blade.php](resources/views/frontend/index.blade.php)
- Login context: [resources/views/frontend/auth/login.blade.php](resources/views/frontend/auth/login.blade.php)
- Register context meta: [resources/views/frontend/auth/register.blade.php](resources/views/frontend/auth/register.blade.php)

JS tarafında input disable + yönlendirme butonları context’e göre yönetiliyor:
[public/js/ai-assistant/index.js](public/js/ai-assistant/index.js)

### 10.5 AI yorum geçmişi sayfası
- Görünüm: [resources/views/frontend/profile/ai-comments.blade.php](resources/views/frontend/profile/ai-comments.blade.php)
- Controller: [app/Http/Controllers/Frontend/Profile/AiCommentController.php](app/Http/Controllers/Frontend/Profile/AiCommentController.php)

Bu sayfa OpenAI üretimli içeriklerin kullanıcıya sunumu, önizleme ve PDF indirme tarafını kapsıyor.

## 11. Frontend Chat Davranışı (UX Akışı)

Ana dosya: [public/js/ai-assistant/index.js](public/js/ai-assistant/index.js)

Kritik davranışlar:
- page-context tespiti
- welcome message’in context’e göre dinamik üretimi
- panelCollect ile chart/panel parametrelerinin payload’a eklenmesi
- POST send-message (Accept: text/event-stream)
- reader/read loop ile SSE chunk parse
- done/error branch yönetimi
- suggestion butonları
- history sessions + detail ekranı
- conversation_session_uuid localStorage ile kısa süreli devamlılık

## 12. Uzun Rapor Akışı (Natal/Annual/Relationship)

Controller: [app/Http/Controllers/Frontend/IndexController.php](app/Http/Controllers/Frontend/IndexController.php#L1130)

Akış:
1. type kontrolü (natal/annual/relationship)
2. token yeterlilik kontrolü
3. panel/chart data build
4. type’a göre OpenAI long report çağrısı (sendLongReport)
5. UserAiComment kaydı
6. token tüketimi

Ek not:
- Annual rapor için solar return + natal + ek teknikler (solar arc, secondary progression naibod, profection) birlikte işleniyor.
- Firdaria dönem anahtarı ve bazı cache/yeniden üretim kararları bu katmanda yönetiliyor.

## 13. Konfigürasyon ve Ortam Değişkenleri

Konfigürasyon:
- [config/services.php](config/services.php)

OpenAI ayarları:
- services.openai.api_key
- services.openai.model
- services.openai.verify_ssl

## 14. Sequence Diyagramları

### 14.1 Chat (SSE) akışı
```mermaid
sequenceDiagram
    participant U as Kullanıcı
    participant FE as Chat Widget JS
    participant C as AIAssistantController
    participant S as AiService
    participant O as OpenAIServiceRefactored
    participant R as VectorSearchService
    participant DB as DB

    U->>FE: Mesaj gönder
    FE->>C: POST /ai-assistant/send-message
    C->>S: sendMessage(request)
    S->>R: performRagSearch(message, chartKey)
    R-->>S: ragContext
    S->>DB: user mesajını kaydet
    S->>O: sendMessageStream(...)
    O-->>S: chunk chunk stream
    S-->>FE: SSE data:{chunk}
    FE-->>U: Daktilo efektiyle yanıt
    S->>DB: assistant mesajını kaydet
```

### 14.2 Uzun rapor akışı
```mermaid
sequenceDiagram
    participant U as Kullanıcı
    participant FE as Panel Modal JS
    participant I as IndexController
    participant B as ChartPageBuilderService
    participant O as OpenAIService
    participant DB as UserAiComment

    U->>FE: Yorum Al (natal/annual/relationship)
    FE->>I: POST /panel/generate-natal-report
    I->>B: build(panel params)
    B-->>I: chart data
    I->>O: sendLongReport(...)
    O-->>I: rapor metni
    I->>DB: yorumu kaydet
    I-->>FE: JSON(content, chart_title, credits)
```

## 15. Dokümantasyon ve Kod Arasındaki Farklar
1. Bazı dokümanlarda eski endpoint/path adları (ai-asistan, türkçe slug) geçiyor; canlı kodda route’lar ai-assistant olarak güncel.
2. Mimari dokümanlarda controller merkezli anlatım var; güncel kodda asıl iş mantığı büyük ölçüde AiService içinde toplanmış.

## 16. Operasyonel Gözlemler
1. SSE ve uzun raporlar için uygulama timeout’ları yükseltilmiş, ancak sunucu katmanında (nginx/php-fpm) timeout uyumu kritik.
2. Log rehberi mevcut ve hata sınıflama yapısı pratikte operasyonu kolaylaştırıyor.
3. RAG var ancak kalite tamamen chart_embeddings verisinin doluluk/kalitesine bağlı.

## 17. İyileştirme Önerileri
1. Prompt token budgeting eklenmeli (özellikle chart + rag birleşiminde).
2. pgvector migration otomasyonu güçlendirilmeli (manuel adım notları kodda bırakılmış).
3. Eski doküman/path adları güncel route adlarıyla hizalanmalı.
4. RAG için kalite metrikleri (hit ratio, kullanıcı geri bildirim skoru) eklenmeli.

## 18. Sonuç
Bu projede OpenAI entegrasyonu sadece chat çağrısından ibaret değil; chart hesaplama, context-aware davranış, topic bazlı prompt yönlendirme, SSE streaming, uzun rapor üretimi, token bazlı erişim kontrolü ve RAG katmanlarıyla birlikte tam bir AI ürün akışı olarak kurgulanmış durumda.

En kritik entegrasyon merkezi [app/Services/Ai/AiService.php](app/Services/Ai/AiService.php) olup, frontend tarafında [public/js/ai-assistant/index.js](public/js/ai-assistant/index.js) bu akışın kullanıcı deneyimini taşıyan ana bileşendir.