Skip to content

kadiraktech/TraceMind

BranchesTags

Repository files navigation

TraceMind

TraceMind, teknik hata ekran görüntülerini analiz eden yerel çalışan bir yapay zeka destekli arıza çözüm uygulamasıdır. Kullanıcı ekran görüntüsü yükler; sistem OCR ile metin ve hata sinyallerini çıkarır, PostgreSQL/pgvector üzerindeki bilgi bankasından ilgili parçaları getirir ve Ollama üzerinden teşhis ile çözüm adımları üretir.

MVP odağı Oracle DB, Microsoft SQL Server, Linux/System, Docker/Linux ve Network/Connectivity gibi teknik alanlarda ekran görüntüsü tabanlı analiz akışını uçtan uca doğrulamaktır.

Mimari

  1. Kullanıcı Angular arayüzünden ekran görüntüsü yükler.
  2. Backend API görüntüyü FastAPI AI servisine gönderir.
  3. AI servisi OpenCV/EasyOCR ile OCR, görsel ön işleme ve teknik sinyal çıkarımı yapar.
  4. Backend OCR çıktısı, kullanıcı açıklaması ve domain bilgisinden retrieval sorgusu oluşturur.
  5. PostgreSQL/pgvector bilgi bankasından ilgili doküman parçaları getirilir.
  6. Ollama ile nihai teşhis, çözüm adımları, kanıtlar ve güven seviyesi üretilir.
  7. Sonuç veritabanına kaydedilir.
  8. Frontend analiz sonucu, çıkarılan metin, kanıtlar, pipeline durumu ve analiz geçmişini gösterir.

Açıklanabilirlik Katmanı

TraceMind analiz sonucunda yalnızca teşhis ve çözüm adımı üretmez; kullanıcıya bu sonuca neden ulaşıldığını da özetler. Canlı analiz ve geçmiş detay ekranında “Bu Sonuca Neden Ulaşıldı?” bölümü gösterilir.

Bu bölümde şu bilgiler yer alır:

  • OCR’dan yakalanan hata kodu, alan/domain, retrieval cache durumu ve kullanılan model gibi tespit edilen sinyaller.
  • Bilgi bankasından getirilen kanıtların güvenli özeti: başlık, domain, eşleşen hata kodu, sıra, kaynak tipi ve varsa relevance skoru.
  • Güven skoru açıklaması: hata kodunun doğrudan yakalanması, domain eşleşmesi, kaç KB kaydı bulunduğu ve LLM/fallback durumu.
  • Çözüm adımlarının dayanağı: önerinin hangi sinyal ve kanıt setinden üretildiğine dair kısa not.

Örnek ORA-12154 akışı: OCR çıktısında ORA-12154 yakalanır, alan Oracle DB olarak sınıflandırılır, Oracle Net/TNS çözümleme bilgisi içeren KB kayıtları sıralanır ve teşhis bu hata kodu ile ranked evidence üstünden açıklanır.

Gizlilik sınırı: açıklanabilirlik alanı tam OCR metnini, tam LLM prompt’unu veya tam LLM cevabını structured log/Sentry/Elasticsearch içine yazmaz. UI’daki kanıt kartları KB chunk metninin tamamını tekrar etmez; kısa, güvenli seçim nedenini gösterir.

Troubleshooting Intelligence Layer

TraceMind ayrıca olası kök nedenleri sıralayan bir troubleshooting intelligence katmanı içerir. Bu katman “tek bir LLM cevabı” yerine, backend tarafında kanıta dayalı adaylar üretir ve kullanıcıya hangi sebebin önce kontrol edilmesi gerektiğini gösterir.

Root cause ranking şu sinyalleri kullanır:

  • OCR’dan çıkarılan exact hata kodu.
  • Domain eşleşmesi.
  • Retrieval rank ve similarity score.
  • KB başlığı/bölümü ve güvenli keyword overlap.
  • OCR confidence gibi destek sinyalleri.
  • Cache hit/miss yalnızca destek metadata’sıdır; ana sebep olarak kullanılmaz.

