veza/veza-backend-api/migrations/982_seller_transfers_reversal_pending_index.sql

37 lines
1.6 KiB
MySQL
Raw Normal View History

feat(marketplace): seller transfer state machine matrix — v1.0.7 item B day 1 Day-1 foundation for item B (async Stripe Connect reversal worker). No worker code, no runtime enforcement yet — just the authoritative state machine that day 2's code will route through. Before writing the worker we want a single place where the legal transitions are defined and tested, so the worker's behavior can be argued against the matrix rather than implicitly codified across call sites. transfer_transitions.go: * SellerTransferStatus constants (Pending, Completed, Failed, ReversalPending [new], Reversed [new], PermanentlyFailed). * AllowedTransferTransitions map: pending → {completed, failed}; completed → {reversal_pending}; failed → {completed, permanently_failed}; reversal_pending → {reversed, permanently_failed}; reversed and permanently_failed as dead ends. * CanTransitionTransferStatus(from, to) — same-state always OK (idempotent bumps of retry_count / next_retry_at); unknown from fails conservatively (typos in call sites become visible). transfer_transitions_test.go: * TestTransferStateTransitions iterates the full 6×6 matrix (36 pairs) and asserts every pair against the expected outcome. * TestTransferStateTransitions_TerminalStatesHaveNoOutgoing double-locks Reversed + PermanentlyFailed as dead ends at the map level (not just at the caller level). * TestTransferStateTransitions_MatrixKeysAreAccountedFor keeps the canonical status list in sync with the map; a new status added to one but not the other fails the test. * TestCanTransitionTransferStatus_UnknownFromIsConservative documents the "unknown from → always false" policy so a future reader sees the intent. Migration 982 adds a partial composite index on (status, next_retry_at) WHERE status='reversal_pending', sibling to the existing idx_seller_transfers_retry (scoped to failed). Two parallel partial indexes cost less than widening the existing one (which would need a table-level lock) and keep the worker query planner- friendly. Day 2 routes processSellerTransfers, TransferRetryWorker, reverseSellerAccounting, admin_transfer_handler through CanTransitionTransferStatus at every Status mutation, and writes StripeReversalWorker. Day 3 exercises the end-to-end flow (refund → reversal_pending → worker → reversed) in a smoke probe. Checkpoint: ping user at end of day 1 before day 2 per discipline agreed upfront. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-17 12:13:02 +00:00
-- v1.0.7 item B (day 1): partial composite index for the reversal
-- worker's hot path.
--
-- The worker's select per tick is:
-- SELECT * FROM seller_transfers
-- WHERE status = 'reversal_pending'
-- AND (next_retry_at IS NULL OR next_retry_at <= NOW())
-- ORDER BY next_retry_at NULLS FIRST
-- LIMIT 20;
--
-- Migration 116 already provides idx_seller_transfers_retry on
-- `(status, next_retry_at) WHERE status='failed' AND next_retry_at
-- IS NOT NULL` for TransferRetryWorker. That index cannot serve the
-- reversal worker's query because (a) the partial WHERE clause
-- excludes reversal_pending rows, and (b) it excludes rows with
-- next_retry_at NULL — which are exactly the freshly-inserted
-- reversal_pending rows the worker should pick up on first pass.
--
-- This migration adds a sibling partial index scoped to
-- reversal_pending, including NULL next_retry_at so the first-pass
-- rows land in the index.
--
-- Why not widen migration 116's existing index instead: widening a
-- partial index requires dropping and recreating it, which would
-- require a table-level lock. Two parallel partial indexes is the
-- cheaper DDL.
--
-- No state machine enforcement in this migration — the authoritative
-- transition matrix lives in
-- `internal/core/marketplace/transfer_transitions.go` and is exercised
-- by TestTransferStateTransitions. Day 2 routes call sites through
-- the matrix; day 3 exercises the end-to-end flow in a smoke probe.
CREATE INDEX IF NOT EXISTS idx_seller_transfers_reversal_pending
ON seller_transfers(status, next_retry_at)
WHERE status = 'reversal_pending';