kolaytercih/docs/veri/yillik-guncelleme.md

Yıllık veri güncellemesi (YÖK Atlas → data/yokatlas.db)

Her yıl yerleştirme sonuçları açıklandıktan sonra bir kez yapılır. Bu sayfayı yukarıdan aşağıya izleyen biri, betiklerin içini bilmeden güncellemeyi tamamlayabilir. Toplam süre: yaklaşık 30 dakika (çoğu bekleme ve gözle kontrol).

Ürünün bütün değeri bu verinin doğruluğuna dayanır. Yanlış bir taban sıralaması, bir öğrencinin yanlış tercih yapması demektir. Bu yüzden betikler şüphede durur; "DURDU:" ile başlayan bir mesaj hata değil, emniyet kilididir. Kilidi aşmaya çalışma — mesajı oku, aşağıdaki "Bir şey durursa" tablosuna bak.

Örneklerde yeni yıl 2027 diye yazıldı; o yıl hangisiyse onu yaz.

0. Ne zaman?

• ÖSYM yerleştirme sonuçlarını açıklar (genelde Ağustos sonu), YÖK Atlas verisini birkaç gün–birkaç hafta sonra günceller. Tarih her yıl değişir → doğrulanmalı.
• Erken koşmanın zararı yok: YÖK Atlas henüz güncellenmediyse 3. adım "… hâlâ 2026 verisi" diyerek hiçbir şey yazmadan durur. Bir hafta sonra tekrar dene.
• Dosya indirmen gerekmez. Veri, YÖK Atlas'ın herkese açık tercih kılavuzu servisinden (https://yokatlas.yok.gov.tr/api/tercih-kilavuz/search) betikle çekilir: 43 istek, aralarında yarım saniye — kaynağı yormaz. Betiği art arda defalarca koşma; ilk çekimden sonra hep kaydedilmiş ham dosyayı (--ham) kullan.

1. Hazırlık (5 dk)

git switch -c veri/2027            # main'de çalışma

src/lib/veri-yillari.ts dosyasında tek satırı değiştir:

export const SON_YIL = 2027;

Betikler ve site yılı yalnız buradan okur. Betiğe verdiğin --yil bununla aynı değilse betik durur (yanlış kolona yazmayı önler).

2. Kopya al — asıl dosyaya dokunma (1 dk)

Dev sunucusu açıksa kapat. Sonra:

mkdir -p /tmp/veri-2027
sqlite3 data/yokatlas.db ".backup '/tmp/veri-2027/once.db'"     # güncelleme ÖNCESİ hâl (geri dönüş + karşılaştırma)
cp /tmp/veri-2027/once.db /tmp/veri-2027/yeni.db                # üzerinde çalışılacak kopya

Bundan sonraki her adım /tmp/veri-2027/yeni.db üzerinde koşar. data/yokatlas.db ancak 8. adımda, her şey yeşilken değişir.

3. Yeni yılı çek (3 dk)

pnpm refresh --yil 2027 --db /tmp/veri-2027/yeni.db

Ne yapar: şemaya sira2027/puan2027/kontenjan2027/yerlesen2027 kolonlarını ekler, yıl kilidini sınar, tüm kılavuzu çeker, ham hâlini data/ham/2027-<tarih>.jsonl.gz olarak saklar (git'e girmez), sonra tek seferde DB'ye yazar.

Görmen gerekenler:

Yıl kilidi: basariSirasi1 = sira2026 → 480/480 (%100.0); eksiz basariSirasi = sira2026 → 0/480 (%0.0)
Çekilen: 21… kayıt, benzersiz kod: 21…, kodsuz: 0, API toplamı: 21…      ← üç sayı aynı
Güncellenen: 19…, eklenen: 1…, atlanan: 0

• Yıl kilidi şunu kanıtlar: servisin "bir önceki yıl" diye verdiği sıralar bizim 2026 kolonumuzla birebir aynı ve "bu yıl" diye verdikleri ondan farklı. Yani yazacağımız veri gerçekten 2027'dir. (Servisteki yil alanına güvenilmez; 2026'da bu alan yüzünden 2025 verisi bozulmak üzereydi.)
• "atlanan" 0 değilse satırlar altında listelenir: kaynağın puan türü vermediği yeni programlardır; uydurulmaz. Sayıyı not et.
• Bu betik mevcut programların eski yıl kolonlarına dokunmaz; dokunursa kendi sağlaması bunu yakalar ve her şeyi geri alır.

Aynı işlemi servise gitmeden tekrarlamak için (ör. 8. adımda): pnpm refresh --yil 2027 --db <db> --ham data/ham/2027-<tarih>.jsonl.gz

4. Geçmiş boşluklarını doldur (1 dk)

