Lewati ke konten utama

Change Example Pack (Realistic Data Change Scenarios)

Quick Summary

Paket ini berisi contoh perubahan yang paling sering kejadian dan paling berisiko salah: status workflow, skema payment split, dan perubahan field schema. Setiap contoh wajib punya: langkah, file impact, migration/backfill, dampak API/UI, dan rollback.

Example 1 — Tambah Status PO Baru: partial_received​

Tujuan​

Membedakan kondisi barang diterima sebagian tanpa langsung masuk complaint.

Langkah implementasi​

  1. Tambah konstanta/status di model PO (PreOrder).
  2. Update validasi transisi status di controller PO (web + API).
  3. Update filter list PO (on-going/received/...) agar status baru tidak hilang.
  4. Update docs flow + state machine.

File impact (minimum)​

  • app/Models/PreOrder.php
  • app/Http/Controllers/Admin/Po/PoController.php
  • app/Http/Controllers/API/V1/PO/POController.php
  • resources/views/... (badge/status label)
  • docs/state-machine.md, docs/business-flows.md

Migration / data change​

  • Umumnya tanpa migration schema jika status disimpan string.
  • Perlu script backfill jika ada data historis yang harus dipetakan ke status baru.

Dampak API/UI​

  • API list/detail PO harus menampilkan nilai status baru.
  • UI filter/status badge wajib tambah label yang konsisten.

Rollback​

  • Mapping partial_received kembali ke approved atau received via script terkontrol.
  • Revert kode yang menambah transisi status baru.

Example 2 — Tambah Kolom bank_reference_no di Payment Split​

Tujuan​

Menyimpan nomor referensi transfer untuk audit pembayaran split.

Langkah implementasi​

  1. Buat migration tambah kolom nullable bank_reference_no.
  2. Update model fillable + request validation.
  3. Update endpoint update/paid payment split.
  4. Update UI form accounting dan detail payment.

File impact (minimum)​

  • database/migrations/*_add_bank_reference_no_to_payment_splits.php
  • app/Models/PaymentSplit.php
  • app/Http/Requests/...PaymentSplit...php
  • app/Http/Controllers/Admin/Pembayaran/PaymentSplitController.php
  • resources/views/admin/pembayaran/...
  • docs/api-examples.md, docs/change-data-playbook.md

Migration / data change​

  • Forward migration: add nullable column.
  • Backfill opsional: isi data historis dari bukti transfer jika tersedia.

Dampak API/UI​

  • Response payment split bisa expose bank_reference_no (role tertentu).
  • UI accounting menampilkan input + readonly view setelah paid.

Rollback​

  • Drop kolom via down migration (jika aman).
  • Jika sudah dipakai audit, rollback jadi soft rollback: sembunyikan dari UI/API tapi kolom tetap ada.

Example 3 — Ubah Payload Create SPB: wajib delivery_date​

Tujuan​

Mengurangi SPB tanpa target tanggal pengiriman.

Langkah implementasi​

  1. Ubah request validation Create SPB agar delivery_date required.
  2. Pastikan update API examples + mobile/web form.
  3. Tambahkan handling error message yang jelas.
  4. Uji create/update SPB untuk role project.

File impact (minimum)​

  • app/Http/Requests/API/V1/SPB/PM/CreateSPBRequest.php
  • app/Http/Controllers/API/V1/SPB/PM/SPBController.php
  • resources/js|views form SPB (web/mobile bila satu repo)
  • docs/api-reference.md, docs/api-examples.md

Migration / data change​

  • Tidak wajib migration.
  • Data lama yang null delivery_date perlu handling di UI/report (fallback label).

Dampak API/UI​

  • Client lama yang tidak mengirim delivery_date akan gagal validasi.
  • UI perlu mandatory marker + helper text.

Rollback​

  • Kembalikan validation jadi nullable.
  • Tetap log warning jika field kosong untuk observability.

Checklist sebelum merge (wajib)​

  • Ada rollback plan yang benar-benar executable.
  • Dampak ke API consumer dicatat (breaking / non-breaking).
  • Dampak ke UI role-based dicatat.
  • Jika ada asumsi, sudah dicatat ke Verification Matrix.

Catatan Verifikasi​

  • Status: Partial
  • Scope: Contoh di atas adalah pattern realistis dari struktur kode saat ini, belum dieksekusi sebagai tiket live tertentu.
  • Action: Saat ada perubahan riil berikutnya, lampirkan PR/commit aktual ke contoh paling relevan.