Lewati ke konten utama

Common Maintenance Tasks (Task-Based)

Fokus: skenario praktis yang sering kejadian. Semua langkah di bawah diasumsikan dilakukan di branch terpisah + environment non-production dulu.

1) Tambah field baru di API response​

Tujuan: menambah informasi tanpa merusak client lama.

File yang diubah:

  • Controller/Resource terkait endpoint
  • docs/api-reference.md
  • docs/request-response-catalog.md

Langkah aman:

  1. Tambah field sebagai optional (jangan langsung mandatory).
  2. Pastikan default/null handling aman.
  3. Tambah test response schema.
  4. Update dokumentasi endpoint.

Verifikasi:

  • Endpoint lama tetap lolos kontrak minimal.
  • Client lama tidak error parsing.

Risiko rollback:

  • Jika client bermasalah, rollback ke response sebelumnya.
  • Simpan kompatibilitas minimal 1 versi rilis.

2) Perbaiki bug transisi status PO​

Tujuan: mencegah status lompat tanpa otorisasi.

File yang diubah:

  • Controller/service status PO
  • Rule validasi role
  • docs/state-machine.md

Langkah aman:

  1. Mapping status saat ini vs status target.
  2. Tambah guard per role.
  3. Tambah test untuk jalur valid dan invalid.

Verifikasi:

  • Role tidak berhak mendapat 403.
  • Jalur valid tetap berjalan.

Risiko rollback:

  • Revert patch status guard.
  • Audit data PO yang sempat berubah selama window issue.

3) Menambah endpoint internal baru​

Tujuan: menyediakan kebutuhan data modul lain.

File yang diubah:

  • Routes + controller endpoint baru
  • Middleware access
  • docs/api-endpoints.md, docs/api-reference.md

Langkah aman:

  1. Definisikan kontrak request/response jelas.
  2. Pasang middleware akses minimum.
  3. Rate-limit bila endpoint berat.

Verifikasi:

  • Hanya role berhak yang bisa akses.
  • Latency endpoint masih dalam batas tim.

Risiko rollback:

  • Disable route baru.
  • Revert release endpoint.

4) Rotasi credential integrasi​

Tujuan: ganti credential service eksternal tanpa downtime.

File yang diubah:

  • File env/config integrasi
  • docs/integration-points.md

Langkah aman:

  1. Siapkan credential baru (dual-valid jika memungkinkan).
  2. Deploy dengan fallback ke key lama (sementara).
  3. Uji koneksi read-only dulu.

Verifikasi:

  • Request integrasi sukses.
  • Tidak ada lonjakan error auth.

Risiko rollback:

  • Balik ke credential lama yang masih aktif.
  • Dokumentasikan waktu rotasi.

5) Menangani failed queue job​

Tujuan: memulihkan job gagal tanpa duplikasi efek samping.

File yang diubah:

  • Job handler terkait
  • Konfigurasi queue/retry
  • docs/observability-ops.md

Langkah aman:

  1. Identifikasi root cause dari failed_jobs/log.
  2. Pastikan job idempotent sebelum retry massal.
  3. Retry bertahap.

Verifikasi:

  • Failed job count turun.
  • Tidak ada data dobel.

Risiko rollback:

  • Stop retry.
  • Restore data terdampak jika ada duplikasi.

6) Patch query lambat​

Tujuan: menurunkan waktu respon endpoint berat.

File yang diubah:

  • Repository/query builder
  • Migration index (jika perlu)
  • docs/database-design-full.md

Langkah aman:

  1. Ambil baseline query plan.
  2. Ubah query/index satu per satu.
  3. Uji performa di data staging representatif.

Verifikasi:

  • P95 latency membaik.
  • Hasil query tetap konsisten.

Risiko rollback:

  • Revert query/index baru jika menurunkan performa write.

7) Update rule validasi input​

Tujuan: menutup data invalid masuk sistem.

File yang diubah:

  • FormRequest/validator
  • Test validasi
  • docs/api-cookbook.md

Langkah aman:

  1. Tandai validasi baru yang berpotensi breaking.
  2. Jika breaking, rilis bertahap + komunikasi.
  3. Tambah contoh payload valid/invalid.

Verifikasi:

  • Input invalid ditolak dengan pesan jelas.
  • Input valid lama tetap aman (jika non-breaking).

Risiko rollback:

  • Kembalikan rule lama sementara.
  • Catat dampak data invalid yang terlanjur masuk.

8) Penyesuaian role permission​

Tujuan: menyesuaikan hak akses tanpa membuka celah.

File yang diubah:

  • Middleware/Policy/Gate
  • Seeder role-permission (jika ada)
  • docs/role-access-matrix.md

Langkah aman:

  1. List endpoint terdampak.
  2. Update policy + test akses per role.
  3. Review oleh senior sebelum merge.

Verifikasi:

  • Role target dapat akses sesuai kebutuhan.
  • Role lain tetap terblokir.

Risiko rollback:

  • Revert mapping permission.
  • Audit akses selama periode perubahan.

9) Hotfix bug produksi (non-schema)​

Tujuan: memperbaiki bug kritikal secepat mungkin tapi tetap aman.

File yang diubah:

  • File bug source (controller/service)
  • Test regresi
  • docs/changelog.md

Langkah aman:

  1. Reproduce bug.
  2. Patch minimal (smallest safe fix).
  3. Tambah test regresi sebelum deploy.

Verifikasi:

  • Gejala hilang.
  • Jalur utama tidak rusak.

Risiko rollback:

  • Rollback release hotfix.
  • Aktifkan workaround sementara jika tersedia.

10) Perubahan enum/status bisnis​

Tujuan: menambah/mengubah status tanpa merusak alur lama.

File yang diubah:

  • Enum/model/status validator
  • State transition logic
  • docs/state-machine.md, docs/business-flows.md

Langkah aman:

  1. Definisikan state transition baru lengkap.
  2. Cek dampak ke report, notifikasi, dan API.
  3. Backfill data lama jika diperlukan.

Verifikasi:

  • Transisi status valid sesuai flow.
  • Report dan notifikasi tidak salah hitung.

Risiko rollback:

  • Nonaktifkan status baru.
  • Kembalikan data ke status lama (sesuai playbook data).