# Astro Bilge Backend – Proje İncelemesi

Projenin baştan aşağı özet yapısı, teknolojiler ve ana bileşenler.

---

## 1. Genel Bilgi

| Özellik | Değer |
|--------|--------|
| **Proje adı** | Astro Bilge (astro-bilge-backend) |
| **Tür** | Astroloji web uygulaması – doğum/ilişki haritaları, AI asistan, içerik siteleri |
| **Backend** | Laravel 12, PHP 8.2+ |
| **Frontend** | Blade + vanilla JS, Tailwind 4, Vite 7 |
| **Veritabanı** | Laravel migrations (MySQL/PostgreSQL uyumlu), pgvector (RAG) |

---

## 2. Dizin Yapısı (Özet)

```
astro-bilge-backend/
├── app/
│   ├── Contracts/          # Arayüzler (Logout, SocialAuth)
│   ├── Helpers/             # Yardımcı fonksiyonlar
│   ├── Http/Controllers/
│   │   ├── Admin/           # Blog, kategori, sayfa, analytics
│   │   ├── Api/              # AstroController (harita API)
│   │   └── Frontend/         # Auth, Panel, AI Asistan, Profil, Faturalar
│   ├── Models/              # User, UserChart, Blog, Page, Invoice, vb.
│   ├── Notifications/       # E-posta bildirimleri
│   ├── Providers/           # App, OpenAIService
│   ├── Services/
│   │   ├── AiAsistan/        # Prompt şablonları, UI metinleri
│   │   ├── Auth/             # Logout, Social, 2FA
│   │   ├── Chart/            # Harita hesaplama, görselleştirme, katalog
│   │   ├── DualChart/        # İkili harita
│   │   ├── OpenAI/           # AI asistan: prompt’lar, transformer’lar, mapper’lar
│   │   ├── Sms/              # NetGsm
│   │   ├── SwetestService.php    # Swiss Ephemeris (swetest) – gezegen/ev hesapları
│   │   ├── ChartVisualizerService.php
│   │   ├── RelationshipChartService.php
│   │   ├── VectorSearchService.php  # RAG (embedding + pgvector)
│   │   └── ...
│   └── View/Components/      # Breadcrumb, LogoutButton, UserAvatar
├── config/                   # app, auth, database, sanctum, locales, vb.
├── database/migrations/     # users, charts, blogs, pages, ai_conversations, visitors, vb.
├── docs/                     # Mimari, akış, manuel test
├── public/
│   ├── js/ai-asistan/        # Chat widget (fetch, SSE, CSRF)
│   ├── frontend/             # CSS, fonts, images
│   ├── admin/                # Admin panel JS
│   └── assets/               # Görseller, SVG
├── resources/views/
│   ├── frontend/             # auth, panel, profile, planets, zodiac, birth-chart, ai-asistan
│   ├── admin/
│   └── components/
├── routes/
│   ├── web.php               # Tüm web rotaları (auth, panel, sayfalar, admin)
│   └── api.php               # Sanctum API: register, login, chart, my-charts
├── tests/                    # Pest (Unit + Feature)
└── storage/                  # logs, app, framework
```

---

## 3. Teknoloji ve Paketler

**Composer (PHP):**
- `laravel/framework` ^12
- `laravel/sanctum` (API token)
- `laravel/socialite` (Google, Facebook)
- `barryvdh/laravel-dompdf` (PDF)
- `intervention/image` (görsel işleme)
- Pest (test)

**NPM:**
- Vite 7, Tailwind 4, Laravel Vite Plugin
- Axios, Puppeteer (bağımlılık)
- Concurrently (dev: server + queue + vite)

**Harici bileşen:**
- **Swiss Ephemeris (swetest)**: `storage/app/sweph/` içinde; gezegen, ev, açı, draconic, solar return, profection, horary vb. hesaplar bu binary ile yapılıyor.

---

## 4. Kullanıcı ve Yetkilendirme

