Sword Backend - Derin Kod Analizi Raporu¶

Tarih: 20.04.2026 Son güncelleme: 25.05.2026

1. Yönetici Özeti¶

Yapılan derin mimari ve güvenlik incelemesi sonucunda kod tabanının temel web uygulaması desenlerinde ciddi sorunlar içerdiği görülmüştür. İlk incelemeden sonra sert kodlanmış OpenAI anahtarı kaldırıldı, daha önce açığa çıkan anahtar harici olarak iptal edildi, bozuk auth token cache ve DB-backed auth lookup cache temizlendi, dosya yükleme doğrulamaları eklendi, tekrarlı API route blokları kaldırıldı, main.py içindeki büyük endpoint aileleri domain router dosyalarına çıkarıldı, temel Factory, Machine, Quote ve Device kayıtları için soft delete uygulandı, digital competency answer/analysis persistence eklendi, calendar event N+1 akışı düzeltildi, odaklı test kapsamı ve Python 3.9 uyumlu CI test kurulumu eklendi. Buna rağmen çıkarılan router'larda hâlâ servis katmanına taşınması gereken iş mantığı vardır. Proje, üretime hazır ve sürdürülebilir sayılabilmesi için kapsamlı ama aşamalı refaktöre ihtiyaç duymaktadır.

2. Teknik Değerlendirme¶

2.1 Kod Kalitesi ve Mimari¶

Uygulama giriş noktası (main.py): main.py artık app bootstrap, static mount'lar, açık dosya route'ları, router inclusion ve geçici OpenAI test uyumluluk shim'iyle sınırlıdır. Domain endpoint'leri app/routers/ altına taşınmıştır.
Route tekrarı koruması: Tekrarlı API route kayıtları kaldırıldı ve tests/test_route_inventory.py aynı (method, path) çiftlerinin tekrar eklenmesini engeller.
Servis katmanı eksikliği: OpenAI ve upload storage için servis modülleri vardır; ancak task, calendar, solution center, PDF/email ve ROI iş mantığı hâlâ router'larda ve CRUD operasyonlarında dağınıktır.
Structured logging: Production app modüllerindeki print() çağrıları module-level logger'larla değiştirildi. Request, hata ve kritik iş olayları için tutarlı logging standardı hâlâ tanımlanmalıdır.

2.2 Güvenlik Riskleri¶

Açığa çıkmış gizli anahtarlar: main.py içindeki sert kodlanmış OpenAI API anahtarı fallback değeri kaldırıldı ve OpenAI artık OPENAI_API_KEY ortam değişkeninden okunuyor. Daha önce açığa çıkan anahtar harici olarak iptal edildi.
Dosya yükleme güvenliği: Makine görsel yüklemeleri artık uzantı, MIME türü ve 12 MiB uygulama seviyesi boyut sınırı doğrulaması yapıyor. Validation, local write, cleanup ve URL helper mantığı app/services/upload_storage.py içine taşındı; main.py mevcut endpoint contract'larını koruyor. Deployment template'lerinde Nginx client_max_body_size 100M olduğu için bu sınır uygulama katmanında uygulanıyor. Internal single-server kullanımda yerel disk kabul edilebilir; uploads/ kalıcı tutulmalı, yedeklenmeli ve disk kullanımı izlenmelidir.
Kimlik doğrulama önbelleği: Bozuk token cache ve DB-backed kullanıcı sorgusundaki lru_cache kaldırıldı. Login ve bearer-token doğrulama akışları normal veritabanı okumalarına dayanıyor.

2.3 Performans ve Ölçeklenebilirlik¶

N+1 veritabanı sorguları: Calendar event liste/detay serialization akışı eager loading ve ortak serializer ile düzeltildi. Kalan düşük öncelikli relationship assignment döngüleri ayrıca batch edilebilir.
Duruma bağlı dosya saklama: Dosyalar yerel uploads/ dizininde tutulmaktadır. Bu mevcut internal single-server kullanım için kabul edilebilir; yatay ölçekleme veya ephemeral disk kullanımı başlarsa S3 uyumlu storage yeniden değerlendirilmelidir.
Bellek içi uygulama durumu: Auth token/user cache kaldırıldı. Kalan global runtime state kullanımları modülerleştirme sırasında ayrıca incelenmelidir.

2.4 Veri Bütünlüğü¶

Core kayıtlarda soft delete: Factory, Machine, Quote ve Device kayıtlarında nullable deleted_at alanları ve ana silme yollarında soft delete uygulanmıştır. Cihaz consumable link geçmişi korunur; temel CRUD helper'ları ve önemli API list/detail yolları soft-deleted kayıtları gizler. Core dışı admin/reference varlıkları için hard delete'in nerede kabul edilebilir olduğuna dair ayrı lifecycle kararı hâlâ gereklidir.
Digital competency persistence: Digital competency answer score ve analysis persistence davranışı API contract ile uyumlu hale getirildi ve aktif Alembic migration yoluna eklendi.

2.5 Üçüncü Taraf Entegrasyonları¶