pnpm gecmis-doldur --yil 2027 --db /tmp/veri-2027/yeni.db

Kılavuz kodu değişen ya da yeni koda taşınan programların eski yıllarını tamamlar. Yalnız boş alanı doldurur; dolu değeri asla ezmez, tahmin yapmaz. Kaynak sırası: servisin kendi geçmiş alanları → servisin bildirdiği eski kod → aynı üniversitede bire bir aynı adlı ve en az bir yılı kanıtla örtüşen tek satır.

Çıktının sonundaki "Dolu olup kaynağın FARKLI söylediği alanlar" listesine bak. Birkaç onluk fark olağandır (kaynak eski sıraları ufak düzeltmelerle yeniden yayımlıyor; 2026'da sira2024 farklarının %95'i on binde birin altındaydı). Binlerce satırda büyük fark görürsen dur ve veri mühendisine sor.

5. Kılavuzdan çıkan programlar: önce sadece raporla (1 dk)

pnpm eski-arsivle --yil 2027 --db /tmp/veri-2027/yeni.db --kuru

Hiçbir şey yazmaz. Şunu söyler: bu yılın kılavuzunda olmayan kaç satır var ve bunlar siteden kalkarsa hangi /bolum/... ve /universite/... sayfaları tamamen kapanır (adlarıyla). Bu liste [BİLAL] kararıdır — sayfa kapanışı SEO'yu etkiler, gerekirse yönlendirme (redirect) eklenir.

Onaydan sonra gerçek taşıma (silmez; satırlar programs_arsiv tablosuna geçer):

pnpm eski-arsivle --yil 2027 --db /tmp/veri-2027/yeni.db

Neden gerekli: arşivlenmezse eski kodlu satırlar listelerde bir yıl önceki sırayla görünmeye devam eder; öğrenci o kodu tercih ekranında bulamaz, kodu değişen program iki kez listelenir.

6. İndeks + dosyayı toparla (1 dk)

pnpm db:index --db /tmp/veri-2027/yeni.db --vacuum

Son satırda USING INDEX idx_programs_tur_onlisans_efektif yazmalı. Yazmıyorsa betik zaten hata verir: sitedeki sıralama aralığı sorguları yavaşlar.

7. Kalite kapısı (1 dk)

pnpm veri-kalite --yil 2027 --db /tmp/veri-2027/yeni.db --onceki /tmp/veri-2027/once.db --arsivli
echo "çıkış kodu: $?"        # 0 olmalı

