IQVflex ERP

ERP ↔ MES entegrasyon platformu. Alan eşleştirme (field mapping), JSON/XML dönüşümleri ve ERP hesap yönetimini tek arayüzden yönetir.

Bileşen	Teknoloji	Konum
Frontend	React 18 + TypeScript + Vite, Ant Design	dashboard/
Backend	Node.js 22 + Express (ESM)	iqvflex/backend/
Veritabanı	MongoDB 7	Docker'da yönetilir veya harici
Go API	Harici servis — bu depoda bulunmaz	GO_API_BASE_URL

Backend, eski Node-RED akışından taşınmıştır; Node-RED artık gerekmez.

---

Installation

Kurulum tek komuttur. npm install, npm run build, docker compose build, .env kopyalama veya klasör oluşturma gibi elle adımlar gerekmez — hepsini kurulum betiği yapar.

Betik şunları yürütür: işletim sistemi ve bağımlılık tespiti → çalışma dizinleri → .env üretimi (secret'lar rastgele üretilir) → imaj derleme → servisleri bağımlılık sırasıyla başlatma → gerçek healthcheck doğrulaması.

Docker – Linux

git clone <repo-url> ERP
cd ERP
chmod +x install.sh
./install.sh

Docker – Windows

git clone <repo-url> ERP
cd ERP
powershell -ExecutionPolicy Bypass -File .\install.ps1

Docker Desktop'ın açılması bekleniyorsa betik kontrollü şekilde bekler.

Native – Linux

Docker yoksa:

./install.sh --mode native

Servisler systemd ile kaydedilir (iqvflex-backend, iqvflex-frontend) ve makine yeniden başladığında otomatik açılır. Servis kaydı sudo gerektirir.

Native – Windows

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Mode native

Servisler yerleşik Zamanlanmış Görev (Scheduled Task) olarak kaydedilir; ek bağımlılık (PM2, NSSM) gerekmez. Yönetici yetkisi ister.

Kurulum kipleri

Kip	Linux	Windows
Otomatik (Docker varsa Docker)	./install.sh	.\install.ps1
Docker	./install.sh --mode docker	.\install.ps1 -Mode docker
Native	./install.sh --mode native	.\install.ps1 -Mode native
Sıkılaştırılmış üretim	./install.sh --profile prod	.\install.ps1 -DeployProfile prod

--profile prod (docker-compose.prod.yml) veritabanı ve backend portlarını dışarıya hiç açmaz, backend kök dosya sistemini salt okunur yapar ve bellek sınırları uygular. Tek giriş noktası nginx olur.

Kurulum sonunda erişim adresi: http://localhost:8080

---

Update

Güncelleme de tek komuttur. git pull, npm install, docker build, yeniden başlatma elle yapılmaz.

Linux

./update.sh

Windows

.\update.ps1

Sıra: kurulum doğrulama → sürüm kaydı → yapılandırma yedeği → git fetch → git pull --ff-only → sürüm/bağımlılık karşılaştırması → gerekli servisleri yeniden derleme → yeniden başlatma → healthcheck.

Güvenlik garantileri

• Takip edilen dosyalarda kaydedilmemiş değişiklik varsa güncelleme durur; hiçbir dosya ezilmez. Değişiklikleriniz olduğu gibi kalır.
• Yalnızca git pull --ff-only kullanılır — birleştirme/rebase yapılmaz, geçmiş değiştirilmez.
• docker compose down -v hiçbir zaman çalıştırılmaz → veritabanı korunur.
• .env ve müşteri yapılandırması ezilmez; önce backups/ altına yedeklenir.

Seçenek	Linux	Windows
Git çekmeden yeniden kur	--no-pull	-NoPull
Hedef dal seç	--branch main	-Branch main
Hata halinde geri dönüşe izin ver	--allow-rollback	-AllowRollback

Otomatik geri dönüş kapalı gelir, çünkü git reset --hard yıkıcıdır. Açıkça istenmedikçe çalışmaz. Veritabanı hiçbir koşulda geri alınmaz.

---

Uninstall

Normal Uninstall

./uninstall.sh          # Linux
.\uninstall.ps1         # Windows

Yapar: servisleri durdurur, container'ları kaldırır, uygulama imajlarını siler, systemd / Zamanlanmış Görev kayıtlarını temizler.

Korur: MongoDB verisi, .env, backups/, kaynak kod.

Full Purge

./uninstall.sh --purge                 # Linux
.\uninstall.ps1 -Purge                 # Windows

Ek olarak siler: derleme çıktıları (dist/), node_modules/, logs/ ve türetilmiş yapılandırma (iqvflex/backend/.env, dashboard/.env). Kök .env, backups/ ve kaynak kod korunur.

Veritabanını da silmek ayrı ve açık bir bayrak ister:

./uninstall.sh --purge --purge-data    # Linux
.\uninstall.ps1 -Purge -PurgeData      # Windows

• --purge-data tek başına reddedilir; yalnızca --purge ile geçerlidir.
• Silme işleminden sonra birimlerin gerçekten kaldırıldığı doğrulanır; doğrulanamazsa betik hata verir (yanlış "silindi" raporu vermez).
• Harici / paylaşımlı MongoDB sunucularına asla dokunulmaz. Yalnızca bu kurulumun sahibi olduğu yerel Docker birimleri kaldırılır.

Üç betik de idempotenttir: ikinci kez çalıştırmak sistemi bozmaz, zaten kaldırılmış sistemde hata yağmuru üretmez.

---

Versioning

Tek canonical sürüm kaynağı: depo kökündeki VERSION dosyası (SemVer, MAJOR.MINOR.PATCH).

• Betikler sürümü yalnızca bu dosyadan okur ve Docker imajlarını bu etiketle işaretler (iqvflex-backend:1.0.0).
• Sürüm Git üzerinden gelir; betikler kendiliğinden sürüm artırmaz.
• Yeni sürüm çıkarmak: VERSION dosyasını güncelle, commit'le, (istenirse) aynı değerle Git tag at, main dalına gönder. Kullanıcı ./update.sh çalıştırınca yeni sürüme geçer.
• dashboard/package.json ve iqvflex/backend/package.json içindeki sürümler bileşen düzeyindedir ve ürün sürümü değildir.

Install çıktısı: Installed Version: x.y.z Update çıktısı: Previous Version: x.y.z / Current Version: x.y.z

---

Environment Variables

Tüm ayarlar kök .env dosyasındadır; şablonu .env.example'dır. .env asla depoya girmez (.gitignore).

ERP_AUTH_SECRET ve MONGO_INITDB_ROOT_PASSWORD kurulumda rastgele üretilir, ekrana/loga basılmaz ve mevcut değerler korunur.

Değişken	Varsayılan	Açıklama
FRONTEND_PORT	8080	Tek giriş noktası (nginx)
BACKEND_PORT	3001	Yalnızca 127.0.0.1'e bağlanır
MONGO_PORT	27017	Yalnızca 127.0.0.1'e bağlanır
MONGODB_URI	(boş)	Boşsa yönetilen MongoDB kullanılır
MONGODB_DATABASE	iqvizyon	Mevcut üretim yapısı — değiştirmeyin
MONGODB_ERP_MAPPING_COLLECTION	erp_mapping	Değiştirmeyin
MONGODB_ERP_USERS_COLLECTION	erp_users	Değiştirmeyin
ERP_AUTH_SECRET	üretilir	JWT/HS256 imza anahtarı
ERP_AUTH_TOKEN_TTL_SECONDS	28800	Token ömrü (8 saat)
GO_API_BASE_URL	—	Harici Go servisinin adresi
GO_API_CLIENT_ID / _SECRET	(boş)	Boşsa Authorization gönderilmez
COMPOSE_PROFILES	managed-mongo	Harici MongoDB için boşaltın
VITE_API_BASE_URL	(boş)	Docker'da boş: aynı köken kullanılır

Harici MongoDB kullanımı

.env içinde:

MONGODB_URI=mongodb://<KULLANICI>:<PAROLA>@<SUNUCU>:27017
COMPOSE_PROFILES=

COMPOSE_PROFILES boşaltıldığında yönetilen MongoDB servisi hiç çalışmaz; compose yapılandırması yine geçerli kalır.

---

Health Check

Sağlık kontrolü süreç kontrolü değildir — gerçek HTTP yanıtı doğrulanır. Docker healthcheck'i ile kurulum betiğinin kontrolü aynı mantığı kullanır.

Ne	Adres	Beklenen
Backend	http://localhost:8080/health	200 + data.status == "ok"
Frontend (nginx)	http://localhost:8080/__nginx_health	200
MongoDB	container healthcheck	db.adminCommand('ping').ok

curl http://localhost:8080/health
docker compose ps          # SERVICE / STATUS / PORTS / HEALTH

nginx şu üç öneki backend'e vekiller: /health, /erp-mapping, /api/. Diğer tüm yollar SPA'ya düşer (React Router).

---

Troubleshooting

Servis healthy olmuyor

docker compose ps
docker compose logs --tail=80 backend

/health 200 dönüyor ama veri gelmiyor Backend, MongoDB'ye ulaşamasa da ayağa kalkar (tasarım gereği) ve ilk sorguda yeniden dener. MONGODB_URI değerini ve MongoDB erişimini kontrol edin. Veri uçlarında getaddrinfo ENOTFOUND görüyorsanız adres yanlıştır.

Port kullanımda .env içinde FRONTEND_PORT değerini değiştirip ./update.sh --no-pull çalıştırın.

Update "kaydedilmemiş değişiklikler var" diyor Bu bir korumadır — değişiklikleriniz ezilmesin diye durur. git stash, git commit yapın ya da ./update.sh --no-pull ile yalnızca yeniden kurun.

Windows'ta betik çalışmıyor powershell -ExecutionPolicy Bypass -File .\install.ps1 şeklinde çağırın. Native kip ve kaldırma işlemleri yönetici yetkisi ister.

Docker Desktop hazır değil Betik açılmasını bekler. Uzun sürerse Docker Desktop'ı başlatıp tekrar deneyin.

---

Developer / Advanced

Üretim kullanıcısının bu bölüme ihtiyacı yoktur. Üretim yöntemi yukarıdaki betiklerdir. Buradaki komutlar yalnızca geliştirme içindir.

# Frontend
cd dashboard
npm ci
npm run dev            # geliştirme sunucusu
npm run typecheck      # tsc --noEmit
npm run lint
npm test               # node:test
npm run build

# Backend
cd iqvflex/backend
npm ci
npm run dev            # node --watch
npm test               # node:test + smoke

# Docker elle
docker compose config
docker compose build
docker compose up -d
docker compose logs -f

Yük testi (k6) iqvflex/backend/test/k6/ altındadır ve yalnızca localhost/test/staging adreslerini hedefleyebilir (üretim adresleri betik tarafından reddedilir).

Dizin düzeni

ERP/
├── install.sh / install.ps1
├── update.sh  / update.ps1
├── uninstall.sh / uninstall.ps1
├── docker-compose.yml          # mongo + backend + frontend
├── docker-compose.prod.yml     # sıkılaştırılmış üretim override'ı
├── .env.example                # şablon (gerçek secret İÇERMEZ)
├── VERSION                     # canonical sürüm
├── scripts/
│   ├── common.sh / common.ps1  # ortak fonksiyonlar
│   └── static-server.mjs       # native kip statik sunucu (bağımlılıksız)
├── dashboard/                  # frontend + Dockerfile + nginx.conf
├── iqvflex/backend/            # backend + Dockerfile
├── data/  logs/  backups/      # çalışma zamanı (Git'e girmez)

Kod ile çalışma zamanı verisi ayrıdır: data/, logs/, backups/ ve .env sürüm kontrolüne girmez, git pull bunları etkilemez.