# Planner.Apper

## Kimlik

Çok kiracılı (multi-tenant) **görev ve iş planlama sistemi**. Haftalık/günlük görev yönetimi, firma/cari takibi, fatura/teklif/anlaşma/fırsat yönetimi, banka hareketleri, tekrarlayan hareketler, Gmail gelen kutusu entegrasyonu ve AI destekli görev tamamlama sunar.

## Teknoloji Yığını

- **Backend**: Laravel **10.x**, PHP **^8.1**
- **Frontend**: Tailwind CSS 3, **Livewire 3**, Blade, Vite 5, `livewire/flux`
- **Auth**: Laravel Jetstream (teams + 2FA) + Fortify + Sanctum
- **Paketler**: `apper/log-manager` (activity log; private VCS: `ugurkaragoz/apper-log-manager`), `guzzlehttp/guzzle`
- **JS bağımlılıkları**: Axios, Tailwind CSS (forms + typography pluginleri)
- **Test**: PHPUnit 10

## Komutlar

```bash
npm run dev                          # Vite dev server
npm run build                        # Frontend build
php artisan serve                    # Dev sunucusu
php artisan test                     # Testler
php artisan queue:work               # Queue worker (bildirimler için)
php artisan gmail:sync               # Bağlı Gmail kutularını senkronla
php artisan gmail:sync --user=eposta # Yalnızca belirli hesabı senkronla
php artisan gmail:demo               # Demo Gmail mesajları oluştur (local test)
php artisan notifications:test       # Bildirim sistemini test et
php artisan optimize:clear
```

## Dizin Yapısı

```
app/
├── Actions/          # İş mantığı
│   ├── Deal/         # Anlaşma iş akışları
│   ├── Fortify/      # Auth action'ları (kullanıcı oluşturma, şifre vb.)
│   ├── Gmail/        # Gmail entegrasyonu (GmailClient, SyncUserInbox,
│   │                 # ConvertMessageToTask, DecodeMessage, MatchMessageToContact, GmailLog)
│   ├── Jetstream/    # Team yönetim action'ları
│   ├── Mistral/      # Mistral AI entegrasyonu
│   ├── Qwen/         # Qwen AI entegrasyonu (görev tamamlama, başlık üretimi)
│   └── XAi/          # XAi entegrasyonu
├── Console/Commands/ # gmail:sync, gmail:demo, notifications:test
├── Http/
│   ├── Controllers/  # HomeController, CompanyController, GoogleOAuthController, AiController
│   └── Middleware/   # CheckUserAccess, SetTimezone vb.
├── Livewire/         # NewWeek (ana haftalık görünüm, ~1268 satır), Day, Week, Today,
│                     # Inbox (Gmail), TasksTimeline
├── Models/           # Eloquent modeller + Scopes/ (CurrentTeamScope, CurrentUserScope)
│                     # + Traits/ (HasEmails)
├── Notifications/    # TaskAssigned, TaskUpdated (mail + database kanalı, ShouldQueue)
└── Providers/        # AppServiceProvider, JetstreamServiceProvider, FortifyServiceProvider,
                      # ViewServiceProvider (global view composer: firmalar, döviz kurları, ürünler)
docs/                # Proje dokümantasyonu (gmail/, official-texts/, proje_mimari.md, api_rehberi.md)
resources/views/     # Blade şablonları
├── livewire/        # Livewire bileşen şablonları (day, inbox, new-week, tasks-timeline, today, week)
├── components/      # Tekrar kullanılabilir Blade bileşenleri (~42 dosya)
├── modals/          # Modal pencereler
├── layouts/         # App ve guest layout
├── companies/       # Firma görünümleri
├── tasks/           # Görev görünümleri
└── teams/, profile/, auth/  # Jetstream görünümleri
routes/web.php       # Web rotaları (dashboard, week, companies, Gmail OAuth)
routes/api.php       # Minimal (sanctum /user)
tests/               # Feature + Unit testleri + CreatesPlannerSchema trait
```

## Mimari

### 🏢 Çok Kiracılılık (Multi-Tenant)

Tüm ana modeller iki global scope ile izole edilir:

```php
// app/Models/Scopes/CurrentTeamScope.php
static::addGlobalScope(new CurrentTeamScope);
// Sorguya otomatik ekler: where('current_team_id', auth()->user()->currentTeam->id)

// app/Models/Scopes/CurrentUserScope.php
static::addGlobalScope(new CurrentUserScope);
// Kullanıcı bazlı filtreleme (oluşturan veya atanan)
```