Skor ve öncelik LLM’e bırakılmaz. LLM, backend’in ürettiği aday listesini görür ve yanıtını bu aday sırasına göre önceliklendirir; ancak score backend heuristic + evidence ağırlıklı kalır. Bu yaklaşım, cevapların daha tekrarlanabilir ve denetlenebilir olmasını sağlar.

ORA-12154 örneğinde TraceMind şu adayları önceliklendirir:

  1. TNS connect identifier cannot be resolved
  2. Wrong or missing tnsnames.ora entry
  3. Oracle client network configuration mismatch
  4. DNS or Easy Connect resolution issue

Her aday için probability label, 0-100 score, reasoning, destekleyen KB başlıkları, önerilen ilk aksiyon ve göz ardı edilirse risk bilgisi gösterilir. Tam OCR metni, tam prompt ve tam LLM cevabı loglara veya evidence raporlarına yazılmaz.

Tamamlanan Entegrasyonlar

Entegrasyon TraceMind'deki kullanım Port / komut / servis
PrimeNG + Sakai-Ng UI geçişi Angular arayüzü PrimeNG 19 bileşenleri, PrimeIcons ve Sakai çizgisine uygun uygulama kabuğu ile düzenlendi. Analiz yükleme, sonuç, geçmiş ve pipeline panelleri bu UI yapısında çalışır. npm run frontend:start -- --host 127.0.0.1 --port 4200
Responsive + çoklu dil desteği Arayüz masaüstü ve dar ekranlarda kullanılabilir olacak şekilde düzenlendi. Türkçe/İngilizce metinler @ngx-translate/core ve i18n JSON dosyalarıyla yönetilir. Frontend dev server: http://127.0.0.1:4200
PWA Angular servis worker, manifest ve ikonlarla kurulabilir uygulama kabuğu sağlanır. PWA offline AI/OCR/RAG çalıştırmaz; analiz için backend, AI service, DB ve Ollama gerekir. npm run build --workspace @tracemind/frontend -- --configuration production, preview: npx http-server apps/frontend/dist/tracemind-frontend/browser -p 4300 -c-1
Sentry Frontend runtime hataları ve backend exception takibi için temel entegrasyon vardır. DSN boşsa uygulama normal çalışır; gerçek DSN env/deploy ortamından verilmelidir. Frontend environment ayarları, backend SENTRY_DSN, Sentry__EnableInDevelopment
Redis cache Bilgi erişimi sonucundaki güvenli retrieval metadata kısa süreli cache edilir. Redis kapalıysa backend PostgreSQL/pgvector üzerinden çalışmaya devam eder. Docker servis: tracemind-redis, port 6379, kontrol: docker exec tracemind-redis redis-cli ping
RabbitMQ management UI Opsiyonel altyapı/management UI gösterimi sağlar. Analyze pipeline aktif olarak RabbitMQ üzerinden çalışmaz; mesaj kuyruğu entegrasyonu bu aşamada yoktur. Docker servis: tracemind-rabbitmq, panel http://127.0.0.1:15672
SonarQube Yerel statik kod analizi, maintainability ve temel code smell görünürlüğü için foundation sağlar. Backend ve frontend scan komutları token env üzerinden çalışır. Docker servis: tracemind-sonarqube, panel http://127.0.0.1:9000
Jenkins CI/CD Repo kökündeki Jenkinsfile build, test, coverage, production build, opsiyonel Selenium, opsiyonel Sonar ve RUN_LOCAL_DEPLOY=true ile local PWA deploy/package stage'lerini tek pipeline altında toplar. Cloud deploy veya image publish yapmaz. Docker servis: tracemind-jenkins, panel http://127.0.0.1:8080
Selenium UI test otomasyonu Frontend smoke test foundation seviyesinde çalışır. Ana kabuk, dil geçişi, upload alanı ve backend kapalıyken kullanıcı dostu durum doğrulanır. npm run frontend:e2e:selenium, varsayılan E2E_BASE_URL=http://127.0.0.1:4200
Elasticsearch + Kibana log merkezi Backend structured logları Elasticsearch'e gönderilebilir; Kibana ile analiz pipeline olayları aranabilir. AI service doğrudan Elasticsearch'e yazmaz, JSON console foundation içerir. Elasticsearch http://127.0.0.1:9200, Kibana http://127.0.0.1:5601

