91 lines
3.0 KiB
Markdown
91 lines
3.0 KiB
Markdown
# Circuit List Editor Migration
|
|
|
|
## Status
|
|
|
|
Upgrade-only. New installations already use the Circuit-First schema and do not
|
|
run this workflow.
|
|
|
|
## Goal
|
|
|
|
Migrate legacy row-first consumers into the circuit-first model without deleting legacy data.
|
|
|
|
## Legacy Mapping
|
|
|
|
Legacy `Consumer` rows map into:
|
|
|
|
- `Circuit` for shared circuit identity and circuit-level technical fields
|
|
- `CircuitDeviceRow` for per-device load rows
|
|
|
|
Multiple legacy consumers can map into one circuit when they share normalized circuit identity.
|
|
|
|
For one circuit list, all new circuits, device rows, trace mappings and the migration report are committed in one SQLite transaction. A failed run therefore leaves none of those prepared migration writes behind.
|
|
|
|
## Grouping Strategy (`circuitNumber`)
|
|
|
|
Migration groups legacy rows by normalized `circuitNumber`:
|
|
|
|
- valid/normalizable values become one target circuit per normalized value
|
|
- duplicates are grouped under that circuit (multiple `CircuitDeviceRow`s)
|
|
- missing/invalid values trigger generated identifiers and may fall back to `unassigned` section
|
|
|
|
## Default Section Backfill
|
|
|
|
Before migration, default sections are created/backfilled per circuit list.
|
|
This guarantees a valid target section space, including `unassigned` when no section can be inferred.
|
|
|
|
## Migration Commands
|
|
|
|
Run in this order for local database workflows:
|
|
|
|
1. Backup:
|
|
- `npm run db:backup`
|
|
2. Migrate schema:
|
|
- `npm run db:migrate`
|
|
3. Verify circuit schema:
|
|
- `npm run db:verify:circuit-schema`
|
|
4. Backfill missing sections:
|
|
- `npm run db:backfill:sections`
|
|
5. Migrate legacy consumers:
|
|
- `npm run db:migrate:legacy-consumers`
|
|
|
|
The migration command finishes with a cutover verification across the complete
|
|
database. It exits with an error while any legacy consumer lacks a migration
|
|
mapping, including consumers that cannot be migrated because they have no circuit
|
|
list assignment. The legacy multi-list UI was removed only after this check passed;
|
|
old `/projects/:projectId/circuit-lists` bookmarks redirect to the project page.
|
|
|
|
## Validation Checks
|
|
|
|
After migration, verify:
|
|
|
|
- tree endpoint returns sections/circuits/rows
|
|
- grouped duplicate circuit numbers are reported
|
|
- generated identifiers are reported where expected
|
|
- migrated rows include `legacyConsumerId` traceability
|
|
- no duplicate BMKs exist inside one circuit list
|
|
|
|
## If Tree Endpoint Returns Empty Sections
|
|
|
|
Likely causes:
|
|
|
|
- circuit-first tables missing (migration not run)
|
|
- sections not backfilled yet
|
|
- migrated dataset genuinely empty for selected list
|
|
|
|
Actions:
|
|
|
|
1. Run schema migration and verification commands.
|
|
2. Run section backfill command.
|
|
3. Run legacy-consumer migration command.
|
|
4. Retry tree endpoint.
|
|
|
|
## Legacy Data Retention
|
|
|
|
Do not delete legacy consumers yet.
|
|
|
|
- legacy read/write endpoints have been removed from the application server
|
|
- migration trace tables reference old/new mapping
|
|
- retained rows allow upgrade verification and audit of the completed mapping
|
|
- a future automatic cleanup migration must migrate and verify old databases
|
|
before dropping these source and trace tables
|