Documentation

docs/circuit-list-editor-migration.md

@@ -0,0 +1,75 @@
+# Circuit List Editor Migration
+
+## 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.
+
+## 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`
+
+## 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 endpoints/views may still depend on them
+- migration trace tables reference old/new mapping
+- keeping legacy rows allows comparison and rollback validation during transition