KBS-Sync

English overview

EGM KBS portalı için yerel ağda çalışan otel kimlik bildirim otomasyonu.

Mobil pasaport taraması → yerel agent → Chrome eklentisi → kbs.egm.gov.tr üzerinde otomatik check-in / check-out.

Veriler otelde kalır: kimlik kayıtlarının şifreli ana kopyası resepsiyon bilgisayarındaki agentta, yerel replikası eşleştirilmiş telefonların korumalı uygulama alanında tutulabilir. KBS şifreleri resepsiyon bilgisayarından çıkmaz; bulut sunucusu yoktur.

Important

Bu bağımsız bir topluluk projesidir; Emniyet Genel Müdürlüğü/KBS ile bağlantılı, onaylı veya desteklenen resmî bir ürün değildir. Yalnızca yetkili hesap ve verilerle kullanın. Kurum kuralları, KVKK ve diğer yükümlülükleri değerlendirmek sistemi işleten tesisin sorumluluğundadır.

Otelci entegrasyon rehberi (baştan sona): docs/HOTEL_INTEGRATION_GUIDE.md

---

Özellikler

• Merkezi tarama arşivi — Flutter cihazları Companion v4 QR ile eşleşir; taramalar benzersiz/idempotent biçimde agentta kalıcı tutulur ve mobil arşivler buradan güncellenir
• Agent kontrollü KBS otomasyonu — Check-in, check-out ve oda değişimi; observe-before-actuate FSM ile allowlist'li KBS API çağrıları kullanılır
• Manuel check-in — TC / pasaport ile resepsiyondan doğrudan giriş
• Aktif konaklayanlar — KBS listesinden çekilir; çıkış tek tıkla kuyruğa alınır
• Yeniden deneme & kurtarma — Oturum düşmesi, grid doğrulama, işlem geçmişi
• Şifreli yerel depolama — Agent SQLite + AES; eklenti ayarları Chrome storage

---

Mimari

flowchart LR
  Mobile["Mobil tarayıcı\n(Flutter)"]
  Agent["Go Agent\n:8080 loopback + :8443 TLS"]
  Ext["Chrome MV3\nEklenti"]
  KBS["kbs.egm.gov.tr"]

  Mobile -->|"TLS + pinned cert\nCompanion v4"| Agent
  Agent <-->|"HTTP + WebSocket\nBrowser Bridge v4"| Ext
  Ext -->|"owned tab + login DOM\nsame-origin kbs.api"| KBS

Loading

Bileşen	Dizin	Açıklama
Mobil companion	apps/id-scanner/	Flutter (Android) MRZ tarama + kuyruk/konaklayanlar + agenttan yenilenen yerel arşiv; Companion v4 QR ile eşleşir (docs/mobile/COMPANION_API.md)
Yerel Agent	agent/	Go HTTP/WebSocket sunucusu, şifreli merkezî SQLite tarama arşivi ve otomasyon kuyruğu
Chrome Eklentisi	extension/	React MV3 paneli + Browser Bridge v4; owned tab, login DOM'u ve same-origin KBS API taşıması
Otomasyon motoru	agent/internal/orchestrator/	Kalıcı FSM, observation, actuation, retry ve recovery kararları
Kurulum scriptleri	scripts/	Windows / Linux production paketleri

---

Production kurulumu

Son kullanıcılar mümkünse GitHub Releases sayfasındaki paketi ve yanında yayımlanan SHA-256 dosyasını kullanmalıdır. Etiketli yayınlar Windows EXE, Linux tar.gz, eklenti ZIP ve Android APK'larını içerir. Kaynaktan paket üretmek isteyenler aşağıdaki akışları izleyebilir.

Windows (otel PC — önerilen)

Tek EXE hem agent hem Chrome eklentisini günceller:

chmod +x scripts/build-windows-installer.sh
./scripts/build-windows-installer.sh

Çıktı: dist/KBS-Sync-Update-X.Y.Z.exe — otel PC'de çift tıklayın, ardından Chrome'da eklentiyi Yeniden yükle.

