# Apper POS Manager - Proje Dokümantasyonu

## Proje Genel Bakış

Apper POS Manager, TALL Stack (Tailwind CSS, Alpine.js, Laravel, Livewire v3) kullanılarak geliştirilmiş, POS (Point of Sale) ve stok yönetim sistemidir. Proje, hem yeni geliştirilen sistem hem de mevcut (legacy) Posmanager sisteminden gelen verileri entegre ederek çalışır.

Sistem, modern bir POS ve stok yönetim çözümü olup, aşağıdaki temel işlevleri sağlar:
- POS ürün ve kategori yönetimi
- Stok takibi ve stok hareketleri
- Satış raporlaması ve analizleri
- Finansal özetler ve maliyet analizleri
- Yapay zeka destekli sorgulama ve raporlama
- Eadisyon entegrasyonu
- Takvim ve zaman çizelgesi yönetimi
- Müşteri ve şirket bilgileri yönetimi
- Çoklu ekip (multi-tenant) desteği
- Kullanıcı erişim kontrolü ve güvenlik
- Excel/PDF dışa aktarım fonksiyonları

## Teknoloji Yığını (TALL Stack)

- **T**ailwind CSS: Utility-first CSS framework
- **A**lpine.js: Minimal JavaScript framework
- **L**aravel 10.x: Backend framework (PHP 8.1+)
- **L**livewire v3: Full-stack reactive framework
- Ayrıca gerektiği yerde Vanilla JS kullanılabilir.

## Proje Özellikleri

### Genel Özellikler
- Google Icons ikon seti kullanılır
- Vanilla JS ve SortableJS ile basitleştirilmiş drag-and-drop işlemleri
- Multi-tenant yapı (ekip bazlı veri izolasyonu)
- Remote ve local database entegrasyonu
- AI destekli sorgulama ve raporlama sistemi
- Eadisyon entegrasyonu

## Veritabanı Mimarisi

Proje, iki farklı veritabanı kullanır (Dual Database Architecture):

### 1. Remote Database (mysql-remote - Posmanager)
Eski sistemden gelen tablolar:
- `sales` → PosSale (POS satış kayıtları)
- `products` → PosProduct (POS ürün kartları)
- `stock_items` → StockItem (Stok kartları)
- `stock_transactions` → StockTransaction (Stok hareketleri)
- `stock_deliveries` → StockDelivery (Tedarikçi teslimatları)
- `stock_mixins` → StockMixin (Ürün reçeteleri)
- `stock_suppliers` → StockSupplier (Tedarikçiler)
- `categories` → PosCategory (POS kategorileri)
- `financial_days` → FinancialDay (Finansal gün verileri)
- `orders` → Order (Siparişler)

### 2. Local Database (mysql - Ana Sistem)
- `categories` → Category (type='pos_stock' filtreli)
- `invoices` → Invoice (Fatura yönetimi)
- `companies` → Company (Şirket/Müşteri bilgileri)
- `teams` → Team (Multi-tenant yapı)
- `users` → User (Kullanıcı yönetimi)
- `user_accesses` → UserAccess (Kullanıcı erişim izinleri)
- `ai_chat_logs` → AiChatLog (Yapay zeka chat geçmişi)
- `ai_reports` → AiReport (Yapay zeka raporları)

## Anahtar Modeller

### StockItem
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'stock_items';

// Global scope ile filtreleme
public function scopeForSelectedPos(Builder $query) { ... }

// İlişkiler
public function transactions() { ... }
public function supplier() { ... }
public function category() { ... }

// Yardımcı metotlar
public function getStockQuantityAttribute() { ... }
public function getLastSupplierNameAttribute() { ... }
public function getLastSupplierPriceAttribute() { ... }
public function getAverageCostAttribute() { ... }
```

### PosSale
```php
// POS satış kayıtları
protected $connection = 'mysql-remote';
protected $table = 'sales';

// İlişkiler
public function products() { ... }
```

### Category
```php
// Local DB bağlantısı
protected $table = 'categories';

// Global scope ile otomatik filtreleme
// type = 'pos_stock' olanlar otomatik alınır
```

### UserAccess
```php
// Kullanıcı erişim izinleri
protected $table = 'user_accesses';

// Global scope ile current_team_id filtreleme
protected static function booted() { ... }
```

### AiChatLog
```php
// AI chat logları
protected $table = 'ai_chat_logs';

// Global scope ile current_user filtreleme
protected static function booted() { ... }
```

### PosCategory
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'categories';

// İlişkiler
public function products() { ... }
```

