IQV Support

IQV Support, IQVizyon destek süreçlerinin uçtan uca yürütüldüğü destek talebi yönetim sistemidir: React + Vite + Ant Design + IQVizyon UI tabanlı bir yönetim paneli (dashboard/), sahadan QR ile açılan bağımsız bir talep formu (qr-form/) ve Express + MongoDB tabanlı bir REST API (backend/) içerir.

Sistemin kapsamı:

• Destek talepleri — talep oluşturma, konu/firma eşleştirme, başlangıç ve öngörü zamanı, çözüm kaydı, resim/video eki (MinIO).
• QR destek formu — panelde üretilen kısa ömürlü QR kodu okutulduğunda açılan, yalnızca tek bir firmaya kilitli, oturum açmayı gerektirmeyen form.
• Firma ve kullanıcı işlemleri — firma bazlı talep özetleri, kullanıcı oluşturma/güncelleme/silme ve izin (permission) bazlı yetkilendirme.
• Bildirimler — talep oluşturulduğunda Telegram, talep çözüldüğünde e‑posta; çözüm anında Gemini ile otomatik analiz zenginleştirmesi. Üçü de ikincil/best-effort'tur ve yapılandırılmadıklarında sessizce atlanır.

Bu README, projeyi production seviyesinde tek komutla kurmak, güncellemek ve kaldırmak için gereken operasyonel özeti verir. Mimari, API ve CI gibi ayrıntılı geliştirici dokümantasyonu için bkz. Documentation.

Dokümantasyon / Documentation

Tam dokümantasyon (TR/EN) MkDocs Material ile üretilir ve GitHub Pages'te yayınlanır: https://iqvizyon-development.github.io/iqv-react-dashboard/

pip install -r requirements-docs.txt
mkdocs serve            # http://127.0.0.1:8000
mkdocs build --strict   # kırık iç bağlantı / eksik nav hedefi = hata

Kaynak: docs/ (Türkçe *.md, İngilizce *.en.md) ve mkdocs.yml.

Components

Component	Technology	Location
Dashboard (Frontend)	React 18 + TypeScript + Vite 4 + Ant Design 5 + IQVizyon UI + Redux Toolkit + Tailwind CSS 3	dashboard/
QR Form (Frontend)	React 18 + TypeScript + Vite 4, bağımsız bundle, base: '/q/'	qr-form/
Backend (API)	Node.js 22 + Express 4 (CommonJS), JWT + bcrypt, resmî mongodb sürücüsü	backend/
Database	MongoDB 7 — Docker modunda konteyner, Native modda harici servis	docker-compose.yml (mongo), .env → MONGODB_URI
Object Storage	MinIO (talep ekleri: resim, video ve doküman)	.env → MINIO_*, backend/src/config/minio.js
Reverse Proxy	nginx 1.27 — tek origin: /, /q/, /api/, /health	docker/nginx.conf, docker/web.Dockerfile
Deployment Scripts	Bash (Linux) + PowerShell (Windows), Docker ve Native modları	scripts/linux/, scripts/windows/, scripts/lib/
Documentation Site	MkDocs + Material for MkDocs	docs/, mkdocs.yml, requirements-docs.txt
CI/CD	GitHub Actions — IQV Support CI (56 kalite kapısı, Q01–Q56)	.github/workflows/ci.yml, scripts/ci/

Dashboard ekranları

