Fix PromotionMigrator duplicate codes when promotions share base_code

Constrain the promotion code batch join in copy_promotion_codes by promotion_id
and created_at to prevent cross-promotion row multiplication and duplicate value
inserts. Adds a regression spec and an audit doc summarizing root cause,
release verification, and related issue/PR research.

Author: NewAlexandria

promotions/docs/PROMOTION_MIGRATOR_DUPLICATE_CODES_FIX.md

@@ -0,0 +1,60 @@
+# PromotionMigrator duplicate code fix
+
+## Context
+
+During migration from `solidus_legacy_promotions` to `solidus_promotions`, `PromotionMigrator#copy_promotion_codes`
+uses a SQL join from legacy code batches to new code batches.
+
+In current releases (4.4.x, 4.5.x, 4.6.x, and `main` at time of writing), the relevant join condition is:
+
+```sql
+LEFT OUTER JOIN solidus_promotions_promotion_code_batches
+  ON solidus_promotions_promotion_code_batches.base_code = spree_promotion_code_batches.base_code
+```
+
+## Problem
+
+`base_code` is not globally unique across promotions. If multiple promotions have code batches with the same
+`base_code`, this join can match more than one target row for a single source row.
+
+That multiplies result rows in `INSERT ... SELECT`, which can duplicate `value` insert attempts into
+`solidus_promotions_promotion_codes`.
+
+Because `solidus_promotions_promotion_codes.value` is unique, migration can fail with:
+
+```text
+PG::UniqueViolation: duplicate key value violates unique constraint
+"index_solidus_promotions_promotion_codes_on_value"
+DETAIL: Key (value)=(suvie-lgm4gw) already exists.
+```
+
+## Change
+
+Constrain the join to the current migrated promotion and the copied batch timestamp:
+
+```sql
+LEFT OUTER JOIN solidus_promotions_promotion_code_batches
+  ON solidus_promotions_promotion_code_batches.base_code = spree_promotion_code_batches.base_code
+  AND solidus_promotions_promotion_code_batches.promotion_id = #{Integer(new_promotion.id)}
+  AND solidus_promotions_promotion_code_batches.created_at = spree_promotion_code_batches.created_at
+```
+
+This makes each migrated code row resolve to the corresponding batch for the promotion currently being migrated,
+preventing cross-promotion row multiplication.
+
+## Validation
+
+A regression spec covers two legacy promotions that both have `PromotionCodeBatch` records with the same
+`base_code`. The migration now inserts each code exactly once, without duplicate key violations.
+
+## Related issues and pull requests reviewed
+
+- Searched open and closed issues/PRs in `solidusio/solidus` for:
+  - `PromotionMigrator`
+  - `copy_promotion_codes`
+  - `base_code`
+  - promotion code migration duplicate-key failures
+- No issue or PR appears to cover this specific join condition in `PromotionMigrator#copy_promotion_codes`.
+- Historic issue [`#1248`](https://github.com/solidusio/solidus/issues/1248) was reviewed. It concerns an older
+  migration path (`spree_promotions.code` to `spree_promotion_codes`) and is not the same bug as this
+  cross-promotion batch join multiplication.

promotions/lib/solidus_promotions/promotion_migrator.rb

@@ -61,7 +61,10 @@ def copy_promotion_codes(new_promotion)
         SELECT solidus_promotions_promotions.id AS promotion_id, solidus_promotions_promotion_code_batches.id AS promotion_code_batch_id, value, spree_promotion_codes.created_at, spree_promotion_codes.updated_at
         FROM spree_promotion_codes
         LEFT OUTER JOIN spree_promotion_code_batches ON spree_promotion_code_batches.id = spree_promotion_codes.promotion_code_batch_id
-        LEFT OUTER JOIN solidus_promotions_promotion_code_batches ON solidus_promotions_promotion_code_batches.base_code = spree_promotion_code_batches.base_code
+        LEFT OUTER JOIN solidus_promotions_promotion_code_batches
+          ON solidus_promotions_promotion_code_batches.base_code = spree_promotion_code_batches.base_code
+          AND solidus_promotions_promotion_code_batches.promotion_id = #{Integer(new_promotion.id)}
+          AND solidus_promotions_promotion_code_batches.created_at = spree_promotion_code_batches.created_at
         INNER JOIN spree_promotions ON spree_promotion_codes.promotion_id = spree_promotions.id
         INNER JOIN solidus_promotions_promotions ON spree_promotions.id = solidus_promotions_promotions.original_promotion_id
         WHERE spree_promotion_codes.promotion_id = #{new_promotion.original_promotion_id};

promotions/spec/lib/solidus_promotions/promotion_migrator_spec.rb

@@ -52,6 +52,55 @@
     end
   end
 
+  context "when multiple promotions have batches with the same base_code" do
+    let(:shared_base_code) { "SUVIE" }
+    let(:shared_time) { Time.current.change(usec: 0) }
+    let!(:spree_promotion) { create(:promotion) }
+    let!(:another_spree_promotion) { create(:promotion) }
+    let!(:first_batch) do
+      Spree::PromotionCodeBatch.create!(
+        promotion: spree_promotion,
+        base_code: shared_base_code,
+        number_of_codes: 1,
+        created_at: shared_time,
+        updated_at: shared_time
+      )
+    end
+    let!(:second_batch) do
+      Spree::PromotionCodeBatch.create!(
+        promotion: another_spree_promotion,
+        base_code: shared_base_code,
+        number_of_codes: 1,
+        created_at: shared_time,
+        updated_at: shared_time
+      )
+    end
+    let!(:first_code) do
+      create(
+        :promotion_code,
+        promotion: spree_promotion,
+        promotion_code_batch: first_batch,
+        value: "suvie-lgm4gw"
+      )
+    end
+    let!(:second_code) do
+      create(
+        :promotion_code,
+        promotion: another_spree_promotion,
+        promotion_code_batch: second_batch,
+        value: "suvie-abc123"
+      )
+    end
+
+    it "copies each code exactly once without raising a duplicate value error" do
+      expect { subject }.not_to raise_error
+      expect(SolidusPromotions::PromotionCode.where(value: [first_code.value, second_code.value]).count).to eq(2)
+      expect(
+        SolidusPromotions::PromotionCode.where(value: [first_code.value, second_code.value]).group(:value).count.values
+      ).to all(eq(1))
+    end
+  end
+
   context "if our rules and actions are missing from the promotion map" do
     let(:promotion_map) do
       {