Skip to main content

Change Example Pack (Realistic Data Change Scenarios)

Quick Summary

This package contains examples of changes that occur most frequently and have the greatest risk of error: workflow status, payment split scheme, and field schema changes. Each example must have: step, impact file, migration/backfill, API/UI impact, and rollback.

Example 1 — Add New PO Status: partial_received​

Objective​

Distinguishing the condition of some goods received without directly entering a 'complaint'.

Implementation steps​

  1. Add a constant/state in the PO model (PreOrder).
  2. Update status transition validation in PO controller (web + API).
  3. Update the PO filter list (on-going/received/...) so that the new status is not lost.
  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​

  • Generally no migration schema if state is stored as a string.
  • Need a backfill script if there is historical data that must be mapped to a new status.

API/UI Impact​

  • The PO list/detail API should display the new status value.
  • The filter/status badge UI must add consistent labels.

Rollback​

  • Mapping partial_received back to approved or received via controlled script.
  • Revert code that adds new state transitions.

Example 2 — Add Column bank_reference_no in Payment Split​

Objective​

Save transfer reference numbers for split payment audits.

Implementation steps​

  1. Create a migration adding a nullable column bank_reference_no.
  2. Update fillable model + request validation.
  3. Update endpoint update/paid payment split.
  4. Update the accounting form UI and payment details.

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/Payments/PaymentSplitController.php
  • resources/views/admin/payments/...
  • docs/api-examples.md, docs/change-data-playbook.md

Migration / data change​

  • Forward migration: add nullable column.
  • Optional backfill: fill in historical data from transfer receipts if available.

API/UI Impact​

  • Split payment response can expose bank_reference_no (certain role).
  • Accounting UI displays input + readonly view after paid.

Rollback​

  • Drop columns via down migration (if safe).
  • If audit has been used, rollback becomes soft rollback: hide from UI/API but the column remains.

Example 3 — Change Payload Create SPB: required delivery_date​

Objective​

Reduce SPB without target delivery date.

Implementation steps​

  1. Change the Create SPB validation request so that delivery_date is required.
  2. Make sure to update API examples + mobile/web forms.
  3. Add clear error message handling.
  4. Test create/update SPB for project role.

File impact (minimum)​

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

Migration / data change​

  • No mandatory migration.
  • Old data that is null delivery_date needs to be handled in the UI/report (fallback label).

API/UI Impact​

  • Old clients that do not send delivery_date will fail validation.
  • UI needs mandatory marker + helper text.

Rollback​

  • Return validation to nullable.
  • Fixed log warning if field is empty for observability.

Checklist before merge (required)​

  • There is a rollback plan that is completely executable.
  • Impact on API consumers is recorded (breaking / non-breaking).
  • Impact to role-based UI noted.
  • If there are assumptions, they have been recorded in Verification Matrix.

Verification Notes​

  • Status: Partial
  • Scope: The above example is a realistic pattern of the current code structure, not yet executed as a specific live ticket.
  • Action: When there is a next real change, attach the actual PR/commit to the most relevant instance.