sudo kullanmayın. Eski sudo build dist/’i root yapar → Inno Setup Error 5 Access denied. Düzeltme: sudo chown -R $(whoami):$(whoami) dist agent/dist

→ Kurulum: docs/WINDOWS_HOTEL_SETUP.md
→ Güncelleme: docs/WINDOWS_UPDATE.md

Linux (otel PC)

chmod +x scripts/build-linux-installer.sh
./scripts/build-linux-installer.sh

Çıktı: dist/KBS-Sync-Linux-X.Y.Z.tar.gz — etiketli yayınlarda SHA256SUMS-LINUX.txt ile birlikte.

Otel bilgisayarında:

tar -xzf KBS-Sync-Linux-X.Y.Z.tar.gz
cd KBS-Sync-Linux-X.Y.Z && ./install.sh

Agent systemd --user servisi olarak çalışır; terminal kapansa da ayakta kalır.

→ Ayrıntılı rehber: docs/LINUX_HOTEL_SETUP.md

Chrome eklentisi

Etiketli temiz yayınlar KBS-Sync-Extension-X.Y.Z.zip paketini ve SHA256SUMS-EXTENSION.txt doğrulama dosyasını içerir. ZIP'i açın ve çıkan klasörü Chrome/Edge'de Paketlenmemiş yükle ile seçin. Bu paket mağaza imzalı bir .crx değildir.

Kurulum paketleri de eklentiyi extension/dist olarak birlikte getirir. Geliştirme veya elle derlemede:

cd extension && npm ci && npm run build

Chrome → chrome://extensions → Geliştirici modu → Paketlenmemiş yükle → extension/dist (veya kurulumdaki extension klasörü).

Mobil MRZ tarayıcı (Android)

Etiketli temiz yayınlar çoğu cihaz için universal APK'yı, mimariye özel APK'ları ve SHA256SUMS-ANDROID.txt dosyasını içerir. APK'lar release anahtarıyla imzalanır; debug imzalı paket yayın akışında reddedilir.

cd apps/id-scanner
./scripts/build_apk_release.sh

APK, kalite kapısı ve sideload: apps/id-scanner/README.md.

---

İlk çalıştırma

Otel kurulumu, KBS ayarları, mobil eşleştirme ve günlük iş akışları:

→ docs/HOTEL_INTEGRATION_GUIDE.md

Geliştirici doğrulama komutları: docs/BUILD.md

Production imzalama, kabul ve rollback kapıları: docs/PRODUCTION_RELEASE.md.

---

Geliştirme

Gereksinimler

• Go 1.26+ (CGO açık — SQLite için GCC gerekir)
• Node.js 20.19+
• Chrome veya Edge
• Flutter 3.44+ (yalnızca mobil tarayıcı için)

Hızlı başlangıç

# Terminal 1 — agent + eklenti derlemesi
./dev.sh

# veya ayrı ayrı:
# cd agent && go run ./cmd/kbs-agent/ --no-tray
# cd extension && npm ci && npm run dev

# Mobil (ayrı cihaz / emülatör)
cd apps/id-scanner && fvm flutter run # veya: flutter run

extension/dist klasörünü Chrome'da yükleyin; araç çubuğu simgesinden panele girin.

Testler

(cd extension && npm test)
(cd agent && go test ./...)
./scripts/check-publication.sh
(cd apps/id-scanner && ./scripts/verify.sh)

---

Mobil entegrasyon

Eklenti Eşleştirme ekranında Companion Protocol v4 QR üretir (kind: kbs-sync-pairing, v: 4, protocolVersion: 4). Eski v1/v2/v3 eşleştirmeleri geçersizdir ve yeniden QR eşleştirmesi gerekir.

Kaynak	Açıklama
docs/mobile/QR_PAIRING_BRIEF.md	Flutter ekibi için tam sözleşme
agent/contracts/companion-v4/scan-request.schema.json	Kanonik JSON Schema 2020-12 sözleşmesi
docs/mobile/ODA_NUMARASI_KONTROL_BRIEF.md	Oda numarası doğrulama

POST https://{ip}:8443/api/v4/scan
Authorization: Bearer {token}
Content-Type: application/json