### PosProduct
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'products';

// İlişkiler
public function category() { ... }
public function sales() { ... }
```

### StockTransaction
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'stock_transactions';

// İlişkiler
public function stockItem() { ... }
public function supplier() { ... }
```

### FinancialDay
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'financial_days';

// Finansal gün verileri için model
```

### Order
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'orders';

// Sipariş verileri için model
```

### StockSupplier
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'stock_suppliers';

// İlişkiler
public function stockItems() { ... }
```

### StockDelivery
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'stock_deliveries';

// İlişkiler
public function supplier() { ... }
public function stockItems() { ... }
```

### Company
```php
// Local DB bağlantısı
protected $table = 'companies';

// Şirket/müşteri bilgileri için model
```

### User
```php
// Local DB bağlantısı
protected $table = 'users';

// Kullanıcı bilgileri ve ilişkiler için model
public function teams() { ... }
public function currentTeam() { ... }
```

### Team
```php
// Local DB bağlantısı
protected $table = 'teams';

// Ekip bilgileri için model
public function users() { ... }
public function owner() { ... }
```

### AiReport
```php
// Local DB bağlantısı
protected $table = 'ai_reports';

// AI raporları için model
```

### Activity
```php
// Local DB bağlantısı
protected $table = 'activities';

// Sistem aktiviteleri için model
```

### Eadisyon
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'eadisyon';

// Eadisyon entegrasyonu için model
```

### ExchangeRate
```php
// Local DB bağlantısı
protected $table = 'exchange_rates';

// Döviz kuru bilgileri için model
```

### Note
```php
// Local DB bağlantısı
protected $table = 'notes';

// Not bilgileri için model
```

### Log
```php
// Local DB bağlantısı
protected $table = 'logs';

// Sistem logları için model
```

### PosCategoryProduct
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'pos_category_products';

// POS kategorisi ve ürün ilişkisi için model
```

### StockMixin
```php
// Remote DB bağlantısı
protected $connection = 'mysql-remote';
protected $table = 'stock_mixins';

// Ürün reçeteleri için model
```

### Product
```php
// Local DB bağlantısı
protected $table = 'products';

// Lokal ürünler için model
```

## Anahtar Servisler

### AIReportService
- Kullanıcı sorgusunu analiz eder
- Rapor talebi mi yoksa basit sorgu mu olduğunu belirler
- Uygun rapor tipi, tarih aralığı ve diğer parametreleri belirler
- Rapor özetini oluşturur

### ExcelExportService
- Excel dışa aktarım işlemleri
- Sayısal formatlama ve para birimi dönüşümleri
- Toplam/alt toplam satırları ekleme
- Çeşitli rapor türleri için dışa aktarım

### OllamaService
- AI sorgularını işler
- Rapor talepleri için AIReportService'i çağırır
- Basit sorgular için doğrudan SQL üretip çalıştırır
- Multi-modal AI yeteneklerini sağlar

### ReportGeneratorService
- Rapor tipine göre veri çeker (remote veritabanından)
- Excel/PDF/CSV dosyası oluşturur
- Meta veri ve toplam hesaplamaları yapar
- Rapor türlerini yönetir (finansal özet, satış raporu, stok raporu, vb.)

## Geliştirme Araçları

Proje geliştirme sürecinde aşağıdaki yardımcı sistemler kullanılmıştır:

- **GitHub Copilot**: Kodlama sırasında yapay zeka destekli öneri sistemleri
- **Laravel Ecosystem**: Laravel Framework, Jetstream, Livewire gibi Laravel ecosystem bileşenleri
- **TALL Stack**: TailwindCSS, Alpine.js, Laravel, Livewire teknolojileri
- **Yapay Zeka Araçları**: Lokal AI modeli (Ollama) ve veritabanı sorgulama sistemleri

## Ana Modüller

### 1. Kullanıcı & Ekip Yönetimi (Jetstream)
- Laravel Jetstream ile kullanıcı kimlik doğrulama
- Laravel Teams ile multi-tenant yapı
- Kullanıcı erişim kontrolü (UserAccess modeli)
- CheckUserAccess middleware ile modül bazlı erişim kontrolü

### 2. POS Ürün ve Kategori Yönetimi
- PosProduct modeli ile POS ürünlerinin yönetimi
- PosCategory modeli ile POS kategorilerinin yönetimi
- Sürükle-bırak ile kategori sıralaması
- Ürün detay sayfaları ve analizleri