(--arsivli'yi yalnız 5. adımda gerçek arşivlemeyi yaptıysan ekle.)

• Her satır GEÇTİ, KALDI, UYARI ya da bilgi ile başlar. Tek bir KALDI varsa yayına çıkılmaz; çıkış kodu 1 olur.
• En önemli iki satır:
  • önceki DB: geçmiş yıllar korunmuş — … değişen/silinen satır: 0
  • sira2027/sira2026 ∈ [0,5; 2] — … (%9x) — programların büyük çoğunluğunun sırası bir yılda yarıya inmez, iki katına çıkmaz. Oran düşükse yıllar kaymıştır.
• UYARI'lar bilgilendirir (ör. ili boş 110 program, yetim net satırları); yeni bir uyarı türü ya da sayıda sıçrama varsa veri mühendisine göster.

Elle 3 program seç (biri çok bilinen: ör. Boğaziçi Bilgisayar Mühendisliği), YÖK Atlas sitesindeki 2027 taban sırasıyla karşılaştır:

sqlite3 /tmp/veri-2027/yeni.db "SELECT id, universite, isim, sira2026, sira2027, puan2027 FROM programs WHERE isim LIKE 'Bilgisayar Mühendisliği%' AND universite LIKE 'BOĞAZİÇİ%';"

8. Yerine koy ve siteyi kontrol et (5 dk)

cp /tmp/veri-2027/yeni.db data/yokatlas.db
rm -f data/yokatlas.db-wal data/yokatlas.db-shm      # eski dosyanın artıkları; yenisi temiz (checkpoint yapılmış)
pnpm build                                           # katalog sayfaları yeni veriden üretilir; hata vermemeli

Netler (yerleşen son kişinin netleri) ayrı bir servisten gelir ve genelde daha geç güncellenir; hazır olduğunda:

pnpm detay --yil 2027 --db data/yokatlas.db          # ~127 istek, ~2 dk; yıl sağlaması tutmazsa durur

--kirilim bayrağını kullanma: kontenjan kırılımını (okul birincisi, şehit-gazi…) sitede okuyan kod yok ve servis bu alanları Eylül 2026'dan beri yayımlamıyor. Bayrak verilse bile alanlar yoksa adım kendini durdurur, mevcut değerlerin üstüne boş yazmaz.

Yıl değişince koddaki metinler ("son 6 yıl", başlıklardaki yıl vb.) veri-yillari.ts sabitlerinden türediği için kendiliğinden güncellenir. Elle yıl yazılmış yer kaldıysa bul:

grep -rnE "sira20[0-9]{2}|20(2[1-9])[–-]20" src scripts --include='*.ts' --include='*.tsx' | grep -v veri-yillari

Tadımlık havuzu ve kayıtlı raporlar eski sıralarla üretilmiştir → yayından sonra prod'da pnpm tadimlik --force (Bilal koşar; ayrıntı scripts/tadimlik-uret.ts başlığında).

9. Commit ve yayın

git add src/lib/veri-yillari.ts data/yokatlas.db
git commit -m "veri: 2027 yerleştirme verisi"

data/ham/ git'e girmez (yerelde sakla; bir sonraki yıl karşılaştırma için işe yarar). Push öncesi AGENTS.md'deki "Push öncesi build zorunlu" kuralı geçerli. Yayın kararı Bilal'in.

Geri alma

Ne zaman	Nasıl	Süre
8. adımdan önce	Hiçbir şey yapma; data/yokatlas.db hiç değişmedi. /tmp/veri-2027/ silinebilir.	0
8. adımdan sonra, commit'ten önce	git checkout -- data/yokatlas.db data/yokatlas.db-wal data/yokatlas.db-shm	1 dk
Commit/yayından sonra	git revert <commit> + yeniden yayın. SON_YIL da aynı commit'te geri döner; site bir önceki yılın verisiyle tutarlı çalışır.	10 dk
Yalnız arşivlemeyi geri almak	INSERT INTO programs SELECT * FROM programs_arsiv; DELETE FROM programs_arsiv; (kopyada dene, sonra pnpm db:index). Netler yeni kodda kalır; zararsız.	5 dk

/tmp/veri-2027/once.db dosyasını yayından bir hafta sonrasına kadar silme.

Bir şey durursa

Mesaj	Anlamı	Ne yap
--yil … ≠ SON_YIL	1. adım atlanmış	veri-yillari.ts'i güncelle
eksiz alanları hâlâ <geçen yıl> verisi	YÖK Atlas henüz yeni yılı yayımlamamış	Bekle, bir hafta sonra tekrar dene
"…1" alanları DB'deki … verisiyle eşleşmiyor	Servis bir yıl daha ilerlemiş (bir yılı atladık) ya da servis biçim değiştirmiş ya da yanlış DB	Yazma. Veri mühendisine göster
Benzersiz kod sayısı … ≠ API toplamı	Çekim sırasında servis sayfaları kaydırdı	Birkaç dakika sonra 3. adımı tekrarla (DB'ye bir şey yazılmadı)
Aynı üniversitede birden fazla unitur	Bir kurumun türü iki farklı yazılmış	Listelenen kurumları veri mühendisine göster; scripts/unitur-onar.ts
Güncel satır sayısı … refresh kaydıyla uyuşmuyor (arşivle)	refresh yarım kalmış	3. adımı tekrarla; arşivleme bilerek çalışmıyor
veri-kalite içinde KALDI	O kontrol tutmadı	Yayına çıkma; satırdaki sayıyı ve örnek kodları veri mühendisine ilet

Betikler ve dokundukları

Betik	Yazar mı?	Ne yazar
scripts/yokatlas-goc.ts (pnpm yokatlas:goc)	evet	Yalnız şema: yıl kolonları, son_kilavuz_yili, eski_kod, programs_arsiv, veri_meta. refresh bunu kendisi çağırır.
scripts/refresh.ts	evet	sira/puan/kontenjan/yerlesen<yıl>, son_kilavuz_yili, eski_kod; yeni programlar; ham dosya
scripts/gecmis-doldur.ts	evet	Yalnız NULL geçmiş yıl alanları + eski_kod
scripts/eski-arsivle.ts	--kuru ile hayır	Satır taşıma programs → programs_arsiv; netler.program_id yeni koda
scripts/db-index.ts	evet	İndeks, --vacuum, WAL checkpoint
scripts/veri-kalite.ts	hayır	Salt okunur; çıkış kodu 0/1
scripts/detay.ts	evet	netler; --kirilim ile (alanlar varsa) bir önceki yılın kırılım kolonları

Kolon sözlüğü: son_kilavuz_yili = programın görüldüğü son tercih kılavuzu (NULL = 2024 ve öncesi, bilinmiyor). eski_kod = kılavuz kodu değiştiyse bir önceki kod — kayıtlı listelerdeki eski kodları yeni koda çevirmek için SELECT id FROM programs WHERE eski_kod = ?.