# 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.

## 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() { ... }
```

## 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 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

## 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)

## 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-categories` → POS kategori listesi
- `/pos-products/export-excel/{id}` → Excel dışa aktarım

### Stok ve Finansal
- `/stocks/index` → Stok listesi
- `/stocks/show/{id}` → Stok detayı
- `/stock-transactions` → Stok hareketleri
- `/reports/show/{start_date}/{end_date}` → Raporlama

### Yapay Zeka
- `/ai/query` → AI sorgulama
- `/ai/generate-sql` → SQL oluşturma
- `/ai/reports` → AI raporları

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

## 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

## 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

## 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