### 3. Stok Yönetimi
- StockItem modeli ile stok kartları
- StockTransaction ile stok hareketleri
- StockSupplier ile tedarikçi bilgileri
- StockDelivery ile teslimat bilgileri

### 4. Satış ve Finansal İşlemler
- PosSale ile POS satış kayıtları
- FinancialDay ile finansal gün bilgileri
- Order modeli ile siparişler
- Maliyet ve kar analizleri

### 5. Yapay Zeka Sistemleri
- AiQueryController ile AI sorgulama sistemi
- AiReportController ile AI destekli raporlama
- RecentAiChats Livewire component'ı ile sohbet geçmişi
- AiChatLog modeli ile chat geçmişi

### 6. Entegrasyonlar
- EadisyonController ile eadisyon entegrasyonu
- Ollama API ile lokal AI destekli sorgulama

## Anahtar Controller'lar

### HomeController
- Kullanıcı paneli ve dashboard sayfası için kontrolör
- `/dashboard` rotası için view döner

### PosProductController
- POS ürün listeleme, detay, sıralama işlemleri
- Excel dışa aktarım fonksiyonu
- `/pos-products` rotaları için sorumludur

### PosCategoryController
- POS kategorileri listeleme ve sıralama işlemleri
- Sürükle-bırak sıralama desteği
- `/pos-categories` rotaları için sorumludur

### StockController
- Stok listeleme ve detay sayfaları
- Stok hareketlerini görüntüleme
- `/stocks` rotaları için sorumludur

### StockTransactionController
- Stok hareketleri listeleme ve ekleme
- `/stock-transactions` rotaları için sorumludur

### CategoryController
- Stok kategorileri ile ilgili işlemler
- `/stocks/categories` rotaları için sorumludur

### AiQueryController
- Yapay zeka sorgularını işleme
- SQL sorgusu üretme
- `/ai/query` ve `/ai/generate-sql` rotaları için sorumludur

### AiReportController
- Yapay zeka raporlarını yönetme
- Rapor indirme ve silme işlemleri
- `/ai/reports` rotaları için sorumludur

### EadisyonController
- Eadisyon entegrasyonu işlemleri
- `/integrations/eadisyon` rotası için sorumludur

### ReportController
- Raporlama işlemleri (satış, maliyet özetleri)
- `/reports` rotaları için sorumludur

### InventoryReportController
- Stok envanter raporları
- Aylık envanter raporları ve dışa aktarımı
- `/reports/inventory` rotaları için sorumludur

### FinancialDayController
- Finansal gün verileri ile ilgili işlemler

### OrderController
- Sipariş işlemleri

### CompanyController
- Şirket/müşteri bilgileri ile ilgili işlemler
- Laravel resource controller yapısını kullanır

### CalendarController
- Takvim ve zaman çizelgesi ile ilgili işlemler
- `/calendar/{start_date}/{end_date}` rotası için sorumludur

### UserAccessController
- Kullanıcı erişim kontrolleri ile ilgili işlemler

### TestController
- Test amaçlı işlemler için kullanılan kontrolör

## Anahtar Middleware'ler

### CheckUserAccess
- Kullanıcının POS Manager modülünü kullanma iznini kontrol eder
- Erişimi olmayan kullanıcıları yönlendirir
- current_team_id ve user_id ile erişim kontrolü yapar

### Authenticate
- Kullanıcı kimlik doğrulama kontrolü
- Kullanıcının giriş yapmış olup olmadığını kontrol eder

### EncryptCookies
- Cookie'leri şifreleme
- Uygulama güvenliği için cookie verilerini şifreler

### PreventRequestsDuringMaintenance
- Bakım modunda istekleri engelleme
- Uygulama bakımdayken istekleri yönlendirir

### RedirectIfAuthenticated
- Zaten kimlik doğrulamış kullanıcıları yönlendirme
- Giriş yapmış kullanıcıları dashboard'a yönlendirir

### TrimStrings
- Gelen istek verilerindeki stringlerin başındaki ve sonundaki boşlukları kaldırma

### TrustHosts
- Güvenilir host kontrolü
- Host header saldırılarına karşı koruma

### TrustProxies
- Güvenilir proxy sunucuları tanımlama
- Proxy arkasındaki gerçek IP adreslerini alma

### ValidateSignature
- URL imza doğrulama
- Paylaşılan URL'lerin imzasını doğrular

### VerifyCsrfToken
- CSRF (Cross-Site Request Forgery) koruması
- Form gönderimlerinin güvenliğini sağlar

## Anahtar Livewire Component'leri

