fix(ci): idempotent inventory migration + self-healing migrate-production (#245)

[RJK134]

Summary

Resolves #245 — the Migrate production database workflow failed red on main (commit 3ce0f13, Phase 2 / #244).

Root cause. Migration 20260612000000_inventory_stock_movements used bare CREATE TYPE / ADD COLUMN / CREATE TABLE. On a database historically synced with prisma db push (production was — see KI-018), those objects already exist, so the first prisma migrate deploy hit a Postgres "already exists" error and exited non-zero with the raw DB error, not the P3018 code. The workflow's self-heal retry loop only matched P3018, so it bailed on attempt 1 ("migrate deploy failed for an unexpected reason").

Why prod is already healthy. A later merge to main saw the now-blocked migration queue as P3018, auto-resolved it, and unblocked deploy — the most recent runs are green and production is migrated + seeded. This PR removes the fragility so the failure class can't recur, and makes a clean replay/restore safe.

Changes

• prisma/.../20260612000000_inventory_stock_movements/migration.sql — now idempotent: enum + FK constraints guarded with DO $$ … IF NOT EXISTS … $$, column/table/indexes use IF NOT EXISTS. Final schema is identical; prisma migrate deploy does not re-checksum already-applied migrations, so this is safe on the already-migrated production DB.
• .github/workflows/migrate-production.yml — the self-heal loop now also recognises the first-pass collision class (already exists / 42P07 / 42710 / 42P06 / 42701), resolves the offending migration as applied, and retries. The graceful skip-when-secret-absent guard is unchanged (no PRODUCTION_DATABASE_URL → workflow SKIPS green).
• docs/KNOWN_ISSUES.md — adds KI-028 with the root cause + fix.

Owner action

No new secret required. Keep the existing PRODUCTION_DATABASE_URL repo secret set (Settings → Secrets and variables → Actions). Without it the workflow skips green by design; forks/preview setups stay green.

Testing

• Verified all workflows' latest main runs are success/skipped (no other red workflows).
• Confirmed the failed step's annotation: "migrate deploy failed for an unexpected reason (attempt 1)" — i.e. a non-P3018 collision the old loop couldn't catch.
• Migration SQL change is schema-equivalent (guards only skip when the object already exists).
• CI (check / docker / security / GitGuardian) green on this PR.
• Next merge to main touching prisma/ runs Migrate production database green (verifies the hardened loop against the live DB).

Note: the self-built "BugBot PR Review" check is expected red until ANTHROPIC_API_KEY is valid (KI-026/KI-027) — not a code signal.

🤖 Generated with Claude Code

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4c00155. Configure here.}

[cursor]

SQLSTATE grep matches migration timestamps

Medium Severity

The self-heal branch treats a failed prisma migrate deploy as a db-push collision when the log matches 42710 or 42701 anywhere. Those five-digit sequences also appear inside 14-digit migration folder timestamps in normal “Applying migration …” lines, so an unrelated failure (syntax, connectivity, constraint) can still set COLLISION and run migrate resolve --applied on the wrong migration.

 

^{Reviewed by Cursor Bugbot for commit 4c00155. Configure here.}