IQV Infra

IQVizyon'un Teknoloji Altyapı (Infra) yönetim uygulaması. Müşteri sahasındaki sunucu/tezgah/ağ altyapısının IQVizyon tarafından kayıt altına alınmasını, müşteriye token'sız bir public form ile doldurtulmasını, IQVizyon kontrolünü ve kurulum kararını yönetir.

• Frontend (dashboard/) -- React tabanlı, admin ekranları ve token'sız public müşteri formu.
• Backend (backend/) -- Express tabanlı API, MongoDB üzerinde çalışır, Swagger/OpenAPI ile kendini belgeler.

Bu README hızlı, operasyonel kurulum/güncelleme/kaldırma komutlarını kapsar. Mimari, geliştirme detayları, tam API referansı ve test altyapısı için dokümantasyon sitesine bakın.

---

Components

Bileşen	Teknoloji	Konum
Frontend	React 18 + TypeScript + Vite 4, antd 5, @iqvizyonui/react-components, Redux Toolkit, React Router 6	dashboard/
Backend	Node.js (CommonJS) + Express 4, MongoDB resmi sürücüsü (ODM yok), JWT (jsonwebtoken), express-rate-limit	backend/
Veritabanı	MongoDB 7 (iqvizyon veritabanı)	Harici -- IQV Infra saglamaz, her iki modda da disaridadir
API Dokümantasyonu	Swagger UI + OpenAPI 3 (gerçek koddan üretilir)	/api-docs, /openapi.json
Dokümantasyon Sitesi	MkDocs + Material, TR/EN	docs/
Konteynerleştirme	Docker + Docker Compose v2	docker-compose.yml
CI/CD	GitHub Actions	.github/workflows/

---

Requirements