### RecentAiChats
- Son AI sohbetlerini listeler
- Chat silme ve filtreleme fonksiyonelliği
- Session bazlı POS servis filtrelemesi

### PosProductEdit
- POS ürün düzenlemesi için form
- AI destekli ürün analiz araçları

### StockItemEdit
- Stok kartı düzenleme
- Stok hareketleri görselleştirme

### Categories
- Kategori yönetimi
- Sürükle-bırak ile sıralama (SortableJS)

### CostSummaryReport
- Aylık maliyet ve gelir analizi sunar
- FinancialDay ve Order modellerinden veri çeker
- Cache yönetimi ile performans iyileştirmesi
- Kar/Zarar hesaplamaları ve görselleştirme

### LogList
- Sistem loglarını listeler
- Log verilerini görsel olarak sunar

## Anahtar Rotalar

### Ana Sayfa ve Kimlik Doğrulama
- `/` → Ana sayfa
- `/dashboard` → Kullanıcı paneli
- `/register` → Kayıt sayfası yönlendirmesi

### POS Ürün ve Kategoriler
- `/pos-products` → POS ürün listesi
- `/pos-products/{id}` → POS ürün detayı
- `/pos-products/show/{id}` → POS ürün detay sayfası
- `/pos-products/export-excel/{id}` → POS ürün Excel dışa aktarımı
- `/pos-products/update-order` → POS ürün sıralama güncelleme
- `/pos-categories` → POS kategori listesi
- `/pos-categories/reorder` → POS kategori sıralama güncelleme

### Stok ve Finansal
- `/stocks/index` → Stok listesi
- `/stocks/show/{id}` → Stok detayı
- `/stocks/clear-cache` → Stok cache temizleme
- `/stocks/movements` → Stok hareketleri
- `/stocks/store` → Yeni stok ekleme
- `/stock-transactions/index` → Stok hareketleri listesi
- `/stock-transactions/show/{id}` → Stok hareketi detayı
- `/stock-transactions/store` → Yeni stok hareketi ekleme
- `/reports/show/{start_date}/{end_date}` → Raporlama
- `/reports/sales` → Satış raporları
- `/reports/cost-summary` → Maliyet özet raporu
- `/reports/inventory` → Stok envanter raporu (index)
- `/reports/inventory/{year}/{month}` → Belirli ay için stok envanter raporu
- `/reports/inventory/{year}/{month}/export` → Stok envanter raporu dışa aktarımı

### Kategoriler
- `/categories/index` → Stok kategorileri listesi
- `/categories/store` → Yeni stok kategorisi ekleme

### Yapay Zeka
- `/ai/query` → AI sorgulama
- `/ai/generate-sql` → SQL oluşturma
- `/ai/health` → AI sağlık durumu kontrolü
- `/ai/reports/` → AI raporları listesi
- `/ai/reports/{report}` → Belirli AI raporu gösterme
- `/ai/reports/{report}/download` → AI raporu indirme
- `/ai/reports/{report}/destroy` → AI raporu silme

### Entegrasyonlar
- `/integrations/eadisyon` → Eadisyon entegrasyonu
- `/test-ollama` → Ollama test rotası

### Şirketler
- `/companies` → Şirket listesi (resource route)
- `/companies/create` → Yeni şirket oluşturma
- `/companies/{company}` → Şirket detayı
- `/companies/{company}/edit` → Şirket düzenleme
- `/companies/{company}` (PUT/PATCH) → Şirket güncelleme
- `/companies/{company}` (DELETE) → Şirket silme

### Takvim
- `/calendar/{start_date}/{end_date}` → Takvim görünümü

### Ekstra
- `/test-log` → Log testi
- `/set-pos-access/{service_id}` → POS erişimi ayarlama

## Excel Dışa Aktarım İyileştirmeleri

### Genel Bakış

Excel dışa aktarım sistemi, aşağıdaki önemli iyileştirmelerle güncellenmiştir:

1. **Sayısal Formatlama**: Artık Excel dosyalarında sayısal veriler uygun biçimde dışa aktarılıyor. Para birimi değerleri için uygun Excel formatı kullanılıyor (örneğin "#,##0.00 [$₺]").

2. **Para Birimi Sembolleri**: Para birimi sembolleri artık hücre değerlerinin bir parçası değil, Excel'in formatlama sistemi aracılığıyla gösteriliyor. Bu sayede kullanıcılar hücrelerde gerçek sayılarla hesaplamalar yapabilir.

