Demo CRM — Kurulum ve İşletim Belgesi

01Ortam Özeti

Öz

Demo CRM, tek kullanıcıya, yerel ortamda çalışan, tek sayfa ve tamamen Türkçe bir müşteri takip uygulamasıdır. Uygulama, uv yönetimiyle kurulur, uvicorn ile çalıştırılır, SQLite veritabanı tutar ve servis betikleri (start.sh, stop.sh, status.sh) ile başlatılır/durdurulur.

Ortam bilgisi tek kaynak olarak docs/devops/ENVIRONMENT.md dosyasında tutulur; bu belge onun müşteri/teslim tarafıdır. Uygulama kökü minimax-clean/ dizinidir.

Arayüz (UI v2): Bu sürüm (cfceea7), görev açılır penceresindeki (popup) müşteri alanının paneldeki seçili müşteri filtresiyle dolu açılmasını içerir: filtre "Tümü" ise müşteri alanı boş açılır; mevcut görevi düzenleme akışı değişmez. Değişiklik yalnızca arayüz katmanındadır; ortam, port, DB ve servis betikleri değişmedi.

Çalıştırma Sürümü

Git başı: cfceea7 · 06.10.2026 · Prod'da · tam regresyon geçti

Çalışma Portu

8021 (ayrılmış, çakışma yok) · http://localhost:8021

Veritabanı

SQLite · data/crm.sqlite3 · UTF-8 · WAL

Ortam bilgisi

Uygulama köküminimax-clean/

Python3.11.9 (pyenv)

uv0.8.12

FastAPI0.116.2

uvicorn0.35.0

Pydantic2.11.10

Çalışma modu--workers 1 (tek worker)

Zaman dilimiEurope/Istanbul (UTC+3)

02Kurulum

Ön koşullar

Bileşen	Gerekli sürüm	Kurulum
Python	3.11.9	`pyenv install 3.11.9`
uv	0.8.12	`uv` ile sanal ortam yönetimi

Python sürümü uv için kritik bir ön koşuldur: 3.11.9 kullanılmalıdır. Daha yüksek sürümler uv ile uyumlu olmayabilir.

Adım adım kurulum

Python kurun: pyenv install 3.11.9 — Python sürümü uv için kritik ön koşuldur.
Sanal ortam oluşturun: uv venv — proje kökünde .venv/ oluşturur.
Bağımlılıkları yükleyin: uv sync — pyproject.toml ve uv.lock dosyalarından tüm bağımlılıkları yükler.

Temel dosyalar

Dosya	Amaç
`pyproject.toml`	Proje yapılandırması ve bağımlılık listesi
`uv.lock`	Bağımlılık kilit dosyası (sürüm sabitleme)
`.venv/`	Sanal ortam dizini (kurulduktan sonra oluşur)
`scripts/start.sh`	Servis başlatma betiği
`scripts/stop.sh`	Servis durdurma betiği
`scripts/status.sh`	Servis durum kontrol betiği

03Yapılandırma

Config dosyası

Uygulama yapılandırması config.py içinde tutulur. Sadece üç temel değer vardır: uygulama kökü, dinleme portu ve veritabanı yolu. Tüm değerler config.py'den okunur.

Değişken	Varsayılan değer	Açıklama
`APP_ROOT`	`Path(__file__).resolve().parent.parent`	Uygulama kök dizini (otomatik)
`PORT`	`8021`	Dinleme portu
`DB_PATH`	`APP_ROOT / "data" / "crm.sqlite3"`	SQLite veritabanı dosyası yolu (otomatik)

Not: Port ve DB yolu config.py içinden okunur; ayrı bir ortam değişkeni dosyası kullanılmaz. Sadece bu üç değer vardır.

Port durumu

Çalışma portu8021

DurumAyrılmış · çakışma yok

Dinleme adresihttp://localhost:8021

04Çalıştırma

Bağımlılık listesi (kurulumda otomatik yüklenir)

Paket	Sürüm
fastapi	0.116.2
uvicorn	0.35.0
pydantic	2.11.10

Manuel başlatma

Servis betiği olmadan doğrudan çalıştırmak için (geliştirme/debug):

cd minimax-clean
source .venv/bin/activate
uvicorn src.minimax_clean.main:app --host 127.0.0.1 --port 8021

Çalıştırma notu: uvicorn ile tek worker kullanılır (--workers 1). SQLite için çoklu worker, dosya kilitleme sorunlarına yol açar. Çoklu worker gerekecek olursa veritabanı çözümü ayrıca tasarlanmalıdır.

Servis betikleri

Başlatscripts/start.sh

Durdurscripts/stop.sh

Durumscripts/status.sh