Teknoloji Yığını

Katman Teknoloji
Ön yüz Angular 19, PrimeNG 19, PrimeIcons, Sakai-Ng tarzı yerleşim
Çoklu dil @ngx-translate/core, @ngx-translate/http-loader
PWA Angular service worker, manifest, PWA ikonları
Arka uç .NET 8 Web API
Veritabanı PostgreSQL 16 + pgvector
Yapay zeka servisi Python, FastAPI, EasyOCR, OpenCV
LLM Ollama, llama3:latest
Vektör temsil Ollama, nomic-embed-text:latest
Önbellek Redis, StackExchange.Redis
Gözlemlenebilirlik Sentry, Elasticsearch, Kibana
Kod kalitesi SonarQube Community LTS, dotnet-sonarscanner, sonar-scanner
CI/CD foundation Jenkins LTS, declarative Jenkinsfile
Yerel altyapı Docker Compose

Hızlı Başlatma

Gerekli araçlar:

  • .NET SDK 8+
  • Node.js ve npm
  • Python 3.11+
  • Docker Desktop
  • Ollama
  • Java 17 JDK/JRE
  • PowerShell

İlk kurulum:

cd C:\Users\Kadir\Desktop\TraceMind
if (-not (Test-Path infra/docker/.env)) { Copy-Item infra/docker/.env.example infra/docker/.env }

docker compose --env-file infra/docker/.env --file infra/docker/docker-compose.yml up -d
dotnet tool restore
dotnet restore TraceMind.sln
npm install

cd apps/ai-service
if (-not (Test-Path .venv)) { python -m venv .venv }
.venv\Scripts\python.exe -m pip install -e .
cd C:\Users\Kadir\Desktop\TraceMind

ollama pull llama3
ollama pull nomic-embed-text

$env:ConnectionStrings__TraceMindDb="Host=localhost;Port=5432;Database=tracemind;Username=tracemind;Password=<local-password>"
dotnet ef database update --project apps/backend/src/TraceMind.Infrastructure --startup-project apps/backend/src/TraceMind.Api

Günlük çalıştırma için servisleri ayrı terminallerde başlatın.

Altyapı servisleri:

cd C:\Users\Kadir\Desktop\TraceMind
docker compose --env-file infra/docker/.env --file infra/docker/docker-compose.yml up -d

Bu komut PostgreSQL/pgvector, Redis, opsiyonel RabbitMQ management UI, SonarQube, Jenkins, Elasticsearch ve Kibana servislerini başlatır. RabbitMQ bu aşamada opsiyonel altyapı gösterimidir; analyze pipeline aktif olarak RabbitMQ üzerinden çalışmaz.

Ollama:

ollama serve

Ollama zaten arka planda çalışıyorsa bu terminale gerek yoktur.

Backend API:

cd C:\Users\Kadir\Desktop\TraceMind
$env:ConnectionStrings__TraceMindDb="Host=localhost;Port=5432;Database=tracemind;Username=tracemind;Password=<local-password>"
$env:REDIS_CONNECTION="127.0.0.1:6379"
$env:TRACEMIND_CACHE_ENABLED="true"
$env:LOG_TO_ELASTICSEARCH="true"
$env:ELASTICSEARCH_URL="http://127.0.0.1:9200"
dotnet run --project apps/backend/src/TraceMind.Api --urls http://127.0.0.1:5180