3. **Toplam/Alt Toplam Satırları**: Excel dışa aktarımlarına artık toplam satırları ekleniyor. Bu, toplamları ve alt toplamları otomatik olarak hesaplayan Excel formüllerini içeriyor.

### Teknik Detaylar

#### ExcelExportService Güncelleme
- `exportProductSales` metodu güncellenerek para birimi sembolleri kaldırılmıştır
- `WithColumnFormatting` arayüzü eklenerek sütunlar için uygun sayısal formatlama uygulanmaktadır
- Yeni bir `exportProductSalesWithTotals` metodu eklenerek toplam satırı eklenmesi sağlanmıştır

#### Export Sınıfları Güncelleme
- `PosProductSalesExport` sınıfı güncellenerek `WithColumnFormatting` arayüzü implement edilmiştir
- `SalesReportExport` sınıfı güncellenerek `WithColumnFormatting` arayüzü implement edilmiştir
- Her iki sınıfta da para birimi sembolleri kaldırılmış ve uygun Excel formatı tanımlanmıştır

#### Formatlar
- Miktar sütunları: `NumberFormat::FORMAT_NUMBER_COMMA_SEPARATED1`
- Para birimi sütunları: `#,##0.00 [$₺]` (Türk Lirası simgesiyle)
- Toplam satırı, Excel formülü kullanılarak (`=SUM(...)`) dinamik olarak hesaplanmaktadır

### Kullanım

Kullanıcılar artık Excel dosyalarını dışa aktardığında:
- Sayısal sütunlarda doğru sayısal değerleri görecekler
- Para birimleri Excel'in formatlama sistemiyle doğru şekilde gösterilecek
- Excel'de toplam satırları kullanılabilir olacak
- Hücrelerdeki değerlerle doğrudan hesaplamalar yapabilecekler

## Kullanım Senaryosu Örnekleri

### Stok Takip Sistemi
```
@workspace /agent financial,livewire StockItem takip sistemi
- Remote DB'den StockItem ve StockTransaction çek
- TALL Stack ile liste ve detay sayfası
- Real-time stok güncellemeleri
- Global scope ile company_id filtresi
```

### AI Chatbot Geliştirme
```
@workspace /agent livewire,security AI chatbot arayüzü
- RecentAiChats component'ini genişlet
- AiChatLog ile geçmiş yönetimi
- Real-time mesajlaşma
- User authorization kontrolü
```

### POS Entegrasyonu
```
@workspace /agent financial,security PosSale ve StockTransaction entegrasyonu
- Remote DB'de transaction yönetimi
- Company bazlı güvenlik
- Decimal precision hesaplamalar
- Error handling ve logging
```

## Kodlama Standartları

### Genel Kurallar
- **PSR-12** kod standardı
- **Laravel best practices** uygulama
- **Action pattern** kullanımı (complex business logic için)
- Her method için **DocBlock** (Türkçe açıklamalar)
- Türkçe yorum satırları, İngilizce kod

### Decimal Precision Kullanımı
```php
// ❌ YANLIŞ: Float kullanma
$total = $amount * 1.20;

// ✅ DOĞRU: bcmath veya BigDecimal
$total = bcmul($amount, '1.20', 2);
$total = bcadd($subtotal, $tax, 2);
```

### Transaction Kullanımı
```php
use Illuminate\Support\Facades\DB;

DB::beginTransaction();
try {
    // İlişkili işlemler
    $invoice = Invoice::create($data);
    $invoice->lines()->createMany($lines);

    // Activity log
    RecordActivity::execute([...]);

    DB::commit();
} catch (\Exception $e) {
    DB::rollBack();
    Log::error('Invoice creation failed', ['error' => $e->getMessage()]);
    throw $e;
}
```

## Multi-Tenant Yapı

- Her model'de `current_team_id` global scope kullanılır
- Kullanıcılar farklı ekiplerde (teams) çalışabilir
- Veri izolasyonu team bazlıdır
- Authorization her endpoint için zorunludur
- currentUserScope ve currentTeamScope global scope'ları kullanılır

## Yapay Zeka Özellikleri

Proje, yapay zeka destekli özellikler içerir:
- **AI Chatbot**: Veritabanına bağlı, sorguları yanıtlayan chatbot
- `RecentAiChats` Livewire component'i
- `AiChatLog` model ile chat geçmişi tutulur
- `AiReportController` ile AI destekli rapor oluşturma
- Ollama API entegrasyonu (lokal AI model desteği)

## Geliştirme Ortamı Kurulumu