Betikler servis betikleri olarak scripts/ dizininde tutulur ve bu yol sabittir. PID dosyası logs/uvicorn.pid, log dosyası logs/uvicorn.log olarak yazılır.

05Veritabanı

Genel

MotorSQLite 3

Dosya yoludata/crm.sqlite3

KodlamaUTF-8

Kilitleme moduWAL

Şema

Veritabanı şeması database.py içinde tanımlıdır. Uygulama ilk başlatıldığında şema otomatik oluşturulur; ayrıca bir kurulum betiği gerekmez.

Tablo	Açıklama
`musteriler`	Müşteri kayıtları (ad, firma, telefon, e-posta, not, oluşturma zamanı)
`gorevler`	Müşteriye bağlı takip görevleri (başlık, vade, durum, müşteri_id, oluşturma zamanı)

Kayıp/boş DB: Dosya yoksa uygulama ilk başlatıldığında şemayı oluşturur. Veriler silinmişse DB dosyasını yeniden oluşturan uygulama otomatik baştan başlar.

06Hizmet Yönetimi

Betikler

Betik	Yol	Görev
start.sh	`scripts/start.sh`	uvicorn'u arka planda başlatır, PID'yi `logs/uvicorn.pid`'ye yazar
stop.sh	`scripts/stop.sh`	PID dosyasından okuyarak süreci durdurur, PID dosyasını siler
status.sh	`scripts/status.sh`	Süreç ve port durumunu gösterir

Başlatma

./scripts/start.sh

Uygulama 127.0.0.1:8021 adresinde dinlemeye başlar. Başarılı başlatmada status.sh "çalışıyor" durumunu ve portu gösterir.

Durdurma

./scripts/stop.sh

Kanıt: Uygulama durdurulduktan sonra port 8021 boşalır (çakışma yok). status.sh "durduruldu" durumunu gösterir. PID dosyası (logs/uvicorn.pid) temizlenir.

Durum kontrolü

./scripts/status.sh

Süreç PID'sini, dinleme portunu ve genel çalışma durumunu raporlar. Port 8021'in kullanılıp kullanılmadığını gösterir.

07Loglar ve İzleme

Log dosyaları

Dosya	Yol	Açıklama
Uygulama logu	`logs/uvicorn.log`	uvicorn uygulama çıktısı
PID dosyası	`logs/uvicorn.pid`	Çalışan sürecin PID'si

Loglar logs/ dizinine yazılır. Uygulama başlatıldığında log dosyası otomatik oluşur; durdurulduğunda PID dosyası temizlenir, log dosyası izleme için saklanır.

İzleme

Port8021

PID dosyasılogs/uvicorn.pid

Loglogs/uvicorn.log

Zaman dilimiEurope/Istanbul (UTC+3)

Görev vadesi gün çözünürlüğüne sahiptir ve yerel saat (UTC+3) üzerinden değerlendirilir; karşılaştırmalar ISO tarih üzerinden yapılır. Log satırlarındaki tarihler de aynı zaman dilimini yansıtır.

08Kabul Testleri

Açılış testi

Uygulama servis betiğiyle başlatıldığında http://localhost:8021 adresinden erişilebilir olmalıdır. Başarılı açılışta boş veritabanı otomatik oluşturulur ve arayüz yüklenir.

Kanıt: Uygulama servis betiğiyle açıldı, localhost:8021 adresinden erişildi ve boş veritabanı otomatik oluşturuldu.

Kabul koşulları

#	Kabul koşulu	Durum
K-1	Uygulama servis betiğiyle açılır, `localhost:8021`'den erişilebilir, boş veritabanı otomatik oluşturulur	Doğrulandı
K-2	Durdurma sonrası port 8021 boşalır (çakışma yok), PID dosyası temizlenir	Doğrulandı
K-3	Port 8021 ayrılmıştır ve başka bir süreç tarafından kullanılmıyor	Doğrulandı
K-4	Çalıştırma sürümü cfceea7; tam regresyon geçti, prod'da kullanımda	Doğrulandı

Kanıt özeti

Başlatmascripts/start.sh → port 8021 dinlemede

Erişimhttp://localhost:8021 → arayüz yüklendi

Veritabanıdata/crm.sqlite3 otomatik oluşturuldu

Durdurmascripts/stop.sh → port boş, PID temizlendi

Durumscripts/status.sh → durduruldu

Sürümcfceea7 · 06.10.2026 · Prod

Araç erişimi ≠ ürün hatası: Konsolsuz ortamda sayfa açma kanıtı, ayrı bir otomatik tarayıcı aracılığıyla üretilir. Araç erişim engeli, ürün hatasından ayrı değerlendirilir.