d0f0cadf51
Phase 7 (user mgmt, all of A–F) and Phase 8 (VIN observability Faz 1–4 + regression alert) are shipped. Teknikborc previously listed many of those as open — clean it up and section the remaining work into: - Phase 7 still-open items (support actions, KVKK, sessions, bulk ops, automation) — explicitly listed at top - Phase 8 still-open items (alert config UI, vin_anomaly_log table, pointing to RUNBOOK.md for documentation) - PRD ↔ Sase.tr reality gaps (EFT killed, B2B doesn't exist, etc.) - Defansif teknik borç (super_panel_reader rol, prisma db push multi-replica risk, pre-existing Sase.tr typecheck errors) - Sase.tr-side work (Faz 0+1 PostHog events; notes that the backend VIN telemetry was tried and reverted because query_logs already has everything we need) - BIP open work (P1 fix, eval golden set, pattern bundle, embedding similarity, multi-project routing) - Minor / low priority polish items RUNBOOK.md is new: founder operations guide. Sections: - Telegram alert → response matrix (success drop, regression, p95 spike, volume drop/spike, timeout dominance) - Founder daily review walkthrough (the / "Bugün" page sequence) - Pipeline/cron health (job cadences + how to check) - Coolify quick reference (app UUIDs + deploy command) - User report → fix call chain - Security model summary - Local dev + new endpoint scaffolding steps Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
181 lines
7.2 KiB
Markdown
181 lines
7.2 KiB
Markdown
# 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:**
|
||
```bash
|
||
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:
|
||
```bash
|
||
cd /home/s/sp
|
||
pnpm i
|
||
pnpm --filter @panel/web dev # port 3000
|
||
pnpm --filter @panel/worker dev
|
||
```
|
||
|
||
Build verify:
|
||
```bash
|
||
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):
|
||
```bash
|
||
# 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
|