[T03] Stock Return Workflow

I'm designing a screen for the EMS admin portal — a Spring Boot + Angular SPA
admin tool used by stock operators and tenant admins to manage race-number
inventory. Visual language matches existing portal screens you've designed
in this project (C01, C03, E01, E05, E06, T02). JHipster 8 / Angular 16 /
PrimeNG / ng-bootstrap stack; match fonts, spacing, palette, density.

Design **T03 — the Stock Return Workflow**: a three-stage screen where a
stock operator scans / pastes / types a list of race numbers being returned
to stock, reviews predicted outcomes, submits, and sees per-number outcome
rows.

T03 sits inside C01's shell. Sidebar is in the `tenant` scope (a new third
scope alongside `portfolio` and `event`, added in this design round) under
the "Inventory" group: Stock (T02), Return (THIS), Bulk (T04), Onboard,
Manufacturer export. T03 owns the main content area.

A cross-cutting design rule: any disabled, hidden-by-policy, or limited
affordance MUST surface its reason inline (tooltip on hover, helper text,
empty-state copy). Operators should never have to guess why a control is
unavailable.

A second cross-cutting rule: every full-screen flow in this portal
includes a persistent collapsible right-rail "About this screen" panel
with stage-aware copy — same pattern as C04, C05, E06.

============================================================
Three stages on ONE screen, driven by component state
============================================================

The flow is: BUILD list  →  CONFIRM  →  OUTCOME SUMMARY
                stage 1       stage 2        stage 3

A small stage indicator at the top reads `Build · Confirm · Done`. Pills
are read-only (not clickable).

Persistent UI on every stage:
- Stage indicator at top.
- Right-rail "About this screen" panel — collapsible, default expanded,
  collapse state persisted in localStorage. Stage-aware copy.
- Top-right "Reset" button — clears the list, returns to Stage 1.

============================================================
Stage 1 — Build the returned list
============================================================

Two-column layout:
- Left column (1fr) — Scan input.
  - Big focus-on-mount text input with placeholder "Scan, paste, or type
    a number — Enter to add". Accepts: race-number `number` (e.g.
    "P3014"), sequence (e.g. "3014"), or tag-mate barcode (long digit
    string).
  - Below the input: a small live "Last scan: <value>" line so the
    operator gets visual feedback that the keywedge fired.
  - Optional textarea below for pasting multiple lines (one per line).
    Pasted text is absorbed into the list, one entry per line.
  - Helper text: "USB keywedge, hand-scanner, or paste from a
    spreadsheet — one number per line."
  - Optional "Note (applies to this submission)" text input below the
    main input. Free text. Passes through to the API as the request's
    `note` field.

- Right column (1.4fr) — The returned-list builder.
  - Each entry is a row with:
    - the scanned input (left, monospace)
    - the resolved bib number + state pill (centre) — blank until
      lookup resolves
    - a predicted-outcome chip on the right — one of:
        RETURNED · DISPOSAL_RECOMMENDED · NO_OP · NOT_FOUND · AMBIGUOUS
      with a tooltip showing what each predicts.
    - delete (X) button on the row's far right.
  - When a number is scanned twice in the same session, the existing
    row gains a "scanned ×N" badge; no second row is added.
  - Stage-1 footer: "{N} entries — Continue" primary button (disabled
    while {N} === 0 or any AMBIGUOUS row remains unresolved); helper
    counts: `{X} found · {Y} not found · {Z} ambiguous`.

============================================================
Stage 2 — Confirmation
============================================================

