🚚 CargoFlow – Gelişmiş ASP.NET Core 8 Kargo Yönetim API’si

✨ Proje Hakkında

CargoFlow, ASP.NET Core 8 ile geliştirilmiş, JWT kimlik doğrulamalı, loglama destekli, görsel yükleme ve metrik dashboard sistemi bulunan kurumsal düzey bir Kargo Takip ve Yönetim Sistemi API’sidir.

Bu proje, gerçek dünya senaryolarında kullanılabilecek API mimarisi, mikroservis hazırlığı, log ve hata yönetimi, arama/filtreleme gibi ileri seviye yaklaşımları içermektedir.

---

⚡️ Özellikler

• JWT tabanlı authentication sistemi
• Kargo CRUD + Durum Güncelleme
• Dosya yükleme (imza gibi)
• Kargo durumu loglama/geçmişi kaydetme
• Dashboard: Toplam, yolda, teslim edilen sayılar
• Dinamik filtreleme (alıcı, durum, tarih aralığı)
• Global exception handler (middleware ile)
• Serilog ile dosyaya log kaydı
• Swagger token entegrasyonu ve test kolaylığı
• Şifreli veri tabanı bağlantısı ve seed admin

---

🚀 Kurulum & Çalıştırma

# 1. Repoyu klonla
$ git clone https://github.com/ThecoderPinar/CargoFlow.git
$ cd CargoFlow

# 2. EF Core migration uygula (veritabanını MSSQL olarak ayarla)
$ dotnet ef database update

# 3. Uygulamayı başlat
$ dotnet run

# 4. Swagger arayüzüne git
https://localhost:7196/swagger

---

🔐 JWT Giriş Bilgisi (Varsayılan)

{
  "email": "admin@cargo.com",
  "password": "Admin123*"
}

Token'ı aldıktan sonra Swagger üzerinde Authorize butonuna basarak Bearer {token} şeklinde girin.

---

🚧 Temel API Uç Noktaları

ShipmentController

• GET /api/Shipment → Tüm kargolar
• GET /api/Shipment/{id} → Kargo detayı
• POST /api/Shipment → Yeni kargo
• PUT /api/Shipment/{id}/status?newStatus=Yolda → Durum güncelle
• GET /api/Shipment/search?receiver=Ahmet → Alıcıya göre ara
• GET /api/Shipment/filter?receiver=Ali&status=Yolda&from=2024-01-01&to=2024-12-31 → Filtreli ara
• GET /api/Shipment/dashboard → Metrik bilgileri (dashboard)

UploadController

• POST /api/Upload/upload?shipmentId=1 → Dosya yükle (imza)
• GET /api/Upload/{fileName} → Dosyayı getir
• DELETE /api/Upload/{fileName} → Dosyayı sil

---

📊 Dashboard JSON Örneği

{
  "totalShipments": 125,
  "pending": 40,
  "inTransit": 70,
  "delivered": 15
}

---

🛠️ Kullanılan Teknolojiler

• ASP.NET Core 8 Web API
• Entity Framework Core
• JWT Bearer Authentication
• Serilog
• FluentValidation
• Swagger + XML Comments
• SQL Server (MSSQL)
• Swagger UI

---

🚀 Proje Rozetleri (Badges)

CargoFlow, modern .NET 8 teknolojileriyle geliştirilmiş gelişmiş bir Kargo Yönetim API'sidir. Aşağıda projede kullanılan araçlar, entegrasyonlar ve platformlara dair detaylı rozetler yer almaktadır:

---

---

📌 Ayrıca bu proje:

• %100 RESTful API standartlarına uygun
• Swagger üzerinden JWT Token ile test edilebilir
• Platform bağımsız olarak çalışabilir: Windows, Linux, macOS
• Gelişmiş Dashboard metrikleri sunar
• Kargo geçmişi loglama sistemine sahiptir

İstersen bu rozetleri GitHub README dosyana doğrudan entegre edebilirsin ✨

---

🔧 Proje Yapısı