Gövde düz değil, kanonik v4 yapısıdır: schemaVersion, identity, stay, capture ve isteğe bağlı extensions. Oda stay.roomNumber alanındadır.

Agent GET /api/v4/scans?includeArchived=true ile merkezi arşivi sunar. Canlı kuyruktan kaldırma kaydı silmez; yalnız otomasyon görünürlüğünden arşivler. Zaman tabanlı otomatik kimlik silme uygulanmaz.

---

Veri konumları

Platform	Agent verisi	Log
Windows	%APPDATA%\KBS-Sync\	kbs-sync.log
Linux	~/.config/kbs-sync/	kbs-sync.log

Bu dizinlerdeki encryption.key, kbs_local.db ve log dosyalarını asla repoya veya paylaşıma koymayın.

---

Dokümantasyon

Konu	Dosya
Otel entegrasyon (baştan sona)	docs/HOTEL_INTEGRATION_GUIDE.md
Derleme & paketleme	docs/BUILD.md
Windows otel kurulumu	docs/WINDOWS_HOTEL_SETUP.md
Windows güncelleme	docs/WINDOWS_UPDATE.md
Linux otel kurulumu	docs/LINUX_HOTEL_SETUP.md
KBS browser DOM/API entegrasyonu	docs/automation/XPATH_INTEGRATION.md
Browser Bridge v4	docs/BROWSER_BRIDGE_PROTOCOL_V4.md
Hata kurtarma matrisi	docs/automation/RECOVERY_DECISION_MATRIX.md
Mimari	docs/ARCHITECTURE.md
Gizlilik ve veri akışı	docs/PRIVACY_AND_DATA.md
Merkezi tarama arşivi	docs/CENTRAL_SCAN_ARCHIVE.md
Test verisi ve kişisel veri temizliği	docs/DATA_SANITIZATION.md

---

Güvenlik notları

• Yönetim ve KBS kimlik bilgisi uçları yalnızca 127.0.0.1:8080 üzerinde çalışır
• Mobil trafik TLS 1.3, sertifika sabitleme ve cihaz bazlı bearer token kullanır
• KBS bilgileri ve kimlik taşıyan agent kayıtları AES-GCM ile şifrelenir; Windows anahtarı DPAPI ile korunur
• Android veritabanı credential-encrypted uygulama alanındadır; yedekleme ve direct-boot erişimi kapalıdır
• Mobil cihazlardan gelen kimlik kayıtlarının benzersiz ve şifreli ana kopyası agentta kalıcı tutulur; eşleşmiş mobil cihazlar arşivlerini agenttan günceller
• Production paketlerini imzalı dağıtım kanallarından paylaşın; kaynak kodu public ise release artifact'ları GitHub Releases üzerinden verin

---

Sürüm

Tek kaynak: VERSION. Güncelleme paketi: ./scripts/build-windows-installer.sh → dist/KBS-Sync-Update-x.y.z.exe (--checksums ile SHA256SUMS).

Windows otelde: USB/e-posta ile EXE'yi çalıştırın → chrome://extensions → Yeniden yükle. Ayrıntı: docs/WINDOWS_UPDATE.md.

Sorun veya portal değişikliği için önce agent logunu (kbs-sync.log), Browser Bridge bağlantısını ve agent/internal/kbs/konaklayan/ endpoint sözleşmesini kontrol edin. kbs-steps.json yalnız login/TOTP ve kalan DOM primitifleri için ilgili ilk kaynaktır.

---

Topluluk ve lisans

• Katkı akışı: CONTRIBUTING.md
• Güvenlik bildirimi: SECURITY.md
• Destek: SUPPORT.md
• Değişiklik günlüğü: CHANGELOG.md

Kod MIT Lisansı ile sunulur. Depodaki üçüncü taraf bağımlılık ve varlıkların kendi lisansları ayrıca geçerlidir; bkz. THIRD_PARTY_NOTICES.md. Yazılım garanti verilmeden sunulur; gerçek KBS işlemlerini üretimde kullanmadan önce kontrollü ortamda doğrulayın.