Yerel Test ve Kurulum¶

Bu sayfa, DiKAS'ı kendiniz nasıl deneyeceğinizi, yerel olarak nasıl kuracağınızı ve geliştirme için nasıl çalıştıracağınızı gösterir. Entegratörlere, yöneticilere ve geliştiricilere yöneliktir.

DiKAS'ı yerel olarak çalıştırmanın iki yolu vardır:

Seçenek	Uygun olduğu durum	Efor
A — Bir VM'de ISO cihazı	Gerçek kasa donanımındaki gibi gerçekçi bir deneme işletimi	Düşük
B — Geliştirici kurulumu (`dotnet` + `ng`)	API geliştirme, uyarlamalar, hata ayıklama	Daha yüksek

Sadece kasaya hızlıca göz atmak mı istiyorsunuz?

DiKAS'ı yalnızca bağlayıcı olmadan test etmek istiyorsanız, eksiksiz bir kasaya en hızlı yol Seçenek A'dır (bir VM'de ISO). VM olmadan salt bir API/ön yüz demosu için aşağıdaki Demo Kasa uygundur (SQLite + demo verileri, tek bir komut).

Sistem Gereksinimleri¶

Sunucu / VM¶

Seçenek	Minimum	Önerilen
Küçük işletme (1–2 kasa)	2 GB RAM, 2 çekirdek	4 GB RAM, 4 çekirdek
Orta ölçekli işletme (3–5 kasa)	4 GB RAM, 4 çekirdek	8 GB RAM, 4 çekirdek
Büyük işletme (5+ kasa)	8 GB RAM, 4 çekirdek	16 GB RAM, 8 çekirdek

Disk / Sanal Disk¶

Kullanım	Minimum	Önerilen
VM'de ISO cihazı	20 GB (işletim sistemi + veritabanı + demo verileri)	40 GB
Geliştirici kurulumu	SDK/araçlara bağlı olarak yakl. 10–15 GB	20 GB

ISO VM için pratik kural

ISO cihazı için denemeye 2 GB RAM (1–2 kasa) ve 20 GB disk yeterlidir. Birden fazla eşzamanlı kasa veya daha uzun bir deneme işletimi için 4 GB RAM ve üzeri önerilir — yukarıdaki tabloyu esas alın.

Seçenek A: Bir VM'de ISO Cihazı¶

DiKAS cihazı, Arch Linux (archiso) tabanlı, hazır ve önyükleme yapılabilir bir işletim sistemi imajıdır. DikasArch uygulamasını (.NET 10) ve veritabanını zaten birlikte getirir — DiKAS'ı bir işletim sistemi kurmadan gerçekçi koşullar altında test etmek için idealdir.

ISO indirme¶

Güncel ISO imajı (yakl. 500 MB–1 GB, hem UEFI hem de BIOS ile önyükleme yapar) şu adreste bulunur:

https://s3.dikas.de/iso/dikas.iso

Cihaz neyden oluşur?

İmaj, dikasiso deposunda derlenir (sh make.sh). Asıl kasa uygulaması dikasarch'tır (Arch paketi dikasarch10-*.pkg.tar.zst, .NET 10). Test işletimi için bunlardan hiçbirini kendiniz derlemeniz gerekmez — yalnızca hazır ISO'yu indirin.

A.1 — Hyper-V (Windows)¶

Hyper-V, Windows 10/11 Pro ve Windows Server'da yer alır („Hyper-V" özelliğini etkinleştirin).

Adım adım (Hyper-V Yöneticisi, grafik arayüz):

Hyper-V Yöneticisi'ni açın → sağda Yeni → Sanal Bilgisayar.
Nesil 1'i seçin (BIOS önyükleme, archiso ile sorunsuz). Nesil 2 (UEFI) de çalışır — ancak bu durumda Secure Boot devre dışı bırakılmalıdır (ISO, Microsoft Secure Boot anahtarıyla imzalanmamıştır).
Bellek: 2048 MB (veya daha fazla, bkz. sistem gereksinimleri). „Dinamik bellek"i etkin bırakabilirsiniz.
Sanal disk: 20 GB ile yeni bir VHDX oluşturun.
Kurulum seçenekleri: „Önyüklenebilir CD/DVD-ROM'dan yükle" → İmaj dosyası (.iso) → dikas.iso dosyasını seçin.
VM'yi başlatın ve VM'ye bağlanın.

Alternatif olarak PowerShell ile (yönetici olarak):

# Nesil 1 (BIOS) - en basit yol
New-VM -Name "DiKAS" -Generation 1 -MemoryStartupBytes 2GB `
  -NewVHDPath "C:\VMs\DiKAS.vhdx" -NewVHDSizeBytes 20GB
Set-VM -Name "DiKAS" -ProcessorCount 2
Add-VMDvdDrive -VMName "DiKAS" -Path "C:\ISOs\dikas.iso"
Start-VM -Name "DiKAS"

Nesil 2 + Secure Boot

Bir Nesil 2 VM kullanıyorsanız Secure Boot kapalı olmalıdır, aksi halde ISO önyüklenmez:

Set-VMFirmware -VMName "DiKAS" -EnableSecureBoot Off

A.2 — VirtualBox (Windows / macOS / Linux)¶

VirtualBox ücretsizdir ve tüm büyük işletim sistemlerinde çalışır.

Adım adım (grafik arayüz):

Yeni → Ad DiKAS, Tür Linux, Sürüm Arch Linux (64-bit).
Bellek: 2048 MB veya daha fazla.
Disk: „Şimdi bir sanal disk oluştur" → VDI → dinamik → 20 GB.
VM'yi işaretleyin → Değiştir → Depolama → optik sürücüye dikas.iso ISO'sunu yerleştirin.
(İsteğe bağlı) UEFI'yi test etmek istiyorsanız Sistem → Ana kart → EFI'yi etkinleştir — ancak ISO standart BIOS modunda da önyükleme yapar.
VM'yi başlatın.

Alternatif olarak komut satırıyla (VBoxManage):

VBoxManage createvm --name "DiKAS" --ostype "ArchLinux_64" --register
VBoxManage modifyvm "DiKAS" --memory 2048 --cpus 2 --nic1 nat
VBoxManage createhd --filename "DiKAS.vdi" --size 20480
VBoxManage storagectl "DiKAS" --name "SATA" --add sata --controller IntelAhci
VBoxManage storageattach "DiKAS" --storagectl "SATA" \
  --port 0 --device 0 --type hdd --medium "DiKAS.vdi"
VBoxManage storageattach "DiKAS" --storagectl "SATA" \
  --port 1 --device 0 --type dvddrive --medium "dikas.iso"
VBoxManage startvm "DiKAS"

A.3 — Linux Ana Bilgisayarı (KVM/QEMU)¶

Bir Linux ana bilgisayarında (Debian/Ubuntu/Arch) ISO, en kolay şekilde KVM/QEMU ile, isteğe bağlı olarak virt-manager üzerinden rahatça önyükleme yapar.

Sanallaştırmayı kurma:

# Debian / Ubuntu
sudo apt install qemu-kvm libvirt-daemon-system virtinst virt-manager

# Arch / CachyOS
sudo pacman -S qemu-full libvirt virt-install virt-manager

VM oluşturma ve ISO'yu önyükleme (virt-install):

virt-install \
  --name dikas \
  --memory 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/dikas.qcow2,size=20 \
  --cdrom /pfad/zu/dikas.iso \
  --os-variant archlinux \
  --graphics spice

Veya doğrudan QEMU ile (libvirt olmadan):

qemu-img create -f qcow2 dikas.qcow2 20G
qemu-system-x86_64 -enable-kvm -m 2048 -smp 2 \
  -drive file=dikas.qcow2,if=virtio \
  -cdrom dikas.iso -boot d

UEFI'yi test etme (OVMF)

VM'nin UEFI ile önyükleme yapmasını istiyorsanız, virt-install'da --boot uefi ekleyin veya QEMU'da bir OVMF donanım yazılımı belirtin (-bios /usr/share/OVMF/OVMF_CODE.fd). ISO her iki önyükleme modunu da destekler.

Cihazın İlk Başlatılması¶

Önyüklemeden sonra cihaz, DiKAS'ı sanal sistemde kurar/başlatır. Ardından kasaya tarayıcıdan erişilebilir.

YAPILACAK — Cihazın ilk başlatma ayrıntıları

Başlatmadan sonra cihazın tam yerel adresi/portu, sanal diske kurulum akışı ve ilk giriş, bu dokümanın hazırlandığı sırada doğrulanmamıştı ve burada yer tutucu olarak işaretlenmiştir. Lütfen cihaz/dikasiso dokümantasyonundan tamamlayın (ör. „Kasaya http://<VM-IP>:<Port> adresinden erişilebilir, şununla giriş yapın…").

VM'de TSE (USB/IP)¶

DiKAS bir VM'de çalışıyor ve bir donanım TSE'si (Swissbit USB bellek) kullanacaksa, bellek ana bilgisayar (üzerine takılı olduğu bilgisayar) tarafından USB/IP üzerinden VM'ye aktarılır. VM'deki DiKAS, TSE'yi ardından otomatik olarak tanır ve bağlar.

Buna ne zaman ihtiyacım var?

Yalnızca bir VM'de donanım TSE'si (Swissbit) kullanılıyorsa. Bir Cloud-TSE (fiskaly) ile USB aktarımına gerek yoktur — bu tamamen internet üzerinden çalışır. Gerçek kasa donanımında (Mini-PC) TSE belleği doğrudan cihaza takılıdır, USB/IP hiç gerekmez.

1. Ana bilgisayarda (Linux) USB/IP hizmetini başlatma ve TSE'yi paylaşıma açma:

# usbip araçlarını kurma (örnek Debian/Ubuntu)
sudo apt install usbip

# USB/IP sunucusunu başlatma
sudo usbipd -D

# bağlı USB cihazlarını listeleme ve Swissbit TSE'yi bulma (VID:PID 1370:0505)
usbip list -l

# TSE'yi Bus-ID'si üzerinden paylaşıma açma (örn. 1-2)
sudo usbip bind -b 1-2

2. VM'de (DiKAS cihazı) TSE'yi bağlama:

# Ana bilgisayar adresi = VM'nin ağ geçidi (NAT'ta genellikle 10.0.2.2,
# değilse ana bilgisayarın ağdaki IP'si)
sudo usbip attach -r 10.0.2.2 -b 1-2

DiKAS, TSE belleğini Hotplug ile tanır, bağlar ve o andan itibaren belge imzalama için kullanır — başka bir ayar gerekmez. Kasanın TSE ayarlarında TSE bağlı olarak görünür.

3. Daha sonra tekrar çözme (ana bilgisayarda):

sudo usbip unbind -b 1-2

Sürekli işletimde

Üretimde sürekli işletim için gerçek kasa donanımı (doğrudan bağlı TSE belleği olan Mini-PC) veya Cloud-TSE daha sağlam bir seçimdir. USB/IP aktarımı özellikle test ve geçiş kurulumları için uygundur.

Seçenek B: Geliştirici Kurulumu (`dotnet` + `ng`)¶

API geliştirme ve uyarlamalar için arka uç (.NET 10) ve ön yüz (Angular) ayrı ayrı başlatılır.

Ön koşullar:

.NET 10 SDK (dotnet)
Node.js 24 + npm
(isteğe bağlı) veritabanı olarak CouchDB — alternatif olarak SQLite (aşağıya bakın)

Arka ucu başlatma¶

cd Dikas.Api
dotnet build Dikas.Api.Web/Dikas.Api.Web.csproj
dotnet run --project Dikas.Api.Web --urls http://localhost:5015

Arch Linux / CachyOS: Derleme geçici çözümü

Arch tabanlı sistemlerde derleme, NU1101 (arch-x64 AppHost) hatasıyla başarısız olabilir. Bu durumda -p:UseAppHost=false ekleyin:

dotnet build Dikas.Api.Web/Dikas.Api.Web.csproj -p:UseAppHost=false
dotnet run --project Dikas.Api.Web --urls http://localhost:5015 -p:UseAppHost=false

Ön yüzü başlatma¶

cd dikas-next
npm ci
npx ng serve dikas-web --port 4200

Geliştirme sunucusu, /api, /hubs, /rest ve /version'ı otomatik olarak 5015 portundaki arka uca yönlendirir.

Her zaman ön yüz üzerinden test edin

Uygulamayı http://localhost:4200 üzerinden açın (doğrudan 5015'teki arka uç üzerinden değil) — API çağrılarının proxy yönlendirmesi ancak bu şekilde devreye girer.

Demo Kasayı Başlatma¶

Demo Kasa, boş bir veritabanını gerçekçi örnek verilerle (ürünler, masalar, personel, cirolar) doldurur ve kullanılabilir bir kasaya en hızlı yoldur.

SQLite ile minimal demo (tek komut)¶

CouchDB olmadan tam bir gastro demosu — arka uç otomatik olarak bir SQLite dosyası (dikas.db) oluşturur ve içine veri tohumlar:

cd Dikas.Api
env Database__Provider=Sqlite \
    DemoSeed__Mode=gastro \
    ASPNETCORE_ENVIRONMENT=Development \
  dotnet run --project Dikas.Api.Web --urls http://localhost:5015

Ardından ön yüzü başlatın (bkz. Seçenek B) ve tarayıcıda giriş yapın.

Migrasyonsuz

SQLite şeması, başlangıçta otomatik olarak oluşturulur ve senkronize edilir (SqlDbInitService) — herhangi bir veritabanı migrasyonu çalıştırmanız gerekmez.

Demo modları¶

İstenen veri kümesi, DemoSeed__Mode ortam değişkeni ile seçilir:

`DemoSeed__Mode`	Sektör / İçerik
`basic`	Kiosk / fırın (doğrudan satış)
`gastro` (varsayılan)	Masalı restoran
`delivery`	Teslimat servisi
`club`	Disko / kulüp
`full`	Tam donanım — tüm modüller aktif

Giriş¶

Alan	Değer
Kullanıcı	`admin`
Parola	`admin`

Tohumlama yalnızca boş bir veritabanında çalışır

Demo verileri yalnızca boş bir veritabanına işlenir. Yeniden tohumlamak için (ör. başka bir mod) taze bir veritabanına ihtiyacınız vardır:

SQLite: İçerik kök dizinindeki dikas.db dosyasını silin.
CouchDB: yeni bir CouchDb__DatabasePrefix ayarlayın (veya mevcut veritabanlarını silin).

Ardından arka ucu istenen DemoSeed__Mode ile yeniden başlatın.

Yerel API Geliştirme¶

Temel bilgiler¶

	Değer
API taban URL'si	`http://localhost:5015/api/v1/`
Swagger / OpenAPI	`http://localhost:5015/swagger` (yalnızca Debug derlemelerinde)
Sağlık kontrolü	`GET http://localhost:5015/healthz`
Varsayılan veritabanı	`http://localhost:5984` adresinde CouchDB
Alternatif veritabanı	SQLite — Env `Database__Provider=Sqlite` (içerik kök dizininde `dikas.db` dosyası)

Kimlik Doğrulama (JWT)¶

API, JWT Bearer token kullanır. Bir token, giriş uç noktası üzerinden istenir ve 480 dakika (8 saat) geçerlidir.

1. Token isteme:

curl -s http://localhost:5015/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}'

Token, yanıtta data.accessToken altında bulunur. Bir kabuk (shell) değişkenine aktarma:

TOKEN=$(curl -s http://localhost:5015/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["accessToken"])')

2. Kimlik doğrulamalı bir çağrı yürütme — token'ı Authorization başlığında gönderin:

curl -s http://localhost:5015/api/v1/articles \
  -H "Authorization: Bearer $TOKEN"

3. Sağlık kontrolü (girişsiz):

curl http://localhost:5015/healthz

Uç noktaları keşfetme

Tüm kullanılabilir uç noktaları, parametreleriyle ve örnek yanıtlarıyla birlikte http://localhost:5015/swagger (Debug derlemesi) adresinde etkileşimli olarak bulabilirsiniz. Açıklayıcı bir genel bakışı ayrıca REST API sayfası sunar.

Token'ın süresi mi doldu?

Token 8 saat sonra sona ererse, tarayıcıdaki uygulama durumu tuhaf davranabilir. Basitçe çıkış yapıp yeniden giriş yapın ya da yeni bir token isteyin.

Sonraki Adımlar¶

Kurulum ve Dağıtım — ISO üzerinden üretim kurulumu
Veritabanı — CouchDB'ye karşı SQLite, yapılandırma
REST API — eksiksiz API dokümantasyonu
API Referansı (Swagger) — etkileşimli uç nokta genel bakışı