1. Projeyi klonla
2. `composer install` komutunu çalıştır
3. `.env` dosyasını yapılandır (remote DB ayarlarını ekle)
4. `php artisan migrate` komutu ile veritabanı migrasyonlarını çalıştır
5. `npm install && npm run dev` komutları ile frontend derlemesi yap

## Proje Bağımlılıkları ve Yapılandırması

### Temel Bağımlılıklar
- **Laravel Framework** (v10.x): Ana uygulama çatısı
- **Laravel Jetstream**: Kullanıcı kimlik doğrulama ve ekip yönetimi
- **Livewire v3**: Full-stack reactive framework
- **Alpine.js**: Minimal JavaScript framework
- **Tailwind CSS**: Utility-first CSS framework
- **Laravel Sanctum**: API kimlik doğrulama
- **Guzzle**: HTTP istemcisi
- **Maatwebsite Excel**: Excel dışa aktarım işlemleri
- **PHPOffice PhpSpreadsheet**: Excel dosyası işlemleri
- **barryvdh/laravel-dompdf**: PDF dışa aktarım işlemleri
- **apper/log-manager**: Uygulama loglama sistemi

### Ekstra Özellikler
- **Ollama API**: Yerel AI model entegrasyonu
- **SortableJS**: Sürükle-bırak sıralama işlemleri
- **Google Icons**: İkon seti

### Yapılandırma Dosyaları
- **config/app.php**: Uygulama genel yapılandırması
- **config/database.php**: Veritabanı bağlantı yapılandırması (local ve remote)
- **config/excel.php**: Excel dışa aktarım yapılandırması
- **config/dompdf.php**: PDF dışa aktarım yapılandırması
- **config/jetstream.php**: Jetstream yapılandırması
- **config/services.php**: Üçüncü parti servis yapılandırmaları
- **config/session.php**: Oturum yapılandırması
- **config/cache.php**: Önbellek yapılandırması

## Veritabanı Yapılandırması

```php
// config/database.php
'connections' => [
    // Ana (local) veritabanı
    'mysql' => [
        // Laravel Jetstream, kullanıcı, ekip ve AI logları burada
    ],

    // Uzak (remote) veritabanı
    'mysql-remote' => [
        // Eski POS sisteminden gelen veriler burada
    ],
],
```

## Test Stratejisi

Proje, unit test, feature test ve Livewire component test'leri içerir:
- Local modeller için: Normal `RefreshDatabase` trait
- Remote modeller için: Test DB bağlantısı yapılandırılmalı
- Integration test'lerde her iki DB'ye erişim gerekebilir

## Ekstra Özellikler

### Takvim ve Zaman Çizelgesi
- CalendarController ile tarih aralığına göre veri görüntüleme
- `/calendar/{start_date}/{end_date}` rotası ile erişim
- Finansal ve satış verilerinin zaman bazlı analizi

### Stok Envanter Raporları
- Aylık envanter raporları
- `/reports/inventory/{year}/{month}` rotası ile belirli ay için rapor
- Excel dışa aktarım desteği
- Stok durumu ve değişikliklerinin takibi

### Döviz Kuru Yönetimi
- ExchangeRate modeli ile döviz kuru takibi
- Farklı para birimleri ile işlem desteği

### Sistem Loglama
- Apper Log Manager kullanılarak detaylı sistem loglama
- Activity modeli ile kullanıcı aktivitelerinin takibi
- `/test-log` rotası ile log testi

### Not ve Açıklama Yönetimi
- Note modeli ile not ekleme ve yönetimi
- Farklı modüllere not ekleme desteği

### POS Erişim Yönetimi
- UserAccess modeli ile POS servislerine erişim kontrolü
- `/set-pos-access/{service_id}` rotası ile aktif POS servisi seçimi
- Çoklu POS servis desteği

### Ölçü Birimi (UOM) Desteği
- UomHelper sınıfı ile ölçü birimi çevirimi
- `uom_localized()` yardımcı fonksiyonu
- Farklı ölçü birimleri için yerelleştirme desteği (Adet, Kg, gr, Lt, cL, mL, dk)

## Ortak Sorunlar ve Çözümler

### 1. Float Kullanımı
Para hesaplarında asla float kullanma, `bcmath` fonksiyonlarını kullan.

### 2. Transaction Unutma
İlişkili işlemlerde DB::transaction() kullan.

### 3. Global Scope Bypass
Team izolasyonunu atlamak için withoutGlobalScopes() kullanma.

### 4. Remote DB Unutma
`stock_transactions`, `financial_days` ve `orders` uzak sunucuda! `DB::connection('mysql_remote')` kullan.

