# Install and rollback — update only

This package is a local-tested candidate. Validate on a private staging clone before enabling it on the live store. Do not upload the work/ directory or any test scripts, database files or local configuration.

## Compatibility check

1. Use PHP 8.1 or newer with the existing extensions and the supplied schema. The local test environment was PHP 8.2.12 / MariaDB 10.4.32. Check that order, payment, attempt, item and inventory tables still use InnoDB, that request/transaction unique indexes remain present, and that guest user_id is nullable.
2. Compare the 12 existing production files with `docs/manifest.json` before hashes. Hashes refer to the exact original bytes in the supplied ZIP. If any file differs, stop the upload and merge/retest against the current version; do not overwrite intervening work. The new `app/order-v41.php` must be absent. If it already exists, preserve and compare it instead of replacing it blindly.
3. Confirm the server still uses the root-domain configuration. Do not change app/config.php, payment-settings.local.php, API keys or base_url.

## Backup

4. Pause new checkout/staff writes briefly for the deployment window. Record the current time and deployment version. Download the exact 12 files marked update into a timestamped backup folder outside the public web root. Record that the V41 compatibility helper is an addition.
5. Take a private, consistent database backup through the hosting backup tool or mysqldump with a transaction-consistent snapshot, including schema/indexes/constraints and all current data. Keep it off the public web root. Verify that the backup can be read/restored to a separate staging database. The supplied export is not a fresh production backup.
6. Keep a separate copy of existing configuration and assets in the normal hosting backup. They are not changed by this package.

## Staging and installation

7. On a private staging copy, upload only the contents of this package's `public_html/` folder into the existing public_html root, preserving paths. Add/overwrite the listed files only. Do not replace or delete the public_html directory. Do not run any installer, demo seeder or old migration. No database migration is required for the supplied schema.
8. Prefer an atomic release/file switch. Otherwise keep the write pause until all 13 files have uploaded and hashes match the manifest after values. Upload the new helper first and then the dependent files. Keep docs and ZIPs outside the web root. Clear OPcache using the host's normal mechanism so changed files execute together.
9. Run the staging checks below. For real gateway testing, use the merchant-approved sandbox configuration on staging only and verify callbacks through the provider dashboard. Keep the live configuration unchanged. Do not enable online payments based solely on simulated local test results.
10. Deploy the same verified files to production using the backup and short write-pause procedure. Resume writes, inspect current server logs, and observe the first authorized orders. Do not create unsolicited test orders or charge real customers.

## Acceptance checks

- Guest and registered COD order, correct variant and stock, inside/outside shipping, valid/invalid coupon, double-submit and refresh.
- Authorized confirmation/tracking/summary, private headers, invalid guest token and unrelated account denied; viewing a page must not change stock/order count.
- Staff confirmation followed by processing and Ready to Ship, simultaneous revision conflict, cancellation releases eligible stock once.
- Real sandbox online payment, amount/transaction verification, duplicate callback, pending retry block, failed-session recovery and late/cancelled payment reconciliation.
- Confirmation/tracking at the five requested widths and current production error logs. Do not mark Phase 1 production acceptance complete until these pass.

## Rollback

11. Pause checkout/staff writes. Restore the 12 backed-up files to their original paths. Remove only the newly added app/order-v41.php if it was absent before deployment, after restoring its dependent callers. If a helper existed before deployment, restore that exact backup instead. Clear OPcache and confirm the original files' hashes.
12. Do not import an old SQL export, reset the database, undo new orders, or recompute stock as part of this code rollback. There is no migration to reverse. Keep all orders/payments received during the deployment; reconcile uncertain payments before retries or stock releases.
13. Restore access after checking logs and core routes. Record that rollback restores the old missing-helper/confirmation/payment defects; keep the corrected patch available for review. If production data needs repair, handle it as a separate reviewed data change using current backups.