FastAPI AI service:

cd C:\Users\Kadir\Desktop\TraceMind\apps\ai-service
.venv\Scripts\activate
uvicorn app.main:app --reload --port 8000

Frontend dev server:

cd C:\Users\Kadir\Desktop\TraceMind
npm run frontend:start -- --host 127.0.0.1 --port 4200

PWA production preview:

cd C:\Users\Kadir\Desktop\TraceMind
npm run build --workspace @tracemind/frontend -- --configuration production
npx http-server apps/frontend/dist/tracemind-frontend/browser -p 4300 -c-1

Servisler ve Portlar

Servis Port / adres Görev
PostgreSQL + pgvector localhost:5432 Analiz geçmişi, bilgi bankası dokümanları, parça kayıtları ve vektör temsil verileri
Redis localhost:6379 Güvenli retrieval metadata cache
RabbitMQ http://127.0.0.1:15672 Opsiyonel management UI; kullanıcı/şifre örnekleri infra/docker/.env.example içindedir
SonarQube http://127.0.0.1:9000 Yerel statik kod analizi
Jenkins http://127.0.0.1:8080 Yerel CI pipeline paneli
Jenkins agent port localhost:50000 Jenkins inbound agent bağlantıları
Elasticsearch http://127.0.0.1:9200 Backend structured log index'i
Kibana http://127.0.0.1:5601 Elasticsearch log arama ve inceleme paneli
Ollama http://127.0.0.1:11434 Yerel LLM ve embedding modeli
Backend API http://127.0.0.1:5180 OCR, retrieval, LLM ve kayıt orkestrasyonu
FastAPI AI service http://127.0.0.1:8000 Görsel işleme, OCR ve teknik sinyal çıkarımı
Frontend dev server http://127.0.0.1:4200 Angular geliştirme sunucusu
PWA preview http://127.0.0.1:4300 Production build statik ön izleme

Test ve Doğrulama

Build ve test komutları:

dotnet build TraceMind.sln
npm run frontend:test:coverage
npm run frontend:e2e:selenium
npm run build --workspace @tracemind/frontend -- --configuration production
docker compose --file infra/docker/docker-compose.yml config

Selenium testleri için önce Angular dev server çalışmalıdır:

cd C:\Users\Kadir\Desktop\TraceMind
npm run frontend:start -- --host 127.0.0.1 --port 4200

Farklı bir adres kullanılacaksa:

$env:E2E_BASE_URL="http://127.0.0.1:4200"
npm run frontend:e2e:selenium

Chrome'u görünür açmak için:

$env:E2E_HEADLESS="false"
npm run frontend:e2e:selenium

Teslim Kanıtları

Teslim kanıtları docs/evidence/ altında tutulur. Bu klasör kaynak koddan ayrıdır ve sahte ekran görüntüsü/video üretimi içermez; eksik görsel veya video kanıtları ilgili markdown dosyalarında manuel alınacak kanıt olarak belirtilir.

