Implement bazaar item identity and offline trading rework

docs/bazaar_item_unique_id_rollout.md

@@ -0,0 +1,109 @@
+# Bazaar Item Unique ID And Offline Trading Rollout
+
+## Purpose
+
+This rollout converts persisted item identity and offline trader or buyer session state to the new production-safe model. The migration is designed for a maintenance window and explicitly clears any in-flight trader, buyer, and offline sessions during cutover.
+
+Do not reopen the server until every verification step passes.
+
+## Preconditions
+
+- Schedule a maintenance window.
+- Stop new logins before beginning the migration.
+- Ensure the `world` binary you are deploying includes this branch.
+- Ensure operators have credentials to run schema updates and database dump commands.
+
+## Mandatory Backup
+
+Take a backup before any schema or migration command:
+
+```powershell
+world database:dump --player-tables --login-tables --dump-path=backups --compress
+```
+
+If you use a separate database backup process, complete it before continuing.
+
+## Local Dev Validation
+
+Run these commands against the local dev database before production:
+
+```powershell
+world database:updates --skip-backup
+world database:item-unique-ids --preflight --verbose
+world database:item-unique-ids --migrate --verbose
+world database:item-unique-ids --verify --verbose
+```
+
+Validate these gameplay scenarios after the migration:
+
+- Two traders listing the same item at different prices.
+- One trader changing a price without affecting another trader.
+- Offline trader purchase.
+- Offline buyer purchase.
+- Parcel retrieval for rows that previously had missing `item_unique_id` values.
+- Alternate bazaar shard search.
+
+## Production Sequence
+
+1. Bring the server into maintenance mode and stop new gameplay activity.
+2. Take the mandatory backup.
+3. Apply schema updates:
+
+```powershell
+world database:updates
+```
+
+4. Run the migration preflight:
+
+```powershell
+world database:item-unique-ids --preflight --verbose
+```
+
+5. If preflight reports missing schema, duplicate live item IDs, or other unexpected errors, stop and resolve them before continuing.
+6. Run the migration:
+
+```powershell
+world database:item-unique-ids --migrate --verbose
+```
+
+This step clears active trader, buyer, and offline session state. Players must re-enter those modes after deploy.
+
+7. Run final verification:
+
+```powershell
+world database:item-unique-ids --verify --verbose
+```
+
+8. Reopen the server only after verification passes.
+
+## What Preflight And Verify Must Show
+
+The migration is not complete unless all of the following are true:
+
+- `inventory`, `sharedbank`, and `trader` contain no null or blank `item_unique_id` values.
+- `character_parcels`, `character_parcels_containers`, and `inventory_snapshots` contain no null or blank `item_unique_id` values.
+- `inventory`, `sharedbank`, and `trader` contain no duplicate `item_unique_id` groups.
+- There are no cross-table duplicate live `item_unique_id` values across `inventory`, `sharedbank`, and `trader`.
+- `offline_character_sessions` is empty after migration.
+- `account.offline` has no rows left set to `1`.
+
+## Rollback Criteria
+
+Rollback instead of reopening the server if any of the following occur:
+
+- `world database:updates` fails.
+- `world database:item-unique-ids --preflight` reports missing required schema.
+- `world database:item-unique-ids --migrate` or `--verify` reports missing IDs, duplicate IDs, or stale offline session state.
+- Bazaar listing, offline trader, offline buyer, or parcel retrieval smoke tests fail after migration.
+
+## Rollback Actions
+
+1. Keep the server in maintenance mode.
+2. Restore the database backup taken before the rollout.
+3. Redeploy the previous server build.
+4. Confirm login, trader, buyer, and parcel behavior on the restored build before reopening the server.
+
+## Notes
+
+- `world database:item-unique-ids --keep-trading-state` exists for non-production diagnostics only. Do not use it during production cutover.
+- The migration command expects schema updates to have been applied first. If required tables or columns are missing, the command fails and should not be bypassed.