From 88fba774390051ec05442ce90427d13cbbb219a3 Mon Sep 17 00:00:00 2001 From: Ohualtex <230626673+Ohualtex@users.noreply.github.com> Date: Sun, 7 Jun 2026 16:24:40 +0300 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20eski/duplike=20d=C3=B6k=C3=BCmanlar?= =?UTF-8?q?=C4=B1=20kald=C4=B1r=20+=20birle=C5=9Ftir=20(33=E2=86=9221)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 7 eski/çelişkili planlama-araştırma dökümanı kaldırıldı (hiç yapılmamış özellikleri anlatıyordu: market scraping, TensorFlow, OpenCV, edge computing, LSTM) - Konsolidasyon: test (3→1 Test_Stratejisi), ML (3→1 Makine_Ogrenimi_Rehberi — sahte GradientBoosting iddiası kaldırıldı, gerçek RandomForest korundu), sensör (2→1) Co-Authored-By: Claude Opus 4.8 --- ...Eri\305\237im_API'si_Geli\305\237tirme.md" | 57 --- docs/cnn_model_status_report.md | 106 ----- .../SENSOR_INTEGRATION_DOCUMENTATION.md | 363 ++++++++++++++---- docs/database/sensor_readme.md | 301 --------------- docs/ml/Makine_Ogrenimi_Rehberi.md | 117 +++++- docs/model_evaluation_report.md | 90 ----- "docs/planning/Veri_Hatti_\304\260zleme.md" | 12 - .../Veri_Kaynagi_ve_Toplama_Plan\304\261.md" | 20 - ...03\266rselle\305\237tirme_Entegrasyonu.md" | 22 -- .../Gerekli_Teknolojilerin_Arastirilmasi.md | 54 --- .../Veri_Seti_Analizi_ve_Model_Secimi.md | 46 --- docs/setup/Gelistirme_Ortaminin_Kurulumu.md | 16 - ...Test_Validasyon_ve_Hata_Ayiklama_Raporu.md | 77 ---- .../Hata_Ayiklama_ve_Dogrulama_Loglari.md | 54 --- docs/testing/Test_Stratejisi.md | 122 +++++- 15 files changed, 501 insertions(+), 956 deletions(-) delete mode 100644 "docs/api/Temel_Veri_Eri\305\237im_API'si_Geli\305\237tirme.md" delete mode 100644 docs/cnn_model_status_report.md delete mode 100644 docs/database/sensor_readme.md delete mode 100644 docs/model_evaluation_report.md delete mode 100644 "docs/planning/Veri_Hatti_\304\260zleme.md" delete mode 100644 "docs/planning/Veri_Kaynagi_ve_Toplama_Plan\304\261.md" delete mode 100644 "docs/planning/Web_Aray\303\274z\303\274_Veri_G\303\266rselle\305\237tirme_Entegrasyonu.md" delete mode 100644 docs/research/Gerekli_Teknolojilerin_Arastirilmasi.md delete mode 100644 docs/research/Veri_Seti_Analizi_ve_Model_Secimi.md delete mode 100644 docs/setup/Gelistirme_Ortaminin_Kurulumu.md delete mode 100644 docs/testing/Hafta_6_Test_Validasyon_ve_Hata_Ayiklama_Raporu.md delete mode 100644 docs/testing/Hata_Ayiklama_ve_Dogrulama_Loglari.md diff --git "a/docs/api/Temel_Veri_Eri\305\237im_API'si_Geli\305\237tirme.md" "b/docs/api/Temel_Veri_Eri\305\237im_API'si_Geli\305\237tirme.md" deleted file mode 100644 index 9a395d8..0000000 --- "a/docs/api/Temel_Veri_Eri\305\237im_API'si_Geli\305\237tirme.md" +++ /dev/null @@ -1,57 +0,0 @@ -# 🌾 Akıllı Tarım Veri Analizi ve Karar Destek Platformu (S.F.D.A.P.) - -> **Tarihsel doküman — proje ilk haftalarındaki API tasarım kararlarını belgeler.** -> Güncel API kullanımı için [`API_Kullanim_Kilavuzu.md`](./API_Kullanim_Kilavuzu.md) ve `/docs` Swagger UI. - -**Departman:** Fırat Üniversitesi, Yazılım Mühendisliği Bölümü - ---- - -## 📑 Proje Genel Bakış ve Problem Tanımı -Modern tarımda verimlilik, rastgele sulama veya gübreleme ile değil; veriye dayalı kararlar ile sağlanır. Bu platform, geleneksel çiftçilik yöntemlerini **IoT (Nesnelerin İnterneti)** ve **Yapay Zeka** ile birleştirerek tarımsal kaynakların optimum kullanılmasını sağlar. - -**Hafta 4 Odak Noktası:** Toprak sensörlerinden ve meteorolojik istasyonlardan gelen heterojen verilerin, sistemin diğer bileşenleri (Mobil uygulama, Web Dashboard ve AI Modelleri) tarafından tüketilebilmesi için standartlaştırılmış bir **RESTful API** katmanının mimari kurulumu gerçekleştirilmiştir. - ---- - -## 🚀 Teknik Stack ve Ekosistem - -Sistemin kalbinde yer alan teknolojiler ve tercih nedenleri: - -| Teknoloji | Kullanım Amacı | Avantajı | -| :--- | :--- | :--- | -| **Python 3.10+** | Ana Programlama Dili | Veri bilimi kütüphaneleriyle (Pandas/TensorFlow) tam uyum. | -| **FastAPI** | Web Framework | Pydantic sayesinde otomatik veri validasyonu ve yüksek performans. | -| **Uvicorn** | ASGI Server | Asenkron istekleri yöneterek sistemin çökmesini engeller. | -| **OpenAPI/Swagger** | Dokümantasyon | Geliştiriciler için interaktif test arayüzü sağlar. | -| **API Key Auth** | Güvenlik | Veri gizliliğini sağlamak adına yetkilendirme katmanı. | - ---- - -## 🛠️ Mimari Katmanlar ve API Tasarımı - -### 1. Veri Erişim Katmanı (Data Access Layer) -API, düşük seviyeli sensör verilerini alır ve bunları anlamlı JSON objelerine dönüştürür. - -* **Toprak Analizi:** Nem (`moisture`), asidite (`pH`) ve besin değerleri (`nitrogen`) sensörlerden asenkron olarak okunur. -* **Meteorolojik Veri:** Lokasyon bazlı sıcaklık ve tahmin verileri standardize edilir. - -### 2. Güvenlik Katmanı (Security Layer) -Üçüncü şahısların sensör verilerine erişimini engellemek adına `X-API-Key` mekanizması uygulanmıştır. Her istek, backend tarafında bir `Depends` (Bağımlılık Enjeksiyonu) filtresinden geçerek doğrulanır. - ---- - -## 📊 API Endpoint (Uç Nokta) Spesifikasyonları - -### [GET] `/api/v1/soil-data` -Tarladaki aktif IoT cihazlarından gelen verileri döndürür. -- **Header:** `X-API-Key: ` -- **Response Format:** `application/json` -- **Örnek Veri Yapısı:** - ```json - { - "sensor_id": "FIRAT-SENS-12", - "moisture_level": 48.7, - "ph_level": 6.4, - "nitrogen_level": 45 - } diff --git a/docs/cnn_model_status_report.md b/docs/cnn_model_status_report.md deleted file mode 100644 index 7f5cb11..0000000 --- a/docs/cnn_model_status_report.md +++ /dev/null @@ -1,106 +0,0 @@ -# Bitki Hastalığı Tespit Modeli — Teknik Durum Notu - -**Proje:** SFDAP — Akıllı Tarım Veri Analizi Platformu -**Hafta:** 6 -**Konu:** CNN Tabanlı Bitki Hastalığı Tespit Modeli Durum Değerlendirmesi -**İlgili Dosya:** `app/ml/plant_disease_model.py` - ---- - -## 1. Mevcut Durum - -`PlantDiseaseModel` sınıfı iki çalışma moduna sahip olarak tasarlanmıştır: - -| Mod | Açıklama | Durum | -|---|---|---| -| **ONNX Modu** | Eğitilmiş CNN modeli ile gerçek inference | Henüz hazır değil | -| **Heuristic Mod** | Renk analizi tabanlı kural-bazlı teşhis | Aktif ve çalışıyor | - -Sistem başlatıldığında `app/ml/models/plant_disease_cnn.onnx` dosyası aranmaktadır. Bu dosya henüz mevcut olmadığından model otomatik olarak heuristic moda geçmektedir. - ---- - -## 2. Tespit Edilebilen Hastalıklar - -Model şu an 8 sınıfı desteklemektedir: - -| Sınıf | Açıklama | Şiddet | -|---|---|---| -| healthy | Sağlıklı yaprak | Yok | -| leaf_spot | Yaprak lekesi | Düşük | -| powdery_mildew | Külleme | Orta | -| rust | Pas hastalığı | Orta | -| blight | Yanıklık | Yüksek | -| mosaic_virus | Mozaik virüsü | Yüksek | -| bacterial_wilt | Bakteriyel solgunluk | Yüksek | -| anthracnose | Antraknoz | Orta | - ---- - -## 3. Model Test Çıktısı - -Heuristic modun 4 farklı yaprak görüntüsü senaryosu üzerindeki tahmin sonuçları -![Test Ciktisi](test_output.png) - -| Test Senaryosu | Teşhis | Güven Skoru | Şiddet | -|---|---|---|---| -| Sağlıklı Yaprak | healthy | 0.86 | none | -| Yaprak Lekesi | leaf_spot | 0.86 | low | -| Külleme | powdery_mildew | 0.80 | medium | -| Yanıklık | blight | 0.95 | high | - ---- - -## 4. Heuristic Modun Çalışma Mantığı - -Model, yaprak görüntüsünü HSV renk uzayına çevirerek şu renk oranlarını analiz eder: - -| Renk Sinyali | Eşik | Olası Teşhis | -|---|---|---| -| Beyaz/gri tabaka | %18 üzeri | powdery_mildew | -| Kahverengi leke | %25 üzeri | blight | -| Kahverengi leke | %12-25 arası | leaf_spot | -| Sarı baskın | %18 üzeri | mosaic_virus veya anthracnose | -| Düşük doygunluk | %15 altı | rust | -| Yüksek yeşil oranı | %40 üzeri | healthy | -| Diğer | — | bacterial_wilt | - ---- - -## 5. Performans Metrikleri - -CNN modeli henüz eğitilmediğinden gerçek metrikler hesaplanamamaktadır: - -| Metrik | Hedef | Mevcut Durum | -|---|---|---| -| Accuracy | %90 ve üzeri | Ölçülemiyor (ONNX eksik) | -| Precision | %88 ve üzeri | Ölçülemiyor (ONNX eksik) | -| Recall | %88 ve üzeri | Ölçülemiyor (ONNX eksik) | -| Confusion Matrix | — | Ölçülemiyor (ONNX eksik) | - ---- - -## 6. Mevcut Sınırlar - -1. **ONNX modeli eksik:** plant_disease_cnn.onnx dosyası henüz üretilmemiştir. -2. **Heuristic modun yetersizliği:** Renk tabanlı analiz yalnızca belirgin renk farklılıklarında doğru çalışır. Erken evre hastalıklar ve düşük ışık koşullarında hatalı teşhis riski yüksektir. -3. **Çoklu hastalık desteği yok:** Model bir görüntüde yalnızca tek bir hastalık sınıfı döndürmektedir. -4. **Bitki türü ayrımı yok:** Tüm bitki türleri için aynı model kullanılmaktadır. -5. **Veri seti bağımlılığı:** PlantVillage veri seti laboratuvar koşullarında çekilmiş görüntüler içermektedir. Gerçek saha görüntüleri ile performans düşebilir. - ---- - -## 7. İlerleyen Sprintler İçin Açık Adımlar - -- PlantVillage veri seti ile TensorFlow/Keras CNN modelinin eğitilmesi -- Eğitilen modelin ONNX formatına export edilmesi (plant_disease_cnn.onnx) -- app/ml/models/ klasörüne ONNX dosyasının eklenmesi -- ONNX modu aktifken accuracy, precision, recall ve confusion matrix hesaplanması -- Test görüntüleri üzerinde gerçek tahmin çıktılarının belgelenmesi -- Bitki türüne göre özelleştirilmiş model desteğinin araştırılması - ---- - -## 8. Sonuç - -CNN tabanlı bitki hastalığı tespit modeli mimari olarak tamamlanmış ve sisteme entegre edilmiştir. Model, ONNX dosyası hazır olduğunda otomatik olarak gerçek CNN inference moduna geçecek şekilde tasarlanmıştır. Mevcut heuristic mod, CNN eğitimi tamamlanana kadar geçici bir çözüm olarak işlev görmektedir. Projenin ilerleyen sprintlerinde PlantVillage veri seti ile model eğitiminin tamamlanması öncelikli hedef olarak belirlenmiştir. diff --git a/docs/database/SENSOR_INTEGRATION_DOCUMENTATION.md b/docs/database/SENSOR_INTEGRATION_DOCUMENTATION.md index 5647c8a..3cdaafd 100644 --- a/docs/database/SENSOR_INTEGRATION_DOCUMENTATION.md +++ b/docs/database/SENSOR_INTEGRATION_DOCUMENTATION.md @@ -1,10 +1,14 @@ # SFDAP Sensör Veri Entegrasyon Modülü - Dokümantasyon +> Bu dosya, sensör veri entegrasyonu için **tek başvuru kaynağıdır**: hem detaylı +> mimari/teknik dokümantasyon hem de hızlı başlangıç kılavuzu burada birleştirilmiştir. + ## 📋 Proje Özeti **Proje Adı:** Smart Farming Data Analysis Platform (SFDAP) — Sensör Veri Entegrasyonu **Modül:** Toprak Nem Sensörleri Veri Temizleme & Veritabanına Kayıt -**Dosya:** `scripts/sensor_integration.py` +**Ana Betik:** `scripts/sensor_integration.py` +**Doğrulama Aracı:** `scripts/verify_sensor_data.py` --- @@ -19,9 +23,45 @@ ### Teknik Gereksinimler - **Kütüphaneler:** Pandas, NumPy, SQLAlchemy -- **Veritabanı:** SQLite (sfdap.db) +- **Veritabanı:** SQLite (`database/sfdap.db`) - **Tablo:** `soil_moisture_readings` - **Python Sürümü:** 3.8+ +- **Platform:** Windows / Linux / macOS + +--- + +## 🗄️ Veritabanı Şeması Uyumu + +ETL betiği, ORM modeli `app.models.models.SoilMoistureReading` ile birebir aynı +`soil_moisture_readings` tablosuna yazar. Tablo alanları: + +| Sütun | Tip | Açıklama | +|-------|-----|----------| +| `id` | Integer (PK) | Otomatik artan birincil anahtar | +| `sensor_id` | Integer (FK → `sensors.id`) | İlgili sensör (zorunlu) | +| `reading_timestamp` | DateTime | Ölçüm zamanı (varsayılan: UTC now) | +| `moisture_percent` | Float | Toprak nem yüzdesi (zorunlu) | +| `depth_cm` | Float | Ölçüm derinliği (cm) | +| `soil_temperature_c` | Float | Toprak sıcaklığı (°C) | +| `electrical_conductivity` | Float | Elektriksel iletkenlik (dS/m) | + +> Not: Sensörlerin kendileri `sensors` tablosunda tutulur +> (`field_id`, `sensor_type`, `serial_number`, `depth_cm`, `lat`, `lng`, `status`). +> 30 günden eski okumalar `sensor_reading_monthly_aggregates` tablosuna periyodik +> olarak özetlenir (bkz. `app.models.models.SensorReadingMonthlyAggregate`). + +### REST API ile İlişki + +Bu ETL betiği toplu/offline veri yükleme içindir. Aynı tabloya canlı erişim +`app/routers/sensors.py` üzerinden `/api/sensors` ön ekiyle sağlanır +(rol-aware RBAC; tüm uçlar Bearer JWT ister): + +- `GET /api/sensors/` — sensörleri listele (rol-aware sayfalama) +- `GET /api/sensors/{sensor_id}` — tek sensör detayı +- `POST /api/sensors/` — sensör ekle (farmer + admin) +- `DELETE /api/sensors/{sensor_id}` — sensör sil (farmer + admin) +- `POST /api/sensors/readings` — okuma kaydet +- `GET /api/sensors/{sensor_id}/readings` — sensör okumalarını listele --- @@ -65,15 +105,16 @@ sensor_integration.py ### Adım 1: Ham Veri Üretimi (Data Generation) ```python -def generate_sample_raw_data(num_records=20) -> pd.DataFrame +def generate_sample_raw_data(num_records: int = 20) -> pd.DataFrame ``` **Üretilen Veriler:** - **Nem Değerleri:** Geçerli (%30-90), Hatalı (%150, -50), Eksik (NaN) - **Sıcaklık Değerleri:** Geçerli (20-26°C), Hatalı (-99°C, 150°C, 999°C), Eksik (NaN) -- **Timestamp:** Güncel tarih/saatler -- **Sensör ID:** 1-4 arası rastgele -- **Derinlik:** 15, 30, 45, 60 cm +- **Timestamp (`reading_timestamp`):** Güncel tarih/saatler (saatlik geriye doğru) +- **Sensör ID (`sensor_id`):** 1-4 arası rastgele (`np.random.randint(1, 5)`) +- **Derinlik (`depth_cm`):** 15, 30, 45, 60 cm +- **Elektriksel İletkenlik (`electrical_conductivity`):** 0.8-4.0 dS/m arası ### Adım 2: Veri Temizleme (ETL Pipeline) @@ -83,7 +124,7 @@ MOISTURE_MIN_PERCENT = 0 MOISTURE_MAX_PERCENT = 100 ``` - %0-100 aralığı dışında olan değerler → NaN -- Hatalı örnek: 150%, -50% → NaN +- Hatalı örnek: 150%, -50%, 200% → NaN #### b) Sıcaklık Verileri Temizleme ```python @@ -94,20 +135,24 @@ TEMPERATURE_MAX_C = 60 - Hatalı örnek: -99°C, 150°C, 999°C → NaN #### c) Timestamp Temizleme -- Timestamp sütununu datetime'a dönüştür -- Eksik zaman damgalarını şimdiki zamana ayarla +- `reading_timestamp` sütununu datetime'a dönüştür (`errors="coerce"`) +- Eksik zaman damgalarını şimdiki zamana (UTC now) ayarla #### d) Eksik Satırları Kaldırma -Kritik alanlar (sensor_id, moisture_percent, soil_temperature_c) eksik olanları sil +Kritik alanlar eksik olan satırlar silinir: +`sensor_id`, `moisture_percent`, `soil_temperature_c` ### Adım 3: Veritabanına Kayıt ```python df.to_sql( - 'soil_moisture_readings', - if_exists='append', # Mevcut veriyi korur - method='multi' # Toplu ekleme + "soil_moisture_readings", + con=engine, + if_exists="append", # Mevcut veriyi korur + index=False, + method="multi", # Toplu ekleme ) ``` +Toplu kayıt başarısız olursa `insert_data_row_by_row()` ile satır satır fallback yapılır. ### Adım 4: Raporlama - Ham veri istatistikleri @@ -116,6 +161,41 @@ df.to_sql( --- +## 🚀 Hızlı Başlangıç + +### 1. Adım: Programı Çalıştır + +```bash +cd Smart_Farming_Data_Analysis_Platform +python scripts/sensor_integration.py +``` + +**Ne Olur?** +- Ham sensör verisi üretilir (20 satır) +- Veri temizleme ve doğrulama yapılır +- Temizlenmiş veriler veritabanına kaydedilir +- Detaylı rapor gösterilir + +**Beklenen Çıktı (özet):** +``` +✓ 12 satır başarıyla kaydedildi (%60 tutma oranı) +✓ 8 satır hatalı/eksik bulunup silindi +``` + +### 2. Adım: Verileri Doğrula + +```bash +python scripts/verify_sensor_data.py +``` + +**Ne Gösterir?** +- Veritabanındaki tüm kayıtlar +- İstatistikler (ortalama, min, max, std. sapma) +- Veri kalitesi kontrolleri +- ⭐ Kalite puanı (ideal: %100) + +--- + ## ✅ Program Çalıştırma Sonuçları ### Örnek Çıktı @@ -195,6 +275,82 @@ df.to_sql( | **Sensör Çeşitliliği** | 4 sensör | İyi coğrafi dağılım | | **Veritabanı Başarısı** | %100 | Hatasız kayıt | +> Değerler örnek/temsilidir; üretim her çalıştırmada rastgele veri ürettiği için +> tam sayılar değişebilir. + +--- + +## 📊 Veri Temizleme Kriterleri + +| Kriter | Aralık | Hatalı Örnekler | +|--------|--------|-----------------| +| **Nem (%)** | 0 - 100 | 150%, -50%, 200% | +| **Sıcaklık (°C)** | -10 - 60 | -99°C, 150°C, 999°C | +| **Timestamp** | Geçerli tarih | - | +| **Eksik Veriler** | YOK | NaN, None | + +--- + +## ⚙️ Konfigürasyon + +### Veritabanı Konumu +```python +# sensor_integration.py içinde +PROJECT_ROOT = current_dir.parent +DATABASE_PATH = PROJECT_ROOT / "database" / "sfdap.db" +``` + +### Doğrulama Aralıklarını Değiştirme +```python +# Nem aralığı (varsayılan: 0-100%) +MOISTURE_MIN_PERCENT = 0 # min +MOISTURE_MAX_PERCENT = 100 # max + +# Sıcaklık aralığı (varsayılan: -10 - 60°C) +TEMPERATURE_MIN_C = -10 # min +TEMPERATURE_MAX_C = 60 # max +``` + +### Ham Veri Sayısını Değiştirme +Varsayılan 20 satırdır. Daha fazla üretmek için `main()` içindeki çağrıyı düzenleyin: +```python +raw_data = generate_sample_raw_data(num_records=40) +``` + +--- + +## 💾 Veritabanı Sorguları + +### Tüm Verileri Görüntüle +```sql +SELECT * FROM soil_moisture_readings ORDER BY reading_timestamp DESC; +``` + +### İstatistikler +```sql +SELECT + COUNT(*) as kayit_sayisi, + AVG(moisture_percent) as ort_nem, + MIN(moisture_percent) as min_nem, + MAX(moisture_percent) as max_nem, + AVG(soil_temperature_c) as ort_sicaklik +FROM soil_moisture_readings; +``` + +### Sensör Başına Ölçümler +```sql +SELECT sensor_id, COUNT(*) as olcum_sayisi +FROM soil_moisture_readings +GROUP BY sensor_id; +``` + +### Son 5 Ölçüm +```sql +SELECT * FROM soil_moisture_readings +ORDER BY reading_timestamp DESC +LIMIT 5; +``` + --- ## 🔍 Hata Yönetimi @@ -205,58 +361,123 @@ df.to_sql( ```python except SQLAlchemyError as e: print(f"⚠ Veritabanı hatası: {e}") - # Satır satır kaydetme fallback + # Satır satır kaydetme fallback (insert_data_row_by_row) ``` #### 2. Yol (Path) Hatası -- Windows uyumu: backslash → forward slash dönüşümü -- Relative path kullanımı +- `pathlib.Path` ile platformlar arası uyumlu yol oluşturma +- `PROJECT_ROOT` referanslı göreli yol kullanımı #### 3. Veri Tipi Hataları -- Timestamp dönüşümler: `errors='coerce'` ile tutarsız formatları işle +- Timestamp dönüşümleri: `errors="coerce"` ile tutarsız formatları işle - NaN işleme: `dropna()` ile eksik satırları kaldır --- -## 📈 Geliştirme Önerileri +## 🐛 Sorun Giderme -### Kısa Vadede -1. **Veri Doğrulama:** JSON şema doğrulaması ekle -2. **Loglama:** `logging` modülü ile kayıt al -3. **Konfigürasyon:** `.env` dosyasından ayarlar oku +### Hata: "Veritabanı dosyası bulunamadı" +```bash +# Veritabanını oluştur +python -c "import sqlite3; sqlite3.connect('database/sfdap.db').close()" -### Orta Vadede -1. **Veri Kalitesi:** İstatistiksel anomali tespiti -2. **Hata İyileştirme:** Outlier değerlerini düzümü/winsorize et -3. **Batch İşleme:** Büyük veri setleri için partition sistemi +# Programı çalıştır +python scripts/sensor_integration.py +``` -### Uzun Vadede -1. **Makine Öğrenmesi:** Anomali tespiti ve tahmin modelleri -2. **Gerçek Zamanlı İşleme:** Kafka/RabbitMQ entegrasyonu -3. **Monitöring:** ELK Stack veya Prometheus uyarıları +### Hata: "Tablo bulunamadı" +Şema eksik. Program otomatik yüklemelidir; manuel yükleme için: +```bash +sqlite3 database/sfdap.db < database/sfdap_schema.sql +``` + +### Hata: "ModuleNotFoundError: pandas/numpy/sqlalchemy" +```bash +pip install -r requirements.txt +``` + +--- + +## 📈 İşlem Adımları (Detaylı) + +``` +1. VERİ ÜRETİMİ + └─ 20 satırlık ham sensör verisi + - ~12 satır geçerli + - ~8 satır hatalı/eksik + +2. ETL ARDIŞIK DÜZENI + ├─ Nem temizliği (0-100%) + ├─ Sıcaklık temizliği (-10-60°C) + ├─ Timestamp normalizasyonu + └─ Eksik satırları kaldırma + +3. VERİTABANINA KAYIT + ├─ Append modu (var olan veriyi korur) + ├─ Toplu işlem (method="multi") + └─ Hata toleransı (satır satır fallback) + +4. RAPORLAMA + ├─ Ham veri istatistikleri + ├─ Temizleme özeti + └─ Veritabanı sonuçları +``` + +--- + +## 📚 Betik İçerik Özeti + +### sensor_integration.py +**Satır:** ~507 | **Fonksiyon:** 12 +**Görevi:** Veri üretme, temizleme, kaydetme, raporlama + +### verify_sensor_data.py +**Satır:** ~227 | **Fonksiyon:** 7 +**Görevi:** Veritabanı doğrulama, istatistik, kalite kontrolü --- -## 🚀 Kullanım +## ✅ Kontrol Listesi + +- [x] Veritabanı bağlantısı çalışıyor +- [x] Veritabanı şeması yüklü +- [x] Ham veri üretimi başarılı +- [x] ETL temizliği işe yaradı (~%60 tutma) +- [x] Veritabanı kaydı başarılı +- [x] Tüm değerler geçerli aralıkta +- [x] Eksik veri yok + +--- -### Çalıştırma +## 📞 Faydalı Komutlar +### Veritabanı İçeriğini SQLite ile Kontrol Et ```bash -cd Smart_Farming_Data_Analysis_Platform -python scripts/sensor_integration.py +sqlite3 database/sfdap.db +sqlite> SELECT COUNT(*) FROM soil_moisture_readings; +sqlite> .tables +sqlite> .schema soil_moisture_readings +sqlite> .exit ``` -### Çıktı Dosyaları - -- **Veritabanı:** `database/sfdap.db` -- **Tablo:** `soil_moisture_readings` +### CSV'ye Dışa Aktar +```bash +sqlite3 database/sfdap.db +sqlite> .mode csv +sqlite> .output readings.csv +sqlite> SELECT * FROM soil_moisture_readings; +sqlite> .exit +``` -### Veritabanı Sorgusu (Kontrol) +### Python REPL'de Kontrol +```python +import pandas as pd +import sqlite3 -```sql -SELECT COUNT(*) as kayit_sayisi FROM soil_moisture_readings; -SELECT AVG(moisture_percent) as ort_nem FROM soil_moisture_readings; -SELECT * FROM soil_moisture_readings ORDER BY reading_timestamp DESC LIMIT 5; +conn = sqlite3.connect("database/sfdap.db") +df = pd.read_sql_query("SELECT * FROM soil_moisture_readings", conn) +print(df.head(10)) +print(df.describe()) ``` --- @@ -264,52 +485,37 @@ SELECT * FROM soil_moisture_readings ORDER BY reading_timestamp DESC LIMIT 5; ## 📝 Teknik Detaylar ### Kullanılan Kütüphaneler - ```python import pandas as pd # Veri işleme -import numpy as np # Sayısal hesaplamalar +import numpy as np # Sayısal hesaplamalar from sqlalchemy import create_engine, text # Veritabanı -from pathlib import Path # Dosya yolu yönetimi -from datetime import datetime, timedelta # Zaman işlemleri +from pathlib import Path # Dosya yolu yönetimi +from datetime import datetime, timedelta, UTC # Zaman işlemleri ``` -### Tasarım Kalıpları - -1. **Builder Pattern:** ETL pipeline yapısı -2. **Strategy Pattern:** Farklı temizleme stratejileri -3. **Error Handler Pattern:** Hata yönetimi - ### Performans - - **Veri İşleme:** O(n) karmaşıklık -- **Veritabanı Kayıt:** Toplu işlem (method='multi') +- **Veritabanı Kayıt:** Toplu işlem (`method="multi"`) - **Bellek Kullanımı:** DataFrame kopyalama minimize edildi --- -## ✨ Öne Çıkan Özellikler - -### 1. Kapsamlı Temizleme -- Nem değerleri doğrulanması -- Sıcaklık değerleri doğrulanması -- Timestamp normalizasyonu -- Eksik veri yönetimi +## 📈 Geliştirme Önerileri -### 2. Detaylı Raporlama -- Ham veri istatistikleri -- Temizleme öncesi/sonrası karşılaştırma -- Veritabanı işlem sonuçları -- Görsel çıktı (emoji, çizgiler) +### Kısa Vadede +1. **Veri Doğrulama:** JSON şema doğrulaması ekle +2. **Loglama:** `logging` modülü ile kayıt al +3. **Konfigürasyon:** `.env` dosyasından ayarlar oku -### 3. Hata Toleransı -- Kısmi başarı durumunda satır satır kaydetme -- Bağlantı hatalarında fallback mekanizması -- Kullanıcı tarafından durdurulabilirlik +### Orta Vadede +1. **Veri Kalitesi:** İstatistiksel anomali tespiti +2. **Hata İyileştirme:** Outlier değerlerini winsorize et +3. **Batch İşleme:** Büyük veri setleri için partition sistemi -### 4. Ölçeklenebilirlik -- Modüler fonksiyonlar -- Parameterize edilebilir sabitler -- Batch işleme desteği +### Uzun Vadede +1. **Makine Öğrenmesi:** Anomali tespiti ve tahmin modelleri +2. **Gerçek Zamanlı İşleme:** Kuyruk tabanlı akış entegrasyonu +3. **İzleme:** Metrik/uyarı altyapısı --- @@ -317,8 +523,9 @@ from datetime import datetime, timedelta # Zaman işlemleri - [Pandas Documentation](https://pandas.pydata.org/docs/) - [SQLAlchemy Documentation](https://docs.sqlalchemy.org/) -- [Clean Code Principles](https://en.wikipedia.org/wiki/Code_smell) -- [SFDAP Veritabanı Şeması](../database/sfdap_schema.sql) +- [SQLite](https://www.sqlite.org/) +- [ETL — Wikipedia](https://en.wikipedia.org/wiki/Extract,_transform,_load) +- [SFDAP Veritabanı Şeması](./sfdap_schema.sql) --- @@ -327,8 +534,8 @@ from datetime import datetime, timedelta # Zaman işlemleri | Sürüm | Tarih | Notlar | |-------|-------|--------| | 1.0 | 2026-04-08 | İlk versiyon - Temel ETL fonksiyonları | +| 1.1 | 2026-06-07 | Hızlı başlangıç kılavuzu birleştirildi; güncel kod/şema ile uyumlandı | --- -**Son Güncelleme:** 2026-04-08 **Durum:** ✅ Üretim Hazır diff --git a/docs/database/sensor_readme.md b/docs/database/sensor_readme.md deleted file mode 100644 index 62e1597..0000000 --- a/docs/database/sensor_readme.md +++ /dev/null @@ -1,301 +0,0 @@ -# SFDAP Sensör Veri Entegrasyon - Hızlı Başlangıç Kılavuzu - -## 📌 Dosya Yapısı - -``` -scripts/ -├── sensor_integration.py # Ana entegrasyon programı -└── verify_sensor_data.py # Veri doğrulama aracı - -docs/database/ -├── SENSOR_INTEGRATION_DOCUMENTATION.md # Detaylı dokümantasyon -└── sensor_readme.md # Bu dosya -``` - ---- - -## 🚀 Hızlı Başlangıç - -### 1. Adım: Programı Çalıştır - -```bash -cd Smart_Farming_Data_Analysis_Platform -python scripts/sensor_integration.py -``` - -**Ne Olur?** -- Ham ısıl sensör verisi üretilir (20 satır) -- Veri temizleme ve doğrulama yapılır -- Temizlenmiş veriler veritabanına kaydedilir -- Detaylı rapor gösterilir - -**Beklenen Çıktı:** -``` -✓ 12 satır başarıyla kaydedildi (%60 tutma oranı) -✓ 8 satır hatalı/eksik bulunup silindi -``` - ---- - -### 2. Adım: Verileri Doğrula - -```bash -python scripts/verify_sensor_data.py -``` - -**Ne Gösterir?** -- Veritabanındaki tüm kayıtlar -- İstatistikler (ortalama, min, max, std. sapma) -- Veri kalitesi kontrolleri -- ⭐ Kalite puanı (ideal: %100) - ---- - -## 📊 Veri Temizleme Kriterlerine - -| Kriter | Aralık | Hatalı Örnekler | -|--------|--------|-----------------| -| **Nem (%)** | 0 - 100 | 150%, -50%, 200% | -| **Sıcaklık (°C)** | -10 - 60 | -99°C, 150°C, 999°C | -| **Timestamp** | Geçerli tarih | - | -| **Eksik Veriler** | YOK | NaN, None | - ---- - -## 🔍 Program Parametreleri - -### Nem Verileri -```python -MOISTURE_MIN_PERCENT = 0 -MOISTURE_MAX_PERCENT = 100 -``` - -### Sıcaklık Verileri -```python -TEMPERATURE_MIN_C = -10 -TEMPERATURE_MAX_C = 60 -``` - -### Ham Veri Sayısı -```bash -python sensor_integration.py # 20 satır varsayılan -``` - -**Değiştirmek için:** Kodu düzenle ve `generate_sample_raw_data(40)` çağrı - ---- - -## 💾 Veritabanı Sorguları - -### Tüm Verileri Görüntüle -```sql -SELECT * FROM soil_moisture_readings ORDER BY reading_timestamp DESC; -``` - -### İstatistikler -```sql -SELECT - COUNT(*) as kayit_sayisi, - AVG(moisture_percent) as ort_nem, - MIN(moisture_percent) as min_nem, - MAX(moisture_percent) as max_nem, - AVG(soil_temperature_c) as ort_sicaklik -FROM soil_moisture_readings; -``` - -### Sensör Başına Ölçümler -```sql -SELECT sensor_id, COUNT(*) as olcum_sayisi -FROM soil_moisture_readings -GROUP BY sensor_id; -``` - -### Son 5 Ölçüm -```sql -SELECT * FROM soil_moisture_readings -ORDER BY reading_timestamp DESC -LIMIT 5; -``` - ---- - -## ⚙️ Konfigürasyon - -### Veritabanı Konumu -```python -# sensor_integration.py içinde -DATABASE_PATH = PROJECT_ROOT / "database" / "sfdap.db" -``` - -### Doğrulama Aralıklarını Değiştirme - -```python -# Nem aralığı (default: 0-100%) -MOISTURE_MIN_PERCENT = 0 # min -MOISTURE_MAX_PERCENT = 100 # max - -# Sıcaklık aralığı (default: -10 - 60°C) -TEMPERATURE_MIN_C = -10 # min -TEMPERATURE_MAX_C = 60 # max -``` - ---- - -## 🐛 Sorun Giderme - -### Hata: "Veritabanı dosyası bulunamadı" - -**Çözüm:** -```bash -# Veritabanını oluştur -python -c "import sqlite3; sqlite3.connect('database/sfdap.db').close()" - -# Programı çalıştır -python scripts/sensor_integration.py -``` - -### Hata: "Tablo bulunamadı" - -**Çözüm:** Şema eksik. Program otomatik olarak yüklemelidir: -```bash -# Şemayı manuel olarak yükle -sqlite3 database/sfdap.db < database/sfdap_schema.sql -``` - -### Hata: "ModuleNotFoundError: pandas/numpy/sqlalchemy" - -**Çözüm:** -```bash -pip install -r requirements.txt -``` - ---- - -## 📈 İşlem Adımları (Detaylı) - -``` -1. VERİ ÜRETİMİ - └─ 20 satırlık ham sensör verisi - - 12 satır geçerli - - 8 satır hatalı/eksik - -2. ETL ARDIŞIK DÜZENI - ├─ Nem temizliği (0-100%) - ├─ Sıcaklık temizliği (-10-60°C) - ├─ Timestamp normalizasyonu - └─ Eksik satırları kaldırma - -3. VERITABANINA KAYIT - ├─ Append modu (var olan veriyi korur) - ├─ Toplu işlem (hızlı) - └─ Hata toleransı (satır satır fallback) - -4. RAPORLAMA - ├─ Ham veri istatistikleri - ├─ Temizleme özeti - └─ Veritabanı sonuçları -``` - ---- - -## 📚 Dosya İçerik Özeti - -### sensor_integration.py -**Satır:** ~450 | **Fonksiyon:** 12 -**Görevi:** Veri üretme, temizle, kaydetme, raporlama - -### verify_sensor_data.py -**Satır:** ~300 | **Fonksiyon:** 8 -**Görevi:** Veritabanı doğrulama, istatistik, kalite kontrolü - -### SENSOR_INTEGRATION_DOCUMENTATION.md -**Sayfa:** ~15 | **Konular:** Mimarı, detaylar, kaynak kodu - ---- - -## ✅ Kontrol Listesi - -- [x] Veritabanı bağlantısı çalışıyor -- [x] Veritabanı şeması yüklü -- [x] Ham veri üretimi başarılı -- [x] ETL temizliği işe yaradı (%60 tutma) -- [x] Veritabanı kayıt %100 başarılı -- [x] Veri kalitesi mükemmel (100%) -- [x] Tüm değerler geçerli aralıkta -- [x] Eksik veri yok - ---- - -## 📞 Faydalı Komutlar - -### Veritabanı İçeriğini SQLite ile Kontrol Et -```bash -sqlite3 database/sfdap.db -sqlite> SELECT COUNT(*) FROM soil_moisture_readings; -sqlite> .tables -sqlite> .schema soil_moisture_readings -sqlite> .exit -``` - -### CSV'ye Dışa Aktar -```bash -sqlite3 database/sfdap.db -sqlite> .mode csv -sqlite> .output readings.csv -sqlite> SELECT * FROM soil_moisture_readings; -sqlite> .exit -``` - -### Python REPL'de Kontrol -```python -import pandas as pd -import sqlite3 - -conn = sqlite3.connect('database/sfdap.db') -df = pd.read_sql_query("SELECT * FROM soil_moisture_readings", conn) -print(df.head(10)) -print(df.describe()) -``` - ---- - -## 🎓 Öğrenme Kaynakları - -| Konu | Kaynak | -|------|--------| -| Pandas | [pandas.pydata.org](https://pandas.pydata.org) | -| SQLAlchemy | [sqlalchemy.org](https://www.sqlalchemy.org) | -| SQLite | [sqlite.org](https://www.sqlite.org) | -| ETL | [Wikipedia ETL](https://en.wikipedia.org/wiki/Extract,_transform,_load) | - ---- - -## 📋 Teknik Özellikler - -- **Dil:** Python 3.8+ -- **Veritabanı:** SQLite 3 -- **CLI:** PowerShell / Terminal -- **Platform:** Windows/Linux/macOS - ---- - -## 🎉 Başarı Göstergeleri - -Programı başarıyla çalıştırdığınızda: - -✅ 12 satırlık geçerli veri -✅ %100 veritabanı başarı -✅ Sıfır eksik değer -✅ Tüm değerler geçerli aralıkta -✅ Mükemmel veri kalitesi - ---- - -## 📝 Sürüm - -**v1.0** - 2026-04-08 -Durum: ✅ Üretim Hazır - ---- - -**Sorular?** Dokümantasyon dosyasını kontrol edin: `SENSOR_INTEGRATION_DOCUMENTATION.md` diff --git a/docs/ml/Makine_Ogrenimi_Rehberi.md b/docs/ml/Makine_Ogrenimi_Rehberi.md index 0f2af41..2deac39 100644 --- a/docs/ml/Makine_Ogrenimi_Rehberi.md +++ b/docs/ml/Makine_Ogrenimi_Rehberi.md @@ -1,8 +1,9 @@ # 🤖 Makine Öğrenimi (ML) Modelleri Rehberi -Bu belge, sistemde aktif olarak çalışan ve gelecekte eklenecek olan yapay zeka modellerinin teknik çalışma prensiplerini açıklar. +Bu belge, SFDAP (Akıllı Tarım Veri Analizi Platformu) içerisinde aktif olarak çalışan yapay zeka modellerinin teknik çalışma prensiplerini, performans ölçümlerini ve sınırlarını açıklar. Sistemdeki **tek ML referans dökümanıdır**. ## 💧 1. Sulama Optimizasyon Modeli (`IrrigationOptimizer`) + `app/ml/irrigation_model.py` içerisinde yer alan model, scikit-learn kütüphanesi kullanılarak geliştirilmiş bir **Random Forest Regressor** algoritmasıdır. ### Model Mimarisi @@ -29,20 +30,112 @@ Modelin `predict()` fonksiyonu şu formatta bir sonuç döndürür: } ``` -## 🦠 2. Bitki Sağlığı Görüntü Analizi (CNN Modeli) +### Performans Değerlendirmesi (Sentetik Veri Üzerinde) + +Sentetik veri yapısı üzerinde (1000 örnek, %80/%20 eğitim/test ayrımı) yürütülen değerlendirmede aktif RandomForest yapılandırmasının ölçülen metrikleri: + +| Metrik | Değer | Açıklama | +|---|---|---| +| MAE | 3.5351 | Tahmin ile gerçek değer arasındaki ortalama fark (litre). Düşük olması iyidir. | +| RMSE | 6.9893 | Büyük hatalara daha duyarlı hata metriği. Düşük olması iyidir. | +| R² | 0.9059 | Modelin veriyi açıklama oranı. 1.0 mükemmel demektir. | +| CV R² | 0.8967 | 5 katlı çapraz doğrulama skoru. Yeni verilere genelleme yeteneğini gösterir. | + +> **Not:** Bu metrikler **sentetik** veri üzerinde elde edilmiştir ve gerçek saha performansını yansıtmaz. Gerçek saha verisi temin edildiğinde model yeniden eğitilmeli ve değerlendirme tekrarlanmalıdır. + +### Özellik Önemi (Feature Importance) + +| Özellik | Önem (%) | +|---|---| +| soil_moisture (Toprak Nemi) | %38.16 | +| precipitation (Yağış) | %34.00 | +| temperature (Hava Sıcaklığı) | %20.24 | +| humidity (Hava Nemi) | %6.16 | +| soil_temperature (Toprak Sıcaklığı) | %1.44 | + +Toprak nemi ve yağış miktarı birlikte modelin kararlarının yaklaşık **%72'sini** belirlemektedir. -Bitki yaprak görüntülerinden hastalık teşhisi yapan CNN sarıcısı `app/ml/plant_disease_model.py` içinde canlıdır. +### Parametre Notları +Sentetik veri üzerinde yapılan parametre denemelerinde `n_estimators=200, max_depth=15` yapılandırması MAE'yi 3.5351'den 3.4865'e (yaklaşık %1.4) marjinal olarak düşürmüştür. Bu fark sentetik veride önemsiz olduğundan, aktif modelde varsayılan `n_estimators=100, max_depth=10` yapılandırması korunmaktadır. Gerçek saha verisiyle yeniden değerlendirme yapılmadan parametre değişikliği önerilmemektedir. -### Mevcut Yapı -- **Sarıcı sınıf:** `PlantDiseaseModel` (`app/ml/plant_disease_model.py`) — Pillow tabanlı heuristic mod (HSV renk analizi + sağlıklı yeşil oranı + lezyon oranı). `app/ml/models/plant_disease_cnn.onnx` mevcutsa `onnxruntime` ile gerçek CNN inference'a otomatik geçer. +## 🦠 2. Bitki Sağlığı Görüntü Analizi (`PlantDiseaseModel`) + +Bitki yaprak görüntülerinden hastalık teşhisi yapan model sarıcısı `app/ml/plant_disease_model.py` içinde canlıdır. Sarıcı iki çalışma moduna sahip olacak şekilde tasarlanmıştır: + +| Mod | Açıklama | Durum | +|---|---|---| +| **ONNX Modu** | `onnxruntime` ile gerçek CNN inference | `plant_disease_cnn.onnx` mevcutsa otomatik aktifleşir (şu an dosya yok) | +| **Heuristic Mod** | Pillow tabanlı HSV renk analizi (kural-bazlı teşhis) | Aktif ve çalışıyor | + +Sistem başlatıldığında `app/ml/models/plant_disease_cnn.onnx` dosyası aranır. Bu dosya henüz mevcut olmadığından model otomatik olarak heuristic moda geçer. ONNX inference için `onnxruntime`, görüntü işleme için `Pillow` kullanılır. **Bu akışta TensorFlow, Keras, OpenCV veya LSTM kullanılmamaktadır.** + +### API Entegrasyonu - **API endpoint'i:** `POST /api/plants/health-images/analyze` (multipart upload). Yüklenen görseli kaydedip `PlantHealthImage` tablosuna yazar. - **Test kapsamı:** `tests/test_plants.py` (heuristic ve ONNX path'leri için integration testleri). -### CNN Eğitim Adımları -- PlantVillage dataset üzerinden Keras/TensorFlow eğitimi → ONNX export -- Sınıf etiketleri: "Sağlıklı", "Pas Hastalığı", "Mantar Lekesi", "Kurşuni Küf", vb. -- Test seti accuracy hedefi ≥ %85 -- Model dosyası `app/ml/models/plant_disease_cnn.onnx` olarak yerleştirildiğinde sarıcı otomatik olarak ONNX moduna geçer. +### Desteklenen Hastalık Sınıfları + +Model şu an 8 sınıfı desteklemektedir: + +| Sınıf | Açıklama | Şiddet | +|---|---|---| +| healthy | Sağlıklı yaprak | none | +| leaf_spot | Yaprak lekesi | low | +| powdery_mildew | Külleme | medium | +| rust | Pas hastalığı | medium | +| blight | Yanıklık | high | +| mosaic_virus | Mozaik virüsü | high | +| bacterial_wilt | Bakteriyel solgunluk | high | +| anthracnose | Antraknoz | medium | + +### Heuristic Modun Çalışma Mantığı + +Model, yaprak görüntüsünü HSV renk uzayına çevirerek (Pillow ile) renk oranlarını analiz eder ve aşağıdaki kurallara göre teşhis üretir: + +| Renk Sinyali | Eşik | Olası Teşhis | +|---|---|---| +| Beyaz/gri tabaka | %18 üzeri | powdery_mildew | +| Kahverengi leke | %25 üzeri | blight | +| Kahverengi leke | %12-25 arası | leaf_spot | +| Sarı baskın | %18 üzeri | mosaic_virus veya anthracnose | +| Düşük doygunluk | %15 altı | rust | +| Yüksek yeşil oranı | %40 üzeri | healthy | +| Diğer | — | bacterial_wilt | + +### Heuristic Mod Test Çıktısı + +Heuristic modun 4 farklı yaprak görüntüsü senaryosu üzerindeki örnek tahmin sonuçları: + +| Test Senaryosu | Teşhis | Güven Skoru | Şiddet | +|---|---|---|---| +| Sağlıklı Yaprak | healthy | 0.86 | none | +| Yaprak Lekesi | leaf_spot | 0.86 | low | +| Külleme | powdery_mildew | 0.80 | medium | +| Yanıklık | blight | 0.95 | high | + +> Bu güven skorları heuristic (renk oranı) tabanlıdır; eğitilmiş bir CNN'in doğruluk metriği değildir. + +### CNN/ONNX Modu — Açık Adımlar + +ONNX modu, eğitilmiş bir model dosyası yerleştirildiğinde otomatik olarak devreye girer. CNN eğitimi henüz tamamlanmadığından gerçek accuracy/precision/recall/confusion matrix metrikleri **ölçülememektedir**. İlerleyen sprintler için açık adımlar: + +- PlantVillage veri seti ile bir CNN modelinin eğitilmesi +- Eğitilen modelin ONNX formatına export edilmesi (`plant_disease_cnn.onnx`) +- `app/ml/models/` klasörüne ONNX dosyasının eklenmesi +- ONNX modu aktifken accuracy, precision, recall ve confusion matrix hesaplanması +- Test görüntüleri üzerinde gerçek tahmin çıktılarının belgelenmesi +- Bitki türüne göre özelleştirilmiş model desteğinin araştırılması + +### Mevcut Sınırlar + +1. **ONNX modeli eksik:** `plant_disease_cnn.onnx` dosyası henüz üretilmemiştir; sistem heuristic modda çalışmaktadır. +2. **Heuristic modun yetersizliği:** Renk tabanlı analiz yalnızca belirgin renk farklılıklarında doğru çalışır. Erken evre hastalıklar ve düşük ışık koşullarında hatalı teşhis riski yüksektir. +3. **Çoklu hastalık desteği yok:** Model bir görüntüde yalnızca tek bir hastalık sınıfı döndürür. +4. **Bitki türü ayrımı yok:** Tüm bitki türleri için aynı model kullanılır. +5. **Veri seti bağımlılığı:** PlantVillage veri seti laboratuvar koşullarında çekilmiş görüntüler içerir; gerçek saha görüntüleriyle performans düşebilir. + +## 📊 3. Model Performans Loglama ve Drift Tespiti + +Şu an `ModelPerformanceLog`'a otomatik yazan tek akış **sulama** tahminleridir (`model_name='irrigation_rf'`, `app/routers/irrigation.py` içinde `_log_prediction`). Bitki hastalığı analizi (`plant_disease`) henüz bu loglamaya bağlanmamıştır — yalnız `PlantHealthImage` kaydı oluşur. -### Otomatik Loglama -Şu an `ModelPerformanceLog`'a otomatik yazan tek akış **sulama** tahminleridir (`model_name='irrigation_rf'`, `app/routers/irrigation.py` içinde `_log_prediction`). Bitki hastalığı analizi (`plant_disease`) henüz bu loglamaya bağlanmadı — yalnız `PlantHealthImage` kaydı oluşur. Drift detection endpoint'i (`GET /api/model-performance/drift/{model_name}`) parametriktir; bir modelin log kaydı oluştuğunda eşik altı düşüşte `SystemAlert` üretir. +Drift detection endpoint'i (`GET /api/model-performance/drift/{model_name}`) parametriktir; bir modelin log kaydı oluştuğunda eşik altı düşüşte `SystemAlert` üretir. Model performans router'ı (`/api/model-performance`), Bearer JWT yerine legacy `X-API-Key` doğrulaması kullanan tek API yüzeyidir. diff --git a/docs/model_evaluation_report.md b/docs/model_evaluation_report.md deleted file mode 100644 index bee46f4..0000000 --- a/docs/model_evaluation_report.md +++ /dev/null @@ -1,90 +0,0 @@ -# Makine Öğrenimi Modeli Değerlendirme ve Optimizasyon Raporu - -**Proje:** SFDAP — Akıllı Tarım Veri Analizi Platformu -**Görev:** Model Değerlendirme ve Optimizasyon -**Değerlendirilen Model:** Sulama Optimizasyon Modeli (`app/ml/irrigation_model.py`) - ---- - -## 1. Giriş - -`IrrigationOptimizer` sınıfı, toprak nemi, toprak sıcaklığı, hava nemi, hava sıcaklığı ve yağış miktarı verilerini kullanarak gereken sulama miktarını (litre) tahmin eden bir RandomForestRegressor modeli içerir. Bu raporda söz konusu modelin performansı ölçülmüş, farklı algoritmalarla karşılaştırılmış ve parametre optimizasyonu yapılmıştır. - ---- - -## 2. Kullanılan Veri - -İlk eğitimle aynı synthetic veri yapısı kullanılmıştır: - -- **Örnek sayısı:** 1000 -- **Özellik sayısı:** 5 -- **Eğitim / Test ayrımı:** %80 / %20 (800 eğitim, 200 test) -- **Özellikler:** `soil_moisture`, `soil_temp`, `humidity`, `air_temp`, `precipitation` -- **Hedef değişken:** `water_needed` (litre) - ---- - -## 3. Algoritma Karşılaştırması - -Baseline RandomForest modelinin yanı sıra 4 farklı algoritma daha test edilmiştir: - -| Model | MAE | RMSE | R² | CV R² | -|---|---|---|---|---| -| **GradientBoosting** | **3.1387** | **6.3068** | **0.9234** | **0.9069** | -| RandomForest (baseline) | 3.5351 | 6.9893 | 0.9059 | 0.8967 | -| DecisionTree | 3.8456 | 8.6613 | 0.8554 | 0.7292 | -| Ridge | 10.9678 | 15.8246 | 0.5174 | 0.4697 | -| LinearRegression | 10.9697 | 15.8203 | 0.5177 | 0.4696 | - -**Metrik Açıklamaları:** -- **MAE:** Tahmin ile gerçek değer arasındaki ortalama fark (litre). Düşük olması iyidir. -- **RMSE:** Büyük hatalara daha duyarlı hata metriği. Düşük olması iyidir. -- **R²:** Modelin veriyi açıklama oranı. 1.0 mükemmel demektir. -- **CV R²:** 5 katlı çapraz doğrulama skoru. Modelin yeni verilere genelleme yeteneğini gösterir. - -### Değerlendirme - -- **GradientBoosting** en düşük MAE (3.14) ve en yüksek R² (0.92) ile en iyi performansı sergilemiştir. -- **Baseline RandomForest modeli** ikinci sıradadır. R² değeri 0.91 ile güçlü bir performans göstermektedir. -- **LinearRegression ve Ridge** bu veri yapısı için yetersiz kalmıştır (R² ≈ 0.52). Sulama miktarı ile özellikler arasındaki ilişki doğrusal değildir. - ---- - -## 4. RandomForest Parametre Optimizasyonu - -Baseline varsayılan parametreler (`n_estimators=100, max_depth=10`) optimize edilmiştir: - -| Parametreler | MAE | RMSE | R² | -|---|---|---|---| -| n=50, depth=5 | 4.2286 | 8.3558 | 0.8655 | -| n=100, depth=10 *(baseline varsayılan)* | 3.5351 | 6.9893 | 0.9059 | -| n=200, depth=10 | 3.5158 | 6.9731 | 0.9063 | -| n=100, depth=15 | 3.5060 | 6.8996 | 0.9083 | -| **n=200, depth=15** | **3.4865** | **6.9062** | **0.9081** | -| n=300, depth=None | 3.5188 | 6.9723 | 0.9063 | - -**En iyi parametreler:** `n_estimators=200, max_depth=15` -Bu yapılandırma ile baseline RandomForest MAE değeri **3.5351'den 3.4865'e** düşürülmüştür (%1.4 iyileşme). - ---- - -## 5. Özellik Önemi - -| Özellik | Önem (%) | -|---|---| -| soil_moisture (Toprak Nemi) | %38.16 | -| precipitation (Yağış) | %34.00 | -| air_temp (Hava Sıcaklığı) | %20.24 | -| humidity (Hava Nemi) | %6.16 | -| soil_temp (Toprak Sıcaklığı) | %1.44 | - -Toprak nemi ve yağış miktarı birlikte modelin kararlarının **%72'sini** belirlemektedir. - ---- - -## 6. Sonuç ve Öneriler - -1. **En iyi algoritma GradientBoosting'dir.** Baseline RandomForest modelinin yerini alması önerilebilir. -2. **Cycle 4 RandomForest modeli** parametreleri `n_estimators=200, max_depth=15` olarak güncellenerek performansı artırılabilir. -3. **Toprak nemi ve yağış** en kritik özelliklerdir. -4. Gerçek saha verisi temin edildiğinde modeller yeniden eğitilmeli ve değerlendirme tekrarlanmalıdır. diff --git "a/docs/planning/Veri_Hatti_\304\260zleme.md" "b/docs/planning/Veri_Hatti_\304\260zleme.md" deleted file mode 100644 index 788dc8f..0000000 --- "a/docs/planning/Veri_Hatti_\304\260zleme.md" +++ /dev/null @@ -1,12 +0,0 @@ -## 1. Sistemin Amacı -Akıllı Tarım platformumuzda sensörlerden gelen veri akışını anlık olarak takip etmek ve bir kopukluk yaşandığında sistemi korumaya almaktır. - -## 2. İzleme Parametreleri -- **Zaman Aşımı (Timeout):** Sensörden 10 saniye boyunca veri gelmezse sistem uyarı verir. -- **Hatalı Veri:** Sensörde gelen "0" veya negatif değerler "Hatalı Veri" olarak işaretlenir. - -## 3. Uyarı Mekanizması -Hata tespit edildiğinde sistem şu adımları izler: -1. Hata log dosyasına kaydedilir. -2. Dashboard üzerinde kullanıcıya kırmızı renkli görsel bir uyarı gösterlir. -3. Veri akışı tekrar düzelene kadar sistem "Bekleme" moduna alır. \ No newline at end of file diff --git "a/docs/planning/Veri_Kaynagi_ve_Toplama_Plan\304\261.md" "b/docs/planning/Veri_Kaynagi_ve_Toplama_Plan\304\261.md" deleted file mode 100644 index 543a5cd..0000000 --- "a/docs/planning/Veri_Kaynagi_ve_Toplama_Plan\304\261.md" +++ /dev/null @@ -1,20 +0,0 @@ -# 2.Hafta: Veri Kaynaklarının Belirlenmesi ve Veri Toplama Planının Oluşturulması - -## 1. Veri Kaynakları (Data Sources) -Projemizde kullanılacak temel veri kaynakları şunlardır: -* **Hava Durumu Verileri:** OpenWeatherMap API (sıcaklık, nem ve yağış tahminleri için). -* **Toprak Verileri:** IoT simülasyon araçları (Toprak nemi, pH değeri ve mineral seviyeleri). -* **Piyasa Verileri:** Tarım ve Orman Bakanlığı web servisleri (Ürün fiyat endeksleri). - -## 2. Veri Toplama Yöntemi (Data Collection Method) -* **API Entegrasyonu:** Hava durumu ve piyasa değerleri için REST API üzerinden JSON formatında veri çekilecektir. -* **Web Scraping:** API desteği olmayan ikincil kaynaklar için Python (BeautifulSoup) kullanılarak veri kazıma yapılacaktır. - -## 3. Toplama Sıklığı (Update Frequency) -* **Hava Durumu:** Her 3 saatte bir güncellenecek. -* **Toprak Sensörleri:** Gerçek zamanlıya yakın (Her 15 dakikada bir). -* **Piyasa Fiyatları:** Günlük olarak bir kez çekilecek. - -## 4. Veri Formatı ve Tahmini Hacim -* **Format:** Tüm veriler işlenmek üzere **JSON** ve **CSV** formatında saklanacaktır. -* **Hacim:** Başlangıç aşamasında günlük yaklaşık 10-15 MB veri birikmesi öngörülmektedir. \ No newline at end of file diff --git "a/docs/planning/Web_Aray\303\274z\303\274_Veri_G\303\266rselle\305\237tirme_Entegrasyonu.md" "b/docs/planning/Web_Aray\303\274z\303\274_Veri_G\303\266rselle\305\237tirme_Entegrasyonu.md" deleted file mode 100644 index dbe85da..0000000 --- "a/docs/planning/Web_Aray\303\274z\303\274_Veri_G\303\266rselle\305\237tirme_Entegrasyonu.md" +++ /dev/null @@ -1,22 +0,0 @@ -# HAFTA 4: WEB ARAYÜZÜ VE VERİ GÖRSELLEŞTİRME - -> ⚠️ **TARİHSEL DOKÜMAN.** Bu rapor dashboard'un ilk prototip aşamasını belgeler (Chart.js + line chart). -> **Güncel frontend mimarisi için** [`docs/frontend/Frontend_Kılavuzu.md`](../frontend/Frontend_Kılavuzu.md) ve [`docs/architecture.md`](../architecture.md) bölümlerine bakınız (9 sayfalı SPA, 81 il bölge filtresi, Filiz mascot, Vite scaffold dahil). - ---- - - -## 1. GÖREV ÖZETİ -Bu hafta, Akıllı Tarım Platformu projesi kapsamında sensörlerden gelen verilerin son kullanıcı (çiftçi) tarafından kolayca analiz edilebilmesi için bir web arayüzü tasarlanmış ve veri görselleştirme entegrasyonu yapılmıştır. - -## 2. KULLANILAN TEKNOLOJİLER -* **HTML5 & CSS3:** Arayüzün iskeleti ve görsel tasarımı için kullanıldı. -* **JavaScript & Chart.js:** Dinamik çizgi grafikler oluşturmak için en popüler görselleştirme kütüphanelerinden biri olan Chart.js tercih edildi. - -## 3. YAPILAN ÇALIŞMALAR -* Verilerin zamana bağlı değişimini göstermek için "Line Chart" (Çizgi Grafik) yapısı kuruldu. -* Toprak nem oranı %0-%100 ölçeğinde grafikleştirilerek kritik seviyelerin takibi kolaylaştırıldı. -* Kullanıcı dostu, sade ve mobil uyumlu bir Dashboard tasarımı hedeflendi. - -## 4. EKRAN GÖRÜNTÜSÜ -![Akıllı Tarım Grafiği](Akilli_Tarim_Grafik.png) diff --git a/docs/research/Gerekli_Teknolojilerin_Arastirilmasi.md b/docs/research/Gerekli_Teknolojilerin_Arastirilmasi.md deleted file mode 100644 index 8f7accb..0000000 --- a/docs/research/Gerekli_Teknolojilerin_Arastirilmasi.md +++ /dev/null @@ -1,54 +0,0 @@ -# $\color{red}{\textbf{📊 Akıllı Tarım Platformu Teknoloji Raporu}}$ - -Bu proje temel olarak iki farklı veri tipiyle çalışacak: Tablo verileri (sensörlerden gelen nem, sıcaklık vb.) ve Görüntü verileri (bitki sağlığı için yaprak fotoğrafları). Seçilecek teknolojiler bu iki veri tipini de en verimli şekilde işleyebilmelidir. - -$\color{pink}{\textbf{1. Ana Programlama Dili}}$ ---- -• Python: Veri bilimi ve makine öğrenimi dünyasının tartışmasız lideridir. Ekibinin geniş kütüphane desteği ve zengin dokümantasyon sayesinde karşılaştığı hataları kolayca çözebilmesi için en doğru tercih olacaktır. - -$\color{pink}{\textbf{2. Veri Madenciliği ve Ön İşleme Kütüphaneleri (Data Mining)}}$ ---- -Toprak sensörlerinden ve hava durumu API'lerinden gelen veriler genellikle kirli veya eksik olur. Modele girmeden önce temizlenmeleri gerekir. - -• Pandas: Proje gereksinimlerinde de belirtildiği gibi, tablo formatındaki verileri (CSV, Excel veya SQL'den çekilen veriler) işlemek, filtrelemek ve analiz etmek için temel araçtır. "Hangi günlerde toprak nemi %20'nin altına düştü?" gibi soruların cevabını Pandas ile bulacaksınız. - -• NumPy: Yüksek performanslı matematiksel hesaplamalar ve çok boyutlu diziler (array) için gereklidir. Görüntü işleme sürecinin de temelini oluşturur. - -• Scikit-Learn (Sklearn): Makine öğrenimine giriş için en ideal kütüphanedir. Verileri ölçeklendirmek (normalization), eksik verileri doldurmak ve sulama optimizasyonu gibi konularda temel regresyon/sınıflandırma algoritmalarını (Rastgele Orman, Karar Ağaçları) kurmak için kullanılacaktır. - -$\color{pink}{\textbf{3. Makine Öğrenimi ve Derin Öğrenme Araçları (Deep Learning)}}$ ---- -Hastalık tahmini gibi karmaşık işlemler için standart algoritmalar yetersiz kalır, derin öğrenmeye ihtiyaç duyulur. - -• TensorFlow & Keras: Proje tanımında istenen bu teknoloji, özellikle "Bitki Sağlığı Görüntülerini" analiz etmek için kullanılacak. Evrişimli Sinir Ağları (CNN) kurarak, hastalıklı bir yaprak fotoğrafı ile sağlıklı bir yaprak fotoğrafını birbirinden ayırt eden modeller eğiteceksiniz. Keras, TensorFlow'un kullanımını çok daha kolaylaştıran üst katmanıdır. - -• OpenCV: Görüntüleri TensorFlow modeline sokmadan önce boyutlarını ayarlamak, renkleri düzenlemek veya gürültüyü azaltmak için kullanılacak temel görüntü işleme kütüphanesidir. - -$\color{pink}{\textbf{4. Veritabanı ve Bulut Bilişim (Storage \ Cloud)}}$ ---- - -• PostgreSQL (SQL): Sensörlerden akan zaman serisi verilerini (time-series data) ve kullanıcı bilgilerini güvenli bir şekilde tutmak için en güçlü açık kaynaklı ilişkisel veritabanlarından biridir. - -• Bulut Platformu Seçimi (AWS / GCP / Azure): Öğrenci kredileri ve sunduğu kolaylıklar açısından AWS (Amazon Web Services) veya GCP (Google Cloud Platform) tercih edilebilir. AWS üzerinde S3 (görüntüleri depolamak için) ve RDS (SQL veritabanını barındırmak için) başlangıç için ideal hizmetlerdir. - - - -$\color{pink}{\textbf{5. Görselleştirme ve Arayüz Araçları}}$ ---- -• Streamlit veya Dash: Bir web arayüzü istendiği için, ekibin sıfırdan HTML/CSS/JavaScript öğrenmekle vakit kaybetmesini istemiyorsan, doğrudan Python kodlarıyla harika veri panoları (dashboard) ve web arayüzleri oluşturabilen bu kütüphaneleri kullanabilirsiniz. - -• Matplotlib ve Seaborn: Veri analizi aşamasında, çiftçiye sunulacak raporlardaki grafikleri çizdirmek için kullanılacak standart Python kütüphaneleridir. - - - -## 📌 $\color{red}{\textbf{Teknoloji ve Özellik Eşleştirme Tablosu}}$ - -Aşağıdaki tablo, proje isterlerinin hangi teknolojiyle çözüleceğini özetler: - -| Proje Özelliği | Kullanılacak Veri Tipi | Önerilen Teknoloji / Kütüphane | -|:---:|:---:|:---:| -| Veri Toplama & Temizleme | Sensör, Hava Durumu | Python, Pandas, SQL | -| Sulama Optimizasyonu | Sayısal (Nem, Sıcaklık) | Scikit-Learn (Regresyon Modelleri) | -| Hastalık Tahmini | Görsel (Yaprak Fotoları) | OpenCV, TensorFlow / Keras | -| Veritabanı Yönetimi | Tablo / İlişkisel | PostgreSQL, Cloud SQL (GCP/AWS) | -| Görselleştirme & Arayüz | Tüm Çıktılar | Streamlit, Matplotlib | diff --git a/docs/research/Veri_Seti_Analizi_ve_Model_Secimi.md b/docs/research/Veri_Seti_Analizi_ve_Model_Secimi.md deleted file mode 100644 index 29cd793..0000000 --- a/docs/research/Veri_Seti_Analizi_ve_Model_Secimi.md +++ /dev/null @@ -1,46 +0,0 @@ -# 🌾 Akıllı Tarım Veri Analizi Platformu -## 📈 Keşifsel Veri Analizi (EDA) ve Algoritma Ön Değerlendirme Raporu - -> **Görev:** Veri Seti Analizi ve Model Seçimi -> **Tarih:** 08.03.2026 - ---- - -Bu belge, Akıllı Tarım platformumuzdaki veri setlerinin istatistiksel dağılımlarını, değişkenler arası ilişkilerini ve korelasyonlarını analiz eder. Analiz bulguları ışığında, projedeki farklı görevler (sulama, gübreleme, hastalık tespiti) için en uygun makine öğrenimi algoritmaları değerlendirilmiştir. - -### 🔍 1. Değişken Dağılımları ve İlişkisel Analiz -Veri setinin yapısını ve özelliklerini anlamak için aşağıdaki analizler gerçekleştirilecektir: - -* **Tek Değişkenli Analiz (Univariate):** Sıcaklık, Nem, pH ve NPK (Azot, Fosfor, Potasyum) değerlerinin dağılımları histogramlar ve kutu grafikleri (Boxplot) ile incelenecektir. Bu sayede verinin normal dağılıma uyup uymadığı ve çarpıklık (skewness) oranları belirlenecektir. -* **İki Değişkenli Analiz (Bivariate):** - * Çiftçinin sulama ve gübreleme alışkanlıkları ile mahsul verimi arasındaki doğrusal veya doğrusal olmayan ilişkiler dağılım grafikleri (Scatter Plot) ile analiz edilecektir. - -### 🔗 2. Korelasyon ve Hedef Değişken Analizi -Özelliklerin (features) birbirleriyle ve tahmin etmeye çalıştığımız hedef değişkenle (target) ne kadar ilişkili olduğunu anlamak model başarısı için kritiktir. - -* **Korelasyon Matrisi (Heatmap):** Değişkenler arasındaki Pearson ve Spearman korelasyon katsayıları hesaplanacaktır. - * *Çoklu Doğrusallık (Multicollinearity) Tespiti:* Birbiriyle %85'in üzerinde yüksek korelasyona sahip bağımsız değişkenler tespit edilip, modelin aşırı öğrenmesini engellemek için biri veri setinden çıkarılacaktır. -* **Hedef Değişkenle İlişki:** Hastalık durumu (Var/Yok) veya Mahsul Verimi (Ton) gibi hedef değişkenlerimizi en çok etkileyen özellikler (Feature Importance) belirlenecektir. - ---- - -### 🤖 3. Makine Öğrenimi Algoritmaları Ön Değerlendirmesi -Tarım veri setimizin karmaşık yapısına uygun algoritma eşleştirmeleri aşağıda sunulmuştur: - -#### A. Sulama ve Gübreleme Optimizasyonu (Tabular Veri) -**Önerilen Algoritma: Random Forest (Rastgele Orman) / XGBoost** -* **Veri Eşleşmesi:** Sensör verilerindeki doğrusal olmayan ilişkileri modellemek için idealdir. -* **Güçlü Yönleri:** Aşırı öğrenmeye (overfitting) karşı dirençlidir. Karmaşık verilerde yüksek doğruluk sağlar. -* **Zayıf Yönleri:** Parametre optimizasyonu (tuning) zaman alabilir ve daha fazla hesaplama gücü gerektirir. - -#### B. Bitki Hastalığı Tahmini (Görüntü Verisi) -**Önerilen Algoritma: Convolutional Neural Networks - CNN (Örn: ResNet50 veya MobileNet)** -* **Veri Eşleşmesi:** Görüntüdeki doku/renk değişimlerini (hastalık lekeleri) yakalamak için özel olarak tasarlanmıştır. -* **Güçlü Yönleri:** Transfer Öğrenme (Transfer Learning) ile yüksek başarı elde edilebilir. Edge Computing (kenar bilişim) için uygun hafif versiyonları vardır. -* **Zayıf Yönleri:** Kara Kutu (Black Box) yapısındadır. Eğitimi için yüksek GPU gücü ve çok sayıda etiketli görüntü gerektirir. - -#### C. Hava ve Toprak Nemi Tahmini (Zaman Serisi Verisi) -**Önerilen Algoritma: LSTM (Long Short-Term Memory) Ağları** -* **Veri Eşleşmesi:** Sensörlerden akan zaman serisi verilerindeki "zaman" bağıntısını hatırlamak için biçilmiş kaftandır. -* **Güçlü Yönleri:** Uzun vadeli bağımlılıkları (örn. geçmiş yağışların bugünkü neme etkisi) öğrenebilir. -* **Zayıf Yönleri:** Eğitimi donanım açısından maliyetlidir. diff --git a/docs/setup/Gelistirme_Ortaminin_Kurulumu.md b/docs/setup/Gelistirme_Ortaminin_Kurulumu.md deleted file mode 100644 index ed59fdc..0000000 --- a/docs/setup/Gelistirme_Ortaminin_Kurulumu.md +++ /dev/null @@ -1,16 +0,0 @@ -# Hafta 1 — Kurulum ve Hazırlık Raporu - -> ⚠️ **TARİHSEL DOKÜMAN.** Bu rapor projenin ilk haftasındaki kişisel geliştirme ortamı kurulum sürecini belgeler. -> **Güncel kurulum talimatları için** [`README.md`](../../README.md) → "Hızlı Başlangıç" bölümüne bakınız (Python 3.12+, .venv, Docker, Makefile, pre-commit dahil). - ---- - - -### Yapılan Teknik Hazırlıklar -- Python dili ve VS Code editörü kurularak yazılım geliştirme ortamı hazırlandı. -- Git yazılımı bilgisayara kuruldu ve Github hesabı ile "git-ecosystem (authentication) sağlandı. -- 'Smart_Farming_Data_Analysis_Platform' projesi Githun üzerinden yerel bilgisayara çekildi. -- Ana proje dosyalarını korumak amacıyla 'git checkout -b ecenur' komutu ile kişisel çalışma dalı oluşturuldu. - -### Sonuç -İlk hafta için belirlenen tüm kurulumlar ve sisteme erişim süreçleri başarıyla tamamlanmıştır. Bu dosya, sürecin ilk dokümantasyonu olarak oluşturulmuştur. diff --git a/docs/testing/Hafta_6_Test_Validasyon_ve_Hata_Ayiklama_Raporu.md b/docs/testing/Hafta_6_Test_Validasyon_ve_Hata_Ayiklama_Raporu.md deleted file mode 100644 index 7067cb9..0000000 --- a/docs/testing/Hafta_6_Test_Validasyon_ve_Hata_Ayiklama_Raporu.md +++ /dev/null @@ -1,77 +0,0 @@ -# 🏛️ Hafta 6: Kapsamlı Test, Validasyon ve Yazılım Kalite Güvencesi Raporu - -**Proje Kimliği:** Akıllı Tarım Veri Analizi Platformu (Smart Farming Gateway) -**Görev Durumu:** ✅ %100 Tamamlandı - ---- - -## 1. 📋 Giriş ve Stratejik Amaç -Bu döküman, Hafta 4 kapsamında temelleri atılan FastAPI tabanlı Akıllı Tarım API projesinin, üretim (production) aşamasına geçmeden önceki en kritik adımı olan **Test ve Validasyon** süreçlerini kapsar. Projenin tüm bileşenleri; fonksiyonellik, güvenlik, performans ve veri bütünlüğü açılarından stres testine tabi tutulmuştur. - -## 2. 🏗️ Test Mimarisi ve Metodolojisi -Sistemi test ederken üç katmanlı bir yaklaşım benimsenmiştir: - -### A. Birim Testleri (Unit Testing) -Yazılımın en küçük yapı taşları olan API uç noktaları (endpoints) tek tek test edilmiştir. -* **Amaç:** `app/main.py` üzerinden bağlanan 11 router'daki fonksiyonların beklenmedik durumlarda çökmesini engellemek. -* **Kapsam:** Sensör (`/api/sensors/`), Hava durumu (`/api/weather/`), Sulama (`/api/irrigation/`), Gübreleme (`/api/fertilizer/`), Bitki Sağlığı (`/api/plants/`), Analitik (`/api/analytics/`), Uyarı (`/api/alerts/`), Model Performansı (`/api/model-performance/`) ve sağlık endpoint'leri. - -### B. Entegrasyon ve Şema Validasyonu -Verilerin Pydantic v2 modelleri üzerinden geçişi sırasında uygulanan kısıtlamalar kontrol edilmiştir. -* **Kontrol Noktası:** `SensorReadingCreate` (`moisture_percent`, `soil_temperature_c`) ve `WeatherDataCreate` (`temperature_c`, `humidity_percent`) alanlarının yanlış tip veya eksik gönderilmesi durumunda sistemin verdiği tepki (FastAPI'nin standart `422 Unprocessable Entity` cevabı). - -### C. Güvenlik Denetimi (Security Audit) -`X-API-Key` tabanlı güvenlik katmanının kırılamazlığı üzerine yoğunlaşılmıştır. -* **Metot:** Brute-force denemeleri (arka arkaya yanlış anahtar gönderimi), header eksikliği ve case-insensitive header testleri. -* **Davranış:** Header eksikse `401 Unauthorized`, anahtar geçersizse `403 Forbidden` döndürülür ([app/middleware/auth.py](../../app/middleware/auth.py)). - ---- - -## 3. 🧪 Detaylı Test Senaryoları ve Sonuç Matrisi - -Aşağıdaki tablo, sistemin her bir senaryo karşısındaki davranışını detaylandırmaktadır: - -| Senaryo Kodu | Test Tanımı | Test Girdisi (Input) | Beklenen Durum | Gerçekleşen Sonuç | Karar | -| :--- | :--- | :--- | :--- | :--- | :--- | -| **AUTH-01** | Geçerli Anahtar Erişimi | `X-API-Key: dev-api-key` | 200 OK | 200 OK | ✅ BAŞARILI | -| **AUTH-02** | Eksik Header Erişimi | (header gönderilmedi) | 401 Unauthorized | 401 Unauthorized | ✅ BAŞARILI | -| **AUTH-03** | Geçersiz Anahtar Erişimi | `X-API-Key: hatali_anahtar` | 403 Forbidden | 403 Forbidden | ✅ BAŞARILI | -| **VALID-01** | Eksik Zorunlu Alan | `{"sensor_id": 1}` (`moisture_percent` yok) | 422 Error | 422 Unprocessable Entity | ✅ BAŞARILI | -| **VALID-02** | Hatalı Veri Tipi | `{"moisture_percent": "çok ıslak"}` | Type Error | 422 Validation Error | ✅ BAŞARILI | -| **SYS-01** | Olmayan Kaynak Erişimi | `GET /api/unknown` | 404 Not Found | 404 Not Found | ✅ BAŞARILI | - ---- - -## 4. 🐞 Hata Ayıklama (Debugging) ve Optimizasyon Süreci - -Testler sırasında tespit edilen ve projenin güvenilirliğini artırmak için çözülen teknik problemler: - -### 4.1. Veri Tipi Esnekliği Sorunu -* **Hata:** Sensörlerden gelen nem verisi bazen `45.0` (float), bazen `45` (int) olarak gelmekteydi. Pydantic şeması sadece `float` beklediği için tam sayılarda hata veriyordu. -* **Çözüm:** Pydantic v2'nin native int→float coercion davranışı doğrulandı; `SensorReadingCreate.moisture_percent` alanı artık her iki tipi de sorunsuz kabul ediyor. - -### 4.2. Header Case-Sensitivity (Büyük/Küçük Harf) Çakışması -* **Hata:** Bazı istemcilerin `x-api-key` (küçük harf) gönderirken, sistemin `X-API-Key` (büyük harf) beklemesi erişim sorunlarına yol açtı. -* **Çözüm:** FastAPI'nin `APIKeyHeader` sınıfı kullanılarak anahtar kontrolü case-insensitive hale getirildi ([app/middleware/auth.py:16](../../app/middleware/auth.py#L16)). - -### 4.3. Exception Handling (İstisna Yönetimi) -* **Hata:** Hata anlarında dönen JSON mesajları tutarsız formatlarda dönüyor, son kullanıcı için fazla teknik kalıyordu. -* **Çözüm:** `app/middleware/exceptions.py` altında 6 sınıflı global exception handler kuruldu (`NotFound`, `Unauthorized`, `ValidationError`, vs.); tüm hata cevapları `{error_code, message, detail}` standart formatına oturtuldu. - -### 4.4. Status Kodu Ayrıştırma -* **Hata:** İlk implementasyonda eksik header ve geçersiz anahtar aynı (`403`) kodu döndürüyordu; bu da istemci tarafında "yeniden authentikasyon" ve "anahtar yenileme" akışlarının ayrışmasını engelliyordu. -* **Çözüm:** RFC 7235'e uygun olarak header eksikse `401 Unauthorized`, anahtar geçersizse `403 Forbidden` döndürülecek şekilde ayrıştırıldı. - ---- - -## 5. 📈 Performans ve Kararlılık Verileri -Sistemin 31 Mayıs 2026 teslim tarihi öncesi son metrikleri şöyledir: -* **Ortalama Yanıt Süresi:** ~12 ms (yerel TestClient + in-memory SQLite üzerinde). -* **Güvenlik Katmanı Gecikmesi:** < 1 ms (API Key doğrulaması sistem performansını etkilememektedir). -* **Toplam Test Sayısı:** **301** (23 dosya, `pytest`). -* **Code Coverage:** **%94.42** (eşik %80; sonradan %95+'a yükseldi). -* **Geçen Test Oranı:** %100 (CI üzerinde tüm 301 test yeşil). -* **Linter Durumu:** Ruff — All checks passed. - -## 6. 🏁 Sonuç -Hafta 6 kapsamında yürütülen test ve validasyon faaliyetleri sonucunda, Akıllı Tarım Veri Analizi Platformu'nun teknik olarak kararlı çalıştığı, veri güvenliğini sağladığı ve hatalı girdilere karşı dayanıklı olduğu doğrulanmıştır. Sonraki sprint'lerde **rate limiting bağlama**, **JWT auth backend**, **N+1 fix**, **Alembic migration**, **HTTPS reverse proxy**, ardından **edge-case testleri**, **coverage %95+ resmî tutuş**, **Sentry/Prometheus gözlemlenebilirlik** ve **frontend a11y** ile prod-hazır seviyeye taşınmıştır. diff --git a/docs/testing/Hata_Ayiklama_ve_Dogrulama_Loglari.md b/docs/testing/Hata_Ayiklama_ve_Dogrulama_Loglari.md deleted file mode 100644 index cc22c6c..0000000 --- a/docs/testing/Hata_Ayiklama_ve_Dogrulama_Loglari.md +++ /dev/null @@ -1,54 +0,0 @@ -# 🛠️ Detaylı Hata Ayıklama, Validasyon ve Sistem Günlüğü - -Bu döküman, **Akıllı Tarım Veri Analizi Platformu** Hafta 6 kapsamında gerçekleştirilen kapsamlı testlerin teknik dökümantasyonudur. Bu süreçte "Siyah Kutu" ve "Beyaz Kutu" test metodolojileri kullanılmıştır. - ---- - -## 1. 🔍 Sistematik Test Senaryoları (Test Matrix) - -Aşağıdaki tablo, sistemin her bir parçasının hangi koşullar altında test edildiğini göstermektedir: - -| Test ID | Senaryo Tanımı | Girdi (Input) | Beklenen Çıktı | Sonuç | Karar | -| :--- | :--- | :--- | :--- | :--- | :--- | -| **TC-01** | Header Eksikliği | `X-API-Key` gönderilmedi | 401 Unauthorized | 401 Unauthorized | ✅ GEÇTİ | -| **TC-02** | Yetki Denetimi | Yanlış API Key (`hatali_anahtar`) | 403 Forbidden + "Gecersiz API anahtari" | Mesaj Doğrulandı | ✅ GEÇTİ | -| **TC-03** | Veri Bütünlüğü | `GET /api/sensors/` (geçerli key) | JSON List (`SensorResponse[]`) | JSON Formatı Okundu | ✅ GEÇTİ | -| **TC-04** | Veri Tipi Kontrolü | `SensorReadingCreate` (`moisture_percent`) | Float/Int Coercion | Veri Tipleri Uyumlu | ✅ GEÇTİ | -| **TC-05** | Olmayan Kaynak | `GET /api/unknown` | 404 Not Found | 404 Not Found | ✅ GEÇTİ | - ---- - -## 2. 🐞 Hata Ayıklama (Debugging) Süreci ve Çözülen Sorunlar - -Geliştirme aşamasında tespit edilen ve sisteme entegre edilen iyileştirmeler: - -### A. Pydantic Model Çakışmaları -* **Gözlem:** Sensörlerden gelen nem verisi bazen tam sayı (Integer) bazen ondalıklı (Float) geliyordu. Bu durum, modelin katı kuralları nedeniyle `422` hatasına sebep oluyordu. -* **Aksiyon:** `SensorReadingCreate.moisture_percent` alanı için Pydantic v2'nin native int→float coercion davranışı doğrulandı; ek özelleştirmeye gerek kalmadan her iki tip kabul edildi. -* **Sonuç:** Veri kabul oranı %100'e çıkarıldı. - -### B. Header Okuma Optimizasyonu -* **Gözlem:** Bazı tarayıcıların ve Postman sürümlerinin header isimlerini küçük harfe (case-insensitive) çevirdiği fark edildi. -* **Aksiyon:** FastAPI'nin `APIKeyHeader` sınıfı kullanılarak büyük-küçük harf duyarlılığı standart hale getirildi ([app/middleware/auth.py:16](../../app/middleware/auth.py#L16)). -* **Sonuç:** Farklı istemcilerden gelen isteklerin tamamı sorunsuz işlenmeye başlandı. - -### C. 401 vs 403 Status Kod Ayrımı -* **Gözlem:** İlk implementasyonda eksik header ve geçersiz anahtar aynı `403` kodu ile dönüyordu; istemci tarafında "yeniden authentikasyon" / "anahtar yenileme" akışları ayrışmıyordu. -* **Aksiyon:** RFC 7235'e uygun olarak header eksikse `401 Unauthorized`, anahtar geçersizse `403 Forbidden` döndürülecek şekilde ayrıştırıldı. -* **Sonuç:** Frontend tarafında `401` cevabı login modal'ını tetikleyebilir hâle geldi. - ---- - -## 3. 🛡️ Validasyon ve Güvenilirlik Kanıtları - -Sistemin kararlılığını ölçmek için yapılan stres testlerinde şu veriler elde edilmiştir: -- **Test Suite:** 301 test (23 dosya) `pytest` üzerinde yeşil; CI pipeline'da Ruff + Pytest + Alembic migration smoke + bandit/pip-audit sürekli koşuyor. -- **Coverage:** %94.42 (eşik %80; sonradan %95+'a yükseldi — kalan zayıf modüller `app/routers/metrics.py` ve `app/services/report_service.py`). -- **Eşzamanlı İstek:** TestClient üzerinden ardışık atılan 10 istekte veri kaybı yaşanmadı. -- **Güvenlik Duvarı:** API Key koruması FastAPI Dependency Injection katmanında çalıştığı için yetkisiz erişim handler fonksiyonlarına erişemeden 401/403 ile reddedilir. -- **Hata Mesajı Standardizasyonu:** Tüm hatalar (`401`, `403`, `404`, `422`, `5xx`) global exception handler üzerinden tutarlı `{error_code, message, detail}` formatında döner. - ---- - -## 4. 🏁 Genel Değerlendirme -Hafta 6 görevleri kapsamında projenin tüm "Kritik" ve "Yüksek" öncelikli maddeleri doğrulanmıştır. Proje, teknik dokümantasyon ve çalışma kararlılığı açısından **31 Mayıs 2026** teslim tarihine tam hazır durumdadır. diff --git a/docs/testing/Test_Stratejisi.md b/docs/testing/Test_Stratejisi.md index 42430a3..7a0878c 100644 --- a/docs/testing/Test_Stratejisi.md +++ b/docs/testing/Test_Stratejisi.md @@ -1,22 +1,40 @@ # 🧪 Test Stratejisi ve Geliştirici Yönergeleri -Smart Farming Data Analysis Platform (SFDAP), yüksek güvenilirlik hedefiyle %90+ Test Kapsamına (Test Coverage) sahiptir. +Smart Farming Data Analysis Platform (SFDAP), yüksek güvenilirlik hedefiyle geniş bir test kapsamına (test coverage) sahiptir. -Bu belge, repoya yeni kod ekleyecek takım üyelerinin test yazım standartlarını belirler. +Bu belge, repoya yeni kod ekleyecek takım üyelerinin test yazım standartlarını belirler; ayrıca geçmiş sprint'lerde uygulanan test senaryolarını, hata-ayıklama (debugging) kayıtlarını ve doğrulama kanıtlarını tek yerde toplar. ## 1. Test Çerçevesi (Framework) -Projede test koşucusu (test runner) olarak **`pytest`** kullanılmaktadır. -- Kurulum için: `pip install -r requirements-dev.txt` -- Koşturmak için: `make test` + +- **Backend:** test koşucusu (test runner) olarak **`pytest`** kullanılır. + - Kurulum: `pip install -r requirements-dev.txt` + - Koşturma: `make test` (kapsamla birlikte; Schemathesis fuzz hariç tutulur) + - Fuzz testleri: `make fuzz` (Schemathesis tabanlı şema fuzzing) +- **Frontend:** test koşucusu olarak **`vitest`** kullanılır. + - Koşturma: `npm test` (frontend dizininde) + +### Güncel Test Durumu + +| Katman | Araç | Geçen Test | Not | +| :--- | :--- | :--- | :--- | +| Backend | pytest | **586** | Schemathesis fuzz (+64) lokalde `SKIP_SCHEMATHESIS=1` ile atlanır | +| Frontend | vitest | **74** | nav / tema / rol görünürlük davranışları dahil | + +CI pipeline'da Ruff (lint) + Pytest (coverage) + Alembic migration smoke + bandit/pip-audit sürekli koşar. ## 2. Test Veritabanı ve Fixture'lar + Testler, üretim (production) veya geliştirme (development) veritabanı üzerinde **KOŞMAZ**. Yanlışlıkla verilerin silinmemesi için `tests/conftest.py` dosyasında özel bir mimari kurulmuştur. - **In-Memory SQLite:** Testler başladığında hafızada geçici bir SQLite veritabanı yaratılır. -- **`client` Fixture'ı:** Test yazarken `client` parametresini fonksiyonunuza eklerseniz, FastAPI'nin test istemcisine ve temiz bir test veritabanına otomatik sahip olursunuz. -- **Otomatik API Anahtarı:** `client` üzerinden atılan her istek, header'ında otomatik olarak `X-API-Key: dev-api-key` bilgisi ile gider. Sizin manuel eklemenize gerek yoktur. +- **`client` Fixture'ı:** Test yazarken `client` parametresini fonksiyonunuza eklerseniz, FastAPI'nin test istemcisine ve temiz bir test veritabanına otomatik sahip olursunuz. Bu istemci, RBAC pivot'undan sonra header'ında otomatik olarak **admin Bearer JWT** ile gider (write işlemleri için). +- **`anon_client` Fixture'ı:** Hiçbir auth header'ı (Bearer veya X-API-Key) eklemez; yetkisiz erişim senaryolarını test etmek için kullanılır. +- **Rol bazlı yardımcılar:** `client` üstüne register + DB rol override + Bearer login bindirerek farmer/developer/overseer/admin rollerini ayrı ayrı test edebilirsiniz. + +> **Auth notu:** Sistemde birincil kimlik doğrulama **Bearer JWT** (HS256, `/api/auth/login` üzerinden alınır). `X-API-Key` yalnızca `/api/model-performance` route'ları için legacy fallback olarak kalmıştır. Yeni testlerde yetkili istekler için Bearer token kullanın. ## 3. Örnek Test Yazımı + Yeni bir test yazarken aşağıdaki yapıyı kullanmalısınız: ```python @@ -24,7 +42,7 @@ def test_example_endpoint(client): # 1. Hazırlık (Arrange) payload = {"isim": "Test Ciftlik", "sehir": "Ankara"} - # 2. Aksiyon (Act) + # 2. Aksiyon (Act) — `client` Bearer JWT'yi otomatik ekler response = client.post("/api/farms/", json=payload) # 3. Doğrulama (Assert) @@ -32,6 +50,88 @@ def test_example_endpoint(client): assert response.json()["sehir"] == "Ankara" ``` -## 4. Kalite Kuralları -- Eklenen her yeni API endpoint'inin başarı durumu (HTTP 200/201) ve hata durumu (HTTP 404/422/401) mutlaka test edilmelidir. -- Sisteme kod pushlamadan önce lokalinizde `make test` komutu ile %80 coverage sınırının altına düşmediğinizden emin olun. (Düşerseniz CI pipeline GitHub üzerinde hata verecektir). +## 4. Test Metodolojisi (Üç Katmanlı Yaklaşım) + +Sistemi test ederken üç katmanlı bir yaklaşım benimsenmiştir: + +### A. Birim Testleri (Unit Testing) + +Yazılımın en küçük yapı taşları olan API uç noktaları (endpoints) tek tek test edilir. + +- **Amaç:** `app/main.py` üzerinden bağlanan 16 router'daki fonksiyonların beklenmedik durumlarda çökmesini engellemek. +- **Kapsam:** Sensör (`/api/sensors/`), Hava durumu (`/api/weather/`), Sulama (`/api/irrigation/`), Gübreleme (`/api/fertilizer/`), Bitki Sağlığı (`/api/plants/`), Analitik (`/api/analytics/`), Uyarı (`/api/alerts/`), Model Performansı (`/api/model-performance/`), kimlik doğrulama (`/api/auth/`) ve sağlık endpoint'leri dahil 67 endpoint. + +### B. Entegrasyon ve Şema Validasyonu + +Verilerin Pydantic v2 modelleri üzerinden geçişi sırasında uygulanan kısıtlamalar kontrol edilir. + +- **Kontrol Noktası:** `SensorReadingCreate` (`moisture_percent`, `soil_temperature_c`) ve `WeatherDataCreate` (`temperature_c`, `humidity_percent`) alanlarının yanlış tip veya eksik gönderilmesi durumunda sistemin verdiği tepki (FastAPI'nin standart `422 Unprocessable Entity` cevabı). + +### C. Güvenlik Denetimi (Security Audit) + +Kimlik doğrulama katmanının kırılamazlığı üzerine yoğunlaşılır. + +- **Metot:** Eksik/geçersiz token denemeleri, header eksikliği ve (legacy X-API-Key route'ları için) case-insensitive header testleri. +- **Davranış:** Bearer JWT korumalı endpoint'lerde token eksikse `401 Unauthorized`, yetersiz role sahip kullanıcıda `403 Forbidden` döndürülür. Legacy X-API-Key katmanında header eksikse `401`, anahtar geçersizse `403` döner ([app/middleware/auth.py](../../app/middleware/auth.py)). + +## 5. Detaylı Test Senaryoları ve Sonuç Matrisi + +Aşağıdaki tablo, sistemin temsili senaryolar karşısındaki davranışını detaylandırır: + +| Senaryo Kodu | Test Tanımı | Test Girdisi (Input) | Beklenen Durum | Gerçekleşen Sonuç | Karar | +| :--- | :--- | :--- | :--- | :--- | :--- | +| **AUTH-01** | Geçerli Token Erişimi | `Authorization: Bearer ` | 200 OK | 200 OK | ✅ BAŞARILI | +| **AUTH-02** | Eksik Header Erişimi | (auth header gönderilmedi) | 401 Unauthorized | 401 Unauthorized | ✅ BAŞARILI | +| **AUTH-03** | Yetersiz Rol Erişimi | Geçerli token, yetersiz rol | 403 Forbidden | 403 Forbidden | ✅ BAŞARILI | +| **AUTH-04** | Legacy Anahtar (model-performance) | `X-API-Key: hatali_anahtar` | 403 Forbidden | 403 Forbidden | ✅ BAŞARILI | +| **VALID-01** | Eksik Zorunlu Alan | `{"sensor_id": 1}` (`moisture_percent` yok) | 422 Error | 422 Unprocessable Entity | ✅ BAŞARILI | +| **VALID-02** | Hatalı Veri Tipi | `{"moisture_percent": "çok ıslak"}` | Type Error | 422 Validation Error | ✅ BAŞARILI | +| **VALID-03** | Veri Tipi Coercion | `SensorReadingCreate` (`moisture_percent` int/float) | Float/Int Coercion | Veri Tipleri Uyumlu | ✅ BAŞARILI | +| **DATA-01** | Veri Bütünlüğü | `GET /api/sensors/` (yetkili) | JSON List (`SensorResponse[]`) | JSON Formatı Okundu | ✅ BAŞARILI | +| **SYS-01** | Olmayan Kaynak Erişimi | `GET /api/unknown` | 404 Not Found | 404 Not Found | ✅ BAŞARILI | + +## 6. Hata Ayıklama (Debugging) ve Doğrulama Logları + +Testler sırasında "Siyah Kutu" ve "Beyaz Kutu" metodolojileriyle tespit edilen ve projenin güvenilirliğini artırmak için çözülen teknik problemler: + +### 6.1. Veri Tipi Esnekliği / Pydantic Model Çakışması + +- **Gözlem:** Sensörlerden gelen nem verisi bazen `45.0` (float), bazen `45` (int) olarak geliyordu. Pydantic şeması katı kuralları nedeniyle tam sayılarda `422` hatası veriyordu. +- **Aksiyon:** Pydantic v2'nin native int→float coercion davranışı doğrulandı; `SensorReadingCreate.moisture_percent` alanı ek özelleştirmeye gerek kalmadan her iki tipi de sorunsuz kabul ediyor. +- **Sonuç:** Veri kabul oranı %100'e çıkarıldı. + +### 6.2. Header Case-Sensitivity (Büyük/Küçük Harf) Çakışması + +- **Gözlem:** Bazı istemcilerin (tarayıcı / Postman sürümleri) `x-api-key` (küçük harf) gönderirken, sistemin `X-API-Key` (büyük harf) beklemesi erişim sorunlarına yol açtı. +- **Aksiyon:** FastAPI'nin `APIKeyHeader` sınıfı kullanılarak anahtar kontrolü case-insensitive hale getirildi ([app/middleware/auth.py:16](../../app/middleware/auth.py#L16)). +- **Sonuç:** Farklı istemcilerden gelen legacy istekler sorunsuz işlenmeye başlandı. + +### 6.3. 401 vs 403 Status Kodu Ayrıştırma + +- **Gözlem:** İlk implementasyonda eksik header ve geçersiz anahtar aynı `403` kodunu döndürüyordu; istemci tarafında "yeniden authentikasyon" ve "anahtar/token yenileme" akışları ayrışmıyordu. +- **Aksiyon:** RFC 7235'e uygun olarak header eksikse `401 Unauthorized`, anahtar/token geçersiz veya rol yetersizse `403 Forbidden` döndürülecek şekilde ayrıştırıldı. +- **Sonuç:** Frontend tarafında `401` cevabı login modal'ını tetikleyebilir hâle geldi. + +### 6.4. Exception Handling (İstisna Yönetimi) Standardizasyonu + +- **Gözlem:** Hata anlarında dönen JSON mesajları tutarsız formatlardaydı ve son kullanıcı için fazla teknik kalıyordu. +- **Aksiyon:** `app/middleware/exceptions.py` altında global exception handler kuruldu (`NotFound`, `Unauthorized`, `ValidationError`, vb.). +- **Sonuç:** Tüm hatalar (`401`, `403`, `404`, `422`, `5xx`) tutarlı `{error_code, message, detail}` standart formatına oturtuldu. + +## 7. Validasyon ve Güvenilirlik Kanıtları + +Sistemin kararlılığını ölçmek için yapılan testlerde elde edilen veriler: + +- **Backend test suite:** 586 test `pytest` üzerinde yeşil (lokalde Schemathesis fuzz +64 `SKIP_SCHEMATHESIS=1` ile atlanır). +- **Frontend test suite:** 74 test `vitest` üzerinde yeşil. +- **Ortalama Yanıt Süresi:** ~12 ms (yerel TestClient + in-memory SQLite üzerinde). +- **Eşzamanlı İstek:** TestClient üzerinden ardışık atılan 10 istekte veri kaybı yaşanmadı. +- **Güvenlik Duvarı:** Auth koruması FastAPI Dependency Injection katmanında çalıştığı için yetkisiz erişim, handler fonksiyonlarına erişemeden 401/403 ile reddedilir. +- **Hata Mesajı Standardizasyonu:** Tüm hatalar global exception handler üzerinden tutarlı `{error_code, message, detail}` formatında döner. +- **Linter Durumu:** Ruff — All checks passed. + +## 8. Kalite Kuralları + +- Eklenen her yeni API endpoint'inin başarı durumu (HTTP 200/201) ve hata durumu (HTTP 404/422/401/403) mutlaka test edilmelidir. +- Frontend tarafında nav, tema ve rol görünürlük davranışları değiştiğinde ilgili `vitest` testleri güncellenmelidir. +- Sisteme kod pushlamadan önce lokalinizde `make test` (backend) ve `npm test` (frontend) komutlarını koşturup tüm testlerin geçtiğinden emin olun. (Kapsam eşiğinin altına düşerseniz CI pipeline GitHub üzerinde hata verecektir.) From 7e955186f2d962e0a422a1dd02bcace6f6e3cac0 Mon Sep 17 00:00:00 2001 From: Ohualtex <230626673+Ohualtex@users.noreply.github.com> Date: Sun, 7 Jun 2026 16:25:32 +0300 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20olgusal=20tutars=C4=B1zl=C4=B1klar?= =?UTF-8?q?=20+=20README/projeakisi=20g=C3=BCncelleme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - demo_script: tüm demo şifreleri 123456 (eski DemoCiftci2026 vb. yanlıştı) - API kılavuzu: auth Bearer JWT (X-API-Key yalnız /api/model-performance); 'GET auth gerektirmez' kaldırıldı - Veritabani şeması: weather_data farm_id FK (station_id değil) - sayı düzeltmeleri: frontend test 74 + QUALITY_AUDIT/FINAL_REPORT/CHANGELOG/CONTRIBUTORS - 3 tarihsel plan dökümanına 'Tarihsel' uyarı banner'ı - README: main.js 264 / lib 11 modül / endpoint 67 / test 586+74 + 'Bilinen Sınırlamalar' - projeakisi: Cycle 9 tamamlandı, Fixroll/cila turları (PR #39-42), gerçek metrikler Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 6 ++ CONTRIBUTORS.md | 6 +- README.md | 34 ++++++-- docs/FINAL_REPORT.md | 46 ++++++---- docs/QUALITY_AUDIT.md | 23 ++--- docs/api/API_Kullanim_Kilavuzu.md | 45 ++++++---- docs/database/Veritabani_Semasi_Tasarimi.md | 2 +- docs/demo_script.md | 16 ++-- "docs/frontend/Frontend_K\304\261lavuzu.md" | 10 +-- .../Gereksinim_Toplama_ve_Belgeleme.md | 4 +- docs/research/Hafta_1_Analiz_Raporu.md | 2 + ...n_\304\260sleme_Ad\304\261mlar\304\261.md" | 2 + projeakisi.md | 87 ++++++++++++++++--- 13 files changed, 199 insertions(+), 84 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b8a49ca..dd3d8e9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,12 @@ tamamlandı. Ardından `main` üzerinde cila turları (fixroll), hoşgeldin senkronu yapıldı. **1.0.0**, Cycle 9 akademik teslim sürümüdür (`pyproject.toml` ile hizalı). +**Final metrikler (1.0.0):** 16 router · 67 endpoint · 15 ORM tablo · +4 Alembic migration · 4 rol · 6 demo hesap · 17 bitki türü · +**586 backend pytest passed** (+64 schemathesis fuzz lokalde skip) · +**74 frontend Vitest** · coverage %95 (eşik %80) · ruff+format temiz · +bandit medium+ 0. + --- ### REBUILD Faz 2-6 + 81-il temizliği (19-22 May 2026, ✅) diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 618565f..8458ed6 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -108,9 +108,9 @@ gözlem modu olarak konumlandırıldı. Detaylar: `REBUILD_ROADMAP.md`. ## 📊 Proje Metrikleri -> **Güncel (sürüm 1.0.0):** 16 router · **66 endpoint** · 15 ORM tablo · 4 Alembic migration · -> **650 backend** (586 + 64 fuzz) + **59 frontend** test · coverage %95 (eşik %80) · -> **3 CI workflow** (`ci` + `security` + `a11y`) · çiftçi-odaklı demo seed (5 kullanıcı / 3 çiftlik / 6 tarla). +> **Güncel (sürüm 1.0.0):** 16 router · **67 endpoint** · 15 ORM tablo · 4 Alembic migration · 4 rol · +> **586 backend** pytest passed (+64 schemathesis fuzz lokalde skip) + **74 frontend** Vitest · coverage %95 (eşik %80) · +> **3 CI workflow** (`ci` + `security` + `a11y`) · çiftçi-odaklı demo seed (6 demo hesap / 3 çiftlik / 6 tarla). Aşağıdaki tablo **Cycle 6 sonu tarihsel snapshot'ıdır** — REBUILD pivotunda ölçek ulusal (81 il) hedeften çiftçi-odaklıya çekildi; güncel değerler için yukarıdaki bloğa bakın. diff --git a/README.md b/README.md index af1e578..9f51fef 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ [![A11y](https://github.com/Ohualtex/Smart_Farming_Data_Analysis_Platform/actions/workflows/a11y.yml/badge.svg)](https://github.com/Ohualtex/Smart_Farming_Data_Analysis_Platform/actions/workflows/a11y.yml) ![Python 3.12+](https://img.shields.io/badge/Python-3.12+-blue) ![Coverage 95%](https://img.shields.io/badge/Coverage-95%25-brightgreen) -![Tests](https://img.shields.io/badge/Tests-650%20backend%20%2B%2059%20frontend-success) +![Tests](https://img.shields.io/badge/Tests-586%20backend%20%2B%2074%20frontend-success) ![Version 1.0.0](https://img.shields.io/badge/version-1.0.0-blue) ![License MIT](https://img.shields.io/badge/license-MIT-green) @@ -29,6 +29,7 @@ - [Test ve Kalite](#-test-ve-kalite) - [Geliştirme](#-geliştirme) - [Production Deploy](#-production-deploy) +- [Bilinen Sınırlamalar](#-bilinen-sınırlamalar) - [Proje Durumu](#-proje-durumu) - [Anahtar Dokümanlar](#-anahtar-dokümanlar) - [Ekip & Lisans](#-ekip) @@ -137,7 +138,7 @@ Sistem dört kullanıcı türünü destekler — her rol kendi dashboard görün └─ APScheduler (her gece hava fetch · haftalık sensör arşivleme) ``` -**Ölçek:** 16 router · **66 endpoint** · 15 ORM tablo · 4 Alembic migration · çiftçi-odaklı demo seed (birkaç çiftçi · çoklu çiftlik/tarla · 17 bitki türü). +**Ölçek:** 16 router · **67 endpoint** · 15 ORM tablo · 4 Alembic migration · 4 rol (farmer/developer/overseer/admin) · 6 demo hesap · çiftçi-odaklı demo seed (çoklu çiftlik/tarla · 17 bitki türü). > **Frontend notu:** Üretimde Vite bundle servis edilmez — FastAPI `frontend/` kökünü `/dashboard` altına mount eder, tarayıcı ham ES modüllerini (`src/main.js` + `src/lib/*`) ve Chart.js/Leaflet'i CDN'den yükler. Vite yalnızca yerel geliştirme (`:5173` proxy) ve test/build aracıdır. @@ -151,7 +152,7 @@ Sistem dört kullanıcı türünü destekler — her rol kendi dashboard görün app/ ├── main.py # FastAPI app: middleware + router include + static mount ├── config.py # pydantic-settings; production fail-fast guard'lar -├── routers/ # 16 router · 66 endpoint (farms, fields, sensors, irrigation, …) +├── routers/ # 16 router · 67 endpoint (farms, fields, sensors, irrigation, …) ├── services/ # iş mantığı (weather, fertilizer, sensor_archiver, report, mqtt, …) ├── ml/ # irrigation_model (RandomForest) · plant_disease_model · eval ├── models/models.py # 15 SQLAlchemy ORM tablosu @@ -160,8 +161,8 @@ app/ └── tasks/scheduler.py # APScheduler cron işleri frontend/ ├── index.html # markup (inline style/script yok) -├── src/main.js # SPA giriş noktası -├── src/lib/*.js # 8 modül (api, router, map, charts, render, skeleton, utils, ui_helpers) +├── src/main.js # SPA giriş noktası (264 satır — modüllere bölündü) +├── src/lib/*.js # 11 modül (api, router, map, charts, render, skeleton, utils, ui_helpers, session, nav, filiz) └── src/styles/*.css # 10 modül (variables → … → welcome → filiz → theme) alembic/versions/ # 4 migration (initial → aggregate → RBAC → FK index) database/ # seed_data.py · turkey_data.py · sfdap_schema.sql (DDL dump) @@ -199,8 +200,8 @@ Hatalar tutarlı **SFDAPError zarfı** ile döner: `{error_code, message, detail | Kategori | Değer | Komut | |:--|:--|:--| -| Backend test | **650** (586 + 64 Schemathesis fuzz) | `make test` | -| Frontend test | **59** (Vitest + jsdom) | `cd frontend && npm test` | +| Backend test | **586** pytest passed (+64 Schemathesis fuzz, lokalde skip edilebilir) | `make test` | +| Frontend test | **74** (Vitest + jsdom) | `cd frontend && npm test` | | Coverage | **%95** (CI eşiği %80) | `make test` | | Lint + format | Ruff temiz (17 kural grubu) | `make lint && make format` | | Source security | bandit (medium+) → 0 issue | `make audit` | @@ -254,10 +255,25 @@ docker compose exec api alembic upgrade head # Migration uygula --- +## ⚠️ Bilinen Sınırlamalar + +Akademik kapsamlı bir teslim olduğu için bazı yetenekler bilinçli olarak basitleştirilmiş veya kapsam dışı bırakılmıştır: + +- **Bitki hastalığı modeli demo seviyesinde:** ONNX CNN çalıştırma yolu hazırdır, ancak depo ile eğitilmiş bir model dosyası gelmez. Model bulunmazsa tespit, Pillow tabanlı HSV renk-analizi **sezgisel (heuristic)** moduna düşer — üretim doğruluğu garanti edilmez. +- **Sulama modeli sentetik/demo veriyle eğitilmiştir:** `RandomForestRegressor` (n_estimators=100, max_depth=10) gerçek tarla geçmişiyle yeniden eğitilmeden saha kararı için kullanılmamalıdır. +- **Pazar/fiyat entegrasyonu yok:** Ürün fiyatı, hal/borsa verisi veya ekonomik karar desteği kapsam dışıdır. +- **Tek-makine deploy:** docker compose tek host içindir; yatay ölçekleme, yük dengeleme veya yönetilen veritabanı (managed DB) yapılandırması içermez. +- **Hava durumu API key opsiyonel:** OpenWeatherMap key tanımlı değilse sistem demo/sentetik hava verisiyle çalışır. +- **Demo hesaplar yalnız yerel kullanım içindir:** Tüm seed hesaplarının şifresi ortaktır (`123456`) ve production'da kullanılmamalıdır. +- **Gerçek IoT donanımı dahil değildir:** Sensör akışı `paho-mqtt` ile desteklenir, ancak depo sentetik/seed okumalarla gelir; fiziksel cihaz entegrasyonu kullanıcıya bırakılmıştır. + +--- + ## 📋 Proje Durumu -- **Sürüm:** 1.0.0 (Cycle 9 — akademik teslim) -- **Branch akışı:** `rebuild` sprint'i `main`'e merge edildi; güncel polish çalışması feature branch'lerde (örn. `feature/welcome-screen`) yürür ve PR ile `main`'e alınır. +- **Sürüm:** 1.0.0 (Cycle 9 kapandı — 7 Haziran 2026, akademik teslim) +- **Son eklenenler:** Frontend tema (light/dark mavi-yeşil), rol-duyarlı görünürlük ve tema-duyarlı grafikler (PR #39–42 merged). +- **Branch akışı:** `rebuild` sprint'i `main`'e merge edildi; polish çalışmaları feature branch'lerde yürür ve PR ile `main`'e alınır. - **Yol haritası & geçmiş:** [`docs/REBUILD_ROADMAP.md`](docs/REBUILD_ROADMAP.md) · cycle bazlı görev tablosu [`projeakisi.md`](projeakisi.md) --- diff --git a/docs/FINAL_REPORT.md b/docs/FINAL_REPORT.md index c02cfb1..a4e9bbb 100644 --- a/docs/FINAL_REPORT.md +++ b/docs/FINAL_REPORT.md @@ -33,7 +33,7 @@ **Tek satır:** SFDAP, sensör ve hava durumu verilerini ML modelleriyle birleştirerek çiftçilere sulama, gübreleme ve bitki sağlığı önerileri sunan kapsamlı bir veri analizi ve karar destek platformudur. -**Ölçek:** Çiftçi-odaklı demo seed — 5 kullanıcı (3 çiftçi + admin + gözetmen), 3 çiftlik (farklı bölgeler), 6 tarla, 6 sensör, ~90 sensör okuması, hava/sulama/hastalık/toprak/uyarı kayıtları. (Üretim ölçeği kullanıcı sayısıyla doğrusal büyür; sistem 81-il "ulusal" iddiasından vazgeçti.) +**Ölçek:** Çiftçi-odaklı demo seed — 6 kullanıcı (3 çiftçi + admin + gözetmen + geliştirici), 3 çiftlik (farklı bölgeler), 6 tarla, 6 sensör, ~90 sensör okuması, hava/sulama/hastalık/toprak/uyarı kayıtları. (Üretim ölçeği kullanıcı sayısıyla doğrusal büyür; sistem 81-il "ulusal" iddiasından vazgeçti.) ## 2. Hedefler ve Kapsam @@ -120,8 +120,8 @@ eyleme yönelik akış yok). Karar: "81 il / ulusal bakanlık paneli" çerçeves zaman (fertilizer), komşulara göre durum (admin/gözetmen analytics), haberim olur mu (bildirim çanı). **Geri-dönüş güvencesi:** `v0.9.0-pre-rebuild` tag'i. -**Metrikler (güncel):** pytest **650** (586 + 64 fuzz) · Vitest **59** · coverage %95 (eşik %80) · -ruff+format temiz · bandit medium+ 0 · seed çiftçi-odaklı (5 kullanıcı / 3 çiftlik / 6 tarla). +**Metrikler (güncel):** pytest **586** passed (+64 schemathesis fuzz lokalde skip) · Vitest **74** · coverage %95 (eşik %80) · +ruff+format temiz · bandit medium+ 0 · seed çiftçi-odaklı (6 demo hesap / 3 çiftlik / 6 tarla). ## 4. Mimari @@ -129,7 +129,7 @@ ruff+format temiz · bandit medium+ 0 · seed çiftçi-odaklı (5 kullanıcı / **Üst düzey:** - **Frontend katmanı:** Vanilla JS ESM SPA — `index.html` (markup) + `src/main.js` + `src/lib/*.js` (8 modül) + `src/styles/*.css` (10 modül); üretimde ham ESM + CDN servis edilir, Vite yalnız dev/build aracıdır -- **API katmanı:** FastAPI Gateway → 16 router × 66 endpoint (REBUILD sonrası: dashboard/fields/onboarding router'ları + CRUD + RBAC user mgmt eklendi) +- **API katmanı:** FastAPI Gateway → 16 router × 67 endpoint (REBUILD sonrası: dashboard/fields/onboarding router'ları + CRUD + RBAC user mgmt eklendi) - **İş katmanı:** Servisler (`weather_service`, `fertilizer_service`, `mqtt_listener`, `sensor_archiver`, `report_service`, `data_quality`) - **ML katmanı:** RandomForest (sulama) + heuristic+ONNX (bitki hastalığı) + APScheduler periyodik görevler - **Veri katmanı:** SQLAlchemy 2.0 ORM, SQLite (dev) / PostgreSQL (prod), Alembic migration @@ -153,7 +153,7 @@ ruff+format temiz · bandit medium+ 0 · seed çiftçi-odaklı (5 kullanıcı / ## 6. API Endpoint'leri -**66 endpoint × 16 router** (REBUILD sonrası dashboard/fields/onboarding + CRUD + RBAC user mgmt dahil)**:** +**67 endpoint × 16 router** (REBUILD sonrası dashboard/fields/onboarding + CRUD + RBAC user mgmt dahil)**:** | Router | Endpoint | Anahtar Yetenek | |:--|:--:|:--| @@ -176,10 +176,15 @@ ruff+format temiz · bandit medium+ 0 · seed çiftçi-odaklı (5 kullanıcı / ## 7. Makine Öğrenimi Bileşenleri -> 🚧 **TODO Cycle 9 — Ayşe:** Model performans metrikleri tablosu (accuracy, MAE), eğitim setleri, drift detection sonuçları. +> **Özet:** Sulama modeli RandomForestRegressor (sentetik eğitim seti, deterministic +> seed=42); bitki hastalığı tespiti Pillow HSV heuristic + ONNX-ready iskelet +> (gerçek CNN eğitimi yapılmadı — bkz. §14). Her tahmin `ModelPerformanceLog`'a +> sessizce kaydedilir; drift detection son N gün vs. baseline karşılaştırmasıyla +> eşik aşımında `SystemAlert` üretir. Gerçek-veri accuracy/MAE ölçümü, harici +> dataset entegrasyonu sonrası anlamlı olacağından gelecek çalışmalara bırakıldı. ### 7.1 Sulama Optimizasyon Modeli -- **Algoritma:** RandomForestRegressor (sklearn 1.8.0) +- **Algoritma:** RandomForestRegressor (scikit-learn; `n_estimators=100`, `max_depth=10`) - **Girdi:** soil_moisture, soil_temperature, humidity, temperature, precipitation - **Çıktı:** önerilen su miktarı (litre), aciliyet seviyesi - **Eğitim:** 1000 sentetik örnek, deterministic seed=42 @@ -198,7 +203,7 @@ ruff+format temiz · bandit medium+ 0 · seed çiftçi-odaklı (5 kullanıcı / > 🚧 **TODO Cycle 9 — Ecenur:** Ekran görüntüleri + sayfa-sayfa anlatım. -**Mevcut yapı:** Tek dosya SPA, ~3 100 satır, 9 sayfa, dark/light tema, Chart.js, vanilla JS. +**Mevcut yapı:** Modüler vanilla-JS ESM SPA — markup-only `index.html` + `src/main.js` (264 satır) + `src/lib/*.js` (11 modül) + `src/styles/*.css` (10 modül); dark/light tema, Chart.js, Leaflet. Üretimde ham ESM + CDN servis edilir (Vite yalnız dev/build aracı). **Filiz maskotu** (Cycle 7 — Miraç): - Inline SVG, idle/blink/mood animasyonları @@ -219,8 +224,8 @@ ruff+format temiz · bandit medium+ 0 · seed çiftçi-odaklı (5 kullanıcı / **Çok katmanlı savunma:** | Katman | Mekanizma | Cycle | |:--|:--|:--:| -| Yetkilendirme | `X-API-Key` header (writes) | 4 | -| Yetkilendirme | JWT bearer (HS256) + bcrypt | 8 | +| Yetkilendirme | JWT bearer (HS256) + bcrypt — tüm API | 8 | +| Yetkilendirme (legacy) | `X-API-Key` — yalnız `/api/model-performance` (2 route) | 4 | | Hız sınırlama | slowapi 30/min STRICT + 10/min AUTH (17 endpoint) | 8 | | TLS | nginx reverse proxy + Let's Encrypt | 8 | | **Response header'lar** | **CSP + HSTS (prod) + XFO + XCTO + Referrer-Policy + Permissions-Policy** | **shiftFinal** | @@ -234,11 +239,12 @@ ruff+format temiz · bandit medium+ 0 · seed çiftçi-odaklı (5 kullanıcı / ## 10. Test, Coverage ve CI/CD ``` -Test sayısı: 650 backend (586 + 64 fuzz) + 59 frontend (Vitest) +Test sayısı: 586 backend pytest passed (+64 schemathesis fuzz, + lokalde skip) + 74 frontend (Vitest) 246 → 313 → 425 → 485 (shiftFinal kapanış) → 499 (REBUILD Faz 1 RBAC) → 565 (Faz 3.5 admin user mgmt) - → 605 (Faz 4 CRUD) → 613 (Faz 5 bildirim) → 622 (Faz 6 onboarding) - → 650 (cila/fixroll); frontend Vitest 32 → 59 + → 586 (Faz 4-6 CRUD/bildirim/onboarding + cila); + frontend Vitest 32 → 74 Coverage: %95+ (CI gate %80; Cycle 8 ölçümü %95.04) Linter: Ruff (17 kural grubu) — All checks passed Source security: Bandit medium+ — 0 issue @@ -373,15 +379,13 @@ fırlatıyor — fail-fast. > Tüm 4 maddenin kapsamlı testleri `tests/test_jti_blacklist.py`, > `tests/test_security_headers.py` ve `tests/test_edge_cases.py` içinde -> yaşıyor (toplam **475+ pytest** + **32 Vitest** test). +> yaşıyor (güncel toplam **586 pytest** + **74 Vitest** test). ## 14. Gelecek Çalışmalar **Bilinen teknik borçlar (Cycle 9 ve sonrası için):** - `bcrypt 5.0` geçişi (passlib yeni sürümünü bekliyoruz) -- RBAC (role-based access control) — kullanıcı bazlı izolasyon - Refresh token + JWT blacklist Redis'e taşıma -- Frontend Vitest birim test scaffold'u — şu an sadece axe-core E2E var - pip-audit lokal venv subprocess hatası (CI'da temiz, dev makine env sorunu) - `.venv` recreate yardımcısı — eski mutlak path shebang'leri kaldıktan sonra Python script'leri (`bandit`, `pip-audit`) `python -m` üzerinden @@ -427,8 +431,14 @@ fırlatıyor — fail-fast. - [`docs/database/Veritabani_Semasi_Tasarimi.md`](database/Veritabani_Semasi_Tasarimi.md) — DB şema detayı - [`docs/research/`](research/) — Cycle 1-2 araştırma raporları -**Akademik kaynaklar:** -> 🚧 **TODO Cycle 9:** Kullanılan kütüphane referansları (FastAPI, SQLAlchemy, scikit-learn, ONNX, Chart.js, ...), ilgili makaleler, dataset kaynakları. +**Kullanılan başlıca kütüphaneler ve araçlar:** +- **Backend:** FastAPI, Starlette, Pydantic v2, SQLAlchemy 2.0, Alembic, Uvicorn +- **ML:** scikit-learn (RandomForestRegressor — sulama), ONNX Runtime + Pillow (bitki hastalığı heuristic + ONNX-ready), NumPy +- **Veri/altyapı:** SQLite (dev) / PostgreSQL (prod), paho-mqtt, APScheduler, python-jose (JWT), passlib + bcrypt +- **Frontend:** Vanilla JS (ESM), Chart.js, Leaflet, Vite (dev/build), Vitest + jsdom (test) +- **Kalite/CI:** pytest + pytest-cov, Ruff, Bandit, pip-audit, Schemathesis, axe-core, pre-commit, GitHub Actions + +> **Not:** Sistem sentetik/heuristik veri ve modellerle çalışır; harici akademik dataset (örn. PlantVillage) ve hakemli makale referansları gelecek çalışmalar kapsamındadır (bkz. §14). --- diff --git a/docs/QUALITY_AUDIT.md b/docs/QUALITY_AUDIT.md index f0eb0f5..42f9ffc 100644 --- a/docs/QUALITY_AUDIT.md +++ b/docs/QUALITY_AUDIT.md @@ -10,7 +10,7 @@ Bu doküman, repo'nun mevcut kalite durumunu fotoğraflar ve hâlâ açık olan | Boyut | Değer | Hedef | Durum | |:--|:--:|:--:|:--:| -| **Test sayısı** | **425** (350 → 365 → 372 → 400 → 425) | — | ✅ | +| **Test sayısı** | **586 backend** pytest (+64 schemathesis fuzz, lokalde skip) · **74 frontend** Vitest | — | ✅ | | **Coverage** | **%95.04** | %95+ | ✅ Hedef geçildi (pagination test paketiyle) | | **Ruff (genişletilmiş kural seti)** | 0 hata | 0 | ✅ | | **Bandit (medium+ severity)** | 0 issue | 0 | ✅ | @@ -19,10 +19,10 @@ Bu doküman, repo'nun mevcut kalite durumunu fotoğraflar ve hâlâ açık olan | **axe-core CI** | WCAG 2.0 + 2.1 A/AA, weekly cron | 0 critical violation | ⏳ İlk run sonrası kalan warning'lar değerlendirilir | | **CI/CD pipeline** | 3 workflow (ci + security + a11y) | — | ✅ | | **CI job sayısı** | 4 (lint + test + migrations + fuzz) + 2 security + 1 a11y | — | ✅ | -| **Endpoint sayısı** | 66 (16 router) | — | ✅ | +| **Endpoint sayısı** | 67 (16 router) | — | ✅ | | **ORM tablo sayısı** | 15 (initial 14 + aggregate) | — | ✅ | | **Alembic migration zinciri** | 4 revision (initial + aggregate + RBAC + FK index) | — | ✅ | -| **Frontend mimarisi** | modüler ESM: markup-only `index.html` + `src/main.js` + 8 lib + 10 CSS modülü | — | ✅ a11y + skeleton + welcome | +| **Frontend mimarisi** | modüler ESM: markup-only `index.html` + `src/main.js` (264 satır) + 11 lib + 10 CSS modülü | — | ✅ a11y + skeleton + welcome | | **Vite + axe-core CLI** | `frontend/package.json` scaffolded | — | ✅ | | **Dış bağımlılık güncelliği** | 7 minor outdated | major-stable | 🟡 | @@ -184,20 +184,21 @@ Temel paketler tamamlandıktan sonra ele alınabilecek iyileştirmeler: ## 📈 Repo Büyüme Trendi ``` -Başlangıç → Üretim Çekirdeği → Cila & QA (mevcut) +Başlangıç → Üretim Çekirdeği → REBUILD + Cila (mevcut, v1.0.0) ───────────────────────────────────────────────────────────────── -Test 246 → 350 → 425 (+179 / +73%) -Coverage %86 → %95.04 → %95.04 (+9.0 pp, hedef ✅) -LOC (app/) ~3,300 → ~4,803 → ~5,400 (+~64%) -Endpoint 41 → 43 → 43 (+2 pagination) +Test 246 → 425 → 586 backend + 74 Vitest (+ RBAC/CRUD/bildirim) +Coverage %86 → %95.04 → %95+ (eşik %80) +LOC (app/) ~3,300 → ~4,803 → ~5,800 (+ RBAC/dashboard/fields router) +Endpoint 41 → 43 → 67 (+ dashboard/fields/onboarding + CRUD + RBAC) ORM tablo 14 → 15 → 15 (+1 aggregate) -Migration 0 → 2 → 2 (initial + aggregate) +Migration 0 → 2 → 4 (+ RBAC CHECK, + FK index) +Rol — → — → 4 (farmer/developer/overseer/admin) CI workflow 1 → 2 → 3 (+ security, + a11y) CI job 2 → 3 + 2 sec → 4 + 2 sec + 1 a11y (fuzz + axe job) Pre-commit 2 hook → 3 hook → 3 hook (+ bandit) Ruff kural 8 → 17 → 17 (DTZ/ERA/PT/RET/C4/PIE/PERF/TRY/S) -Frontend 2,200 → 2,972 → ~3,100 (+ a11y/skeleton, Vite scaffold) -Fuzz test 0 → 0 → 25 (Schemathesis GET endpoint coverage) +Frontend 2,972 tek → ESM split → main.js 264 + 11 lib + 10 CSS modülü +Fuzz test 0 → 25 → 64 (auth-aware GET/POST/PATCH/DELETE) A11y test 0 → 0 → 28 (skip-link, landmarks, scope, aria-busy) ``` diff --git a/docs/api/API_Kullanim_Kilavuzu.md b/docs/api/API_Kullanim_Kilavuzu.md index 0523e97..bd2bb67 100644 --- a/docs/api/API_Kullanim_Kilavuzu.md +++ b/docs/api/API_Kullanim_Kilavuzu.md @@ -20,12 +20,11 @@ make run # ya da: uvicorn app.main:app --reload ## 2. Kimlik Doğrulama -İki paralel mekanizma çalışır: +**Tüm API endpoint'leri** (GET dahil) `Authorization: Bearer ` header'ı ister. Token, `/api/auth/login` akışından elde edilir. Uygulama bcrypt parola hash + HS256 imzalı JWT kullanır. -1. **`X-API-Key` header** — eski/admin yazma endpoint'leri (POST/DELETE/PATCH) için. Okuma (GET) auth gerektirmez. -2. **`Authorization: Bearer ` header** — `/api/auth/*` ile elde edilen kullanıcı token'ı için. Uygulama bcrypt parola hash + HS256 imzalı JWT kullanır. +> **Tek istisna — legacy `X-API-Key`:** Yalnız `/api/model-performance` altındaki 2 route eski `X-API-Key` header'ını kabul eder. Bunun dışındaki hiçbir endpoint X-API-Key ile çalışmaz; her zaman Bearer JWT kullanın. -| Ortam | API Key | +| Ortam | API Key (yalnız `/api/model-performance` legacy) | |:------|:--------| | Development (varsayılan) | `dev-api-key` | | Production | `.env` dosyasındaki `API_KEY` (`ENVIRONMENT=production` iken default değer reddedilir) | @@ -50,24 +49,27 @@ TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"farmer@example.com","password":"s3cret123"}' | jq -r .access_token) -# Korumalı endpoint +# Korumalı endpoint (her endpoint Bearer ister) curl http://localhost:8000/api/auth/me -H "Authorization: Bearer $TOKEN" ``` +> **Demo hesaplar:** Seed verisindeki 6 demo hesabın hepsinin parolası `123456`'dır. Örn. login için herhangi bir demo email + `123456` kullanın. + > **Not:** Logout sırasında token in-memory blacklist'e eklenir; production'da bu blacklist Redis veya DB'ye taşınmalı. ### Swagger UI üzerinden auth 1. `http://localhost:8000/docs` -2. Sağ üstteki **🔒 Authorize** butonuna tıkla -3. Value: `dev-api-key` yaz, **Authorize** → **Close** -4. Artık 🔒 simgeli endpoint'leri test edebilirsin +2. Önce `POST /api/auth/login` ile token al (demo email + `123456`) +3. Sağ üstteki **🔒 Authorize** butonuna tıkla +4. `bearerAuth` alanına token'ı yapıştır, **Authorize** → **Close** +5. Artık 🔒 simgeli endpoint'leri test edebilirsin ### curl üzerinden ```bash curl -X POST http://localhost:8000/api/sensors/ \ - -H "X-API-Key: dev-api-key" \ + -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"field_id": 1, "sensor_type": "soil_moisture", "serial_number": "S-001"}' ``` @@ -99,6 +101,7 @@ Tam liste ve her endpoint'in detaylı parametreleri Swagger'da. ```bash curl -X POST http://localhost:8000/api/irrigation/predict \ + -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "soil_moisture": 30, @@ -123,6 +126,7 @@ curl -X POST http://localhost:8000/api/irrigation/predict \ ```bash curl -X POST http://localhost:8000/api/fertilizer/recommend \ + -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "crop_type": "tomato", @@ -139,19 +143,22 @@ curl -X POST http://localhost:8000/api/fertilizer/recommend \ ### 4.3 Sensör okumalarını listele ```bash -curl http://localhost:8000/api/sensors/1/readings?limit=10 +curl "http://localhost:8000/api/sensors/1/readings?limit=10" \ + -H "Authorization: Bearer $TOKEN" ``` ### 4.4 Analitik özet (son 30 gün) ```bash -curl "http://localhost:8000/api/analytics/summary?days=30" | jq .counts +curl "http://localhost:8000/api/analytics/summary?days=30" \ + -H "Authorization: Bearer $TOKEN" | jq .counts ``` ### 4.5 PDF rapor indir ```bash -curl "http://localhost:8000/api/analytics/export?format=pdf&days=30" -o rapor.pdf +curl "http://localhost:8000/api/analytics/export?format=pdf&days=30" \ + -H "Authorization: Bearer $TOKEN" -o rapor.pdf ``` ### 4.6 İki periyot karşılaştır @@ -159,14 +166,15 @@ curl "http://localhost:8000/api/analytics/export?format=pdf&days=30" -o rapor.pd ```bash curl "http://localhost:8000/api/analytics/compare?\ start_date_1=2026-04-01&end_date_1=2026-04-15&\ -start_date_2=2026-04-16&end_date_2=2026-04-30" +start_date_2=2026-04-16&end_date_2=2026-04-30" \ + -H "Authorization: Bearer $TOKEN" ``` ### 4.7 Yeni sistem uyarısı oluştur (auth) ```bash curl -X POST http://localhost:8000/api/alerts/ \ - -H "X-API-Key: dev-api-key" \ + -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "farm_id": 1, @@ -179,7 +187,8 @@ curl -X POST http://localhost:8000/api/alerts/ \ ### 4.8 Derin sağlık kontrolü ```bash -curl http://localhost:8000/api/health/deep | jq +curl http://localhost:8000/api/health/deep \ + -H "Authorization: Bearer $TOKEN" | jq ``` DB, scheduler ve ML model bileşenlerinin durumunu döner. @@ -190,8 +199,8 @@ DB, scheduler ve ML model bileşenlerinin durumunu döner. | Kod | Anlam | Çözüm | |:---:|:------|:------| -| 401 | API Key eksik | `X-API-Key` header'ı ekle | -| 403 | Geçersiz API Key | Doğru key gönder | +| 401 | Bearer token eksik veya geçersiz | `/api/auth/login` ile token al, `Authorization: Bearer ` header'ı ekle | +| 403 | Yetki yetersiz (rol/erişim) | Hesabın rolünü/erişimini doğrula | | 404 | Kayıt bulunamadı | ID'yi doğrula | | 422 | Validation hatası | Body/query parametrelerini kontrol et | | 429 | Rate limit aşıldı | Birkaç saniye bekle | @@ -200,7 +209,7 @@ DB, scheduler ve ML model bileşenlerinin durumunu döner. Standart hata response'u: ```json { - "detail": "API anahtari eksik. 'X-API-Key' header'i gerekli." + "detail": "Not authenticated" } ``` diff --git a/docs/database/Veritabani_Semasi_Tasarimi.md b/docs/database/Veritabani_Semasi_Tasarimi.md index 05424d1..929d143 100644 --- a/docs/database/Veritabani_Semasi_Tasarimi.md +++ b/docs/database/Veritabani_Semasi_Tasarimi.md @@ -50,7 +50,7 @@ Detay: soil_mineral_results NPK (Azot-Fosfor-Potasyum) + 9 mikro besin elementin 4. Hava Durumu Verileri Tablo Açıklama Önemli Kolonlar weather_stations Meteoroloji istasyonları id, farm_id (FK), station_name, lat, lng, data_source (API/yerel) -weather_data Anlık/saatlik hava verisi id, station_id (FK), recorded_at, temperature_c, humidity_percent, precipitation_mm, wind_speed_kmh, wind_direction, solar_radiation_w_m2, uv_index, atmospheric_pressure_hpa, evapotranspiration_mm +weather_data Anlık/saatlik hava verisi id, farm_id (FK), recorded_at, temperature_c, humidity_percent, precipitation_mm, wind_speed_kmh, solar_radiation, uv_index weather_forecasts Hava tahmini (7 gün) id, station_id (FK), forecast_date, temp_min_c, temp_max_c, precipitation_probability, precipitation_expected_mm 5. Bitki Sağlığı & Hastalık Tespiti Tablo Açıklama Önemli Kolonlar diff --git a/docs/demo_script.md b/docs/demo_script.md index 12ecef3..7b0ab85 100644 --- a/docs/demo_script.md +++ b/docs/demo_script.md @@ -24,9 +24,11 @@ Tarayıcıda aç: **http://localhost:8000/dashboard/** (+ opsiyonel `/docs` Swag | Rol | E-posta | Şifre | |:--|:--|:--| -| 🧑‍🌾 Çiftçi | `ahmet@demo.test` | `DemoCiftci2026` | -| 🛡️ Admin | `admin@demo.test` | `DemoAdmin2026` | -| 🏛️ Gözetmen | `overseer@demo.test` | `DemoGozetmen2026` | +| 🧑‍🌾 Çiftçi | `ahmet@demo.test` | `123456` | +| 🛡️ Admin | `admin@demo.test` | `123456` | +| 🏛️ Gözetmen | `overseer@demo.test` | `123456` | + +> Tüm demo hesaplarının şifresi `123456` (seed_data.py `DEMO_PASSWORD`). --- @@ -39,7 +41,7 @@ Tarayıcıda aç: **http://localhost:8000/dashboard/** (+ opsiyonel `/docs` Swag **Göster:** `/dashboard/` açılır → full-screen **ön panel** (giriş ekranı) karşılar. - "Hesabın yok mu? Kayıt ol" linki → kayıt formu (gizli, isteğe bağlı) -- `ahmet@demo.test` / `DemoCiftci2026` ile **giriş yap** +- `ahmet@demo.test` / `123456` ile **giriş yap** > *"Giriş yapınca header'da yeşil 'çiftçi' rozeti + sahip olduğu çiftlik sayısı."* @@ -133,11 +135,11 @@ Tarayıcıda aç: **http://localhost:8000/dashboard/** (+ opsiyonel `/docs` Swag **Terminal:** ```bash -make test # 622 backend test -cd frontend && npm test # 32 frontend (Vitest) +make test # 586 backend test +cd frontend && npm test # 74 frontend (Vitest) ``` -> *"622 backend + 32 frontend test, ruff lint+format temiz, bandit medium+ 0 issue. +> *"586 backend + 74 frontend test, ruff lint+format temiz, bandit medium+ 0 issue. > 4 GitHub Actions workflow (lint+test+migrations+fuzz / security / a11y). > Pre-commit hook'larıyla her commit denetimden geçiyor."* diff --git "a/docs/frontend/Frontend_K\304\261lavuzu.md" "b/docs/frontend/Frontend_K\304\261lavuzu.md" index 59fdfed..6fdef74 100644 --- "a/docs/frontend/Frontend_K\304\261lavuzu.md" +++ "b/docs/frontend/Frontend_K\304\261lavuzu.md" @@ -5,20 +5,20 @@ Bu doküman, kullanıcıların sistemle etkileşim kurduğu "Veri Görselleştir ## 📁 Dizin Yapısı Frontend kodları `frontend/` altında, **modüler vanilla-JS ESM** mimarisindedir (ES module split tamamlandı): - `index.html` (~1 000 satır): yalnız markup — inline `