CargoFlow/
├── API/              # Controller ve Middleware'ler
├── Application/      # DTO'lar, Service Interface'leri
├── Domain/           # Entity ve Enum tanımları
├── Persistence/      # DbContext ve seed veriler
├── wwwroot/uploads/  # Yüklenen imzalar
├── Logs/             # Serilog log dosyaları
└── CargoFlow.sln

---

🔍 Swagger UI & Token Entegrasyonu

• Swagger UI token entegrasyonu sayesinde her endpoint test edilebilir.
• Token alındıktan sonra Authorize ❤️ Bearer Token özelliği ile tüm endpoint'ler test edilir.

---

🔐 Yetkilendirme Akışı (Authorization Flow)

CargoFlow API, JWT tabanlı kimlik doğrulama ve rol bazlı yetkilendirme sistemi kullanır. Aşağıdaki adımlar, istemci tarafından yetkilendirme akışını detaylandırır:

✅ 1. Giriş (Login)

• Endpoint: POST /api/Auth/login
• Giriş yapan kullanıcıya JWT token verilir.
• Token örneği: Bearer eyJhbGciOiJIUzI1...

🔑 2. Korunan Endpoint'lere Erişim

• Swagger üzerinde “Authorize” butonuna tıklanır.
• JWT token girilerek, API uç noktalarına erişim sağlanır.

🔰 3. Rol Bazlı Yetki

• Sadece Admin rolü, Shipment statüsü güncelleyebilir (PUT /shipment/{id}/status).
• Diğer endpoint'ler kullanıcı rolüyle de erişilebilir.

🧪 Test Senaryoları (Swagger / Postman Üzerinden)

✅ Shipment Oluşturma

• Endpoint: POST /api/Shipment
• Gövde:

{
  "senderName": "Pınar Topuz",
  "receiverName": "Ahmet Yılmaz",
  "productDescription": "Elektronik"
}

• Beklenen: 201 Created + JSON Cevap

🚤 Status Güncelleme

• Endpoint: PUT /api/Shipment/1/status?newStatus=Yolda
• Auth zorunlu.
• Beklenen: 204 No Content

📈 Dashboard Metrics

• Endpoint: GET /api/Shipment/dashboard
• Auth ile test edilir.
• Beklenen: Toplam, Hazırlanan, Yolda, Teslim Edilen sayıları

🔍 Filtreleme

• Endpoint: GET /api/Shipment/filter?receiver=Ali&status=Yolda
• Beklenen: Dinamik filtreye uyan liste

📂 Dosya Yükleme

• Endpoint: POST /api/Upload/upload?shipmentId=1
• Form-data: file
• Beklenen: 200 OK + Dosya URL

❗ Olası API Hataları ve Anlamları

HTTP Kodu	Hata Mesajı	Anlamı
400	One or more validation errors occurred.	Eksik veya geçersiz alanlar vardır.
401	Unauthorized	Token eksik/geçersiz, oturum açılmalı.
403	Forbidden	Kullanıcı bu işlemi yapmaya yetkili değil.
404	Not Found	Kayıt bulunamadı.
500	Internal Server Error	Sunucu taraflı genel hata.

⚠️ Tüm hatalar application/problem+json formatında döner ve geliştirici için traceId içerir.

---

🙌 Katkıda Bulun

Pull request ve issue'larınızı memnuniyetle kabul ediyoruz. Şunlara dikkat edin:

• Kodları Clean Architecture prensiplerine uygun yazın
• Kod içine yorum eklemekten çekinmeyin
• Swagger belgelerinde eksik bırakmayın

---

📄 Lisans

MIT Lisansı çerçevesinde sunulmuştur. Daha fazlası için LICENSE dosyasına bakabilirsiniz.

---

🔗 Bağlantılar

• GitHub: https://github.com/ThecoderPinar/CargoFlow
• Swagger UI: https://localhost:7196/swagger

---

✨ CargoFlow, ileri seviye .NET geliştiricileri için özenle hazırlanmış kurumsal mimariye sahip bir kargo yönetim API projesidir.