Data & Migrations

Data model (HR standard)

Standar HR mengikuti SAP SuccessFactors sebagai referensi utama:

Entity align dengan definisi SuccessFactors (MDF / Foundation Objects).
Semua transaksi HR pakai effective dating + event reason.
Build order ikut pendekatan Employee Central–first.
Kontrak API entity-based, ikut konvensi OData / REST.
Person / Employment dipisah (lihat data model workspace). Deviasi dari standar SuccessFactors wajib didokumentasikan (rationale, risk, approval).

Detail: workspace docs/hr-standards.md.

Three migration systems

HAER pakai tiga sistem migration berbeda — jangan ketuker:

1. TypeORM — `haer-platform-api`

synchronize: false selalu. Jangan pernah true di environment manapun.
Jangan generate migration terhadap DB shared/remote/pre-existing. Pakai scratch DB lokal: DB kosong → run semua migration → baru generate.
Verifikasi di clean DB. Drop scratch DB, recreate, run semua migration. Gagal di clean DB = migration rusak, jangan merge.
Oracle butuh wrapper script — jangan panggil TypeORM CLI langsung.
Migration dari entity wajib dipasangkan buat dua provider (Postgres + Oracle) di PR yang sama.
Jangan edit migration yang udah merged/applied — bikin yang baru.
Sebelum handoff: migration:show, migration:run, migration:revert (kalau reversible).

2. golang-migrate — `haer-platform-bgjobs` & `haer-claims-api`

Verifikasi up → down → up di clean DB.
Migration = source of truth schema untuk service Go.

3. Alembic — `haer-connector`

uv run alembic upgrade head apply semua migration.
Postgres-only (SQLAlchemy 2 async). Pakai scratch-DB recipe buat generate/verify.

Runbook — ubah schema dengan aman

Langkah demi langkah buat perubahan schema (contoh: nambah kolom via TypeORM di haer-platform-api). Prinsip yang sama berlaku buat golang-migrate & Alembic.

Ubah entity dulu, bukan nulis SQL migration tangan (kecuali destructive / rename / backfill / logic per-provider — itu pakai migration:create).
Siapin scratch DB kosong yang terpisah dari dev/shared. DB kosong → run semua migration existing dulu.
Generate migration lawan scratch DB itu — jangan pernah lawan DB remote/pre-existing (nanti nge-reference tabel yang belum dibuat migration sebelumnya).
Pair Postgres + Oracle di PR yang sama. Oracle lewat wrapper script, bukan TypeORM CLI langsung.
Verifikasi di clean DB: drop scratch DB → recreate → run semua migration. Gagal = migration rusak, jangan merge.
migration:show / migration:run / migration:revert (kalau reversible) buat provider yang kena, sebelum handoff.
Kalau perubahan nyiratin kontrak berubah (kolom baru dikonsumsi web/mobile), tulis di PR “API contract impact” + kabarin konsumer. Lihat merge order.

Jangan: set synchronize: true (bikin schema di luar history migration), edit migration yang udah merged, atau generate di atas DB yang state schema-nya ad-hoc.

Migration review gate

PR yang menyentuh file migration wajib menyertakan di body: migration reviewed, rollback, dan test evidence. Danger/CI meng-enforce ini di repo yang punya. Perubahan schema yang implikasinya lintas-repo dikoordinasikan lewat “API contract impact”.

Source: workspace CLAUDE.md → “Backend TypeORM Migration Rules”; README.md masing-masing repo untuk perintah pastinya.