### 5. Erişim Kontrolü
Kullanıcıların POS Manager erişimi olup olmadığını kontrol etmek için `CheckUserAccess` middleware'ini kontrol et.

## Deployment Notları

- Production ortamı için `APP_ENV=production`, `APP_DEBUG=false` ayarları
- Remote DB bağlantı bilgilerini güvenli şekilde yapılandır
- Queue sistemini (database veya redis) etkinleştir
- Cache ve session ayarlarını production uygun şekilde yapılandır
- Ollama AI servisinin (varsa) erişilebilir olduğundan emin ol

## Katkıda Bulunma

1. Fork yap
2. Yeni bir branch oluştur
3. Değişiklikleri yap
4. Commit ve push yap
5. Pull Request oluştur

## İletişim

Daha fazla bilgi için GitHub Issues sayfasını ziyaret edin.

## Yapay Zeka Rapor Sistemi

### Genel Bakış

AI Rapor Sistemi, kullanıcıların doğal dil ile rapor talep edebilmesini sağlayan gelişmiş bir yapıdır. Bu sistem, kullanıcıların "Bu ayın satış raporunu excel olarak hazırla" gibi doğal dildeki isteklerini alır, yapay zeka yardımıyla analiz eder ve uygun formatlarda (Excel/PDF/CSV) raporlar oluşturur.

### Sistem Bileşenleri

#### 1. AIReport Modeli
- `ai_reports` tablosunda kullanıcı raporlarını saklar
- Multi-tenant yapıya sahiptir (her kullanıcı sadece kendine ait raporları görebilir)
- Rapor parametreleri, veri, meta veri ve durum bilgilerini içerir

#### 2. AIReportService
- Kullanıcı sorgusunu analiz eder
- Rapor talebi mi yoksa basit sorgu mu olduğunu belirler
- Uygun rapor tipi, tarih aralığı ve diğer parametreleri belirler
- Rapor özetini oluşturur

#### 3. ReportGeneratorService
- Rapor tipine göre veri çeker (remote veritabanından)
- Excel/PDF/CSV dosyası oluşturur
- Meta veri ve toplam hesaplamaları yapar
- Desteklenen rapor tipleri:
  - `financial_summary` - Finansal Özet
  - `sales_report` - Satış Raporu
  - `stock_report` - Stok Raporu
  - `purchase_report` - Alış Raporu
  - `expense_report` - Gider Raporu
  - `profit_loss` - Kar/Zarar raporu
  - Ek rapor tipleri kolayca eklenebilir

#### 4. OllamaService
- AI sorgularını işler
- Rapor talepleri için AIReportService'i çağırır
- Basit sorgular için doğrudan SQL üretip çalıştırır
- Multi-modal AI yeteneklerini sağlar

#### 5. AiReportController
- Raporları listeleme, görüntüleme, indirme ve silme işlemlerini yönetir
- HTTP API sağlar

#### 6. AiReportView (Livewire Component)
- Raporları kullanıcı dostu arayüzde sunar
- Sayfalama, filtreleme ve indirme özellikleri sağlar
- Kullanıcıların raporlarını görüntülemesini sağlar

### Kullanım Akışı

1. Kullanıcı doğal dilde bir rapor talebi gönderir (örn. "Geçen ayın satış raporunu excel olarak hazırla")
2. AIReportService sorguyu analiz eder ve rapor talebi olduğunu belirler
3. ReportGeneratorService verileri çeker ve rapor dosyasını oluşturur
4. AiReport modeli ile veritabanına kaydeder
5. Kullanıcıya raporun durumu ve indirme bağlantısı sunulur

### Yetkilendirme ve Güvenlik

- Multi-tenant yapı sayesinde kullanıcılar sadece kendi takımına ait raporları görebilir
- Policy tabanlı yetkilendirme kullanılır
- Remote veritabanı erişimleri güvenli bir şekilde yapılır

### Geliştirme ve Genişletme

Sisteme yeni rapor tipleri eklemek kolaydır:
1. ReportGeneratorService sınıfına yeni bir metod ekleyin
2. fetchReportData metodunda yeni rapor tipini tanımlayın
3. Gerekirse modelde etiket/label tanımlamalarını güncelleyin

### Kullanım Örnekleri

Kullanıcılar doğal dilde şu tarz sorgular gönderebilir:
- "Bu ayın satış raporunu PDF olarak oluştur"
- "Son 3 ayın stok raporunu excel'e aktar"
- "Ocak ayı kar/zarar raporu"
- "Tedarikçilere göre alış raporu ver"
- "Finansal özet çıkar"

