F 11 Payouts

Status: 🟢 ready to test Owner: Adilet Last updated: 2026-05-08 Last verified on production: —

Goal

An admin settles approved issues by paying testers. Three paths exist, in order of preference:

1. Period batch — preferred. Pick a date range; one transaction pays every approved + verified issue across the whole window.
2. Per-tester batch — pay one tester's outstanding queue in one click. For one-off settlements between periods.
3. Per-issue manual payment — pay a single issue. For corrections and edge cases.

All three paths write to issue_payouts (the audit ledger) first, then flip issues.payout_status='paid'. The verification gate (F-10) applies to all three.

Actors

• Primary — Admin
• Secondary — Testers (notified via ISSUE_PAID)

Preconditions

• At least one issue exists with payout_status='approved' and (if gate active) status='verified'
• Admin is signed in

Trigger

Admin opens /app/admin/payouts.

Path A — Period batch (preferred settlement)

Path B — Per-tester batch

Path C — Per-issue manual payment

Acceptance criteria

• AC-1 — Given a date range, when admin runs dryRun=true, then the response lists every issue that would be paid, totals by currency, unique tester count, and any failedIssueIds (bad data) / unverifiedIssueIds (gate blocking).
• AC-2 — Given the same range and dryRun=false, when the run commits, then payout_batches has one new row, issue_payouts has N rows with batch_id pointing to that batch, and N issues are flipped to paid.
• AC-3 — Given the gate is active and an approved-unverified issue falls in the range, then the run excludes it and reports it in unverifiedIssueIds. The issue stays approved.
• AC-4 — Given a tester has 5 paid issues in a batch, when the notifications fan out, then they receive one row per paid issue (5 rows), each linking to the issue detail.
• AC-5 — Given the per-tester batch endpoint, when a list of issue IDs is supplied, then it pays exactly those (intersection with approved + verified-if-gated). Non-eligible IDs are reported back.
• AC-6 — Given the per-issue payment, when the gate is active and the issue is not verified, then the API returns 400 "issue not verified".
• AC-7 — Given a paid issue, when admin tries to approve it again via triage, then API 400 (allowed transitions: paid → void).
• AC-8 — Given a payout_batches row exists, when the corresponding rows are deleted from issue_payouts (manual fix), then the batch row is harmlessly orphaned — no FK violation (soft FK, set null on delete).

Test data / fixtures

• Baseline seed
• 3+ approved + verified issues spread across 2 testers, with at least 2 different payout_currency values if you want to verify multi-currency totals

Negative paths

Manual QA checklist

• On /app/admin/payouts aggregate header, confirm "Approved · unpaid" totals match the pay queue
• Open RunBatchPanel, pick "Last 7 days" → preview loads, shows N issues + totals
• Confirm any unverified issues are listed in the preview's "excluded" callout
• Pick method=Kaspi, reference="TST-2026-W19", notes="QA test batch"
• Click "Run batch" → success toast with paid count + totals
• Verify payout_batches has a new row; issue_payouts has N rows linking to it
• Sign in as a tester who got paid → bell shows "Paid: via Kaspi · ref TST-2026-W19"
• Sign in as same tester → /app/test-cycles/balance "Total paid" bumped, "Available" reduced
• Run pay-all on a tester group via "Pay queue" → second path (per-tester batch) works the same
• On an individual approved+verified issue, click "Mark paid" → per-issue path
• Try a per-issue payment on a non-verified issue (gate active) → 400

Automated test outline

test.describe("F-11 payouts", () => {
  test("period batch dry run + commit", async ({ request }) => { … });
  test("per-tester batch", async ({ request }) => { … });
  test("per-issue gated by verification", async ({ request }) => { … });
  test("notifications fan out", async ({ request }) => { … });
  test("paid → void only", async ({ request }) => { … });
});

Code references

• Pages: src/app/app/admin/payouts/page.tsx
• UI:
  • src/components/test-cycles/admin/RunBatchPanel.tsx (period batch)
  • src/components/test-cycles/admin/BatchPayDialog.tsx (per-tester)
  • src/components/test-cycles/admin/PayoutsByTesterTable.tsx (queue)
  • src/components/test-cycles/ApprovalPayoutCard.tsx (per-issue)
  • src/components/test-cycles/PayoutTotalsCard.tsx (aggregate header)
• API:
  • src/app/api/admin/payouts/run-batch/route.ts (period batch — dry-run + commit)
  • src/app/api/admin/payouts/batch-pay/route.ts (per-tester)
  • src/app/api/test-cycles/[id]/issues/[issueId]/payments/route.ts (per-issue)
  • src/app/api/admin/payouts/route.ts (queue feed)
• Hooks: src/hooks/test-cycles/admin-payouts.ts
• Lib: src/lib/issue-payout.ts (requiresVerification, effectiveRatesFor)
• Schema: payout_batches, issue_payouts (with batch_id), issues.payout_*, PAYMENT_METHODS, ISSUE_PAID notification

Events emitted (proposed)

• payout.batch_run — { batch_id, paid_count, tester_count, totals_by_currency, method, period_start, period_end, run_by }
• payout.tester_batch_paid — { paid_count, tester_id, totals_by_currency, method, run_by }
• payout.issue_paid — { issue_id, amount_cents, currency, method, paid_by }
• payout.gate_blocked — { issue_id, source: 'run_batch' \| 'batch_pay' \| 'manual' }

Open questions / known gaps

• Past batches view is not built yet — payout_batches rows have no UI for drill-down / receipt regen / void. This is the highest-leverage follow-up (flagged in feature-matrix.md §5.2).
• Void path exists in the schema (PAYOUT_STATUSES.VOID, paid → void transition allowed), but no UI button.
• No idempotency key on run-batch (relies on the approved status filter to prevent double-pay).
• Multi-currency totals shown as separate lines (intentional — we don't FX-convert).