schema(scanner): add scan_country to scan_history (#921)

[ericsocrat]

Summary

Adds a nullable scan_country column to scan_history with FK to country_ref(country_code). This captures the user's catalog region at scan time, enabling downstream country-aware scanner features.

Part of epic #920. Closes #921.

---

Changes

Migration: 20260320000100_scan_history_country.sql

• ALTER TABLE scan_history ADD COLUMN IF NOT EXISTS scan_country text REFERENCES country_ref(country_code) — nullable for backward compat
• Partial index idx_sh_country on scan_country WHERE scan_country IS NOT NULL — for country-scoped analytics
• Column comment documenting purpose and NULL semantics

pgTAP: schema_contracts.test.sql

• 3 new tests: has_column, col_is_null, fk_ok for scan_history.scan_country
• Plan count corrected from 288 → 297 (pre-existing drift of 6 tests + 3 new)

---

Files Changed

File	Change
supabase/migrations/20260320000100_scan_history_country.sql	New migration
supabase/tests/schema_contracts.test.sql	+3 pgTAP tests, plan 288→297

2 files changed, +26 / -1 lines

---

Acceptance Criteria

• scan_history has scan_country text REFERENCES country_ref(country_code) column
• Column is nullable (existing rows remain NULL)
• Partial index idx_sh_country exists on scan_country WHERE NOT NULL
• pgTAP: has_column('scan_history', 'scan_country') passes
• Migration is idempotent (ADD COLUMN IF NOT EXISTS)
• supabase db reset succeeds cleanly
• .\RUN_QA.ps1 — no new failures introduced

---

Verification

supabase db reset                → ✅ All 210 migrations applied cleanly
supabase test db                 → schema_contracts: 297 tests, 296 pass, 1 pre-existing failure
                                   (test 294: trg_record_score_change — unrelated)
                                   My 3 new tests (295-297) all pass.
.\RUN_QA.ps1                     → 45/49 suites pass. 4 failures are pre-existing
                                   data-dependent (Confidence, Diet, Allergen,
                                   MultiCountry — caused by db reset clearing
                                   pipeline product data, not by this migration).

Column verification

scan_country | text | YES (nullable)
idx_sh_country index exists
FK to country_ref(country_code) confirmed

---

Wording Corrections

Issue #921 body says WHERE NOT NULL in the acceptance criteria but WHERE scan_country IS NOT NULL in the SQL block. The migration uses the technically correct WHERE scan_country IS NOT NULL syntax (standard SQL).

---

Scope

This PR adds only the schema column — no API changes, no frontend changes, no data backfill. Those are handled by downstream issues in the #920 epic.

Next Issue

Recommend: #922 — schema(scanner): add scan_country + suggested_country to product_submissions

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
tryvit	Ready	Preview, Comment	Mar 17, 2026 1:31am

[Copilot]

Pull request overview

Adds country context to the scanner’s persisted history by extending scan_history with a nullable, FK-backed scan_country column. This supports the broader “country-aware scanner” epic by enabling country-scoped analytics and downstream routing decisions without changing API behavior yet.

Changes:

• Add scan_history.scan_country (nullable) with FK to country_ref(country_code).
• Add a partial index on scan_history(scan_country) for non-NULL rows to support country-scoped queries.
• Extend pgTAP schema contract tests to assert the new column, nullability, and FK; update plan count.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
supabase/migrations/20260320000100_scan_history_country.sql	Adds nullable scan_country with FK + partial index for analytics queries.
supabase/tests/schema_contracts.test.sql	Adds pgTAP assertions for the new column/FK and updates the test plan.