Ana içeriğe geç
Mevzuat RadarDokümantasyon
Uygulamaya git ↗

Yerel Geliştirme ve Entegrasyon Testi

İki farklı çalışma biçimi vardır: API tüketicisi kendi entegrasyonunu dener; yetkili proje geliştiricisi ise MevzuatRadar deposundan yerel ortam kurar. Ayrı bir API anahtarı üretmek, canlı API’yi izole test ortamına dönüştürmez.

API tüketicisi için deneme

API ayarlarından  denemeye özel, dar izinli, son kullanma tarihi olan bir anahtar oluşturulabilir. Gerekiyorsa izinli IP listesiyle sınırlandırılır. Canlı API’ye yapılan çağrılar kurumun kullanımına işlenir; ayrı anahtar ayrı veri kümesi veya kota sağlamaz.

İstemcinin adresi yapılandırılabilir tutulur:

export MEVZUATRADAR_API_BASE_URL="https://api.mevzuatradar.com"

MEVZUATRADAR_API_KEY güvenli sır kaynağından alınır. Node.js SDK’sındaki karşılığı apiKey ve baseUrl seçenekleridir:

import { MevzuatRadarClient } from '@mevzuat-radar/sdk'; const client = new MevzuatRadarClient({ apiKey: process.env.MEVZUATRADAR_API_KEY, baseUrl: process.env.MEVZUATRADAR_API_BASE_URL, });

Bu değişken adları örnek istemci ayarlarıdır; MevzuatRadar sunucusunun yapılandırma değişkenleriyle aynı olmak zorunda değildir. Kimlik doğrulamasız örnek veri için GET /api/v1/public/regulations kullanılabilir. Canlı veride değişiklik yapan denemeler ve yük testleri için ayrıca yetkilendirilmiş, izole bir hedef gerekir.

Depodan yerel kurulum

Bu bölüm depo erişimi olan geliştiriciler içindir. Komutlar depo kökünde çalıştırılır. Araç zinciri Node.js 22.23.4, npm 10.9.2 olarak sabitlenmiştir; .node-version, kök package.json ve docker/quality-runner/runtime-lock.json aynı sürümü tanımlar. Docker Engine ve Compose eklentisi altyapı servisleri için gereklidir.

node --version npm --version npm ci

Sürüm çıktıları sırasıyla v22.23.4 ve 10.9.2 olmalıdır. Kök .env, yetkili yerel yapılandırmadan hazırlanır; .env.example değişken adları için şablondur. Üretim sırları veya üretim bağlantı adresleri yerel ortama kopyalanmaz. Özellikle DATABASE_URL, REDIS_URL, NEXTAUTH_URL, API_URL, NEXT_PUBLIC_API_URL, API_PORT, MEILISEARCH_HOST ve S3_ENDPOINT yerel hedefleri göstermelidir. JWT, oturum, depolama ve sağlayıcı sırları ayrıca güvenli biçimde yapılandırılır.

Kök .env API, web ve Prisma tarafından ortak kullanılır:

ln -sf "$PWD/.env" apps/api/.env ln -sf "$PWD/.env" apps/web/.env ln -sf "$PWD/.env" packages/db/.env

Altyapı ve şema hazırlığı:

npm run docker:up npm run db:generate npm run db:migrate

docker:up, docker/docker-compose.dev.yml dosyasını kullanır. db:migrate, mevcut migration’ları prisma migrate deploy ile uygular; yeni migration üretmez. Bu komuttan önce DATABASE_URL hedefinin ayrılmış yerel veritabanı olduğu doğrulanır. db:seed mevcut veriyi değiştirebildiğinden normal başlangıç adımı değildir; yalnız gözden çıkarılabilir, ayrılmış veritabanında değerlendirilir.

Hibrit çalışma modeli

Günlük geliştirmede PostgreSQL, Redis, Meilisearch ve MinIO Docker’da; API ve web ana makinede çalışır. Ayrı terminallerde:

npm run dev:api
npm run dev:web

Dokümantasyon sitesi gerektiğinde ayrı başlatılır:

npm run dev -w @mevzuat-radar/docs

Bu komutlar API/web/dokümantasyon geliştirme sunucularını açar; tüm arka plan işlerinin veya kaynak toplama akışının hazır olduğunu kanıtlamaz. Genel arka plan işleri için npm run dev:worker ayrı süreçtir. Yerleşik resmî kaynakların toplama sahibi yerelde de TR worker’dır; ana makinede veya API sürecinde yerleşik kaynak toplama başlatılmaz. Tam kaynak toplama doğrulaması yetkili geliştiricinin ayrıca yapılandırdığı yerel kanıt bağlantısını gerektirir.

Başlatma betiğinde bilinen sürüm uyumsuzluğu

Kanonik toplu başlatma betiği ./start.command, Docker altyapısını hazırlar; migration ve yerel taksonomi hazırlığından sonra PM2 ile API, web, kalite worker’ı, tarayıcı servisleri, dokümantasyon ve yardım uygulamasını başlatır. Betik kök .env ile .env.docker veya .env.docker.example dosyasını arar; PM2 ve yerel sektör modeli hazırlığına da bağımlıdır.

24 Ekim 2026 kod denetimi: Betiğin ensure_project_node_runtime fonksiyonu hâlâ Node 20 arar ve bulursa onu seçer; bu davranış Node 22.23.4 sözleşmesiyle çelişir. Betik düzeltilene kadar Node 22 ile uyumlu toplu başlatma yolu olarak kabul edilmez. Yukarıdaki ayrı geliştirme komutları kullanılır; eski Node sürümüne dönülmez. Bu not, betiğin çalıştırılarak doğrulandığı anlamına gelmez.

Yerel portlar

Aşağıdaki adresler yalnız depo geliştirme ortamı içindir; entegrasyon örneklerinde canlı API temel adresi kullanılır.

ServisYerel adres veya port
Webhttp://localhost:3100
APIhttp://localhost:3101 (API_PORT=3101)
Prisma Studio3102 (npm run db:studio)
Geliştirici dokümantasyonuhttp://localhost:3103
Yardım sitesihttp://localhost:3104
PostgreSQL5433 (konteyner içinde 5432)
Redis6380 (konteyner içinde 6379)
Meilisearch7701 (konteyner içinde 7700)
MinIO API9002 (konteyner içinde 9000)
MinIO konsolu9003 (konteyner içinde 9001)

Yerel alan adlarında müşteri/yönetim alan adı yönlendirmesi bilinçli olarak uygulanmaz. Geliştirme süreçleri ilgili terminalde Ctrl+C ile durdurulur. Altyapıyı kapatmak için npm run docker:down kullanılır; bu komuta veri hacimlerini silen seçenekler eklenmez. PM2 ile açılan süreçler ayrıca proje PM2 bağlamında yönetilir; Compose komutu bu süreçleri kapatmaz.

Webhook alıcısı ve sorun giderme

Alıcı önce yetkilendirilmiş test ortamında denenir. Panelde Test Gönder veya POST /api/v1/webhooks/:id/test örnek teslimat üretir; bu da dış alıcıya istek gönderir. İmza doğrulaması ayrıştırılmamış istek gövdesi üzerinde uygulanır. Ayrıntılar Webhook Akışı sayfasındadır.

  • 401: anahtar yanlış, iptal edilmiş veya süresi dolmuş olabilir.
  • 403: plan, rol, izin veya IP kısıtı denetlenir.
  • 429: API anahtarı hız sınırında Retry-After bekleme süresi izlenir.

Test verisi sentetik veya uygun biçimde anonimleştirilmiş olarak hazırlanır. Sorun bildiriminde zaman, yol ve HTTP durum kodu paylaşılır; kişisel veri ve kimlik bilgileri çıkarılır. Deneme bitince geçici anahtar iptal edilir.