neta/docs/self-hosted-redesign/i18n-phase-0/migration-contract.md

title, description, phase, status, last_updated

title	description	phase	status	last_updated
Faz 0 Migration ve Geri Donus Sozlesmesi	Cok dillilik calismasi icin expand/migrate/contract sirasi ve backup kurallari.	0	completed	2026-07-19

Faz 0 Migration ve Geri Donus Sozlesmesi

Bu sozlesme Faz-1'den itibaren veritabani degisikliklerinin nasil yapilacagini tanımlar. Neta self-host bir urun oldugu icin migration'lar veri kaybi riski tasimamali ve rollback hikayesi basit kalmalidir.

Uygulama sirasi

1. Expand

Yeni tablolar ve yeni nullable kolonlar eklenir. Mevcut kolonlar kaldirilmaz, renamelenmez ve zorunlu hale getirilmez.

2. Backfill

Mevcut Turkce veriler instance default locale'i kabul edilerek content_translations icine kopyalanir. Orijinal kolonlar okunabilir kalir.

3. Dual read

Okuma katmani once translation resolver'a bakar, eksikse mevcut kolona duser. Bu asamada eski veriler ve yeni veriler ayni anda calisir.

4. Dual write

Formlar instance default locale alanini hem mevcut kolona hem translation tablosuna yazar. Ek locale'ler sadece translation tablosuna yazilir.

5. Contract

Ancak en az bir release sonra eski kolonlarin kaldirilmasi veya tamamen internal fallback haline getirilmesi tartisilir. Ilk cok dillilik fazlarinda contract adimi yapilmayacak.

Backup adimlari

Her schema migration oncesi:

pnpm db:backup

Backup dosyasi deploy notuna yazilmalidir. Dokploy veya Docker deploy'da volume path'i kontrol edilmeden migration calistirilmamalidir.

Geri donus adimlari

Migration sonrasi kritik hata varsa:

1. Uygulama yeni surumden onceki image/commit'e geri alinir.
2. SQLite dosyasi backup'tan restore edilir.
3. pnpm db:restore <backup-file> veya host tarafindaki manuel restore adimi kullanilir.
4. Restore sonrasi pnpm phase9:smoke ile health/API temel davranisi kontrol edilir.

Faz bazli DB dokunuslari

Faz	DB degisikligi	Risk	Not
Faz-1	Locale ve translation tablolari, clients.portal_locale, portal_invitations.locale, preference check constraint genisletme	Orta	Expand only.
Faz-2	DB yok veya yalnizca katalog version seed'i	Dusuk	Runtime/cache agirlikli.
Faz-3	UI translation CRUD	Orta	Admin-only mutation ve audit gerekli.
Faz-5	Domain content translations dual write	Yuksek	Backfill ve resolver testleri sart.
Faz-6	Portal locale davet akisi	Orta	Auth oncesi davet dili kritik.
Faz-8	API contract genisletme	Dusuk/Orta	Backward compatible response alanlari eklenir.

Non-goal

Ilk cok dillilik release'inde asagidakiler yapilmayacak:

• Mevcut projects.name, tasks.title gibi kolonlari kaldirmak.
• Otomatik makine cevirisi eklemek.
• Public route'lara locale prefix eklemek.
• Chat/gunluk/revizyon taleplerini otomatik cevirmek.
• Kullanici yazili icerigini farkli locale'e sessizce overwrite etmek.