Centred summary card:
- Title: "Confirm return — {N} numbers"
- Predicted-outcome counts as four large tiles:
    Returned to stock · Recommend disposal · Already in stock · Not recognised
  Each tile shows the count and a single-line description of what
  happens (or doesn't) for that outcome — see the .adoc copy table.
- Optional note (read-only — shown if the operator typed one in
  Stage 1).
- Two buttons at the bottom:
  - Secondary: "Back — edit list" → returns to Stage 1 with the list
    intact and focus on the input field.
  - Primary: "Submit return" — disables on click, fires
    POST /api/race-numbers/return, transitions to Stage 3 on response.

A failure-state inline notice appears in this card if the request
fails: "Couldn't submit. {error}. Try again — your list is preserved."
The Submit button re-enables on failure.

============================================================
Stage 3 — Outcome summary
============================================================

Layout:
- Page header: "Returned {N} numbers" + finished-at timestamp.
- Tabbed sections, one per outcome code, in this order with these
  exact tab titles + sub-context blurbs:
    1. "Returned to stock — N"
       "These numbers were with a participant or in use; they're now
        back in stock and available for re-issue."
    2. "Recommend disposal — N"
       "These numbers were flagged UNFIT before return. Ownership
        cleared. Use Dispose these N below to mark them DESTROYED,
        or keep them flagged for later."
       Tab body has a primary button "Dispose these {N}" at the top
       that navigates to T04's confirm dialog with the UNFIT ids
       pre-loaded.
    3. "Already in stock or terminal — N"
       "Nothing to do for these — they were already in stock, never
        tracked, or already destroyed. Safe outcome of a double-scan
        or a re-submit after a partial failure."
    4. "Not recognised — N"
       "We couldn't find a number matching this scan. Most often a
        typo, a foreign-system number, or a damaged barcode. Use
        Edit list to correct or remove."
       Tab body has an "Edit list" action that returns to Stage 1
       with the list rehydrated and focus on the first NOT_FOUND
       row's input.
- Tabs that have zero count are still visible but greyed; click
  shows the tab body with an empty state.
- Per-row entries inside each tab: scanned input (left), resolved bib
  number + state pill (centre), drill-down link "View audit log →" on
  the right. Drill-down link navigates to T02 with the bib id in the
  drill-down panel pre-opened (T02 reads `?openLog={id}` from the URL
  and opens the side panel automatically).
- Footer:
  - Secondary: "Return more numbers" — resets to Stage 1 with an
    empty list.
  - Primary: "Done" — navigates back to T02.

============================================================
Idempotency / double-scan behaviour
============================================================

The right-rail "About this screen" panel must explain on Stage 1, 2,
and 3 that:
- The endpoint is idempotent — re-submitting numbers that are already
  in stock produces "Already in stock" outcome rows; nothing else
  happens.
- A scanner double-firing on the same number produces a single list
  entry with a "scanned ×N" badge — submit body still contains the
  number once.
- Operators can safely re-submit the entire list after a partial
  failure — rows that landed last time return as "Already in stock"
  this time; rows that didn't land transition normally.

============================================================
API surface
============================================================

POST /api/race-numbers/return
  Request:  { "numberIds": [Long...], "note": "string?" }
  Response: { "outcomes": [{ "numberId": Long, "outcome": "RETURNED"|"DISPOSAL_RECOMMENDED"|"NO_OP"|"NOT_FOUND", "scannedInput": "string?", "stateBefore": "...", "stateAfter": "..." }, ...] }

(Stage 1 lookup endpoint — TBD on Thread B's criteria sweep — may be
either a dedicated single-row lookup OR a paginated /stock?q= query.
Render the lookup with whatever shape Thread B confirms.)

POST /api/race-numbers/dispose  (used by the "Dispose these N" shortcut)
  See T04.

GET /api/race-numbers/{id}/state-log
  Returns: List<RaceNumberStateLogDTO> ordered by createdDate DESC.
  T03 does NOT call this directly; the drill-down link navigates to
  T02 with `?openLog={id}` and T02's side panel calls the endpoint.

============================================================
Output
============================================================

For each of these screen states:
  - Stage 1 — empty list (just the input)
  - Stage 1 — list with mixed rows (RETURNED + DISPOSAL_RECOMMENDED +
    NOT_FOUND + a "scanned ×3" double-scan row)
  - Stage 2 — confirmation with 12 / 4 / 2 / 1 outcome counts
  - Stage 3 — outcome summary with all four tabs populated, "Recommend
    disposal" tab open showing the Dispose-these-N shortcut button
  - Stage 3 — outcome summary with a NOT_FOUND-heavy result, "Not
    recognised" tab open showing the Edit-list affordance
  - Stage 2 failure inline notice

Provide:
  - HTML/JSX + matching styles per stage / state.
  - Screen README explaining the three stages, the idempotency
    contract (and how it surfaces in the UI), the four outcome codes,
    and the API endpoints consumed.
  - Cross-screen note: T03 hands off to T04 (modal launch) for the
    Dispose-these-N shortcut, and back to T02 for `Done`. The T02 and
    T04 screens are designed separately in this same round.