# Data migrations

Changes every environment needs (new fields, indexes, menu nodes, seed rows, backfills)
go here, not in `OneTimeCronController`. Deploys apply them automatically - nobody runs
them by hand on dev or prod.

`php yii mongodb-migrate/up` applies every file in this folder not yet recorded in the
`migration` collection, in filename order.

Use `mongodb-migrate`, never plain `migrate`: `php yii migrate` is Yii's SQL migration tool
and fails with `Failed to instantiate component or class "db"` - this app has no SQL
connection.

Locally, from the host:

```bash
docker exec -w /var/www/html/ng-crm/yiiapp optimacrmphp php yii mongodb-migrate/up --interactive=0
```

or inside the container (`docker exec -it optimacrmphp bash`):

```bash
php yii mongodb-migrate/up
```

## When they run

| Environment | Where                     | When                                              |
|-------------|---------------------------|---------------------------------------------------|
| Prod        | `scripts/deploy.prod.sh`  | after the blue/green flip, once the old colour is stopped |
| Dev         | `scripts/deploy.dev.sh`   | every deploy, after the RBAC migrations           |
| Local       | by hand (command below)   | after pulling code that adds a migration          |

On prod only the new release is serving by the time they run, so old code can neither
see a change (e.g. a menu node for a route it lacks) nor race it (e.g. writing rows a
backfill is fixing). A failure there does not roll back the deploy: it finishes with
status `DONE_WITH_WARNINGS`, and the migration - still unrecorded - is retried on the
next deploy. On dev a failure stops the deploy.

Because migrations run after the new code is live, the new code must cope with the
migration not having run yet (e.g. a field that is still missing on old rows).

## Writing one

```bash
php yii mongodb-migrate/create add_payments_menu
```

Rules:

1. **Idempotent.** Mongo cannot roll back a half-applied migration; the fix is to
   correct it and run again. A second run must change nothing (check before insert,
   `$set` rather than `$inc`, skip rows already done).
2. **No arguments, no agency-specific data** for schema / shared seeds. Exception:
   leasing invoicing config (`m261001_120000_seed_leasing_invoicing_config`) is
   agency-scoped by design — pass `LEASING_INVOICING_AGENCY_ID=<objectId>` (or rely
   on `platform=property_management` / name fallback). Do not put operational
   one-offs in `OneTimeCronController`.
3. **Ids from `Counters::getNextIdentityCounter`**, stepping past ids already in use -
   counters can lag hand-inserted rows.
4. `down()` returns false unless a real reversal exists.
5. Removing or renaming data is a two-deploy job: ship the code that stops reading it,
   then remove it in a later deploy.

### Leasing invoicing seed

```bash
# Seed one agency (e.g. Property Management on this server):
LEASING_INVOICING_AGENCY_ID=66aaaaaaaaaaaaaaaaaaaaaa \
  php yii mongodb-migrate/up --interactive=0

# Or omit the env var — migration targets every agency with
# platform=property_management, else name matching /property management/i.
```

Source rows: `console/data/leasing_invoicing_config.php` (from
Leasing_Invoicing_Configuration.xlsx; payment methods / bank accounts / penalty /
term-type sheets are intentionally skipped).

### Property management demo seed

`m261028_100000_seed_pm_demo_data` loads `console/data/pm_seed_v1.php` (generated from
optima_pm_seed_data_v1.xlsx) into the Property Management demo agency only - pass
`PM_SEED_AGENCY_ID=<objectId>` to target another one. A server without that agency skips it.
Records follow each module's own flow (approvals, renewals, work order steps); no invoices
or receipts are raised. A work order with an estimate gets the provider's quote as a subcontract
line when it is assigned; a closed job with lines is left verified, since Close needs its bill
and charge first. Workbook dates are shifted to the day it runs. Every amount is in the
agency currency (the workbook's SAR rows included), and PM records with no currency of their own
(ancillary spaces, assets, agreements, work orders and lines, stock) get it stamped. `down()` removes
every row carrying `seed.source = pm_seed_v1`.

`m261028_150000_seed_pm_demo_billing` then bills those tenancies from the workbook's payment
schedule: PDC cheques on the contract, deposit and rent invoices (lines whose 30-day invoicing
window is open), payments recorded and verified, settlement and ledger rows. Its rows carry
`seed.source = pm_seed_v1_billing`; `down()` removes them and clears the schedule lines.
It then records the provider's bill on those verified jobs, raises the charge (owner statement
deduction or a C-MAINT recharge invoice, by payer and collection model) and closes them. Bills and
invoices share the default series, numbered in creation order.
It needs the agency's leasing invoicing config (C-RENT, C-RENTADV, C-SDEP), the payment modes,
and for work orders a default invoice series and the C-MAINT concept.

## Useful commands

```bash
php yii mongodb-migrate/new            # pending, not yet applied
php yii mongodb-migrate/history        # applied, newest first
php yii mongodb-migrate/mark <version> # treat everything after <version> as pending again
```

## Restoring a database

The history lives in the same database as the data, so a full restore rewinds both
together: anything applied after the backup becomes pending again. Run them straight
after restoring rather than waiting for the next deploy:

```bash
php yii mongodb-migrate/up --interactive=0
```

After a *partial* restore (a few collections, not the history), the history can claim a
migration ran that the restored data no longer has. `mark` back to before it, then `up` -
safe because migrations are idempotent.
