sp/RUNBOOK.md

Süper Panel Runbook

Founder operasyon kılavuzu. Telegram alert → ne yapacağın matrisi.

---

Telegram alert geldiğinde

🔴 VIN decode anomaly: success_rate_drop

Sase decode başarı oranı son 15dk'da baseline'ın altında.

1. sp.semih.ai → Bugün sayfasına bak: 24h success delta + recent regressions
2. sp.semih.ai/projects/sase/vin-decode → P95, error breakdown, provider performans
3. Error breakdown kartında en sık hata bucket'ına tıkla → drill-down
4. Hangi provider/brand etkilenmiş? Drill-down'da görünür
5. /projects/sase/vin-decode/trends → bu provider/marka düştü mü histor ic?
6. Eğer deploy regression ile çakışıyorsa → bir sonraki bölüme bak

🔴 VIN regression after deploy

Sase.tr deploy sonrası 30dk içinde success rate ≥10pp düştü.

1. Mesajdaki commit SHA'sına bak: Deploy 5b26d10b: 94.2% → 81.3%
2. Gitea'da o commit'i aç: git.semih.ai/root/sase.tr/commit/<sha>
3. Roll back kararı: değişiklik küçük ve net ise revert PR aç; büyükse ileriye doğru fix
4. Acil revert: Gitea API ile yeni branch'te git revert -m 1 <merge-sha> → PR → merge → Coolify auto-deploy
5. /projects/sase/vin-decode → 5-10dk sonra success rate düzelmesini doğrula

🟡 VIN decode anomaly: p95_latency_spike

P95 yanıt süresi baseline'ın 2-3 katı.

1. /projects/sase/vin-decode → provider attempts kartı: hangi provider yavaş?
2. /providers/[name] → o provider'ın günlük trendi
3. Sase.tr loglarında o provider'a özgü timeout/error pattern'i var mı (Coolify panel)
4. PL24 circuit breaker tetiklendiyse otomatik açılır (30s), tekrarlı oluyorsa upstream sorun

🟡 VIN decode anomaly: volume_drop

Son 15dk'da volume baseline'ın -80% altında. Olası outage sinyali.

1. sase.tr erişilebilir mi? curl/browser
2. Sase.tr Coolify status (cool.semih.ai)
3. Frontend hata mı veriyor (kullanıcılar erişip sorgu yapamıyor)?
4. CloudFlare/Traefik routing sorunu mu?

🟡 VIN decode anomaly: volume_spike

Son 15dk'da volume baseline'ın 5x'i. Fraud veya viral.

1. /projects/sase/users → "Son 7g aktif" filtrele, yeni kayıt sayısı normal mi?
2. Tek bir kullanıcı mı patlattı (queryCount30d sırala): /projects/sase/vin-decode/business → Power users
3. Tek bir IP/UA pattern'i var mı (audit log'a bak)
4. Fraud ise: kullanıcı detayında [Ban] veya [Suspend]

🟡 VIN decode anomaly: timeout_dominance

Hatalarin ≥%50'si timeout. Bir provider çökmüş gibi davranıyor.

1. /projects/sase/vin-decode → provider attempts: hangi provider'ın p95'i yüksek?
2. O provider'ı drill-down et: /providers/[name]
3. Geçici çözüm: Sase.tr'de PL24 circuit breaker zaten var; manuel müdahale şart değil
4. Uzun süreliyse upstream provider ile iletişim (PCAT/PL24 destek)

---

Founder daily review (sabah 08:00)

sp.semih.ai/ → Bugün sayfası. Sırayla:

1. Üst KPI strip: Sase 24h success + delta vs prior 24h
2. "Bugün bakmam gerekenler" action list — kritik/high item'lara tıkla
3. Açık insight kartı: P0/P1 varsa /insights?severity=P0 aç
4. Son admin aksiyonlar: Senin yapmadığın bir aksiyon var mı? (Tek founder ortamında olmamalı)
5. Sase user health: Dormant payer 10+ mı? → retention kampanyası tetiklenmeli
6. Recent deploys: Regression var mı? Varsa fix loop'a gir