- **Web:** Session tabanlı auth; `guest` / `auth` middleware.
- **API:** Laravel Sanctum (`auth:sanctum`) – token ile `/api/chart`, `/api/my-charts` vb.
- **Admin:** Ayrı guard (`admin.auth`), Admin modeli; `/admin/login`, `/admin/dashboard`.
- **Sosyal giriş:** Google, Facebook (SocialAuthController, LegalController – veri silme callback).
- **2FA:** TwoFactorController, TwoFactorService; kod e-posta ile.
- **Profil:** Şifre, avatar, tema (light/dark), fatura bilgisi, 2FA aç/kapa.

---

## 5. Ana İş Akışları

### 5.1 Panel (Harita Ekranı)

- **Rota:** `GET /panel` → `IndexController::index` (auth gerekli).
- **Veri:** `ChartPageBuilderService::build()` – doğum bilgisi (tarih, saat, yer) ve isteğe bağlı parametrelerle (inner/outer harita, transit, ev sistemi) tüm harita türleri hesaplanır.
- **Harita türleri:** Natal, Traditional, Draconic, Solar Return, Solar Arc, Profection, Secondary Progression (361°/Naibod), Horary, Sidereal, Heliocentric; artı transit overlay.
- **Combo modal:** İç/dış halka seçimi; `POST /panel/chart-combo` ile yeni kombinasyonlar.
- **Frontend:** Panel Blade + `public/js/panel/`, `public/js/ai-asistan/index.js` (aktif harita, chat).

### 5.2 AI Asistan (Chat)

- **Rotolar:**  
  - `GET /ai-asistan/context`, `/ai-asistan/context-aspects`  
  - `POST /ai-asistan/mesaj-gonder` (SSE stream)  
  - `POST /ai-asistan/pdf-olustur` (auth)
- **Akış:** Kullanıcı mesajı → AIAsistanController::sendMessage → ChartPageBuilderService (gerekirse) → OpenAIServiceRefactored::sendMessageStream → OpenAI API (stream). Cevap SSE ile chunk chunk döner; chat tarafında daktilo efekti.
- **Prompt’lar:** SystemPromptBuilder ile modüler (Identity, AstrologySchool, ChartCategoryEkol, Synastry, Career, vb.). Harita türüne göre ekol eşlemesi: Draconic → Karma, Solar Return/Arc/Profection/Secondary → Öngörü, Horary → Soru, Natal → Modern/Psikolojik. Kullanıcı “karma” talep ederse prompt’ta vurgu eklenir.
- **Veri:** ChartDataTransformer ile gezegen/ev/açı listesi JSON’a çevrilir; RAG (VectorSearchService) opsiyonel.
- **Hata:** 419 (Page Expired) için chat’te anlamlı mesaj; CSRF token yoksa sayfa yenileme uyarısı.

### 5.3 Kayıtlı Haritalar ve İlişki Haritaları

- **Haritalarım:** MyChartsController – CRUD; `user_charts` tablosu.
- **İlişki haritaları:** RelationshipChartController – iki kişi, karşılaştırma, önizleme, kaydetme.
- **İkili harita:** DualChartController, DualChartService.

### 5.4 İçerik ve Yönetim

- **Statik sayfalar:** Doğum haritası, gezegenler, burçlar, elementler (route → view).
- **Dinamik sayfa:** `FrontendPageController::show` – `/sayfa/{slug}`; admin’de oluşturulan sayfalar.
- **Admin:** Blog, Kategori, Sayfa CRUD; Analytics (ziyaretçi, sayfa görüntüleme); toggle status.

### 5.5 Faturalama ve Yasal

- **Faturalar:** InvoiceController (indir, görüntüle); BillingInfo modeli.
- **Yasal:** LegalController – gizlilik, hizmet şartları, Facebook veri silme durumu ve callback.

---

## 6. Veritabanı (Migrations Özeti)