Bileşen	Docker modu	Native mod
Docker + Compose v2	24+	--
Node.js	-- (yalnızca test/geliştirme için)	20+ (22 önerilir)
npm	-- (yalnızca test/geliştirme için)	10+
MongoDB	7+, ayrıca kurulmalı (IQV Infra saglamaz)	7+, ayrıca kurulmalı
PM2	--	son sürüm (install script gerekirse kurar)
Git	2.x (update script'lerinin git pull adımı için, her iki modda)	2.x
k6	Opsiyonel, yalnızca npm run test:k6 için	Opsiyonel, yalnızca npm run test:k6 için

---

Quick Start

Linux + Docker:

git clone <repo-url> && cd iqv-react-dashboard
cp .env.example .env            # JWT_SECRET ve MONGODB_URI'yi düzenleyin
./scripts/linux/docker/install.sh

Windows + Docker:

git clone <repo-url>; cd iqv-react-dashboard
copy .env.example .env
.\scripts\windows\docker\install.ps1

Kurulum bittiğinde arayüz http://localhost:8080, API dokümantasyonu http://localhost:8080/api-docs adresindedir.

Native (Docker'sız) kurulum için bkz. Native Installation.

---

Configuration Layers

Depoda tek bir .env vardır (repo kökü). Hem backend (backend/src/config/env.js) hem dashboard (dashboard/vite.config.ts, envDir: '..') aynı dosyayı okur.

Dosya	Git	Ne içerir
.env.example	Commit edilir	Şablon: gerçek bir sır içermez, gruplandırılmış tüm değişkenler ve açıklamaları
.env (repo kökü)	.gitignore'da, commit edilmez	Gerçek değerler (MongoDB URI, JWT_SECRET, SMTP, Telegram, Gemini)
backend/.env	Yok	--
dashboard/.env	Yok	--

Frontend bundle'a yalnızca VITE_ önekli değişkenler girer (Vite'in kendi davranışı). MONGODB_URI, JWT_SECRET, SMTP_PASSWORD, TELEGRAM_BOT_TOKEN ve GEMINI_API_KEY frontend'e asla dahil edilmez, imaja gömülmez ve loglanmaz.

Kurulum öncesi mutlaka değiştirilmesi gerekenler: JWT_SECRET ve MONGODB_URI. Install script'leri JWT_SECRET şablon değerdeyken kurulumu durdurur.

---

Installation

Kurulum, güncelleme ve kaldırma dört ortam kombinasyonunda (Linux/Windows × Docker/Native) tek komutla yapılır; her işlem ayrı bir script dosyasıdır. Aşağıda Docker ve Native için operasyonel özet verilmiştir; script davranışının tam açıklaması (idempotency, path çözümü, health check mekanizması) için dokümantasyon sitesindeki Kurulum bölümüne bakın.

Docker Installation

Linux:

./scripts/linux/docker/install.sh

Windows:

.\scripts\windows\docker\install.ps1

Script sırasıyla: Docker ve Compose varlığını doğrular, .env yoksa .env.example'dan oluşturur, JWT_SECRET'i denetler, imajları build eder, docker compose up -d çalıştırır ve gerçek HTTP health check yapar:

Frontend: OK
Backend: OK
Database: OK

Kontrollerden biri başarısız olursa script [ERROR] yazar ve non-zero exit code döner -- başarısız kuruluma asla "success" yazılmaz.

IQV Infra MongoDB sağlamaz. Çalıştırmadan önce erişilebilir bir MongoDB instance'ı ve MONGODB_URI gereklidir; .env boşsa install script'i durur.

Servisler: iqv-infra-dashboard (nginx, dışa açık tek port) ve iqv-infra-backend (Express, yalnızca iç ağ) -- ikisi de IQV_INFRA_APP_NETWORK (varsayılan iqv-infra-net) içindedir. Dışa açılan port .env içindeki IQV_INFRA_HTTP_PORT ile değiştirilir (varsayılan 8080).

Belirli bir sunucuya özgü değerler (reverse proxy ağı gibi) base docker-compose.yml'de YOKTUR; deploy/docker-compose.server.example.yml şablonunu kopyalayıp uyarlayın ve -f ile opsiyonel olarak devreye alın (diyagramlar asagida).

Standalone / yerel:

Tarayıcı -> host:IQV_INFRA_HTTP_PORT -> dashboard (nginx) -> backend -> harici MongoDB

Reverse proxy ile production:

Internet -> reverse proxy (Caddy/Nginx/Traefik) -> [opsiyonel ingress ağı]
         -> dashboard -> (app ağı) -> backend -> harici MongoDB

Native Installation

Docker olmadan; PM2 ile iki süreç çalışır (iqv-infra-backend, iqv-infra-frontend). MongoDB'nin ayrıca erişilebilir olması gerekir (.env → MONGODB_URI).

Linux:

./scripts/linux/native/install.sh

Windows:

.\scripts\windows\native\install.ps1
# Windows açılışında otomatik başlatma için:
.\scripts\windows\native\install.ps1 -AutoStart

Frontend, Docker'daki nginx'in native karşılığı olan bağımlılıksız scripts/common/static-server.mjs ile servis edilir; backend uçlarını (/api, /infra-record, /infra-public-*, /openapi.json, …) aynı origin üzerinden backend'e proxy'ler. Varsayılan portlar: frontend 5173, backend 4000.

---

Update

Tek komut: git pull --ff-only → bağımlılıklar → build → yeniden başlatma → health check → sürüm bilgisi.

./scripts/linux/docker/update.sh        # Linux + Docker
./scripts/linux/native/update.sh        # Linux native

.\scripts\windows\docker\update.ps1     # Windows + Docker
.\scripts\windows\native\update.ps1     # Windows native

Çalışma ağacında kaydedilmemiş değişiklik varsa git pull atlanır ve [WARN] yazılır -- yerel değişiklikler ezilmez. --ff-only kullanılır; otomatik merge/rebase yapılmaz.

---

Uninstall

Varsayılan uninstall veri silmez. Kalıcı veri (MongoDB volume'ü) ve .env korunur; veriyi de silmek için açıkça --purge / -Purge verilmelidir ve script ayrıca onay ister.

./scripts/linux/docker/uninstall.sh              # container + network
./scripts/linux/docker/uninstall.sh --images     # imajları da kaldırır

./scripts/linux/native/uninstall.sh              # PM2 süreçlerini kaldırır
./scripts/linux/native/uninstall.sh --purge      # node_modules + dist + .env

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

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

Uninstall (Docker veya Native) hiçbir koşulda MongoDB verisini silmez -- IQV Infra MongoDB saglamadigi icin ona hicbir sekilde dokunmaz; yalnizca kendi container/imaj/PM2 kayitlarini kaldirir. Hiçbir uninstall script'i kaynak kodu silmez.

---

Version Management

Sürümün tek kaynağı backend/package.json → version alanıdır; aynı değer OpenAPI şemasının info.version alanına da buradan gelir. Ayrı bir VERSION dosyası veya ikinci bir sürüm sistemi yoktur.

Update script'leri, işlem sonunda çalışan sürümü yazdırır:

IQV Infra updated successfully.
Version: 1.0.0
Commit: abc1234

Commit bilgisi git rev-parse --short HEAD ile okunur.

---

Environment Variables

Değişken	Varsayılan	Açıklama
PORT	4000	Backend HTTP portu
IQV_INFRA_HTTP_PORT	8080	Docker kurulumunda dışa açılan port
IQV_INFRA_APP_NETWORK	iqv-infra-net	Docker Compose iç ağ adı
IQV_INFRA_INGRESS_NETWORK	boş	Yalnızca sunucuya özgü compose overlay'inde (deploy/docker-compose.server.example.yml) kullanılan harici reverse-proxy ağı
IQV_FRONTEND_PORT	5173	Native kurulumda frontend portu
MONGODB_URI / MONGODB_DB	mongodb://127.0.0.1:27017 / iqvizyon	Harici veritabanı (IQV Infra saglamaz, ZORUNLU)
MONGODB_*_COLLECTION	iqvizyon-users, organizations, infra-record, infra-reminder	Koleksiyon adları
JWT_SECRET / JWT_EXPIRES_IN	-- / 12h	Kimlik doğrulama (zorunlu)
CORS_ORIGIN	http://localhost:5173	Virgülle ayrılmış origin listesi
FRONTEND_BASE_URL	boş	Mail'deki public form linkinin origin'i
PUBLIC_API_BASE_URL	boş	OpenAPI "Production" sunucu girdisi
SMTP_*	boş	Boşsa uygulama yine başlar, yalnızca mail gönderimi hata verir
TELEGRAM_BOT_TOKEN, INFRA_TELEGRAM_CHAT_ID	boş	Boşsa Telegram bildirimi sessizce atlanır
GEMINI_API_KEY / GEMINI_MODEL	boş / gemini-3.1-flash-lite	/api/it/bil kapasite önerisi
E2E_*, K6_*	--	Yalnızca test çalıştırıcıları için, bkz. dokümantasyon sitesi

Tüm gruplar ve satır satır açıklamalar için .env.example dosyasına bakın. Gerçek sır değerleri hiçbir dokümana yazılmaz.

---

Health Check

Uç	Davranış
GET /health	Canlılık (liveness). Süreç ayaktaysa 200 {"status":"ok"}
GET /health/ready	Hazırlık (readiness). MongoDB'ye gerçek bir ping komutu gönderir; DB cevap vermiyorsa 503 döner

Örnek GET /health/ready yanıtı (200):

{
  "status": "ok",
  "database": "ok"
}

Install/update script'lerinin "Database: OK" doğrulaması bu yanıttaki "database":"ok" alanını okur. Docker healthcheck'i de aynı ucu kullanır (backend/Dockerfile).

---

API Documentation

Adres	İçerik
/api-docs	Swagger UI (statik dosyalar swagger-ui-dist'ten gelir, CDN bağımlılığı yoktur)
/openapi.json	Ham OpenAPI 3.0 şeması

Swagger UI:   /api-docs
OpenAPI JSON: /openapi.json

Production örneği: https://infra.iqvizyon.com/api-docs (local'de host ortama göre değişir, ör. http://<BILGISAYAR_IP>:5173/api-docs). Her iki yol da her zaman aynı origin üzerinden backend'e proxy'lenir; React route'u değildir, PWA Service Worker'ın navigation fallback'inden (navigateFallbackDenylist) ve nginx SPA fallback'inden hariçtir.

Her ikisi de kimlik doğrulama gerektirmez ve hiçbir gizli değer içermez. Şema gerçek koddan üretilir: backend/src/docs/ altındaki routeInventory.js canlı Express router yığınını gezer, schemas.js/paths.js gerçek request/response ve summary/description/security bilgisini belgeler.

npm run docs:openapi   # docs/api/openapi.json dosyasını üretir
npm run docs:check     # şema ↔ canlı router farkı varsa non-zero exit

docs:check, aynı doğrulamayı yapan backend/tests/contract/ suite'i ile birlikte npm run test:all içinde çalışır -- yeni bir endpoint belgelenmeden eklenirse CI kırılır.

Sınıflandırma (x-iqv-classification: INTERNAL/OUTPUT/SYSTEM), domain gruplama, Public Infra token/session akışının tam açıklaması ve Infra Logs sistemi için Backend API sayfasına bakın -- Swagger'daki tüm uçların listesi burada tekrar edilmez.

---

CI/CD

.github/workflows/ci.yml (IQV Infra CI) main dalına her push/PR'da ve manuel (workflow_dispatch) olarak çalışır:

Job	Kapsam	Gate
Security Precheck	scripts/ci/security-precheck.mjs -- commit edilmiş .env, private key, token, kimlikli Mongo URI, hardcode secret taraması (değerler log'a basılmaz)	bloklayıcı
Workflow Lint	actionlint (+ shellcheck) ile ci.yml ve docs.yml	bloklayıcı
Dashboard — lint/prettier/typecheck/test/build	ESLint + Prettier (mevcut biçim borcu nedeniyle Warning), typecheck, Vitest unit + component, production build	bloklayıcı (20 puan)
Backend Tests	test:all (unit/integration/auth/security/contract) + docs:check	bloklayıcı (25)
E2E — Playwright	Bellek içi test stack'ine (tests/e2e/harness/start-stack.js) karşı Chromium	bloklayıcı (15)
Runtime Smoke (SPA)	Dashboard'dan sonra; /, /form, /health, /api-docs, /openapi.json	bloklayıcı (10)
Docker Build	docker compose config + docker compose build + nginx -t (registry push yok)	bloklayıcı (15)
k6 Smoke	Yerel test stack'ine karşı kısa smoke	bloklayıcı (10)
Deployment Scripts — Linux / Windows	bash -n + shellcheck / PowerShell 7 + 5.1 parser (script çalıştırılmaz)	bloklayıcı (3 + 2)
k6 Load/Stress (Manual)	Yalnızca workflow_dispatch; push'ta Environment Skipped	non-blocking
Quality Pipeline	En sonda; needs.*.result'tan IQV Infra Quality Result Job Summary + iqv-infra-quality-report artifact'i (REPORT.md, REPORT.json, QUALITY.svg)	Strict Gate

Strict Gate AÇIK, Soft Gate KAPALI: bloklayıcı bir job FAIL / SKIPPED / CANCELLED olursa sonuç skor ne olursa olsun FAILED olur. Puan etiketleri: 90–100 Çok İyi, 80–89 İyi, 70–79 Kabul Edilebilir, 60–69 İyileştirme Gerekli, 0–59 Kritik. Artifact yüklenemezse (ör. storage kotası) Summary'de Artifact Upload: UNAVAILABLE yazar; Quality Result bundan etkilenmez.

Dokümantasyon sitesi ayrı bir iş akışıyla (IQV Infra Docs: MkDocs build → Deploy to GitHub Pages, .github/workflows/docs.yml) GitHub Pages'e build/deploy edilir -- bkz. aşağıdaki Documentation bölümü.

Test tiplerinin ve çalıştırıcıların tam listesi (unit, integration, auth, security, contract, component, E2E, load, k6) için Test Raporları sayfasına bakın; bu README'de test komutlarının tekrarı yerine yalnızca CI iş akışı özetlenmiştir.

---

Documentation

Detaylı mimari, geliştirme, API ve test dokümantasyonu MkDocs + Material ile üretilir; Türkçe (varsayılan) ve İngilizce olarak yayınlanır.

Yerel olarak çalıştırmak için:

pip install -r requirements-docs.txt
mkdocs serve      # http://127.0.0.1:8000
mkdocs build      # site/ klasörüne üretir

Yayınlanan site: https://iqvizyon-development.github.io/iqv-react-dashboard/ (GitHub Pages, main'e her push'ta .github/workflows/docs.yml ile otomatik yayınlanır).

---

Troubleshooting

Aşağıda en sık karşılaşılan sorunlar özetlenmiştir; tam liste (PM2, reverse proxy, Docker/nginx statik dosya, test suite sorunları dahil) için dokümantasyon sitesindeki Sorun Giderme sayfasına bakın.

Belirti	Neden / Çözüm
[ERROR] JWT_SECRET ayarlanmamis	.env içindeki şablon değer değiştirilmemiş. Uzun, rastgele bir değer üretin (openssl rand -base64 48).
Database: FAIL	MONGODB_URI erişilemiyor. Docker'da docker compose logs mongo, native'de MongoDB servisini kontrol edin. /health/ready gerçek ping yapar, sahte başarı döndürmez.
Backend: FAIL	docker compose logs backend / pm2 logs iqv-infra-backend. Genelde eksik .env değeri veya dolu port.
Public form "oturumu sona ermiş veya geçersiz"	/form adresine session cookie'si olmadan doğrudan girilmiş ya da cookie'nin süresi dolmuş. Müşteri mail'deki /it/public-access/<token> bağlantısını tekrar kullanmalıdır; uygulama hiçbir kaydı tahmin ederek açmaz.
Eski mail linki (/it/public/<token>) çalışmıyor	Reverse proxy /it/public önekini backend'e iletmiyordur. Üç proxy tanımı da bu öneki içermelidir: dashboard/nginx.conf, dashboard/vite.config.ts, scripts/common/static-server.mjs.
Mail linki yanlış adrese gidiyor	.env → FRONTEND_BASE_URL boş ve reverse proxy X-Forwarded-Proto/Host göndermiyor.
Telegram bildirimi gelmiyor	TELEGRAM_BOT_TOKEN veya INFRA_TELEGRAM_CHAT_ID boş -- bildirim sessizce atlanır (tasarım gereği). cd backend && node scripts/list-telegram-chats.js ile chat_id bulunabilir.
docs:check hata veriyor	Kod ile OpenAPI şeması ayrışmış. Yeni endpoint'i backend/src/docs/paths.js içinde belgeleyin.
Port çakışması	Docker'da .env → IQV_INFRA_HTTP_PORT; native'de PORT / IQV_FRONTEND_PORT.
npm run build → TS7016: Could not find a declaration file for module 'react-router-dom'	Kaynak kod hatası değildir: yarım kalmış bir npm install, node_modules'u bozmuştur. Çözüm: rm -rf dashboard/node_modules && npm --prefix dashboard ci.

---

Developer Mode

npm --prefix backend run dev       # backend (http://localhost:4000)
npm --prefix dashboard run dev     # dashboard (http://localhost:5173)

Backend'de otomatik yeniden başlatma (nodemon/watch) yoktur -- npm run dev düz node src/server.js çalıştırır; kod değişikliğinden sonra süreci elle yeniden başlatmanız gerekir. Dashboard tarafı standart Vite HMR kullanır.

Vite dev sunucusu backend uçlarını VITE_DEV_API_PROXY_TARGET (varsayılan http://localhost:4000) adresine proxy'ler -- dev, native ve Docker kurulumlarının üçü de aynı URL sözleşmesini kullanır. Proxy'lenen path listesi üç yerde birden tutulur ve birlikte güncellenir: dashboard/vite.config.ts (dev), dashboard/nginx.conf (Docker) ve scripts/common/static-server.mjs (native).

Kod kalitesi:

npm --prefix dashboard run lint          # ESLint
npm --prefix dashboard run prettier      # format kontrolü
npm --prefix dashboard run typecheck     # tsc --noEmit

Test komutlarının tam listesi için Test Raporları sayfasına bakın; hızlı özet:

npm run test:all     # lint, typecheck, unit, component, integration, auth, security, contract, docs:check
npm run test:full    # yukarıdakiler + e2e + load + k6

---

Production Mode

• Docker: dashboard (nginx) dışa açık tek servistir; backend yalnızca IQV_INFRA_APP_NETWORK iç ağındadır (varsayılan iqv-infra-net). IQV Infra MongoDB sağlamaz -- backend harici bir MongoDB instance'ına MONGODB_URI üzerinden bağlanır. Her serviste restart: unless-stopped, healthcheck ve boyut sınırlı JSON log sürücüsü tanımlıdır.
• İmajlar: çok aşamalı (multi-stage) build; backend imajı yalnızca production bağımlılıklarını içerir ve non-root (node) kullanıcı ile çalışır; frontend imajında Node ve kaynak kod bulunmaz.
• Sırlar: imaja gömülmez, çalışma anında env_file: .env ile gelir. .dockerignore .env* dosyalarını build context'inden çıkarır (.env.example hariç).
• Kalıcı veri: IQV Infra kendi başına kalıcı veri tutmaz; tüm veri harici MongoDB instance'ındadır.
• Native production: PM2 ile aynı iki süreç (iqv-infra-backend, iqv-infra-frontend) production build'i üzerinden çalışır; ayrı bir "production modu" bayrağı yoktur, NODE_ENV=production ve dashboard/dist production build'i kullanılır.

---

Directory Structure

backend/            Express API (src/, tests/, scripts/, docs/)
dashboard/          React + Vite arayüz (src/, tests/)
scripts/
  common/           PM2 ecosystem + native statik sunucu
  linux/{docker,native}/{install,update,uninstall}.sh
  windows/{docker,native}/{install,update,uninstall}.ps1
  run-tests.js      test:all / test:full orkestratörü
tests/              e2e/, k6/, load/, reports/
docs/               MkDocs kaynakları (TR/EN) + üretilen openapi.json
.github/workflows/  ci.yml (IQV Infra CI + Quality Pipeline) ve docs.yml (GitHub Pages)
docker-compose.yml  Production stack
mkdocs.yml          Dokümantasyon konfigürasyonu
requirements-docs.txt  MkDocs Python bağımlılıkları
.env.example        Ortam değişkeni şablonu

---

License

Bkz. LICENSE.