Türetilebilir metrik (henüz dashboard'da yok):

• Daily Brief Telegram'ı sabah 08:00'de geliyor (apps/worker/src/jobs/daily-brief.ts). İçeriği: cost + insight özeti.

---

Pipeline / cron sağlığı

Aktif cron'lar (apps/worker/src/schedulers/pipeline.ts):

Job	Cadence	Ne yapar
posthog-ingest	*/5min	PostHog'tan session event'leri çekip BIP'e besler
tag-sessions	*/2min	Yeni session'lara tag uygula
compress-sessions	*/3min	Tag'li session'ları timeline+sanitize ederek MinIO'ya kaydet
analyze	*/4min	LLM analizi (DeepSeek), insight üret
validation	05:00 UTC	Shipped insight'ları 14d sonra validate/regression
github-sync	*/10min	Gitea issue state'lerini insight'lara yansıt
retention	04:15 UTC	Eski session/MinIO/custom-event temizlik
daily-brief	05:00 UTC (08:00 İstanbul)	Telegram daily cost+insight özeti
vin-anomaly-detect	*/5min	Sase VIN decode anomalies + deploy regression check

Cron çalışmıyor mu kontrolü:

• Coolify → panel-worker container log'larını izle
• Son [pipeline] X log'larından her cron'un en son ne zaman fire ettiği görünür
• BullMQ schedulers Redis'te (panel-redis); restart sonrası upsertJobScheduler otomatik kurulur

---

Coolify hızlı referans

App	UUID	Branch	Build pack
panel-web	os0w8sks8soo8k04cs0gg80k	main	Dockerfile
panel-worker	jk8gsg04w0kwo4sc4s84k8cc	main	Dockerfile
sase.tr	ro48g8ooo0gk4kskog0oo8s8	main	Docker compose

Deploy tetikle:

TOKEN=<coolify_token>
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://cool.semih.ai/api/v1/deploy?uuid=<app-uuid>"

Env değişikliği sonrası: Coolify env edit sonra deploy gerekir. Bazı env'ler runtime, bazıları build-time (Coolify UI'da işaretli).

---

Çağrı zinciri: kullanıcı raporu → fix

Tipik akış:

1. Müşteri Telegram/WhatsApp ile "VIN sorgusu çalışmıyor" diyor
2. sp.semih.ai/projects/sase/users → email/isim ile bul
3. User detay → Aktivite sekmesi: son ne yaptı, hangi VIN, ne zaman
4. Audit sekmesi: kendi yaptığım bir aksiyon mu durumu tetikledi (suspend gibi)?
5. Gerekirse Impersonate (read-only) → 15dk yeni sekmede o user olarak Sase.tr'ye bak
6. Sorunu repro ettiysen: ya direkt fix (panel'den lifecycle/billing aksiyon), ya da Sase.tr code change
7. Geri dönüş: notes sekmesinde olay özeti

---

Güvenlik

• Panel sadece Tailscale ile erişilir (sp.semih.ai Cloudflare Tunnel arkasında Tailscale-tag'li)
• Founder login: Better Auth + TOTP zorunlu (/settings üzerinden TOTP yönetimi)
• Sase.tr admin token'ları: INTERNAL_API_TOKEN Coolify env'de; paneldeki log'lara basılmaz
• Impersonation: read-only, 15-60dk TTL, mutation isteği → 403; cookie HMAC-imzalı (Better Auth uyumlu)
• Mutasyonel her aksiyon audit_log'a yazılır (panel-pg) + Sase.tr-side de log'lanır (double audit)

---

Geliştirme

Local:

cd /home/s/sp
pnpm i
pnpm --filter @panel/web dev   # port 3000
pnpm --filter @panel/worker dev

Build verify:

pnpm --filter @panel/web build
pnpm --filter @panel/web exec tsc --noEmit
pnpm --filter @panel/worker exec tsc --noEmit

Schema değişikliği (panel-pg):

# Edit apps/web/prisma/schema.prisma
# `start` scripti `prisma db push` çalıştırıyor — deploy yeterli
# Sase RO için:
pnpm --filter @panel/web exec prisma generate --schema=prisma/sase/schema.prisma

Yeni Sase.tr admin endpoint:

1. Sase.tr apps/api/src/internal-admin/<feature>.controller.ts + service
2. InternalTokenGuard ekle: @UseGuards(InternalTokenGuard) + @Public()
3. Panel: apps/web/src/lib/admin-sdk/sase.ts SaseAdmin interface + impl
4. Panel: /api/sase/... route handler + auth check
5. Panel: UI client component + page mount