Documentation

src/domain/services/legacy-consumer-migration.service.ts

@@ -40,6 +40,8 @@ export class LegacyConsumerMigrationService {
   private readonly roomRepository = new RoomRepository();
 
   async migrateCircuitList(projectId: string, circuitListId: string): Promise<LegacyMigrationReport> {
+    // Migration is additive: legacy consumers are preserved, and circuit-first entities are created
+    // with mapping records so transition remains auditable and reversible.
     const list = await this.circuitListRepository.findById(projectId, circuitListId);
     if (!list) {
       throw new Error("Circuit list not found in project.");
@@ -73,6 +75,7 @@ export class LegacyConsumerMigrationService {
       warnings: [],
     };
 
+    // Idempotency guard: skip consumers already mapped in previous migration run.
     const migratedRows = await db
       .select({ consumerId: legacyConsumerCircuitMigrations.consumerId })
       .from(legacyConsumerCircuitMigrations)
@@ -80,6 +83,8 @@ export class LegacyConsumerMigrationService {
     const migratedConsumerIds = new Set(migratedRows.map((row) => row.consumerId));
     const consumersToMigrate = legacyConsumers.filter((consumer) => !migratedConsumerIds.has(consumer.id));
 
+    // Legacy rows are grouped by normalized circuit number so duplicates become
+    // multiple device rows within one circuit instead of duplicate circuits.
     const byNormalizedCircuitNumber = new Map<string, LegacyConsumerRow[]>();
     const withoutNormalizedCircuitNumber: LegacyConsumerRow[] = [];
     for (const consumer of consumersToMigrate) {
@@ -94,6 +99,8 @@ export class LegacyConsumerMigrationService {
       byNormalizedCircuitNumber.get(normalized)!.push(consumer);
     }
 
+    // Duplicate normalized circuit numbers are expected and represented as one circuit
+    // with multiple circuit_device_rows.
     report.groupedDuplicateCircuitNumbers = [...byNormalizedCircuitNumber.entries()]
       .filter(([, grouped]) => grouped.length > 1)
       .map(([normalizedCircuitNumber, grouped]) => ({ normalizedCircuitNumber, count: grouped.length }));
@@ -105,6 +112,7 @@ export class LegacyConsumerMigrationService {
       isGeneratedIdentifier: boolean;
     }> = [];
 
+    // Stable normalized circuit numbers keep existing intent where available.
     for (const [normalizedCircuitNumber, grouped] of byNormalizedCircuitNumber.entries()) {
       groups.push({
         equipmentIdentifier: normalizedCircuitNumber,
@@ -114,6 +122,8 @@ export class LegacyConsumerMigrationService {
       });
     }
 
+    // Missing/invalid circuit numbers are migrated as single-row groups with
+    // generated identifiers and best-effort section inference.
     for (const consumer of withoutNormalizedCircuitNumber) {
       groups.push({
         equipmentIdentifier: null,