01Genel Bakış
Amaç ve kapsam
Demo CRM; tek kullanıcıya, yerel ortamda çalışan, tek sayfa ve tamamen Türkçe bir müşteri takip uygulamasıdır. Üç iş alanından oluşur: müşteri kayıtları ve bunların yönetimi, müşteriye bağlı takip görevleri ve üç özet sayacı.
Arayüz ile arka uç birlikte çalışır; filtreler ve sayaçlar yalnızca kaydedilmiş gerçek veriyi gösterir. Her başarılı işlemden sonra ilgili liste ve sayaçlar yenilenir.
Arayüz (UI v2): Bu sürüm, arayüzün yeni tasarım sistemine göre yeniden çizildiği görsel sürümle uyumludur (yerel Fira yazı tipi yığını, dış CDN yok; mavi vurgu paleti; tablo taşma kontrolü) ve detay panelindeki notu düzenleme için bir not popup bileşeni içerir. İşlev ve veri sözleşmesi değişmedi; fark yalnızca görsel ve bu yeni bileşendir.
Müşteriler
Beş alanlı müşteri kaydı: oluşturma, listeleme, düzenleme, silme, arama ve firma filtresi.
Görevler
Müşteriye bağlı takip görevleri: başlık, vade ve durum; müşteri ve gecikmiş filtreleri.
Sayaçlar
Toplam müşteri, gecikmiş görev ve bu ay eklenen müşteri sayaçları.
Belge hakkında
MUST — başlangıç brief'inde açıkça yer alan zorunluluk. V- — brief sessiz kaldığı yerlerdeki düşük etkili varsayım; kaynak şartı değildir. Öneri — mimariye devredilen tercih; zorunluluk değildir.
Belge kalite kontrolü
- Açık karar bekleyen konu yok — kaynakta yer alan her ifade bir gereksinim, varsayım veya kapsam dışı maddesine karşılık geliyor.
- Tek veri sözleşmesi — her alanın adı, tipi, zorunluluğu ve hata davranışı tek yerde tanımlı.
- Her arayüz işlemi için kabul maddesi — girdi/eylem ve beklenen ekran sonucu belgeli.
- Her zorunluluk kaynağa dayanıyor — brief sessiz kaldığı yerler açıkça varsayım olarak etiketli.
- Sayaç etkileri koşul bazlı — her işlemin sayaçları nasıl etkilediği, değişen/değişmeyen örneklerle tanımlı.
02Varsayımlar ve Öneriler
Başlangıç brief'i sessiz kaldığı konularda düşük etkili varsayımlar tanımlanmıştır. Her biri gerekirse değişiklik talebiyle güncellenebilir; hiçbiri kaynak şartı olarak yazılmamıştır.
+V-1Görev vadesi gün çözünürlüklüdürEtki: düşük
Görev vadesi "gün" çözünürlüklüdür (YYYY-MM-DD); saat tutulmaz.
Gerekçe: Gün çözünürlüğü gecikme kuralını basit tutar. Saate ihtiyaç doğarsa değişiklik talebiyle eklenir.
+V-2Bugün vadesi olan görev gecikmiş sayılmazEtki: orta-düşük
Gecikme, vadenin bugünden önce olması demektir (vade < bugün); bugün vadesi olan görev gecikmiş sayılmaz. "Bugün", sunucunun yerel saat dilimine (Türkiye, UTC+3) göre belirlenir.
Gerekçe: Brief "gecikmiş" derken sınırı tanımlamaz.
+V-3"Bu ay eklenen" oluşturulma gününe göre sayılırEtki: orta-düşük
"Bu ay eklenen müşteri", müşterinin oluşturulduğu günün yerel saat dilimindeki takvim ayına göre sayılır; ay, her ayın 1'inde 00:00'da başlar.
Gerekçe: Brief "bu ay eklenen" derken sınırlarını vermez.
+V-4Arama dört metin alanında çalışırEtki: düşük
Arama; isim, firma, telefon ve e-posta alanlarında kısmi ve büyük/küçük harf duyarsızdır; not alanına bakmaz.
Gerekçe: Brief arama kapsamını vermez; telefon da metin eşleşmesiyle aranır.
+V-5Firma filtresi tam eşleşmedirEtki: düşük
Firma filtresi, seçilen firmanın tam eşleşmesini uygular; eşleşen müşteri kümesini listeler.
Gerekçe: "Firma filtresi"nin en doğal okuması tekil firma seçimidir.
+V-6Görevin müşteri alanı zorunludurEtki: orta-düşük
Görevler müşteriye bağlıdır: müşteri alanı görev oluştururken zorunludur. Görev filtresi yalnızca "müşteri" ve "gecikmiş" olmak üzere tanımlıdır.
Gerekçe: "Müşteriye bağlı" ifadesi zorunluluğa okunur.
+V-7Müşteri silinince görevleri de silinirEtki: orta-düşük
Bir müşteri silindiğinde ona bağlı görevler birlikte silinir; yetim görev kabul edilmez.
Gerekçe: İlişki bütünlüğü; kullanıcıya sormadan yapılabilen düşük etkili okuma.
+V-8Varsayılan liste sıralamasıEtki: düşük
Müşteri listesi isme göre artan; görev listesi vadeye göre artan sıralanır (eşitlikte oluşturulma sırası).
Gerekçe: Sıralama brief'te yer almaz.
+V-9Yeni görev penceresinde müşteri varsayılanıEtki: düşük
"Yeni Görev Kayıt" penceresi açıldığında müşteri alanı, panelde seçili olan müşteri filtresiyle dolu gelir. Filtre "Tümü" (boş) ise alan boş kalır. Düzenleme akışında alan, görevin bağlı olduğu müşteriyle dolu açılır (etkilenmez). Varsayılan her zaman kullanıcının değiştirebildiği bir başlangıç değeridir.
Gerekçe: Panelde zaten daraltılmış bir müşteri görünümünde görev açarken aynı müşteri tekrar seçilmek zorunda kalınmasın; brief sessiz kaldığı için düşük etkili varsayım olarak belirlendi.
Öneriler (mimariye devredilen tercihler)
Not alanı için 2.000 karakter üst sınırı
Performans eşiği değil, veri sağlamlığı için tanımlanmıştır; mimari onaylar veya değiştirir.
E-posta için pratik biçim doğrulaması
Örneğin @ işareti zorunludur. Kötü veri korumasıdır; brief dışı zorunluluk değildir.
Sayfa içi liste boyu: 100 kayıt
Yerel, tek kullanıcı uygulamaya uygun hacim sınırı; brief'te hacim tanımı yoktur.
03Veri Modeli
İki kayıt türü vardır: müşteri ve takip görevi. Her alanda arayüz etiketi ile sistem alan adı ayrı sütunda gösterilir; bu tablo tek sözleşmedir.
Müşteri
| Alan | Sistem adı | Tip | Zorunlu | Boş/null değerde | Geçersiz giriş örneği |
|---|---|---|---|---|---|
| İsim | ad | metin, 1–200 karakter | Evit | hata gösterilir, kayıt oluşmaz | "" (boş), 201+ karakter |
| Firma | firma | metin, 0–200 karakter | Hayır | boş olarak saklanır | 201+ karakter |
| Telefon | telefon | metin, 0–30 karakter (rakam, boşluk, + - ( )) | Hayır | boş olarak saklanır | 31+ karakter, harf içeren değer |
| E-posta | eposta | metin, 0–200 karakter | Hayır | boş olarak saklanır | ornek.com (@ yok) |
| Not | not | metin, 0–2000 karakter | Hayır | boş olarak saklanır | 2001+ karakter |
- • Oluşturmada yalnızca İsim zorunludur; diğer alanlar gönderilmeyebilir.
- • Oluşturulma zamanı sistem üretir ve "bu ay eklenen" sayacının tek kaynağıdır (V-3).
- • Kimlik (
id) artan tam sayı olarak sistem üretir; silme kalıcıdır ve zamanı saklanmaz. - • Not alanı, detay panelindeki not popup bileşeniyle düzenlenir: mevcut metni gösterir, 2.000 karakter üst sınırıyla yazı alanı, karakter sayacı, "Vazgeç" ve "Kaydet" seçenekleri sunar.
Takip görevi
| Alan | Sistem adı | Tip | Zorunlu | Boş/null değerde | Geçersiz giriş örneği |
|---|---|---|---|---|---|
| Başlık | baslik | metin, 1–200 karakter | Evit | hata gösterilir, kayıt oluşmaz | "" (boş), 201+ karakter |
| Vade | vade | tarih, YYYY-MM-DD (V-1) | Evit | hata gösterilir | 31-02-2026, 2026-13-01 |
| Durum | durum | acik | tamamlanmis | Evit (varsayılan: acik) | oluşturmada varsayılana döner; güncellemede boş gönderilirse hata | yapildi (geçersiz durum) |
| Müşteri | musteri_id | müşteri kimliği (tam sayı) | Evit (V-6) | var olmayan müşteri için hata | var olmayan kimlik |
- • Gecikmişlik kayıtlı bir alan değil, türetilmiş bir değerdir: durum Açık ve vade bugünden önce (V-2).
- • Görevin oluşturulma zamanı sistem üretir; silme kalıcıdır.
Durum değerleri
| Durum | Değer (kod) | Arayüz etiketi |
|---|---|---|
| Görev durumu | acik, tamamlanmis | Açık, Tamamlandı |
| Gecikmişlik (türetilmiş) | gecikmis, gecikmis_degil | Gecikmiş, Gecikmiş değil |
Oluşturma ve güncelleme kuralları
- • Oluşturma: zorunlu alan eksikse veya boşsa hata (422) gösterilir; kayıt oluşmaz, veri değişmez.
- • Güncelleme: yalnızca gönderilen alanlar değişir (kısmi güncelleme / PATCH); gönderilmeyen alan korunur.
null, alanı "boş" olarak yazar (zorunlu alanlarda hata). - • Boş metin (
""), zorunlu metin alanlarında hatadır. - • Her başarılı değişiklikten sonra ilgili liste ve sayaçlar kaynaktan yeniden hesaplanır; önbellek tutulmaz.
04Fonksiyonel Gereksinimler
On altı fonksiyonel gereksinim; modül filtresiyle daraltılabilir.
Müşteri oluşturulur
Girdi: İsim (zorunlu), Firma, Telefon, E-posta, Not.
Müşteriler listelenir
Müşteri düzenlenir
Tüm beş alan düzenlenebilir; güncelleme kısımdaki kısmi güncelleme kuralına göre çalışır.
Müşteri silinir
Silme kalıcıdır; müşteriye bağlı görevler de birlikte silinir (V-7).
Müşteri listesi aranır
Aranan alanlar: isim, firma, telefon, e-posta; kısmi ve büyük/küçük harf duyarsız (V-4).
Müşteri listesi firma filtresiyle daraltılır
Firma filtresi tam eşleşmedir (V-5).
Arama ve firma filtresi birlikte çalışır
Müşteriye bağlı görev oluşturulur
Girdi: Başlık, Vade, Durum (varsayılan: Açık), Müşteri.
Görev güncellenir
Başlık, vade, durum ve müşteri değiştirilebilir; kısmi güncelleme kuralına göre çalışır.
Görev silinir
Görev listesi müşteri filtresiyle daraltılır
Görev listesi "gecikmiş" filtresiyle daraltılır
Müşteri ve gecikmiş filtreleri birlikte çalışır
"Toplam müşteri" sayacı
"Gecikmiş görev" sayacı
"Bu ay eklenen müşteri" sayacı
05Arayüz Kabulü
Tek sayfa Türkçe arayüzde her işlem için girdi/eylem ve beklenen ekran sonucu. Hata durumunda kayıt oluşmaz/değişmez, Türkçe hata mesajı gösterilir ve mevcut liste korunur.
| # | İşlem | Girdi / eylem | Beklenen ekran sonucu |
|---|---|---|---|
U-01 | Müşteri ekleme | Formda İsim (zorunlu) + diğer alanlar; "Kaydet" | Yeni müşteri listede görünür; "Toplam müşteri" sayacı 1 artar (bu ay eklenmişse "Bu ay eklenen" de artar); form temizlenir |
U-02 | Müşteri ekleme — hata | Boş İsim ile "Kaydet" | Müşteri oluşmaz; "İsim zorunludur" benzeri Türkçe hata; liste ve sayaçlar değişmez |
U-03 | Müşteri düzenleme | Satırda "Düzenle" → alan değiştir → "Kaydet" | Satır yeni değerlerle görünür; değiştirilmeyen alanlar korunur; sayaçlar değişmez |
U-04 | Müşteri silme | Satırda "Sil" → onay | Satır listeden kalkar; bağlı görevler görev listesinde görünmez; "Toplam müşteri" 1 azalır; bu ay eklenmişse "Bu ay eklenen" 1 azalır; bağlı açık gecikmiş görev varsa gecikmiş sayacı da azalabilir (bkz. Sayaç Etkileri) |
U-05 | Arama | Arama kutusuna metin yaz (isim, firma, telefon, e-posta — V-4) | Liste yalnızca eşleşen kayıtlara daralır; eşleşme yoksa "Kayıt bulunamadı"; kutu boşsa tam liste |
U-06 | Firma filtresi | Firma seç (V-5) | Liste yalnızca o firmanın müşterilerine daralır; "Tümü" seçilince tam liste |
U-07 | Arama + firma | İkisi birlikte | AND sonuç; biri temizlenince diğeri tek başına geçerli kalır |
U-08 | Görev ekleme | Müşteri seç + Başlık + Vade + Durum; "Kaydet" | Pencere açılırken müşteri alanı, panelde seçili müşteri filtresiyle dolu gelir (filtre "Tümü" ise boş — V-9); görev, ilgili müşterinin görev listesinde görünür; vade dünden önce ve durum Açık ise "Gecikmiş görev" sayacı artar, aksi halde değişmez |
U-09 | Görev ekleme — hata | Başlıksız veya vadesiz "Kaydet" | Görev oluşmaz; hata mesajı; liste ve sayaçlar değişmez |
U-10 | Görev güncelleme | Görevde "Düzenle" → Durum: Tamamlandı → "Kaydet" | Görev tamamlanmış görünür; "Gecikmiş görev" sayacı azalır (görev önceden gecikmişse) |
U-11 | Görev silme | Görevde "Sil" → onay | Görev listeden kalkar; sayaçlar Sayaç Etkileri kuralına göre yenilenir |
U-12 | Görev filtresi — müşteri | Müşteri seç | Yalnızca o müşterinin görevleri görünür |
U-13 | Görev filtresi — gecikmiş | "Gecikmiş" filtresi açılır | Yalnızca gecikmiş açık görevler görünür; bugün vadesi olan açık görev listede yer almaz (V-2) |
U-14 | Görev filtreleri birleşimi | Müşteri + gecikmiş | AND sonuç; biri temizlenince tek filtre geçerli kalır |
U-15 | Boş durumlar | Yeni (kayıtsız) veri veya eşleşmesiz filtre | Listelerde "Kayıt yok" benzeri Türkçe boş durum; sayaçlar 0; hata üretilmez |
U-16 | Müşteri notunu not popup ile düzenle | Detay panelinde "Not" düğmesine bas → yazı alanına metin gir → "Kaydet" (veya "Vazgeç" / ESC) | Popup, seçili müşterinin adını ve mevcut notu gösterir; "Kaydet"te not yeni metniyle detay panelinde ve listede görünür, sayaçlar değişmez; "Vazgeç"/ESC'te popup kapanır ve not değişmez; 2.000 karakter üst sınırı karakter sayacıyla izlenir |
Arayüz kabul maddeleri, ayrı senaryolar halinde "Kullanım Senaryoları" belgesinde de yer alır.
06Sayaç Etkileri
Tarih sınırları: "bugün" = sunucu yerel saati (UTC+3); "bu ay" = oluşturulma tarihinin takvim ayı (ayın 1'i, 00:00'da başlar — V-2, V-3).
Müşteri işlemleri ve sayaçlar
| İşlem | Toplam müşteri | Bu ay eklenen | Gecikmiş görev |
|---|---|---|---|
| Müşteri oluştur | +1 | +1 | değişmez |
| Müşteri sil (bu ay eklenmiş) | −1 | −1 | bağlı açık gecikmiş görev kadar azalır (V-7) |
| Müşteri sil (geçen ay eklenmiş) | −1 | değişmez | aynı etki (V-7) |
| Müşteri düzenle | değişmez | değişmez | değişmez |
Görev işlemleri ve gecikmiş görev sayacı
| İşlem | Gecikmiş görev sayacı |
|---|---|
| Açık görev ekle, vade bugünden önce | +1 |
| Açık görev ekle, vade bugün veya sonrası | değişmez (bugün vadesi gecikmiş değildir — V-2) |
| Açık gecikmiş görevi tamamla | −1 |
| Tamamlanmış, geçmiş vadeli görevi sil | değişmez (zaten sayaçta değildi) |
| Açık gecikmiş görevi sil | −1 |
| Açık görevin vadesini bugüne çek | −1 (artık gecikmiş değil) |
| Açık görevin vadesini geleceğe çek (önceden bugün vadesiydi) | değişmez |
Değişen / değişmeyen örnekler
07Kapsam Dışı
Aşağıdaki maddeler bu sürümde kapsam dışıdır ve başlangıç brief'inde açıkça belirtilmiştir.
Docker
Uygulama Docker ile paketlenmez.
Kullanıcı hesabı / kimlik doğrulama
Ürün tek kullanıcıya yöneliktir; hesap ve kimlik doğrulama yoktur.
Dış API entegrasyonu
Dış servislerle veri alışverişi yapılmaz.
E-posta gönderimi / bildirim
Sistem e-posta göndermez, bildirim üretmez.
Çoklu dil
Arayüz yalnızca Türkçedir.
Yük testi
Yük testi kapsamı dışıdır.
Ücretli bağımlılık
Yalnızca ücretsiz bağımlılıklar kullanılır.
Model / servis / önbellek ayarı değiştirme
Bu ayarlar değiştirilmez.
Brief dışı zorunluluk
Başlangıç brief'i dışında ek zorunluluk tanımlanmamıştır.
08Teknik Gereksinimler
Teknoloji yığını
Python 3.11+, FastAPI, SQLAlchemy, SQLite (WAL modu), uvicorn.
Dört ayrı ortam
Geliştirme, test, önizleme ve üretim ortamları ayrıdır: her ortam kendi veri dosyasını, yapılandırmasını, sürecini ve günlüğünü kullanır. Hedef portlar 8201/8202/8203/8204; kullanımdan önce uygunluk doğrulanır.
Veri kaybı olmaz
Silme kalıcıdır ancak onay gerektirir (U-04, U-11); geçersiz giriş veri değiştiremez.
Ortam karışması olmaz
Her ortam yalnızca kendi veri dosyasına bağlanır.
Kurulum ve kullanım belgeleri
Ürün, kurulum ve kullanım kılavuzu ile birlikte teslim edilir.
Kullanıcı onayı
Her üretim adayı, yayına alınmadan önce gerçek kullanıcı onayını bekler.
Kanıt zinciri
Yayına giren aday için: geliştirici testleri, bağımsız kod incelemesi, kalite testleri ve aynı adayın önizleme ortamındaki tam regresyonu.
Performans eşiği tanımlanmaz
WAL + tek yerel kullanıcı ölçeği için ek performans eşiği tanımlanmamıştır; kaynakta eşik tanımı yoktur.
09İzlenebilirlik
Başlangıç brief'indeki her davranış, bu belgedeki ilgili maddeye karşılık gelir.
| Brief davranışı | Belge maddesi |
|---|---|
| Müşteri ekleme | REQ-MST-01 · Arayüz Kabulü U-01, U-02 |
| Müşteri listeleme | REQ-MST-02 · Arayüz Kabulü U-15 |
| Müşteri düzenleme | REQ-MST-03 · Arayüz Kabulü U-03 |
| Müşteri silme | REQ-MST-04 · Arayüz Kabulü U-04 |
| Müşteri alanları (isim, firma, telefon, e-posta, not) | Veri Modeli |
| Arama | REQ-MST-05 · Arayüz Kabulü U-05 |
| Firma filtresi | REQ-MST-06, REQ-MST-07 · Arayüz Kabulü U-06, U-07 |
| Görev (başlık, vade, durum, müşteriye bağlı) | Veri Modeli · REQ-TSK-01 · Arayüz Kabulü U-08, U-09 |
| Görev güncelleme / silme | REQ-TSK-02, REQ-TSK-03 · Arayüz Kabulü U-10, U-11 |
| Müşteri + gecikmiş görev filtresi | REQ-TSK-04, REQ-TSK-05, REQ-TSK-06 · Arayüz Kabulü U-12, U-13, U-14 |
| Üç sayaç (toplam müşteri, gecikmiş görev, bu ay eklenen) | REQ-CNT-01, REQ-CNT-02, REQ-CNT-03 · Sayaç Etkileri |