- **users:** Giriş, sosyal, 2FA, tema, terms_accepted_at, birth_place_id, birth_date, birth_time.
- **user_charts:** Kayıtlı tekil haritalar.
- **user_relationship_charts:** İlişki haritaları.
- **user_dual_charts:** İkili harita kayıtları.
- **geonames_cities:** Şehir araması (panel, doğum yeri).
- **blogs, categories, pages:** İçerik ve sayfa yönetimi.
- **admins:** Admin girişi.
- **billing_infos, invoices:** Faturalama.
- **ai_conversations:** Chat geçmişi (isteğe bağlı kayıt).
- **chart_embeddings:** RAG için embedding (pgvector).
- **visitors, page_views:** Analytics.
- **horoscope_hours, settings, astrolog_licenses:** Çeşitli ayar ve referans tabloları.

---

## 7. Konfigürasyon

- **config/app.php:** APP_NAME, locale, timezone, debug.
- **config/auth.php:** Guards (web, admin), providers.
- **config/sanctum.php:** API token.
- **config/locales.php:** Desteklenen diller (dil değiştirme route’u).
- **.env:** APP_KEY, DB_*, OPENAI_API_KEY, OPENAI_MODEL, mail, queue, session, vb.

---

## 8. Önemli Servisler (Kısa)

| Servis | Amaç |
|--------|------|
| **SwetestService** | Swiss Ephemeris çağrıları; natal, transit, draconic, solar return, profection, horary, secondary progression, sidereal, heliocentric hesapları. |
| **ChartPageBuilderService** | İstekten panel parametrelerini çıkarır, SwetestService + ChartVisualizerService ile tüm harita verilerini üretir. |
| **ChartVisualizerService** | Ham gezegen/ev verisini görsel ve AI için yapılandırır (stellium, synastry grid, transit tablosu vb.). |
| **OpenAIServiceRefactored** | System prompt (SystemPromptBuilder) + ChartDataTransformer + OpenAI API stream. |
| **VectorSearchService** | RAG: embedding + pgvector ile ilgili metinleri bulup prompt’a ekler. |
| **RelationshipChartService / DualChartService** | İlişki ve ikili harita hesaplama/mantığı. |

---

## 9. Frontend Özeti

- **Layout:** `main_master.blade.php`; CSRF meta, Vite, global JS.
- **Panel:** `panel.blade.php` – harita alanı, Combo modal, transit, yıldızlar, AI Asistan butonu.
- **Chat:** `chat-widget.blade.php` + `public/js/ai-asistan/index.js` – mesaj gönder, SSE oku, daktilo, PDF, hata (419 vb.) yönetimi.
- **Auth:** login, register, forgot/reset password, 2FA verify.
- **Profil:** show, settings, security, billing, avatar, tema.
- **Stil:** Tailwind 4, `public/frontend/css/`, Vite ile derlenen kaynaklar.

---

## 10. API (Sanctum)

- `POST /api/register`, `POST /api/login`
- `GET /api/user-profile` (auth)
- `GET /api/chart`, `GET /api/chart/full` (auth) – AstroController
- `GET/POST/DELETE /api/my-charts` (auth)
- `POST /api/logout` (auth)

---

## 11. Test ve Dokümantasyon

- **Test:** Pest; `tests/Unit`, `tests/Feature`; örn. ChartInterpretationEkolMapper (veya ekol eşlemesi) unit testleri.
- **Docs:** `docs/CHAT-ARCHITECTURE.md`, `docs/CHAT-TRANSIT-PROMPT-FLOW.md`, `docs/PANEL-DATA-REFERENCE.md`, `docs/LOG-BAKMA.md`, `tests/MANUAL-TEST-EKOL.md` (chat’te ekol testi).

---

## 12. Güvenlik ve İyi Uygulamalar

- CSRF: Tüm POST’larda token; chat’te `X-CSRF-TOKEN` + meta tag.
- Session: Oturum süresi dolunca 419; chat’te kullanıcıya “sayfayı yenile” mesajı.
- Şifre: Laravel hash; reset password mailli.
- 2FA: Kod ile doğrulama.
- Admin: Ayrı guard ve middleware.
- API: Sanctum token; hassas işlemler auth ile.

---

Bu doküman projenin mevcut yapısına göre hazırlanmıştır; yeni özellik veya refaktör sonrası güncellenebilir.