Kanıt Durum Dosya / hedef
SonarQube analiz özeti Rapor foundation hazır, dashboard screenshot'ları manuel alınır docs/evidence/sonarqube/sonarqube-report.md, hedef PNG'ler: docs/evidence/sonarqube/*.png
RabbitMQ management UI Opsiyonel management UI hazır; analyze pipeline RabbitMQ kullanmaz docs/evidence/rabbitmq/rabbitmq-evidence.md, panel: http://127.0.0.1:15672
Selenium UI test sonucu/video Test komutu ve sonuç notu hazır; video manuel kaydedilir docs/evidence/selenium/selenium-test-result.md, hedef video: docs/evidence/selenium/selenium-ui-test-recording.mp4
Jenkins local deploy kanıtı Local PWA Deploy stage'i local preview/package kanıtı üretir; cloud deploy değildir docs/evidence/jenkins/jenkins-local-deploy-result.md, docs/evidence/jenkins/real-local-deploy-setup.md, hedef video: docs/evidence/jenkins/jenkins-local-deploy-recording.mp4
Explainability smoke ORA-12154 açıklanabilirlik alanları gerçek endpoint ile doğrulandı docs/evidence/explainability/ora-12154-explainability-smoke.md
Root cause ranking smoke ORA-12154 kök neden aday sıralaması gerçek endpoint ile doğrulandı docs/evidence/troubleshooting-intelligence/ora-12154-root-cause-ranking.md

Evidence index:

docs/evidence/evidence-index.md

Sağlık kontrolleri:

Invoke-RestMethod -Uri "http://127.0.0.1:5180/api/health"
Invoke-RestMethod -Uri "http://127.0.0.1:8000/api/health"
Invoke-RestMethod -Uri "http://127.0.0.1:11434/api/tags"
docker exec tracemind-redis redis-cli ping
Invoke-RestMethod -Uri "http://127.0.0.1:9200"
Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:5601" | Select-Object -ExpandProperty StatusCode
Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:9000" | Select-Object -ExpandProperty StatusCode
Invoke-WebRequest -UseBasicParsing -Uri "http://127.0.0.1:8080" | Select-Object -ExpandProperty StatusCode

Backend SonarQube scan:

$env:SONAR_TOKEN="<local-sonar-token>"
dotnet tool restore

dotnet dotnet-sonarscanner begin `
  /k:"tracemind-backend" `
  /n:"TraceMind Backend" `
  /d:sonar.host.url="http://127.0.0.1:9000" `
  /d:sonar.token="$env:SONAR_TOKEN" `
  /d:sonar.exclusions="apps/frontend/**,apps/ai-service/**,node_modules/**,**/bin/**,**/obj/**"

dotnet build TraceMind.sln

dotnet dotnet-sonarscanner end `
  /d:sonar.token="$env:SONAR_TOKEN"

Frontend SonarQube scan:

$env:SONAR_TOKEN="<local-sonar-token>"
npm run frontend:test:coverage
npm run quality:sonar:frontend -- `
  "-Dsonar.host.url=http://127.0.0.1:9000" `
  "-Dsonar.token=$env:SONAR_TOKEN"

Jenkins notları:

  • Jenkins servisi Docker Compose ile http://127.0.0.1:8080 adresinde çalışır.
  • İlk admin password değeri yalnızca lokal kurulum ekranında kullanılmalı, README veya repoya yazılmamalıdır.
  • Sonar stage'leri SONAR_TOKEN yoksa güvenli şekilde skip edilir.
  • Selenium stage'i opsiyoneldir; RUN_UI_TESTS=true verilmedikçe çalışmaz.
  • RUN_LOCAL_DEPLOY=true verilirse Local PWA Deploy stage'i production PWA çıktısını deploy/frontend-pwa/ altına paketler. Bu yalnızca local preview/deploy kanıtıdır; cloud dağıtımı, registry push veya image publish değildir.

Bilgi Bankası

Geliştirme bilgi bankası manifest tabanlıdır:

  • Manifest: data/knowledge/manifest.dev.json
  • Kaynak dokümanlar: data/knowledge/raw/dev
  • Kapsanan alanlar: Oracle DB, Microsoft SQL Server, Linux/System, Network/Connectivity

Güncel kapsam:

Alan Doküman
Oracle DB 10
Microsoft SQL Server 10
Linux/System 10
Network/Connectivity 10

Bilgi bankasını içe aktar:

dotnet run --project apps/backend/tools/TraceMind.KbIngestion -- --manifest data/knowledge/manifest.dev.json

Vektör temsil üret:

dotnet run --project apps/backend/tools/TraceMind.KbIngestion -- --generate-embeddings --batch-size 10

Vektör temsilleri zorla yenile:

dotnet run --project apps/backend/tools/TraceMind.KbIngestion -- --generate-embeddings --force --batch-size 10

Faydalı veritabanı kontrolleri:

docker exec -i tracemind-postgres psql -U tracemind -d tracemind -c "SELECT COUNT(*) FROM knowledge_documents;"
docker exec -i tracemind-postgres psql -U tracemind -d tracemind -c "SELECT COUNT(*) FROM knowledge_chunks;"
docker exec -i tracemind-postgres psql -U tracemind -d tracemind -c "SELECT COUNT(*) FROM knowledge_chunks WHERE embedding IS NOT NULL;"

Manuel Test Seti

Manuel test seti sentetik ekran görüntülerinden oluşur:

  • Görseller: data/testsets/manual/screenshots
  • Beklenen sonuçlar: data/testsets/manual/ground-truth/manual-testset-v1.json
  • Detaylı rapor: docs/manual-testset-v1-report.md

Güncel sette 40 PNG bulunur:

Kategori Adet
Oracle 10
SQL Server 8
Linux 8
Docker 6
Network 8

Test setini yeniden üret:

python data/testsets/manual/generate_manual_testset_v1.py

Örnek analiz görseli:

data/testsets/manual/screenshots/oracle/oracle-001-ora-12154.png

API Örnekleri

Görsel analiz:

curl.exe -X POST "http://127.0.0.1:5180/api/analysis/image" `
  -F "image=@data/testsets/manual/screenshots/oracle/oracle-001-ora-12154.png" `
  -F "userPrompt=Kök nedeni ve çözüm adımlarını açıkla." `
  -F "domainHint=Oracle DB"

Analiz geçmişi:

curl.exe "http://127.0.0.1:5180/api/analysis/logs?pageNumber=1&pageSize=20"
curl.exe "http://127.0.0.1:5180/api/analysis/logs/{id}"

Bilgi bankası arama:

curl.exe -G "http://127.0.0.1:5180/api/knowledge/search" `
  --data-urlencode "query=ORA-12154" `
  --data-urlencode "domain=Oracle DB" `
  --data-urlencode "topK=5"

Güvenlik ve Gizlilik Notları

  • Gerçek connection string, parola, API key, token, private key veya DSN değeri repoya eklenmez.
  • README'deki secret alanları placeholder olarak gösterilir; gerçek lokal değerler yazılmaz.
  • infra/docker/.env.example yalnızca örnektir; yerel infra/docker/.env dosyası commitlenmemelidir.
  • apps/ai-service/.env oluşturulabilir, fakat gerçek değerlerle repoya eklenmemelidir.
  • Sentry DSN env/deploy ortamından verilmelidir; frontend ve backend varsayılanları DSN boşken güvenli çalışır.
  • Sonar token SONAR_TOKEN env değişkeni veya Jenkins credential olarak kullanılmalıdır; token dosyalara yazılmaz.
  • Jenkins admin password, API token ve credential değerleri repo dosyalarına eklenmez; Jenkins credentials store kullanılır.
  • OCR ham tam metni, LLM prompt'u ve tam LLM cevabı structured log, Sentry event veya Elasticsearch kaydı olarak tutulmaz.
  • Upload edilen screenshot binary içeriği cache veya log yapılmaz.
  • Redis yalnızca güvenli retrieval metadata cache için kullanılır; screenshot, prompt, token, cookie veya connection string cache edilmez.
  • Authorization header, cookie, token, DB connection string, request body ve kullanıcı local path bilgileri log filtrelerinden geçirilir.
  • Test ve bilgi bankası içeriklerinde password, token, secret gibi kelimeler sentetik arıza çözüm metni olarak geçebilir; bunlar gerçek kimlik bilgisi değildir.

Gözlemlenebilirlik

Sentry

Sentry frontend çalışma zamanı hataları ve backend exception takibi için temel seviyede entegredir. Üretim DSN'i repoya yazılmaz.

Backend ayarları:

$env:SENTRY_DSN="<sentry-dsn>"
$env:Sentry__TracesSampleRate="0"
$env:Sentry__EnableInDevelopment="false"
$env:Sentry__EnableDebugEndpoint="false"

Debug endpoint varsayılan olarak kapalıdır. Açıldığında /api/debug/sentry-test kontrollü backend test uç noktası olarak kullanılabilir. Frontend tarafında debug route varsayılan olarak kapalıdır.

Elasticsearch ve Kibana

Backend loglarını Elasticsearch'e göndermek için:

$env:LOG_TO_ELASTICSEARCH="true"
$env:ELASTICSEARCH_URL="http://127.0.0.1:9200"
$env:ELASTICSEARCH_INDEX="tracemind-backend-dev"

Backend tarafında şu analyze olayları structured metadata olarak loglanır:

  • analysis_started
  • ocr_completed
  • error_code_extracted
  • retrieval_cache_hit
  • retrieval_cache_miss
  • llm_completed
  • history_persisted
  • analysis_failed

Index kontrolü:

Invoke-RestMethod -Uri "http://127.0.0.1:9200/_cat/indices?v"

Analyze event arama örneği:

Invoke-RestMethod `
  -Uri "http://127.0.0.1:9200/tracemind-backend-dev/_search?q=message:analysis_started&pretty"

AI service doğrudan Elasticsearch client kullanmaz; FastAPI console loglarını JSON formatına normalize eder. Bu loglar ileride Docker log collector, Filebeat veya Logstash ile Elasticsearch'e alınabilir.

Redis Önbellek Altyapısı

Redis, analiz pipeline içindeki bilgi erişimi sonucunu kısa süreli cache etmek için kullanılır. Aynı domain ve hata kodu için tekrar eden sorgularda bilgi bankası arama sonucu cache üzerinden dönebilir.

Backend ayarları:

$env:REDIS_CONNECTION="127.0.0.1:6379"
$env:TRACEMIND_CACHE_ENABLED="true"

Alternatif ayar yolu:

{
  "Cache": {
    "Enabled": true,
    "Connection": "127.0.0.1:6379",
    "KeyPrefix": "tracemind:",
    "RetrievalTtlMinutes": 20
  }
}

Cache kapsamı:

  • Cache edilen alan: bilgi erişimi sonucundaki güvenli bilgi bankası parça metadatası.
  • Cache anahtarı: tracemind: prefix'i, domain, hata kodu ve güvenli hata ifadesi özetinden türetilen hash.
  • TTL: varsayılan 20 dakika.
  • Gözlemlenebilirlik: backend loglarında retrieval cache hit/miss görülebilir; analiz yanıtında cacheUsed ve retrievalCacheHit alanları opsiyonel dönebilir.

SonarQube Kod Kalitesi Altyapısı

SonarQube, yerel statik kod analizi için foundation sağlar. Runtime monitoring değildir; çalışan uygulama hatalarını izlemez. Kod kalitesi, maintainability, olası bug riskleri, tekrar eden kod ve temel güvenlik kokularını görünür hale getirir.

Panel:

http://127.0.0.1:9000

İlk kurulumda SonarQube arayüzünden proje token'ı oluşturun ve token'ı yalnızca env veya Jenkins credential üzerinden kullanın. Gerçek token repo içine yazılmamalıdır.

Frontend scan apps/frontend/sonar-project.properties ve apps/frontend/tsconfig.sonar.json dosyalarını kullanır. Coverage import için apps/frontend/coverage/tracemind-frontend/lcov.info beklenir.

Bu foundation quality gate zorlaması, PR decoration, SonarCloud veya enterprise branch stratejisi içermez. FastAPI AI servisi Python scan kapsamına alınmamıştır.

Jenkins CI/CD Altyapısı

TraceMind, yerel CI pipeline foundation için Jenkins LTS servisi ve repo kökünde Jenkinsfile içerir. Pipeline build, test, coverage, kalite analizi hazırlığı ve Docker Compose yapı doğrulamasını tek akış altında toplar.

Jenkinsfile stage'leri:

  • Checkout
  • Environment Info
  • Restore .NET Tools
  • Backend Build
  • Frontend Install
  • Frontend Test Coverage
  • Frontend Production Build
  • Selenium UI Smoke Tests
  • Frontend SonarQube Scan
  • Backend SonarQube Scan
  • Local PWA Deploy
  • Docker Compose Config Check

Selenium UI stage'i opsiyoneldir. Jenkins job ortamında RUN_UI_TESTS=true verilmedikçe çalışmaz. Çalıştırılacaksa Jenkins agent üzerinde Chrome/Chromium bulunmalı ve E2E_BASE_URL erişilebilir bir Angular dev server veya statik preview adresini göstermelidir.

SonarQube stage'leri opsiyoneldir. Jenkins job ortamında SONAR_TOKEN yoksa güvenli şekilde skip edilir. Token kullanmak için Jenkins credential oluşturulmalı ve pipeline ortamına SONAR_TOKEN olarak bağlanmalıdır.

Bu foundation Docker socket mount etmez, image publish etmez, artifact registry kullanmaz, Kubernetes veya cloud deploy kurmaz. RUN_LOCAL_DEPLOY=true verilirse Local PWA Deploy stage'i production PWA çıktısını deploy/frontend-pwa/ klasörüne paketler. Bu yalnızca local preview deploy kanıtı içindir; cloud deploy, Docker image publish veya canlı ortam yayını değildir.

Bilinen Sınırlamalar

  • AI service logları Elasticsearch'e doğrudan gönderilmez; JSON console logging foundation vardır.
  • Hazır Kibana dashboard paketi yoktur; data view ve aramalar manuel oluşturulur.
  • Jenkins pipeline cloud deploy yapmaz; RUN_LOCAL_DEPLOY=true ile local PWA deploy/package kanıtı üretir.
  • Selenium UI testi smoke test foundation seviyesindedir; tam uçtan uca iş akışı kapsamı değildir.
  • Ollama model yükleme ve inference latency değeri yerel donanıma göre yüksek olabilir.
  • Enterprise auth, SSO, çok kiracılı yapı ve production secret management tamamlanmamıştır.
  • PWA offline durumda AI/OCR/RAG çalıştırmaz; yalnızca kurulabilir frontend kabuğu sağlar.
  • Bilgi bankası seçilmiş markdown dosyalarından oluşur; canlı dış kaynak senkronizasyonu yoktur.
  • Manuel test setindeki ekran görüntüleri sentetiktir ve tekrarlanabilir yerel değerlendirme için kullanılır.

Yol Haritası

  • Üretim ortamı için kimlik doğrulama ve yetkilendirme.
  • Sentry release, sourcemap ve alarm yönetiminin sıkılaştırılması.
  • Kibana dashboard ve log collector entegrasyonu.
  • AI service için ayrı Python kalite analizi.
  • Bilgi bankası yönetim ekranı.
  • Daha geniş domain kapsamı ve gerçek vaka tabanlı test setleri.
  • Deploy ve artifact publish akışlarının ayrıca tasarlanması.

RabbitMQ management UI

RabbitMQ servisi teslim kanıtı için gerçek management UI sağlayan opsiyonel altyapı olarak eklenmiştir. Uygulamanın analyze pipeline'ı bu aşamada RabbitMQ kullanmaz ve herhangi bir mesaj kuyruğu entegrasyonu yapılmış gibi sunulmamalıdır. Yerel panel: http://127.0.0.1:15672. Kullanıcı adı ve şifre için infra/docker/.env.example içindeki örnek RABBITMQ_DEFAULT_USER ve RABBITMQ_DEFAULT_PASS değerleri kullanılabilir; gerçek secret repo dosyalarına yazılmaz.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages