8d6f798f2d
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>
36 lines
1.6 KiB
SQL
36 lines
1.6 KiB
SQL
-- 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';
|