OpenAI model seçimi: Model seçimi app/services/openai_client.py içinde merkezileştirildi. Onaylı sıra gpt-4.1 birincil ve gpt-4o fallback olacak şekildedir.
Şişkin bağımlılıklar: requirements/dev.txt içindeki kullanılmayan ağır google-cloud-aiplatform ve google-cloud-bigquery bağımlılıkları kaldırıldı. CI, full dev freeze yerine requirements/runtime.txt ve odaklı requirements/test.txt dosyasını kurar.

3. Adaptasyon Süresi ve Devredilebilirlik¶

Bu kodu ekip devralabilir mi? Yüksek zorlukla.
Adaptasyon süresi: Orta/kıdemli bir geliştiricinin mevcut çökme sorunlarını ve karmaşık akışı çözmesi için 2-3 hafta gerekecektir.
Refaktör maliyeti: Yaklaşık 140 - 180 saat olarak tahmin edilmektedir.

4. Öncelikli Aksiyon Maddeleri¶

Servis ayrımına devam edin: Task, calendar, solution center, PDF/email ve ROI iş mantığını router'lardan servis modüllerine taşıyın.
Production observability kapsamını genişletin: Mevcut module logger'ların üzerine request, hata ve kritik iş olayları için tutarlı logging davranışını tanımlayın.
Kalan N+1 döngülerini batch edin: Factory relationship assignment gibi düşük öncelikli döngüleri in_() sorgularıyla toparlayın.
CI'ı yeşil tutun: .github/workflows/tests.yml workflow'unu her refactor dilimiyle birlikte koruyun.
Entegrasyon testlerini genişletin: Temel oluşturma/güncelleme/silme akışları ve temsilî workflow endpoint'leri için testler ekleyin.
Konfigürasyonu güçlendirin: Kalan magic value'ları ve entegrasyon ayarlarını tipli konfigürasyona taşıyın.
Ölü kodu temizleyin: Modüller ayrılırken kullanılmayan import'ları, tekrarlı route desenlerini ve erişilemeyen branch'leri kaldırın.
Pydantic V2 temizliği yapın: Deprecated config ve .dict() kullanımlarını güncel API'lere taşıyın.
Reference data lifecycle kararını verin: User, catalog/reference entity, task ve admin taxonomy silmelerinde hard delete'in nerede kabul edilebilir olduğunu belirleyin.
Local storage operasyonlarını netleştirin: Internal single-server kullanım için uploads/ dizinini kalıcı, yedekli ve deploy adımlarından korunur tutun.

5. Python Refaktör İlkeleri¶

5.1 Temel İlkeler¶

DRY: main.py içindeki aşırı tekrarları ortak fonksiyonlara toplayın.
KISS: Karmaşık iç içe geçmiş yapılar yerine daha sade Pythonik desenler kullanın.
SRP: Her modül, sınıf ve fonksiyon tek bir sorumluluğa sahip olmalıdır.
Separation of Concerns: İş mantığı servis katmanına taşınmalıdır.

5.2 Python'a Özgü En İyi Uygulamalar¶

Pythonic yapılar kullanın.
Güçlü type hint'ler ekleyin.
Guard clause kullanarak iç içe if-else yapılarını azaltın.
Sabitleri ve dosya yollarını konfigürasyon haline getirin.
Büyük fonksiyonları küçük, test edilebilir parçalara bölün.
Kullanılmayan bağımlılıkları kaldırın.
Structured logging kullanın.
Statelss tasarıma geçin.

6. Nihai Karar¶

Teknik karar: Refaktör etmeye devam.

Temel SQLAlchemy model yapısı, Alembic migration kurulumu ve test yapısı kullanılabilir durumdadır; ayrıca birkaç kritik güvenlik sorunu düzeltilmiştir. Proje sıfırdan yazılmamalıdır, ancak üretime hazır sayılmadan önce routing, servis katmanı, veri yaşam döngüsü, sorgu performansı, logging ve dosya saklama taraflarında disiplinli refaktör gerektirir.

7. Kısa Değerlendirme Tablosu¶

Kategori	Durum	Risk	Not / Aksiyon
Kod Kalitesi	Orta	Orta	Tekrarlı route'lar kaldırıldı ve domain router'ları çıkarıldı; servis katmanı hâlâ genişletilmeli.
Güvenlik	Orta	Orta	OpenAI secret fallback, auth cache ve upload validation riskleri çözüldü; config ve operasyonel hardening devam etmeli.
Mimari	Orta	Orta	`main.py` büyük ölçüde bootstrap'a indi; workflow iş mantığı router'lardan servislere taşınmalı.
Logging	Orta	Orta	App modülleri logger kullanıyor; request ve business-event logging politikası eksik.
Veritabanı	Orta	Orta	`Factory`, `Machine`, `Quote` ve `Device` soft delete kullanıyor; kalan hard delete kararları netleşmeli.
API/Entegrasyon	Orta	Orta	OpenAI fallback ve digital competency persistence contract'ı düzeldi; entegrasyon ayarları tipli config'e taşınmalı.
Test/Deployment	Orta	Orta	Odaklı pytest kapsamı ve CI workflow'u var; temel business flow testleri genişletilmeli.
Devredilebilirlik	Zayıf	Yüksek	İlk duruma göre daha iyi, ancak servis eksikliği ve eski monolit izleri devri zorlaştırıyor.