Ekran	Route	Açıklama
Destek	/support	Firma özet tablosu ve talep listesi
Talep	/talep	Yeni destek talebi + QR üretimi
Saha Talebi	/saha-talebi	Saha ihtiyaç/talep formu — Ürün/Uygulama, Konu, Gereksinim, Beklenen Fayda ve ek dosya
Rapor	/rapor	Rapor
Kullanıcı	/users	Kullanıcı yönetimi
Talep detayı	/show-talep?id=<ticketId>	Kayıt detayı ve güncelleme (sidebar'da yer almaz)

Saha Talebi kayıtları ayrı bir koleksiyona yazılmaz: normal taleplerle aynı support-record koleksiyonuna gider ve source: "field-request" alanıyla ayırt edilir. Bu nedenle Destek listesinde, sayaçlarda ve Rapor ekranında ek bir değişiklik olmadan görünürler.

API Dokümantasyonu / Swagger

Backend, ayrı bir sunucu gerektirmeden Swagger UI + OpenAPI 3.0.3 JSON sunar (kaynak: backend/src/docs/openapi.js, backend/src/routes/docs.routes.js) — ayrıntılı sözleşme açıklaması için docs/backend-api.md sayfasına, uçları tarayıcıdan denemek için ise aşağıdaki adreslere bakın:

• Swagger UI: https://support.iqvizyon.com/api-docs/
• OpenAPI JSON: https://support.iqvizyon.com/openapi.json

Yerel geliştirmede (npm run dev, backend BACKEND_PORT varsayılanı 3001):

• Swagger UI: http://localhost:5173/api-docs (Vite proxy) veya http://localhost:3001/api-docs (doğrudan backend)
• OpenAPI JSON: http://localhost:5173/openapi.json veya http://localhost:3001/openapi.json

Requirements

Component	Docker mode	Native mode
Docker Engine 24+ + Compose v2	✅ gerekli	—
Node.js 20+ + npm	—	✅ gerekli
systemd (Linux)	—	✅ gerekli
PM2 (Windows)	—	✅ gerekli — install script'i kurar
Erişilebilir bir MongoDB örneği	konteyner içinde ayağa kalkar	✅ gerekli (harici)
git	güncelleme için	güncelleme için
Python 3 + pip	—	yalnızca dokümantasyon sitesi için (mkdocs)

Native kurulum MongoDB kurmaz: .env içindeki MONGODB_URI çalışan bir sunucuyu göstermelidir. Docker kurulumu MongoDB'yi kendi konteynerinde ayağa kaldırır ve veriyi iqv-support-mongo-data adlı kalıcı volume'de tutar.

MinIO bu depo tarafından kurulmaz; ekler yalnızca .env içindeki MINIO_* değerleri doldurulduğunda yüklenir.

Quick Start

# Linux — Docker
./scripts/linux/docker/install.sh

# Windows — Docker
.\scripts\windows\docker\install.ps1

Bu tek komut: ön koşulları doğrular, .env yoksa .env.example üzerinden üretir ve güvenli bir JWT_SECRET oluşturur, compose yapılandırmasını doğrular, image'ları derler, servisleri başlatır ve /health ile gerçek bir sağlık kontrolü yapar. Kurulum sonrasında elle docker compose up, npm install veya npm run build çalıştırmak gerekmez.

Kurulum bittiğinde:

• Arayüz: http://localhost:8080
• QR formu: http://localhost:8080/q/
• Sağlık: http://localhost:8080/health

Installation

IQV Support dört ortamda kurulabilir. Script'ler bulundukları konumdan repo kökünü kendileri hesaplar; hangi dizinden çağrıldıkları önemli değildir.

scripts/
├── linux/
│   ├── docker/   install.sh  update.sh  uninstall.sh
│   └── native/   install.sh  update.sh  uninstall.sh
└── windows/
    ├── docker/   install.ps1 update.ps1 uninstall.ps1
    └── native/   install.ps1 update.ps1 uninstall.ps1

Linux — Docker

./scripts/linux/docker/install.sh
./scripts/linux/docker/update.sh
./scripts/linux/docker/uninstall.sh

Kurulan yapı: mongo + backend + web (nginx) konteynerleri, iqv-support network'ü ve iqv-support-mongo-data volume'ü.

Linux — Native

./scripts/linux/native/install.sh
./scripts/linux/native/update.sh
./scripts/linux/native/uninstall.sh

Kurulan yapı: iqv-support-backend.service (Node, :3001) ve iqv-support-web.service (bağımlılıksız statik sunucu, :IQV_HTTP_PORT) systemd unit'leri. Dashboard ve QR formu tek kök altında birleştirilir (var/www ve var/www/q).

Windows — Docker

.\scripts\windows\docker\install.ps1
.\scripts\windows\docker\update.ps1
.\scripts\windows\docker\uninstall.ps1

Windows — Native

.\scripts\windows\native\install.ps1
.\scripts\windows\native\update.ps1
.\scripts\windows\native\uninstall.ps1

Kurulan yapı: PM2 üzerinde iqv-support-backend ve iqv-support-web süreçleri; yeniden başlatma sonrası otomatik açılış yerleşik schtasks göreviyle sağlanır.

Dry run (--check / -Check)

Her giriş noktası, hiçbir değişiklik yapmadan ne yapacağını raporlayan bir kuru çalışma moduna sahiptir:

./scripts/linux/docker/install.sh   --check
./scripts/linux/docker/uninstall.sh --check --purge

.\scripts\windows\native\update.ps1     -Check
.\scripts\windows\docker\uninstall.ps1  -Check -Purge

Bu modda dosya oluşturulmaz/silinmez, image build edilmez, servis başlatılmaz/durdurulmaz, git fetch/git merge çalışmaz; yalnızca ön koşullar ve uygulanacak adımlar listelenir. Çıkış kodu her zaman 0'dır. CI de kurulum script'lerini bu modda çalıştırıp yan etkisizliğini ölçer.

Update

Her update script'i aynı akışı izler:

mevcut sürümü yazdır → git status ile çalışma ağacını doğrula →
git fetch + git merge --ff-only → bağımlılıkları kur / image'ları üret →
servisleri yeniden başlat → gerçek health check → güncel sürümü yazdır

Güncelleme veri kaybettirmez: git reset --hard ve git clean -fd kullanılmaz. Kaydedilmemiş değişiklik varsa script durur ve git commit veya git stash önerir. Fast-forward mümkün değilse birleştirme denenmez, hata verilir.

[VERSION] Current Version : 1.1.0
[VERSION] Latest Version  : 1.2.0
[INFO]    Updating...
[VERSION] Updated Version : 1.2.0

Uninstall

Varsayılan kaldırma kalıcı müşteri verisini korur:

./scripts/linux/docker/uninstall.sh            # konteyner + network + image
./scripts/linux/docker/uninstall.sh --purge    # + MongoDB volume (GERİ ALINAMAZ)

.\scripts\windows\docker\uninstall.ps1
.\scripts\windows\docker\uninstall.ps1 -Purge

Native kurulumlarda --purge / -Purge yalnızca node_modules ve .env dosyasını siler; MongoDB harici bir servis olduğu için veritabanına hiçbir modda dokunulmaz.

Kaldırma işlemleri yalnızca iqv-support ön ekli kaynakları hedefler. docker system prune, docker volume prune, global npm cache clean veya pm2 delete all gibi makinedeki başka projeleri etkileyecek komutlar kullanılmaz; CI bunu statik olarak da doğrular (Q47).

Version Management

Tek doğruluk kaynağı repo kökündeki VERSION dosyasıdır (şu an 1.1.0). Script'ler sürümü yalnızca buradan okur ve Docker image etiketleri bu değerden üretilir (iqv-support-backend:<VERSION>, iqv-support-web:<VERSION>).

package.json dosyalarındaki sürümler VERSION ile aynı olmak zorundadır; CI bunu zorunlu bir kapı olarak doğrular (Q02). Sürüm yükseltirken dört dosya birlikte güncellenir:

VERSION
package.json
backend/package.json
dashboard/package.json
qr-form/package.json

Configuration

Depoda tek bir .env dosyası vardır ve repo kökündedir; dashboard/.env veya backend/.env yoktur.

• backend/, dosyayı kendi konumundan çözülen mutlak bir yolla okur (backend/src/config/env.js), bu yüzden hangi dizinden başlatıldığı önemli değildir.
• dashboard/ ve qr-form/, Vite'ın envDir seçeneğiyle aynı kök dosyayı okur. Bundle'a yalnızca VITE_ önekli değişkenler girer; MONGODB_URI, JWT_SECRET, MINIO_SECRET_KEY gibi değerler frontend'e asla dahil olmaz. CI bunu sentinel değerlerle gerçekten ölçer (Q32).

cp .env.example .env

Sık kullanılan değişkenler (tam liste ve açıklamalar için .env.example):

Variable	Used by	Purpose
BACKEND_HOST / BACKEND_PORT	backend	API sunucusunun dinlediği adres (varsayılan 0.0.0.0:3001)
MONGODB_URI / MONGODB_DATABASE	backend	MongoDB bağlantısı ve veritabanı adı (iqvizyon)
JWT_SECRET / JWT_EXPIRES_IN	backend	Oturum imzalama sırrı ve süresi (varsayılan 12h)
FRONTEND_ORIGIN	backend	CORS izin listesi (virgülle ayrılmış)
SUPPORT_QR_TTL_MINUTES	backend	QR oturumunun geçerlilik süresi
MINIO_*	backend	Ek yükleme hedefi; boşsa yükleme devre dışı kalır
TELEGRAM_* / SMTP_* / GEMINI_*	backend	Bildirim ve AI zenginleştirme; boşsa sessizce atlanır
IQV_HTTP_PORT	deployment	Uygulamanın dışa açık HTTP portu
IQV_PUBLIC_ORIGIN	deployment	Tarayıcının uygulamayı açtığı genel adres
MONGODB_URI_DOCKER	deployment	Yalnızca Docker modunda backend'in gördüğü MongoDB adresi
VITE_API_BASE_URL	dashboard, qr-form	API taban adresi (tek origin kurulumunda /api/v1)
VITE_QR_FORM_BASE_URL	dashboard	QR bağlantısının üretildiği taban adres

Ayrıntı: docs/configuration.md.

Ports

Port	Variable	Description
8080	IQV_HTTP_PORT	Uygulamanın dışa açık tek HTTP portu
3001	BACKEND_PORT	Backend API — Docker modunda yalnızca konteyner ağı içinde
27017	—	MongoDB — Docker modunda dışarı açılmaz
5173 / 5174	—	Yalnızca geliştirme: dashboard ve qr-form Vite sunucuları

Docker kurulumunda nginx tek origin sunar: / → dashboard, /q/ → qr-form, /api/ ve /health → backend, /nginx-health → yalnızca web katmanı.

Health Check

Install ve update "konteyner ayakta" ile yetinmez; gerçek HTTP kontrolü yapar ve başarısızlıkta kurulumu başarısız sayar.

curl -i http://localhost:8080/health
# 200 {"status":"ok","database":"connected"}
# 503 {"status":"error","database":"disconnected"}

Yanıt gövdesi bağlantı dizesi veya kimlik bilgisi içermez. Docker modunda ayrıca GET /nginx-health ile web katmanı ayrıca doğrulanır.

API

Tüm uçlar /api/v1 altındadır; /health kök seviyededir. Kimlik doğrulama Authorization: Bearer <JWT> başlığıyla yapılır ve her uç izin (permission) bazlı korunur.

Method	Path	Permission
POST	/api/v1/auth/login	— (herkese açık)
GET	/api/v1/support/organizations	support.read | ticket.read | report.read
GET	/api/v1/support/subjects	yukarıdakiler | support.qr.read
POST	/api/v1/support/subjects	ticket.create
GET	/api/v1/support/tickets	support.read | ticket.read | report.read
POST	/api/v1/support/tickets	ticket.create
POST	/api/v1/support/field-requests	ticket.create
PUT	/api/v1/support/tickets/:id	ticket.create
POST	/api/v1/support/qr-sessions	ticket.create
POST	/api/v1/support/qr-sessions/resolve	— (QR kodu ile)
POST	/api/v1/support/files/upload	ticket.upload | ticket.create
GET	/api/v1/users, /api/v1/users/:id	users.read
POST	/api/v1/users	users.create
PATCH	/api/v1/users/:id	users.update
DELETE	/api/v1/users/:id	users.delete
GET	/health	—

Ayrıntı: docs/backend-api.md.

Continuous Integration

Depoda iki GitHub Actions workflow'u vardır ve görevleri kesin olarak ayrılmıştır. Bu ayrım bilinçlidir: bir doküman değişikliği pahalı kod pipeline'ını, bir kod değişikliği de GitHub Pages yayınını gereksiz yere tetiklemez. İki workflow ayrı concurrency grubu kullanır (iqv-support-ci-* / iqv-support-docs-*), bu yüzden birbirlerini iptal etmezler.

Workflow	Dosya	Sorumluluğu
IQV Support CI	.github/workflows/ci.yml	Uygulama kodu: 56 kalite kapısı (Q01–Q56), Quality Gate ve kalite raporu
IQV Support Docs	.github/workflows/docs.yml	Yalnızca dokümantasyon: MkDocs strict build + GitHub Pages dağıtımı

IQV Support CI

Her push ve pull_request (main) bu workflow'u tetikler; docs/**, mkdocs.yml, requirements-docs.txt ve .github/workflows/docs.yml paths-ignore ile hariç tutulur. Pipeline hiçbir yere deploy etmez ve hiçbir registry'ye image push etmez; izinleri salt okunurdur (permissions: contents: read).

Repository / Backend / Frontend / Docker / Linux Scripts / Windows Scripts
                              │
                            Smoke
                              │
                        Quality Gate

Job	Runner	Gates
Repository	ubuntu-latest	Q01–Q11
Backend	ubuntu-latest (+ mongo:7 servisi)	Q12–Q21
Frontend	ubuntu-latest	Q22–Q33
Docker	ubuntu-latest	Q34–Q43
Linux Scripts	ubuntu-latest	Q44–Q50
Windows Scripts	windows-latest	Q51–Q52
Smoke	ubuntu-latest	Q53–Q56
Quality Gate	ubuntu-latest	rapor + strict gate

Smoke, Frontend job'unun ürettiği support-dashboard-dist / support-qr-form-dist artifact'lerine bağlıdır (needs: [frontend]). Quality Gate diğer yedi job'un tamamına bağlıdır ve if: always() ile çalışır: bir job başarısız olsa bile rapor üretilir.

Sonuç iqv-support-quality-report artifact'i olarak indirilebilir (REPORT.html, REPORT.md, REPORT.json, QUALITY.svg) ve aynı özet Actions ekranındaki Job Summary bölümünde görünür.

Quality gate (strict, soft gate yok): Critical > 0 veya Blocking Error > 0 ise sonuç skor ne olursa olsun FAILED'dir. Zorunlu bir kapı (build, typecheck, sözdizimi, Docker build, compose doğrulaması) atlanamaz; sonucu üretilmemiş bir kapı FAILED sayılır. Gerçek bir test paketi yoksa kapı dürüstçe SKIPPED — test suite not defined raporlanır.

Aynı kapılar yerelde de çalıştırılabilir:

npm run ci:check                          # ortamda koşabilecek gruplar
npm run ci:check -- --groups repo,backend # seçili gruplar
npm run ci:check -- --all                 # docker + windows dahil hepsi

Ayrıntı: docs/development/ci.md · English.

IQV Support Docs

Yalnızca dokümantasyon değiştiğinde çalışır (paths: docs/**, mkdocs.yml, requirements-docs.txt, .github/workflows/docs.yml). Bu workflow'da frontend build, backend build, Docker build, k6, uygulama testleri, kurulum script'leri ve Quality Gate yoktur.

MkDocs Build  →  Deploy to GitHub Pages

Job	Runner	Görevi
MkDocs Build	ubuntu-latest	requirements-docs.txt kurulumu, mkdocs build --strict, Pages artifact'i
Deploy to GitHub Pages	ubuntu-latest	actions/deploy-pages — yalnızca main'e push'ta

Pull request'lerde yalnızca build çalışır; hiçbir şey yayınlanmaz. Yazma izinleri (pages: write, id-token: write) yalnızca deploy job'unda, job seviyesinde verilir ve environment: github-pages kullanılır.

Documentation

Dokümantasyon sitesi MkDocs + Material for MkDocs ile üretilir ve main'e push'ta .github/workflows/docs.yml tarafından GitHub Pages'e yayınlanır.

pip install -r requirements-docs.txt
mkdocs serve                # http://127.0.0.1:8000
mkdocs build --strict       # kırık bağlantıda hata verir

Site iki dillidir (mkdocs-static-i18n, suffix modu): Türkçe varsayılan dildir ve site kökünde yayınlanır, İngilizce /en/ altındadır. <sayfa>.en.md dosyası varsa İngilizce sürüm olarak kullanılır, yoksa Türkçe içerik gösterilir.

Page	Content
docs/index.md	Genel bakış ve hızlı başlangıç
docs/architecture.md	Bileşenler, veri akışı, MongoDB koleksiyonları, yetkilendirme
docs/configuration.md	.env katmanları, portlar, gizli değer kuralları
docs/backend-api.md	REST API sözleşmesi ve izin matrisi
docs/installation/	Dört ortam için kurulum, güncelleme, kaldırma
docs/development/ci.md	İki workflow ayrımı, CI mimarisi, 56 kalite kapısı, puanlama
docs/development/ci.en.md	Aynı sayfanın İngilizcesi (/en/development/ci/)
docs/troubleshooting.md	Sık karşılaşılan hatalar ve çözümleri

Troubleshooting

Symptom	Resolution
Docker daemon calismiyor	Linux: sudo systemctl start docker · Windows: Docker Desktop'ı başlatın
permission denied ... docker.sock	sudo usermod -aG docker $USER, sonra oturumu yenileyin
... running scripts is disabled (Windows)	Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
Port kullanımda	.env → IQV_HTTP_PORT değerini değiştirip install'ı tekrar çalıştırın
/health 503 dönüyor	MongoDB erişilemiyor — Docker: docker compose logs mongo, Native: .env → MONGODB_URI
Calisma agacinda kaydedilmemis degisiklikler var	git commit veya git stash yapıp update'i tekrarlayın
Hizli ileri sarma (fast-forward) mumkun degil	git pull --rebase ile elle birleştirin
Ekler yüklenmiyor	.env → MINIO_* değerleri boş; MinIO yapılandırılmadan yükleme devre dışıdır

Loglar — Docker: docker compose logs -f backend · Linux native: journalctl -u iqv-support-backend -f · Windows native: pm2 logs iqv-support-backend.

Ayrıntı: docs/troubleshooting.md.

Developer Mode

# Backend  -> http://localhost:3001
cd backend && npm install && npm run dev

# Dashboard -> http://localhost:5173
cd dashboard && npm install && npm run dev

# QR form   -> http://localhost:5174/q/
cd qr-form && npm install && npm run dev

Kalite komutları:

cd backend   && npm run lint && npm test          # ESLint + node:test
cd dashboard && npm run typecheck && npm run lint && npm run prettier
cd qr-form   && npm run typecheck
npm run ci:check                                   # depo genelinde kalite kapıları

Backend derleme adımı yoktur: CommonJS JavaScript doğrudan çalıştırılır (node src/server.js). Dashboard ve qr-form tsc && vite build ile derlenir.

Directory Structure

.
├── .github/workflows/ci.yml   # IQV Support CI (56 kalite kapısı)
├── backend/                   # Express REST API (CommonJS)
│   ├── src/                   # config, routes, controllers, services, repositories
│   ├── scripts/               # bakım/denetim yardımcıları
│   └── tests/                 # node:test birim testleri
├── dashboard/                 # Yönetim paneli (React + Vite, base '/')
├── qr-form/                   # QR talep formu (React + Vite, base '/q/')
├── docker/                    # backend.Dockerfile, web.Dockerfile, nginx.conf
├── docs/                      # MkDocs kaynakları
├── scripts/
│   ├── ci/                    # kalite kapıları ve rapor üreteci
│   ├── lib/                   # ortak shell/PowerShell kütüphaneleri
│   ├── linux/                 # docker/ + native/ install|update|uninstall
│   └── windows/               # docker/ + native/ install|update|uninstall
├── tests/k6/smoke.js          # k6 performans smoke testi
├── .env.example               # tek ve paylaşılan .env şablonu
├── docker-compose.yml         # mongo + backend + web
├── mkdocs.yml
└── VERSION                    # tek sürüm doğruluk kaynağı

License

Bkz. LICENSE.