- Yeni modelde `current_team_id`'yi `create()` verisine mutlaka ekle.
- **Dikkat**: Console/queue'da auth yokken scope no-op olur (tüm kayıtlar görünür) — komutlarda team'i manuel filtrele.
- `CheckUserAccess` middleware'i her request'te kullanıcının planner erişim iznini doğrular.

### 📧 Gmail Entegrasyonu

Kullanıcı bazlı OAuth2 ile Gmail gelen kutusu entegrasyonu:

1. **OAuth akışı**: `GoogleOAuthController` → Google Cloud Console üzerinden yetkilendirme
2. **Token saklama**: `GoogleAccount` modelinde şifreli (encrypted) access/refresh token
3. **Senkronizasyon**: `SyncUserInbox` action'ı ile Gmail API'den mesaj çekme (bütçe sınırı: varsayılan 25 detay isteği)
4. **Otomik eşleştirme**: `MatchMessageToContact` — gelen e-postaları Company (domain) veya Person (e-posta) ile otomatik eşleştirir
5. **Göreve dönüştürme**: `ConvertMessageToTask` — Gmail mesajını Task kaydına dönüştürür, kaynak bilgisi Note'a yazılır
6. **Zamanlama**: `gmail:sync` komutu scheduler ile her 15 dakikada bir çalışır (`withoutOverlapping(10)`)
7. **Loglama**: `GmailLog` — yapılandırılmış log, gizli bilgileri otomatik sansürler

### 🤖 AI Entegrasyonları

- **Qwen AI**: Görev tamamlama, başlık üretimi (`QWEN_API_KEY`, `QWEN_API_URL` env değişkenleri)
- **Mistral AI**: Alternatif AI sağlayıcı
- **XAi**: Alternatif AI sağlayıcı

### 📅 Haftalık/Günlük Planlama

- **NewWeek** Livewire bileşeni: Ana haftalık görünüm — görevler, firmalar, finansal veriler, bildirimler, AI görev tamamlama, takım üyesi atama
- **Day**: Günlük görünüm — görev yönetimi, notlar, finansal özet
- **Week**: Haftalık görünüm — görevler, fırsatlar, teklifler, anlaşmalar, faturalar, banka hareketleri
- **Today**: Bugünün görevleri ve finansal özet
- **TasksTimeline**: Görev zaman çizelgesi

### 💰 Finansal Modeller

- **Invoice**: Fatura yönetimi (satış/alış)
- **Offer / OfferLine**: Teklif ve teklif kalemleri
- **Deal**: Anlaşma takibi
- **Opportunity**: Fırsat takibi
- **BankAccount / BankTransaction**: Banka hesapları ve hareketler
- **RecurringMovement**: Tekrarlayan finansal hareketler
- **ExchangeRate**: Döviz kurları (Cache: 60 dk)
- **Company**: Firma/cari kayıtları (offers, opportunities, deals, tasks, invoices, bankTransactions, persons ilişkileri)
- **Person**: Kişi kayıtları
- **Product**: Ürün/hizmet tanımları
- **Hiring**: İşe alım takibi

### 🔔 Bildirimler

- `TaskAssigned`: Görev atandığında (mail + database kanalı)
- `TaskUpdated`: Görev güncellendiğinde (tamamlanma, not, durum değişikliği)
- Her iki bildirim `ShouldQueue` implement eder — async teslimat
- Queue yapılandırması: sync (geliştirme), database/Redis/SQS destekli

### 🕐 Saat Dilimi

- `SetTimezone` middleware'i (web middleware grubuna kayıtlı) kullanıcının team saat dilimine göre uygulama saat dilimini ayarlar
- Gmail `received_at` alanı timezone-aware olarak işlenir

## Rotalar Haritası (`routes/web.php`)

Tümü `auth:sanctum` + Jetstream session + `verified` + `check.user.access` middleware'i arkasındadır:

| Rota                        | Açıklama                     |
| --------------------------- | ---------------------------- |
| `GET /dashboard`            | `new-week`'e yönlendirir     |
| `GET /week/{time}`          | Haftalık görünüm (eski)      |
| `GET /new-week/{time}`      | Haftalık görünüm (yeni, ana) |
| `GET /auth/google/connect`  | Google OAuth başlat          |
| `GET /auth/google/callback` | Google OAuth callback        |
| `DELETE /auth/google`       | Google bağlantısını kes      |
| `GET /companies`            | Firma listesi                |
| `GET /companies/clients`    | Müşteri firmalar             |
| `GET /companies/suppliers`  | Tedarikçi firmalar           |
| `GET /companies/{slug}`     | Firma detayı                 |
| `POST /companies`           | Firma oluştur                |
| `PUT /companies/{slug}`     | Firma güncelle               |
| `DELETE /companies/{slug}`  | Firma sil                    |

Public rotalar (auth gerektirmez): `/privacy-policy`, `/terms`

## Kod Standartları

- **PSR-12**, Türkçe yorum/açıklama, İngilizce kod
- Controller: `camelCase` metodlar; DB: çoğul `snake_case` tablolar
- Her request'te validation; her endpoint'te Policy/authorize kontrolü
- Blade'de kaçış: `{{ }}` kullan, asla `{!! !!}` (XSS)
- Para hesaplarında float kullanma — string tabanlı aritmetik/bcmath

## 🗄️ Migration Yönetimi (ÖNEMLİ)

Migration dosyaları ve `php artisan migrate` işlemleri **`admin.apper` ana yönetim projesinde** yapılır — **bu projede `php artisan migrate` ÇALIŞTIRMA**.

Bu projede bir özellik geliştirirken DB şeması değişikliği gerekiyorsa:

1. Migration dosyasını bu projede oluştur: `php artisan make:migration <ad>` (yalnızca dosya üretimi, migrate yok)
2. İçeriğini bu projede yaz (şema değişikliği, index, foreign key vb.)
3. Dosyayı kullanıcıya **bildir**: hangi tablo/alanda ne değişti, admin.apper projesinde migrate edilmesi gerektiği
4. `php artisan migrate`, `migrate:fresh`, `migrate:rollback`, `db:seed` gibi komutları burada asla çalıştırma; remote DB (`mysql_remote`) tablolarına migration uygulanmaz — remote şema değişikliği kullanıcıya bildirilir

## Test

- `tests/Feature`: Gmail entegrasyonu, görev oluşturma (email-to-task), bildirimler + Jetstream auth testleri
- `tests/Unit`: Hesaplamalar
- `tests/Concerns/CreatesPlannerSchema.php`: Test şeması migration olmadan dinamik oluşturulur (SQLite in-memory)
- Testlerde `userWithTeam()` helper'ı ile team'i olan doğrulanmış kullanıcı oluşturulur
- Gmail işlemlerinde `Http::fake()` kullan; testlerde gerçek Gmail API'ye bağlanma

## Harici Dokümanlar (konuyla ilgiliyse oku)

- `@docs/gmail/gmail-auth.md` — Google OAuth akışı ve token yönetimi
- `@docs/gmail/inbox-entegrasyonu.md` — Gmail gelen kutusu entegrasyonu (tam dokümantasyon)
- `@docs/proje_mimari.md` — Proje mimari dokümantasyonu
- `@docs/api_rehberi.md` — API kullanım rehberi
- `@docs/CHANGELOG.md` — Değişiklik günlüğü
- `@docs/CONTRIBUTING.md` — Katkı sağlama rehberi

## ⚠️ Yaygın Tuzaklar

1. `docs/proje_mimari.md` ve `docs/api_rehberi.md` eski şablon içerik barındırabilir — güncel kod ile tutarlılığını doğrula
2. Global scope'u `withoutGlobalScopes()` ile atlamak team izolasyonunu bozar
3. Bu projede `php artisan migrate` çalıştırmak → migration'lar `admin.apper` ana projesinde koşulur; burada yalnızca dosya üret (bkz. "Migration Yönetimi")
4. `NewWeek` Livewire bileşeni ~1268 satırdır — değişiklik yaparken dikkatli ol, ilgili bölümü oku
5. Console/queue komutlarında auth bağlamı yok → `CurrentTeamScope` ve `CurrentUserScope` no-op olur; team filtresini manuel uygula
6. Gmail senkronizasyonu bütçe sınırı ile çalışır (varsayılan 25) — çok fazla yeni mesaj varsa bazıları sonraki çalıştırmaya kalır
7. Queue worker çalışmıyorsa bildirimler (TaskAssigned, TaskUpdated) teslim edilmez
8. `GoogleAccount` token'ları encrypted saklanır — asla düz metin olarak okunamaz/write edilemez