FarmerDeck Kullanıcı Kılavuzu

Bu kılavuz, FarmerDeck'in kişisel hesabınız için hazır olan modüllerini uçtan uca anlatır. Her bölümde ekranları, alanları ve gerçek kod tarafından desteklenen iş kurallarını bulacaksınız.

1. Çiftlik Oluşturma

Yeni bir kullanıcı hesabıyla home/farmerdeck rotasına girdiğinizde karşınıza onboarding sihirbazı çıkar. Sihirbaz iki adımdan oluşur ve tüm kayıt tek bir veritabanı işleminde tamamlanır.

1.1 Çiftlik bilgileri

Sihirbazın ilk adımında çiftliğinizin temel bilgilerini girersiniz:

• Çiftlik adı: 2–100 karakter, zorunlu.
• Ülke kodu: ISO 3166 alpha-2 kodu (TR için 81 il listesinden seçim yapılır).
• İl: Ülke kodu TR ise 81 il; diğer ülkeler için serbest metin.
• İlçe: TR seçildiğinde il'e bağlı ilçeler kademeli olarak listelenir.
• Enlem / Boylam: -90..90 ve -180..180 aralığında. Hava uyarılarının doğru çalışması için konum bilgisi gereklidir.
• Saat dilimi: Varsayılan Europe/Istanbul. Open-Meteo bu alanı kullanır.
• Toplam alan (hektar): Çiftliğin tahmini toplam büyüklüğü; parsellerin toplamıyla birlikte gösterilir.

1.2 İlk parsel

İkinci adımda çiftliğe ait ilk parseli tanımlarsınız:

• Parsel adı: 1–100 karakter.
• Alan (hektar): Pozitif sayı.
• Toprak tipi: kil, kum, tın, mil, peat, kireçli, killi-tın, kumlu-tın, siltli-tın seçeneklerinden biri.

Onboarding tamamlandığında complete_onboarding RPC'si tek işlemde çiftlik, parsel ve opsiyonel olarak bir ekini kaydeder. home/farmerdeck sayfasındaki KPI kartları, parsel sayısını ve açık ürün döngüsü sayısını hemen göstermeye başlar.

1.3 Çiftlik düzenleme ve silme

Çiftlik detay sayfasından (home/farmerdeck/farms/[farmId]) ad, koordinat, adres ve saat dilimi bilgilerini güncelleyebilirsiniz. Çiftlik silindiğinde bağlı parsel, ürün döngüsü ve hava uyarıları da kademeli olarak temizlenir (ON DELETE CASCADE).

2. Parseller (Tarlalar)

Parseller çiftliğin altındaki üretim alanlarıdır. home/farmerdeck/fields ekranı hesabınıza ait tüm parselleri çiftlik adıyla birlikte listeler.

2.1 Yeni parsel

Çiftlik detay sayfasındaki Yeni Parsel butonu sizi parsel oluşturma formuna götürür. Formda parsel adı, alan, opsiyonel enlem/boylam, toprak tipi ve serbest not alanları yer alır.

2.2 Parsel düzenleme ve silme

Parsel detay sayfasından tüm alanlar güncellenebilir. Silme işlemi tetiklenmeden önce parsele bağlı farm_events ve crop_cycles kayıtları kaldırılır.

2.3 Parça görünürlüğü

Çiftlik kartında parsel sayısı ve toplam alan otomatik hesaplanır. Parselleri olmayan çiftliklerde kart "henüz parsel yok" rozeti gösterir.

3. Ürün Döngüsü ve Takvim/Timeline

Bir parselde üretim başlatmak için ürün döngüsü oluşturursunuz. Ürün döngüsünün beş durumu vardır: planned, planted, growing, harvested, failed.

3.1 Ürün döngüsü oluşturma

home/farmerdeck/crops/new formunda şu alanlar yer alır:

• Parsel: Hesabınıza ait parsellerden biri.
• Ürün adı: 1–100 karakter.
• Ürün kategorisi: Serbest metin (opsiyonel).
• Ekim tarihi: Tarih, zorunlu.
• Tahmini hasat tarihi: Tarih, opsiyonel.
• Not: 2000 karakter, opsiyonel.

Yeni döngü planned durumunda başlar. Tarih bilgileri parsele bağlı olarak takvimde gösterilir.

3.2 Timeline ve takvim görünümü

Ürün döngüsü detay sayfasında iki sekme bulunur:

