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 ciSü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/.envAltyapı ve şema hazırlığı:
npm run docker:up
npm run db:generate
npm run db:migratedocker: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:apinpm run dev:webDokümantasyon sitesi gerektiğinde ayrı başlatılır:
npm run dev -w @mevzuat-radar/docsBu 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.
| Servis | Yerel adres veya port |
|---|---|
| Web | http://localhost:3100 |
| API | http://localhost:3101 (API_PORT=3101) |
| Prisma Studio | 3102 (npm run db:studio) |
| Geliştirici dokümantasyonu | http://localhost:3103 |
| Yardım sitesi | http://localhost:3104 |
| PostgreSQL | 5433 (konteyner içinde 5432) |
| Redis | 6380 (konteyner içinde 6379) |
| Meilisearch | 7701 (konteyner içinde 7700) |
| MinIO API | 9002 (konteyner içinde 9000) |
| MinIO konsolu | 9003 (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ındaRetry-Afterbekleme 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.