[T03] Stock Return Workflow

Summary

Stock-take return workflow. Operator scans/imports returned numbers; system clears person_id and transitions each to IN_STOCK. Treats pre-assigned and stock-held tags identically per the project feedback feedback_returns_stock_model.md.

Actor & Context

Actor: stock operator, tenant admin. Frequency: post-event; periodic stock-takes. Precondition: user has TENANT_ADMIN permission; physical numbers in hand or scanned data ready. Entry point: Tenant-admin workspace nav Stock return; or from T02 selection.

Main Flow

  1. Bulk scanning input — USB keywedge / barcode / manual entry / paste from spreadsheet.

  2. Returned-list builder — appends each scanned number; delete + undo per row.

  3. Confirmation — shows transitions to be applied (per ADR-0001: RaceNumberAssignmentServiceEx.recordNumberAssignment is the only path).

  4. Operator confirms — POST batch return.

  5. Post-confirmation summary — per-number outcome (RETURNED, DISPOSAL_RECOMMENDED, NO_OP, NOT_FOUND); audit-log link per number.

Alternative Flows

  • AF-1: Scanned ID not found — surfaces NOT_FOUND row; operator can correct or remove.

  • AF-2: UNFIT entries in the DISPOSAL_RECOMMENDED list link through to T04.

  • AF-3: Loan number return — clears person_id while preserving EP→number history (per the journal).

Acceptance Criteria

  • Use-case page authored.

  • Status design-todo → handoff-ready after Claude Design pass.

  • Implementation calls the existing return endpoint(s).

  • Pre-assigned + stock-held tags treated identically; ownership cleared uniformly.

  • Loan number history preserved on return.

API Surface

Call Purpose

POST /api/race-numbers/return

Batch return endpoint (existing).

Out of Scope

  • Stock browsing — T02.

  • Bulk flag/dispose for UNFIT — T04.

  • Tag-level scanning (vs number scanning) — pending WS3.

Design Anchors

Notes

Honour the feedback rule: returns clear ownership uniformly; do NOT scope by event_id or recency. Post-event return clears person_id while preserving EP→number history for results.