Basit sorgular (örn. "Bugün kaç kg domates aldık?") rapor olarak işlenmez, doğrudan SQL sorgusu olarak işlenir.

### Dosya Formatları

Sistem şu dosya formatlarını destekler:
- Excel (.xlsx)
- PDF (.pdf)
- CSV (.csv)

Her rapor tipi için en uygun format otomatik olarak seçilir, ancak kullanıcı seçim yapabilir.

## Qwen Added Memories
- POS Manager sisteminde satış raporlarında yalnızca tamamlanmış satışların yer alması gerekli. Satışı tamamlanmamış (henüz tahsil edilmemiş) siparişlerin deleted_at değeri null olur. Bu yüzden satış raporunda filtreleme yaparken o.deleted_at sütunu kullanılır.

## Cost Summary Report

### Genel Bakış

Cost Summary Report, POS sistemi için aylık bazda maliyet ve gelir analizini sunan bir rapordur. Rapor, FinancialDay modelinden satış verilerini ve Order modelinden maliyet verilerini kullanarak kar/zarar analizi sunar.

### Sistem Bileşenleri

#### 1. CostSummaryReport (Livewire Component)
- resources/views/livewire/cost-summary-report.blade.php: Raporun kullanıcı arayüzünü sunar
- app/Http/Livewire/CostSummaryReport.php: Arka planda veri işleme ve cache yönetimi sağlar

#### 2. ReportController
- app/Http/Controllers/ReportController.php: cost_summary metodu sayfa yönlendirmesi yapar

#### 3. Views
- resources/views/reports/cost-summary-report.blade.php: Ana view dosyası, Livewire component'i içerir

#### 4. Rota
- routes/web.php: /reports/cost-summary rotası Cost Summary Report için kullanılır

### Veri Kaynakları

#### Satış Verileri
- `FinancialDay` modeli kullanılır
- `net_sales` sütununun toplamı satış olarak kabul edilir
- Tarih aralığına göre filtreleme yapılır

#### Maliyet Verileri
- `Order` modeli kullanılır
- `deleted_at` değeri dolu olan kayıtların `total_price` sütununun toplamı maliyet olarak kabul edilir
- Tarih aralığına göre filtreleme yapılır

### Performans İyileştirmeleri

#### Cache Yönetimi
- Rapor verileri 24 saat cache'te tutulur
- `Illuminate\Support\Facades\Cache` ile cache işlemi yapılır
- Ana sayfa her yüklendiğinde veriler hesaplanmaz, cache'ten çekilir
- Her ay için ayrı cache anahtarı kullanılır

#### Güncelleme Mekanizması
- Kullanıcı, "Güncelle" butonu ile bireysel aylar için verileri yeniden hesaplayabilir
- Güncellenen veriler tekrar 24 saatlik cache'e alınır

#### Aylık Raporlama
- Rapor aylık bazda sunulur
- 12 ayın verileri tek bir tabloda listelenir
- Kullanıcı yıl seçebilir ve belirtilen yıla ait tüm aylar gösterilir

### Kullanım Arayüzü

#### Özellikler
- Yıl seçimi dropdown menüsü
- Aylık tabloda satış, maliyet ve kar/zarar verileri
- Her ay için ayrı güncelleme butonu
- Toplam satırı (Alt toplamlar)
- Renkli göstergeler (kar için yeşil, zarar için kırmızı)
- Rapor hakkında bilgilendirme metni

#### Stil ve Sunum
- Tailwind CSS ile tasarlanmıştır
- Responsive tasarım
- Kullanıcı dostu arayüz
- Tabloda veriler para birimine göre formatlanır (₺)

### Teknik Detaylar

#### Cache Anahtarları
- Anahtar formatı: `cost_summary_report_2024_1` (2024 yılı 1. ay için)
- Ay ve yıl bazında ayrı cache anahtarları kullanılır

#### Veri Hesaplama Süreci
1. Belirtilen yıl ve ay için başlangıç ve bitiş tarihleri belirlenir
2. FinancialDay modelinden net_sales toplamı alınır (satış)
3. Order modelinden deleted_at != null olan kayıtların total_price toplamı alınır (maliyet)
4. Kar = Satış - Maliyet formülüyle hesaplama yapılır
5. Elde edilen veriler cache'e yazılır
6. Kullanıcıya sunulur

#### Filtreleme
- Order modeli için satışı yapılan siparişlerin tarihine göre filtreleme yapılır
- FinancialDay modeli için gün tarihine göre filtreleme yapılır