• Timeline: Ekim tarihinden tahmini hasada uzanan yatay çubuk üzerinde tüm farm_events olayları (ekim, sulama, gübreleme, ilaçlama, hasat, not) işaretlenir.
• Takvim: Olaylar ay görünümünde listelenir; bir güne tıklayınca o günkü olaylar ayrıntılarıyla gösterilir.

3.3 Olay kayıtları

Bir ürün döngüsüne olay eklemek için şu olay tiplerinden birini seçersiniz:

• planting (ekim)
• irrigation (sulama)
• fertilization (gübreleme)
• pesticide (ilaçlama)
• harvest (hasat)
• note (serbest not)

Her olay için tarih/saat, miktar, birim, maliyet ve opsiyonel envanter kalemi bağlantısı girilebilir. Bir olay envanterden tüketildiğinde (örn. gübreleme için record_inventory_out RPC'si) sistem otomatik farm_events kaydı oluşturur; stok hareketi ve tarla olayı tek seferde yazılır.

3.4 Hasat kaydı

Hasat kaydı formu (RecordHarvestSchema) ile harvested_at, yield_amount ve yield_unit alanlarını doldurarak döngüyü harvested durumuna alırsınız. Döngü failed durumuna da elle alınabilir; her iki geçiş de crop_cycles üzerinde güncellenir.

4. Görevler

Görevler (tasks) hem manuel hem de sistem tarafından üretilen kayıtları içerir. Görev kaynakları: manual, auto_weather, auto_low_stock, auto_maintenance, auto_harvest.

4.1 Manuel görev oluşturma

home/farmerdeck/tasks/new formu şu alanlardan oluşur:

• Başlık: 1–200 karakter.
• Açıklama: 2000 karakter, opsiyonel.
• Teslim tarihi: Tarih/saat, opsiyonel.

Görev otomatik olarak manual kaynakla ve pending durumla kaydedilir.

4.2 Görev tamamlama ve iptal

Görev listesinde bir kaydı Tamamla veya İptal olarak işaretleyebilirsiniz. Tamamlanan görevlerde completed_at alanı otomatik dolar.

4.3 Otomatik görevler

• auto_weather: Orta ve yüksek riskli hava uyarıları için weather_alerts tetikleyicisi tarafından oluşturulur; görev başlığı "Hava durumu uyarısı: …" formatındadır ve teslim tarihi, tahmin zamanı ile şimdi+7 gün arasındaki en yakın tarihtir.
• auto_low_stock: Saatlik pg_cron görevi (farmerdeck-low-stock-tasks) envanterde current_quantity <= min_threshold olan her kalem için, açık bir otomatik görev yoksa yeni bir görev oluşturur. Görev başlığı "Stok uyarısı: … (düşük seviye)" formatındadır.
• auto_maintenance: 7 gün içinde bakım zamanı gelen aktif ekipmanlar için "Bakım hatırlatması" özet görevi; günde en fazla bir kez oluşturulur.

Dashboard'daki Yaklaşan görevler kartı, bekleyen ve teslim tarihi 7 gün içinde olan görevleri v_upcoming_tasks görünümü üzerinden listeler.

5. Ekipman ve Bakım

Ekipmanlar çiftliğin makine parkıdır. Türler: tractor, trailer, plow, pump, harvester, other. Durumlar: active, maintenance, broken, sold.

5.1 Ekipman kartı

home/farmerdeck/equipment/new formu şu alanları içerir:

• Çiftlik: Opsiyonel; boş bırakılırsa hesap genelinde tanımlı olur.
• Ad: 1–100 karakter.
• Tür: Listeden seçim.
• Marka, model, seri numarası: Opsiyonel.
• Satın alma tarihi ve fiyatı: Opsiyonel; varsayılan para birimi USD'dir, EUR ve TRY de seçilebilir.
• Çalışma saati: Mevcut saat sayısı, opsiyonel.
• Not: 2000 karakter.

5.2 Durum değişimi

Ekipman detay sayfasında durum seçici ile active, maintenance, broken, sold arasında geçiş yapılır. sold durumundaki ekipmanlar v_active_equipment görünümünde listelenmez.

5.3 Bakım kayıtları

Bir ekipman kartında Bakım Ekle butonu ile olay kaydı açılır:

• Olay tipi: oil_change, tire, general, repair, inspection.
• Tarih/saat: Olay zamanı, varsayılan olarak şu an.
• Açıklama: 2000 karakter.
• Maliyet: Pozitif sayı; girildiğinde create_maintenance_expense tetikleyicisi aynı anda maintenance kategorili bir finans kaydı oluşturur ve equipment_maintenance_events.transaction_id alanını bağlar.
• Çalışma saati: Olay anındaki saat.
• Sonraki bakım tarihi / saati: Opsiyonel; 7 gün içindeyse "Bakım hatırlatması" özet görevinin tetiklenmesini sağlar.

Bakım olayları kronolojik olarak ekipman detayında listelenir.

6. Stok / Envanter

Envanter kalemleri tohum, gübre, ilaç, yem, ürün veya diğer kategorilerinde tanımlanır. Birimler: kg, liter, bag, piece, ton.

6.1 Stok kartı oluşturma

home/farmerdeck/inventory/new formunda:

• Çiftlik: Opsiyonel.
• Ad: 1–100 karakter.
• Kategori: Listeden seçim.
• Birim: Listeden seçim.
• Açılış miktarı: Pozitif sayı, varsayılan 0.
• Minimum eşik: Boş bırakılırsa düşük stok uyarısı üretmez.
• Not: 2000 karakter.

Kayıt tek işlemde gerçekleşir; açılış bakiyesi sıfırdan büyükse aynı işlemde bir inventory_transactions (tip in) oluşturulur ve current_quantity trigger tarafından güncellenir.

6.2 Giriş, çıkış ve satış

Stok kartı detay sayfasında üç işlem yapılır:

• Giriş (in): Pozitif miktar, opsiyonel birim maliyet veya toplam maliyet. Maliyet girildiğinde kategoriye göre (seed, fertilizer, pesticide, feed, other) bir gider finans kaydı oluşturulur.
• Çıkış (out): Miktar, opsiyonel parsel ve ürün döngüsü bağlantısı. Çıkış, parsel/ürün bağlıysa kategoriye göre bir farm_events olayı oluşturur (tohum için planting, gübre için fertilization, ilaç için pesticide, diğerleri için note).
• Satış: Birim fiyat pozitif olmalıdır. record_inventory_sale RPC'si envanter çıkışı ve gelir (sale kategorili) kaydını atomik olarak yazar.

6.3 Düşük stok uyarısı

current_quantity <= min_threshold olan kalemler için v_low_stock görünümü dashboard'daki "Düşük stok" kartında listelenir. Saatlik pg_cron her kalem için açık bir auto_low_stock görevi yoksa yeni bir görev oluşturur.

7. Finans

Finans modülü gelir ve gider kayıtlarını tutar. Kategoriler: seed, fertilizer, pesticide, labor, fuel, feed, maintenance, sale, other. Varsayılan para birimi TRY; manuel kayıtlarda da TRY kullanılır, ekipman alımları için USD/EUR/TRY seçilebilir.

7.1 Manuel işlem oluşturma

home/farmerdeck/finance/new formunda:

• Çiftlik: Zorunlu (sistem bağlamı için).
• Tür: income veya expense.
• Kategori: Yukarıdaki listeden.
• Tutar: Pozitif sayı.
• Tarih/saat: İşlem zamanı.
• Açıklama: 1000 karakter.
• Bağlantılar: Parsel, ürün döngüsü, ekipman veya envanter kalemi (opsiyonel).

7.2 Otomatik finans kayıtları

• Bakım olayında maliyet girildiğinde maintenance kategorili gider kaydı otomatik üretilir.
• Stok girişinde maliyet girildiğinde kategoriye göre gider kaydı oluşturulur.
• Stok satışında gelir kaydı oluşturulur.
• Bu kayıtlar source = 'auto_*' olarak işaretlenir ve ilgili envanter/bakım kaydına bağlanır; böylece çift yazım önlenir.

7.3 Dönem özeti ve grafikler

home/farmerdeck/finance ekranında dönem seçici ile bu ay, geçen ay veya bu yıl görünümleri arasında geçiş yapılır. Seçilen dönem için gelir, gider ve net rakamlar get_monthly_profit_loss RPC'sinden gelir. Yıllık görünümde özet, ilgili yılın tüm işlemlerinin istemci tarafında toplanmasıyla hesaplanır.

7.4 Parsel kârlılığı (FR-004)

get_parcel_profitability(parcel_id, from_date, to_date) RPC'si belirli bir parsel için gelir, gider, net ve kategori bazlı dökümü döner. İleride parseller arası karşılaştırma grafikleri bu RPC üzerine kuruludur.

8. Yönetici Daveti ve Çiftlik-Bazlı Finans İzni

Çiftlik sahibi (account_id sahibi), çiftliğine yönetici davet edebilir. Bir çiftlik birden fazla kişiyle paylaşılabilir; her üyenin finans erişimi ayrıca kontrol edilir.

8.1 Davet gönderme

Çiftlik detay sayfasındaki Yöneticiler kartı üzerinden bir e-posta adresine davet gönderilir. Davet sırasında rol seçilir: manager (yönetici) veya viewer (görüntüleyici).

Gönderim aşamasında:

1. farm_invitations tablosuna yedi gün geçerli bir token ile kayıt yazılır (farm_id, email çifti benzersizdir; aynı adres için tek davet bulunur).
2. Sistem, EMAIL_SENDER ve NEXT_PUBLIC_SITE_URL ortam değişkenleri tanımlıysa davet e-postasını gönderir. E-postadaki bağlantı farm-invitations/join?invite_token=… yolunu içerir.
3. E-posta gönderimi başarısız olursa davet kaydı otomatik silinir ve kullanıcıya hata mesajı gösterilir.

8.2 Daveti kabul etme

Davet bağlantısına tıklayan kullanıcı farm-invitations/join sayfasına yönlendirilir. Bu sayfada:

• Çiftlik adı, davet edilen e-posta ve rol özetlenir.
• Kabul et düğmesi acceptFarmInvitationAction server action'ını tetikler.
• Sunucu tarafında accept_farm_invitation RPC'si çalışır: token doğrulanır, süresi geçmemiş olmalı, davet edilen e-posta ile oturum açan kullanıcının hesap e-postası birebir eşleşmelidir. Eşleşme sağlanırsa farm_members tablosuna üye kaydı yazılır (veya mevcut üyenin rolü güncellenir) ve davet kaydı silinir.
• Kabul sonrası kullanıcı çiftlik detay sayfasına yönlendirilir.

8.3 Bekleyen davetleri yönetme

Çiftlik sahibi bekleyen davetleri iptal edebilir. İptal edilen davet farm_invitations tablosundan silinir; ilgili token bir daha kullanılamaz.

8.4 Çiftlik üyelerinin finans erişimi

Çiftlik sahibi, çiftliğe eklenen her üye için finans erişim seviyesi belirleyebilir:

• none: Finansla ilgili hiçbir veri gösterilmez.
• view: Gelir-gider listesi okunabilir; kayıt oluşturulamaz.
• manage: Finans kayıtları oluşturulabilir ve düzenlenebilir.

Erişim seviyesi farm_member_permissions tablosunda tutulur: view için finance.view, manage için finance.view + finance.manage izinleri atanır. none seçildiğinde ilgili izin satırları silinir. Bu izinler, ileride eklenecek olan RLS kontrolleri için temel sağlar.

8.5 Üye kaldırma

Çiftlik sahibi üyeleri çiftlikten çıkarabilir. Kaldırma işlemi farm_members satırını siler; bağlı izin satırları da temizlenir.

9. Hava Uyarıları

Hava modülü, çiftliğinizin koordinatına göre Open-Meteo'nun ücretsiz tahminlerini kullanır (API anahtarı gerekmez).

9.1 Veri kaynağı ve güncelleme

• Tahminler Open-Meteo /v1/forecast endpoint'inden çekilir; temperature_2m_max, temperature_2m_min, precipitation_sum, wind_speed_10m_max, weather_code alanları 7 günlük olarak alınır.
• Next.js fetch revalidate: 900 (15 dakika) ile önbelleğe alınır.
• Sistem tarafında app/api/cron/weather-sync route handler'ı Vercel Cron olarak 6 saatte bir çalışır ve tüm çiftliklerin koordinatlarını gruplar halinde işler. Vercel'in GET çağrısı, CRON_SECRET ortam değişkeninin Authorization: Bearer … başlığıyla eşleşmesi halinde kabul edilir.

9.2 Uyarı kuralları

evaluateAlerts fonksiyonu 7 günlük tahmini tarar ve aşağıdaki kurallarla uyarı üretir:

• Don (frost): temp_min <= 0; -5'in altında high, aksi halde medium.
• Aşırı yağış (heavy_rain): precipitation >= 30 mm; 50 mm üzeri high, aksi halde medium.
• Dolu (hail): WMO kodu 96 veya 99; her zaman high.
• Fırtına (storm): WMO kodu ≥ 95; her zaman high.
• Sıcak hava dalgası (heatwave): temp_max >= 38°C; high.

Her risk tipi için sadece en erken tahmin zamanı saklanır.

9.3 Uyarı kayıtları ve tetiklenen görevler

Uyarılar weather_alerts tablosuna yazılır. Bu tablo kullanıcılar için salt okunurdur (authenticated yalnızca SELECT yapabilir). Orta ve yüksek riskli uyarılar için create_weather_alert_task tetikleyicisi otomatik bir auto_weather görevi oluşturur ve görevin kimliğini weather_alerts.task_id alanına yazar.

Aynı çiftlik/risk/tahmin kombinasyonu için weather_alerts_farm_risk_forecast_uidx unique index'i tekil kayıt garantisi verir; hava senkronizasyonu kontrollü paralel gruplar halinde çalıştığı için mükerrer uyarılar oluşmaz.

9.4 Dashboard ve banner

Dashboard'da birincil çiftliğin 7 günlük tahmini WeatherWidget üzerinden gösterilir (günün en yüksek/düşük sıcaklığı, yağış, rüzgâr). Aktif uyarı varsa WeatherAlertBanner üstte görünür.

10. Güvenlik

10.1 Çok kiracılı veri izolasyonu

Tüm alan tabloları account_id üzerinden RLS ile korunur. auth.uid() ile eşleşen veya yardımcı fonksiyon has_role_on_account(account_id) tarafından yetkilendirilen kullanıcılar satırları görebilir ve düzenleyebilir. accounts tablosu kit.protect_account_fields tetikleyicisi ile id, is_personal_account, primary_owner_user_id ve email alanlarının istemci tarafından değiştirilmesini engeller.

10.2 Çapraz kiracı referans kontrolü

parcels, crop_cycles, farm_events, equipment, equipment_maintenance_events, inventory_items, inventory_transactions ve weather_alerts tablolarında kit.assert_same_account_references tetikleyicisi, yabancı anahtar alanlarının aynı hesaba ait olduğunu yazma anında doğrular. Farklı bir hesaba ait UUID kullanılırsa işlem 23514 kodu ile reddedilir.

10.3 Stok toplamı bütünlüğü

kit.update_inventory_current_quantity trigger'ı, inventory_transactions üzerinde yapılan INSERT/DELETE sonrasında ilgili kalemin current_quantity alanını sistem tarafından yeniden hesaplar. Trigger yalnızca service_role yetkisiyle çalışır; kullanıcılar bu alanı doğrudan değiştiremez.

10.4 Atomik işlemler

• record_inventory_sale: Envanter çıkışı ve gelir finans kaydı tek bir işlemde yazılır; bir parça başarısız olursa tümü geri alınır.
• record_inventory_in ve record_inventory_out: Envanter hareketi, ilgili finans kaydı ve tarla olayı tek işlemde yazılır.
• create_inventory_item_with_balance: Stok kartı ve açılış bakiyesi tek işlemde oluşturulur.

10.5 Davet token'ı

Davet token'ları UUID formatındadır ve 7 gün geçerlidir. Davet yalnızca davet edilen e-postayla eşleşen oturum açmış kullanıcı tarafından kabul edilebilir; eşleşme accept_farm_invitation RPC'sinde sağlanır.

10.6 Hava cron koruması

app/api/cron/weather-sync route handler'ı yalnızca CRON_SECRET ortam değişkeniyle eşleşen Authorization: Bearer … başlığını kabul eder; aksi halde 401 döner.

11. Destek

11.1 Hata veya veri sorunu bildirimi

Bir işlem kaydı, stok toplamı veya hava uyarısı beklediğiniz gibi değilse:

1. Etkilenen hesapla oturum açın ve home/farmerdeck dashboard'unu kontrol edin.
2. Sorun devam ediyorsa tarayıcıda konsol hatası olup olmadığını not edin.
3. Hata ekran görüntüsü, hesap kimliği (gizli) ve ilgili parsel/ürün/ekipman UUID'si ile destek ekibine başvurun.

11.2 Bilinen kısıtlar

• Hava uyarıları yalnızca enlem/boylam bilgisi girilmiş çiftlikler için üretilir.
• Bakım hatırlatması özet görevi günde en fazla bir kez oluşturulur; kalem bazlı auto_low_stock görevleri ise saatlik cron ile üretilir.
• Stok satışı yalnızca pozitif miktar ve pozitif birim fiyatla kaydedilebilir; aksi durumda RPC hata döner.

11.3 Ortam gereksinimleri

Aşağıdaki ortam değişkenlerinin tanımlı olması gerekir:

• NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY (uygulama istemcisi için).
• OPEN_METEO_API_URL (opsiyonel, varsayılan Open-Meteo'nun genel uç noktası).
• EMAIL_SENDER, NEXT_PUBLIC_SITE_URL (çiftlik davet e-postaları için; tanımsızsa davet e-postası gönderilmez ve kullanıcı bilgilendirilir).
• CRON_SECRET (hava senkronizasyonu için).