# Paket rilis dan pembaruan

Paket berisi satu versi lengkap kode aplikasi dan hasil build frontend. Paket ini tidak mengubah server, database, maupun storage secara otomatis.

## Membuat dan memeriksa paket

Di komputer pengembang, dari folder proyek:

```powershell
npm run release:package -- --version 2026.11.16-1 --migration review --notes "Ringkasan perubahan"
node scripts/verify-release.cjs releases/2026.11.16-1
```

Ganti versi untuk setiap rilis; skrip tidak menimpa versi yang sudah ada. Pembuatan paket menjalankan release gate dan build terlebih dahulu. Hasil berada di `releases/<versi>`. Pindahkan seluruh folder tersebut ke server melalui saluran yang aman dan verifikasi ulang menggunakan skrip `scripts/verify-release.cjs` di dalam paket.

Nilai `--migration` harus dinilai untuk setiap rilis: `none` jika sudah dipastikan tidak ada perubahan database, `required` jika ada migrasi, atau `review` jika belum dipastikan. Jangan menerapkan paket dengan status `review` sebelum membandingkan perubahan database dan menguji migrasinya pada salinan database UAT. Manifest mencatat status, catatan, pemeriksaan dan SHA-256 semua berkas. Checksum mendeteksi perubahan tidak sengaja, bukan membuktikan identitas pembuat.

Paket sengaja tidak berisi `.env`, `node_modules`, `backend/storage`, `backend/public/uploads`, data pelanggan, foto, atau database. Jangan menyalin storage atau konfigurasi dari komputer pengembang ke server produksi.

## Sebelum penerapan

1. Uji rilis, dependensi, peran pengguna, integrasi dan, jika diperlukan, migrasi pada lingkungan UAT dengan salinan data yang layak. Catat versi Node yang sesuai `engines`, perubahan konfigurasi, dan waktu maintenance.
2. Umumkan maintenance dan hentikan layanan aplikasi serta worker yang menulis data. Pastikan tidak ada penulisan database atau unggahan selama backup dan perpindahan versi.
3. Buat dan verifikasi backup database, seluruh `backend/storage`, seluruh `backend/public/uploads`, `backend/.env`, serta kode, build, `package.json` dan `package-lock.json` versi yang sedang berjalan. Simpan backup di luar folder aplikasi dan di lokasi aman; konfigurasi dan data pengguna bersifat rahasia. Uji pemulihan di lingkungan terpisah.
4. Verifikasi checksum paket dan catat manifest. Periksa konfigurasi yang baru diperlukan tanpa mengganti `.env` produksi. Pastikan tersedia ruang disk dan prosedur menjalankan ulang layanan.

## Memasang

1. Dengan layanan masih berhenti, simpan salinan versi lama. Perbarui folder `backend/server`, berkas migrasi yang disertakan di `backend/database`, tiga skrip operasional di `backend/scripts`, folder `frontend/dist`, dan tiga `package.json` serta `package-lock.json` dari paket. Ganti folder kode dan build sebagai satu kesatuan agar berkas usang tidak tertinggal; jangan sentuh `backend/.env`, `backend/storage`, atau `backend/public/uploads`.
2. Di folder proyek server, jalankan `npm ci --omit=dev` dengan versi Node yang didukung dan akses ke registry yang disetujui. Periksa hasil pemasangan sebelum melanjutkan.
3. Hanya jika manifest menyatakan `required` dan migrasi telah diuji, dari folder `backend` jalankan `node database/migrate.js` menggunakan konfigurasi produksi. Skrip migrasi proyek ini bersifat gabungan; tinjau isi dan hak database terlebih dahulu. Jangan menjalankan seed, reset, atau data UAT pada produksi.
4. Dari folder `backend`, jalankan `node scripts/preflight.js`, kemudian mulai layanan sesuai pengelola layanan server. Pastikan `NODE_ENV=production` dan akses `/api/ready` melalui jalur yang sesuai.
5. Uji login dan alur yang terdampak dengan akun yang berwenang, termasuk akses file. Pantau log dan notifikasi sebelum mengakhiri maintenance.

## Pemulihan

Hentikan layanan dan hentikan penulisan terlebih dahulu. Kembalikan kode, build, manifest paket/dependensi dan konfigurasi versi sebelumnya; pasang kembali dependensi sesuai lockfile lama. Jika migrasi atau data sudah berubah, kode lama belum tentu kompatibel: tentukan pemulihan database dan storage dari backup yang konsisten sesuai titik waktu, dengan memahami bahwa transaksi setelah backup dapat hilang. Jangan mengembalikan database secara otomatis. Uji kesiapan dan akses file sebelum layanan dibuka kembali.
