[C05] Import Mapping Flow (shared)

I'm designing a multi-step screen flow for the EMS admin portal — a Spring
Boot + Angular SPA admin tool used by event operators (race directors)
to manage participants, events, and operational data. Visual language
matches existing portal screens you've designed in this project (C01, C03,
C06, E01, E02, E05) — JHipster 8 / Angular 16 / PrimeNG / ng-bootstrap
stack; match fonts, spacing, palette, density.

Design the **import flow**: an event organiser uploads a participants
CSV/XLSX, walks through a strict mapping flow, watches an async job run,
and lands on a reconciliation summary. The flow spans two use-case
screens that must feel like one journey:

  E06 upload  →  C05 columns  →  C05 cells  →  C05 verifying  →  C05 processing  →  E06 summary
   bookend         shared           shared        shared           shared            bookend

The middle four steps (C05) are SHARED — the same screens are reused
later by E08 (result import) with no behaviour change, just a different
caller key. Design accordingly: nothing in C05 may be EP-specific.

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.

============================================================
[E06] Upload screen
============================================================

Single full-screen page with a right-rail "About this screen" panel
(see "Information panel pattern" below).

Main area:
- Page title: "Import participants — <event name>".
- File picker (CSV/XLSX) with drag-and-drop zone.
- **Source system** dropdown (REQUIRED, single-select). Options come
  from the tenant's RegistrationSystem rows. Each option's data
  carries a hidden `is_self: boolean` flag that drives downstream UI
  state. Helper text below: "Where does this file come from? Pick the
  system that produced it."
- **Trust file PKs** checkbox. Default OFF. Always visible.
  - When the selected source system has `is_self == true` → ENABLED.
  - When `is_self == false` → DISABLED with tooltip on hover:
    "Trust file PKs is only available for our own registration
    systems."
  - Helper text below the checkbox: "Use the file's EventParticipant
    and Person IDs as authoritative when matching rows."
- **Update existing PII** checkbox. Default OFF. Always enabled.
  Helper text below: "When a row matches an existing person, refresh
  their name / DOB / gender / contact from the file. Blank values in
  the file never overwrite populated fields."
- "Recent imports" list below the inputs — date, filename, source
  system, row count, status. Clicking a row opens a read-only summary
  of that import (the same E06 summary screen, but for that uuid).
- Primary action: "Upload" (disabled until a file is picked AND a
  source system is selected; tooltip on the disabled button explains
  whichever requirement is missing).

On Upload click:
- POST /api/imports (multipart: file + sourceSystemId + trustPKs +
  updatePII).
- On 201 response, take the returned `uuid` and write
  `localStorage.setItem('importCaller:' + uuid, 'e06')`.
- Navigate to C05 at `/imports/{uuid}`.

============================================================
[C05] Mapping flow — shared 5-stage screen
============================================================

ONE full-screen page that progresses through 5 stages driven by the
backend state machine: COLUMN_MAPPING → CELL_MAPPING → FINGERPRINT_*
→ PROCESSING → COMPLETED/FAILED/CANCELLED.

Persistent UI on every stage:
- **Stage bar** — 5 pills at the top:
    Columns · Cells · Verifying · Processing · Done
  Current stage highlighted; prior stages marked complete; pills are
  READ-ONLY (not clickable). Forward-only flow; going back requires
  cancel + re-upload.
  - The **Verifying** pill renders SKIPPED (greyed out, dotted border
    or similar quiet treatment) when the operator's upload had
    `sourceSystem.is_self == false` OR `trustPKs == false`, because
    the backend skips FINGERPRINT_CHECK in those modes. Tooltip on
    the skipped pill: "Skipped — file is from an external system" or
    "Skipped — Trust file PKs was not enabled" depending on which
    condition skipped it. (Disabled-with-explanation rule.)
- **Right-rail "About this screen" information panel** — collapsible,
  default expanded, collapse state persisted in localStorage per screen.
  Content is STAGE-AWARE: different short purpose paragraph + bulleted
  operational details for each of the 5 stages.
- **Top-right "Cancel import" button** — DELETE /api/imports/{uuid},
  then redirect to caller's summary bookend (E06) with cancelled state.

Stage 1 — COLUMN_MAPPING
  Two-column layout:
  - Left: source CSV columns (header + first 3 sample rows for context).
  - Right: each source column's row showing what it maps to in the
    canonical schema. Three visual row states:
      • AUTO-MATCHED — quiet/grey treatment, target field shown,
        small `auto` tag, expandable to override.
      • USER-SET — neutral/strong treatment (no tag), target field shown.
      • NEEDS MAPPING — accent colour + required indicator, dropdown
        prominent.

  TARGET-FIELD FILTERING by sourceSystem.is_self:
  - When `is_self == true` — `ourEventParticipantId`, `ourPersonId`,
    and `sourceSystemParticipantId` are mappable; `sourceSystemPersonId`
    is NOT in the dropdown.
  - When `is_self == false` — `sourceSystemPersonId` and
    `sourceSystemParticipantId` are mappable; `ourEventParticipantId`
    and `ourPersonId` are NOT in the dropdown.
  - When a column's auto-suggested target was filtered out by this
    rule (e.g. file has an `EPID` column but source system is
    external), the row renders in a fourth visual state: NOT MAPPABLE
    HERE — quiet/grey treatment, target field shows "—" with helper
    icon, hover tooltip: "This column can't be mapped — your source
    system is external. The column will be ignored when the import
    runs." (Disabled-with-explanation rule.) The row is non-blocking;
    operator continues without resolving it.

  TEMPLATE AUTO-APPLY:
  - On stage entry, the SPA calls a (server-resolved) preview that
    indicates how many ColumnMappingTemplate rows match the
    `(sourceSystem, importerKey, eventTypeKey)` tuple.
  - Zero matches → no banner, default auto-suggest behaviour.
  - Exactly ONE match → mapping rows render with the template's
    mappings already applied (visually indistinguishable from
    server-suggested AUTO-MATCHED; same `auto` tag).
  - MULTIPLE matches → non-blocking banner above the mapping rows:
      "N saved templates match this source system: <name1> ·
      <name2> · <name3> — pick one to apply, or continue with
      auto-suggest only."
    Each name is a clickable chip; clicking applies that template
    (rows update to AUTO-MATCHED with the template's targets).
    Banner has a `Dismiss` button to revert to default auto-suggest.

  - Primary action bottom-right: "Continue" — disabled while any row
    is NEEDS MAPPING (NOT MAPPABLE HERE rows do not block).
    Calls PUT /api/imports/{uuid}/column-mappings.

Stage 2 — CELL_MAPPING
  List of unmatched FK values, grouped by FK type (e.g. "Category" group
  with the 3 unrecognised category strings beneath it). Each unmatched
  value gets a single filterable dropdown — ONE component reused across
  all FK types. Filter input auto-appears when the candidate list
  exceeds ~10 options; smaller lists render as a plain dropdown.
  Practical sizing: client-side filtering, hundreds of entries max.
  - Primary action: "Continue" — disabled until every unmatched FK is
    resolved. Calls PUT /api/imports/{uuid}/cell-mappings. (Renamed
    from "Start import" because the next stage might be Verifying,
    not processing.)

Stage 3 — Verifying (FINGERPRINT_CHECK / FINGERPRINT_WARN /
FINGERPRINT_ABORT)
  ONLY runs when `sourceSystem.is_self == true AND trustPKs == true`.
  Otherwise this stage is SKIPPED (pill greyed; flow auto-progresses
  to Processing).

  When running:
  - State `FINGERPRINT_CHECK` (in flight, transient ~1-3s):
    Centred panel reads "Verifying file matches our records..." with
    a thin indeterminate progress indicator. Polls
    GET /api/imports/{uuid}.

  - State `FINGERPRINT_WARN` (1-2 of 10 sample rows inconsistent):
    Stage pill turns YELLOW. Centred card:
    - Title: "We found some unexpected differences"
    - Body: "We checked <N> sample rows from your file against the
      records that match by ID. <M> rows had differences strong
      enough to flag (mismatched name, DOB, or gender)."
    - Sample table: per-row breakdown showing the matched DB record's
      values vs the file row's values, with mismatched fields
      highlighted.
    - Two buttons:
      • PRIMARY-LIKE-WARNING: "Continue anyway" — sends
        `acknowledgeFingerprintWarning=true` on the resume call and
        progresses to Processing.
      • SECONDARY: "Abort import" — DELETE /api/imports/{uuid},
        return to upload screen.

  - State `FINGERPRINT_ABORT` (≥3 of 10 inconsistent — terminal):
    Stage pill turns RED. Centred card:
    - Title: "This file doesn't look like ours"
    - Body: "<M> of <N> sample rows didn't match the records they
      claim to update. The import has been stopped to protect your
      data."
    - Same sample table.
    - Single button: "Abort import" — same DELETE + redirect.
    - No "Continue anyway" — abort is non-overrideable.

Stage 4 — PROCESSING
  Centred progress component:
  - Optional thin sub-stage label above the bar (hidden when the API
    returns no sub-stage). Designed for future API: `Validating →
    Summarising → Done`. v1 backend exposes a single PROCESSING state
    with a row-by-row counter, so the sub-stage label is hidden today
    — but the visual scaffolding is in place.
  - 0–100% progress bar.
  - "<rows processed> of <total> rows" counter.
  - Elapsed time.
  - "Cancel" button (DELETE /api/imports/{uuid}).
  - Polling cadence ~1s.

Stage 5 — Terminal (COMPLETED / FAILED / CANCELLED)
  IMMEDIATE redirect — no intermediate "Done" card.
  - Read `localStorage.getItem('importCaller:' + uuidFromRoute)`.
  - Remove that localStorage entry.
  - Navigate to the matching bookend's summary screen.
  - Fallback if caller key missing: navigate to `My imports` list.

State-error UX:
  - 409 on PUT /column-mappings or /cell-mappings — toast "This step
    has already been completed" + auto-refresh state via
    GET /api/imports/{uuid}.
  - Fatal job error (non-fingerprint) — render the failure with
    reason + a "Try again" action that returns to the caller's
    upload screen.

============================================================
[E06] Summary screen — pure reconciliation view
============================================================

Operator arrives here from C05's terminal-state redirect. The job is
already in a terminal state — this screen does NOT poll, does NOT show
a progress bar, and never reverts to "in-flight" rendering.

On mount:
- Call GET /api/imports/{uuid}/results once.
- Render the reconciliation view.

Layout:
- Page header — "Import complete" (or "Import cancelled" / "Import
  failed"), filename, finished-at timestamp, source system name,
  "N rows processed" counter.
- Right-rail "About this screen" panel (same pattern as C05; copy
  describes what the summary represents and what to do next).
- Body: per-row reconciliation, in tabbed sections:
  - Created / updated counts.
  - Unresolved-person count + drill-down list.
  - FK-mismatch count + drill-down list (e.g. category not found).
  - Merge candidates created (when present): list with link to merge
    review queue. Surfaces external-UID-vs-SAID collisions.
  - Ignored columns (when present): list of columns that were
    auto-filtered out by the source-system rule (e.g. "EPID — column
    ignored because the source system is external"). One-line
    warning, not a hard error.
- Bottom: "Open event participants" (links to E02) + "Import another
  file" (returns to E06 upload).

Failure-mode rendering:
- CANCELLED → header reads "Import cancelled" + the same per-row
  breakdown for whatever was processed before cancel.
- FAILED → header reads "Import failed" + reason + "Try again"
  returning to the upload screen.
- Fingerprint-aborted job (FAILED with fingerprint-abort reason) —
  same FAILED layout, but the sample-mismatch table from C05 is
  preserved at the top of the body so the operator has a reference
  when they investigate the file offline.

============================================================
Information panel pattern (cross-cutting)
============================================================

Persistent collapsible right-rail panel ("About this screen") on every
full-screen step in this flow. Default expanded. Collapse state
persisted per-screen-key in localStorage. Content per screen:
- Short purpose paragraph (1–2 sentences explaining what THIS step is
  for).
- Bulleted operational details (the things an operator might be
  unsure about — what `is_self` means, what `Trust file PKs` enables,
  what `auto` means, what happens on cancel, what fingerprint
  verification is doing, etc).

Goal: train operators in-flow. They shouldn't need external docs to
complete an import.

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

For each of the 6 screen states (E06 upload, C05 columns, C05 cells,
C05 verifying [render all three sub-states: in-flight, warn, abort],
C05 processing, E06 summary):
- HTML/JSX + matching styles.
- Screen README that explains what it does and which API endpoints
  it consumes.
- Cross-screen README that explains:
  - The caller-key contract (per-uuid scoping, who writes, who reads,
    who removes, fallback).
  - The stage-ownership split (C05 owns columns/cells/verifying/
    processing; bookend owns upload + summary).
  - When the Verifying stage is skipped vs run (the
    `is_self && trustPKs` predicate) and how the SKIPPED pill state
    is rendered + tooltipped.
  - How target-field filtering changes when the operator picks
    different source systems on the upload screen.
  - How the template auto-apply + multi-match banner relate to the
    server's stored ColumnMappingTemplate rows.
  - How to reuse C05 unchanged when E08 (result import) becomes the
    caller — the only difference is the literal value written to the
    caller key (`'e06'` vs `'e08'`).

I'm designing a multi-step screen flow for the EMS admin portal — a Spring
Boot + Angular SPA admin tool used by event operators (race directors)
to manage participants, events, and operational data. Visual language
matches existing portal screens you've designed in this project (C01, C03,
E01, E05) — JHipster 8 / Angular 16 / PrimeNG / ng-bootstrap stack;
match fonts, spacing, palette, density.

Design the **import flow**: an event organiser uploads a participants
CSV/XLSX, walks through a strict 2-phase mapping flow, watches an async
job run, and lands on a reconciliation summary. The flow spans two
use-case screens that must feel like one journey:

  E06 upload  →  C05 columns  →  C05 cells  →  C05 processing  →  E06 summary
   bookend         shared           shared        shared            bookend

The middle three steps (C05) are SHARED — the same screens are reused
later by E08 (result import) with no behaviour change, just different
caller key. Design accordingly: nothing in C05 may be EP-specific.

============================================================
[E06] Upload screen
============================================================

Single full-screen page with a right-rail "About this screen" panel
(see "Information panel pattern" below).

Main area:
- Page title: "Import participants — <event name>".
- File picker (CSV/XLSX) with drag-and-drop zone.
- One option: **Mode** — radio: `Overwrite` (default) | `Append`.
- "Recent imports" list below the picker — date, filename, row count,
  status. Clicking a row opens a read-only summary of that import (the
  same E06 summary screen, but for that uuid).
- Primary action: "Upload" (disabled until file picked).

On Upload click:
- POST /api/imports (multipart: file + mode).
- On 201 response, take the returned `uuid` and write
  `localStorage.setItem('importCaller:' + uuid, 'e06')`.
- Navigate to C05 at `/imports/{uuid}`.

============================================================
[C05] Mapping flow — shared 4-stage screen
============================================================

ONE full-screen page that progresses through 4 stages driven by the
backend state machine: COLUMN_MAPPING → CELL_MAPPING → PROCESSING →
COMPLETED/FAILED/CANCELLED.

Persistent UI on every stage:
- **Stage bar** — 4 pills at the top: Columns · Cells · Processing · Done.
  Current stage highlighted; prior stages marked complete; pills are
  READ-ONLY (not clickable). Forward-only flow; going back requires
  cancel + re-upload.
- **Right-rail "About this screen" information panel** — collapsible,
  default expanded, collapse state persisted in localStorage per screen.
  Content is STAGE-AWARE: different short purpose paragraph + bulleted
  operational details for each of the 4 stages.
- **Top-right** "Cancel import" button — DELETE /api/imports/{uuid},
  then redirect to caller's summary bookend (E06) with cancelled state.

Stage 1 — COLUMN_MAPPING
  Two-column layout:
  - Left: source CSV columns (header + first 3 sample rows for context).
  - Right: each source column's row showing what it maps to in the
    canonical schema. Three visual row states:
      • AUTO-MATCHED — quiet/grey treatment, target field shown,
        small `auto` tag, expandable to override.
      • USER-SET — neutral/strong treatment (no tag), target field shown.
      • NEEDS MAPPING — accent colour + required indicator, dropdown
        prominent.
    Operator's job is to scan auto-matched rows (the `auto` tag is the
    review affordance) and resolve any NEEDS MAPPING rows.
  - Primary action bottom-right: "Continue" — disabled while any row is
    NEEDS MAPPING. Calls PUT /api/imports/{uuid}/column-mappings.

Stage 2 — CELL_MAPPING
  List of unmatched FK values, grouped by FK type (e.g. "Category" group
  with the 3 unrecognised category strings beneath it). Each unmatched
  value gets a single filterable dropdown — ONE component reused across
  all FK types. Filter input auto-appears when the candidate list
  exceeds ~10 options; smaller lists render as a plain dropdown.
  Practical sizing: client-side filtering, hundreds of entries max.
  - Primary action: "Start import" — disabled until every unmatched FK
    is resolved. Calls PUT /api/imports/{uuid}/cell-mappings.

Stage 3 — PROCESSING
  Centred progress component:
  - Optional thin sub-stage label above the bar (hidden when the API
    returns no sub-stage). Designed for future API: `Validating → 15%
    → 47% → 84% → Summarising → Done`. v1 backend exposes only one
    PROCESSING state with a row-by-row counter, so the sub-stage label
    is hidden today — but the visual scaffolding is in place.
  - 0–100% progress bar.
  - "<rows processed> of <total> rows" counter.
  - Elapsed time.
  - "Cancel" button (DELETE /api/imports/{uuid}).
  - Polling cadence ~1s.

Stage 4 — Terminal (COMPLETED / FAILED / CANCELLED)
  IMMEDIATE redirect — no intermediate "Done" card.
  - Read `localStorage.getItem('importCaller:' + uuidFromRoute)`.
  - Remove that localStorage entry.
  - Navigate to the matching bookend's summary screen.
  - Fallback if caller key missing: navigate to `My imports` list.

State-error UX:
  - 409 on PUT /column-mappings or /cell-mappings — toast "This step has
    already been completed" + auto-refresh state via GET /api/imports/{uuid}.
  - Fatal job error — render the failure with reason + a "Try again"
    action that returns to the caller's upload screen.

============================================================
[E06] Summary screen — pure reconciliation view
============================================================

Operator arrives here from C05's terminal-state redirect. The job is
already in a terminal state — this screen does NOT poll, does NOT show
a progress bar, and never reverts to "in-flight" rendering.

On mount:
- Call GET /api/imports/{uuid}/results once.
- Render the reconciliation view.

Layout:
- Page header — "Import complete" (or "Import cancelled" / "Import
  failed"), filename, finished-at timestamp, "N rows processed" counter.
- Right-rail "About this screen" panel (same pattern as C05; copy
  describes what the summary represents and what to do next).
- Body: per-row reconciliation, in tabbed sections:
  - Created / updated counts.
  - Unresolved-person count + drill-down list.
  - FK-mismatch count + drill-down list (e.g. category not found).
- Bottom: "Open event participants" (links to E02) + "Import another
  file" (returns to E06 upload).

Failure-mode rendering:
- CANCELLED → header reads "Import cancelled" + the same per-row
  breakdown for whatever was processed before cancel.
- FAILED → header reads "Import failed" + reason + "Try again" returning
  to the upload screen.

============================================================
Information panel pattern (cross-cutting)
============================================================

Persistent collapsible right-rail panel ("About this screen") on every
full-screen step in this flow. Default expanded. Collapse state
persisted per-screen-key in localStorage. Content per screen:
- Short purpose paragraph (1–2 sentences explaining what THIS step is for).
- Bulleted operational details (the things an operator might be unsure
  about — what mode does, what `auto` means, what happens on cancel,
  etc).

Goal: train operators in-flow. They shouldn't need external docs to
complete an import.

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

For each of the 5 screens (E06 upload, C05 columns, C05 cells, C05
processing, E06 summary):
- HTML/JSX + matching styles.
- Screen README that explains what it does and which API endpoints
  it consumes.
- Cross-screen README that explains:
  - The caller-key contract (per-uuid scoping, who writes, who reads,
    who removes, fallback).
  - The stage-ownership split (C05 owns processing; bookend owns summary).
  - How to reuse C05 unchanged when E08 (result import) becomes the
    caller — the only difference is the literal value written to the
    caller key (`'e06'` vs `'e08'`).

[Long prompt with 4 stages: Upload → Column mapping → Cell mapping → Processing+results;
 attempted to address the 2-phase issue but still didn't reference the canonical `.adoc`,
 invented some details (e.g. "Save mapping as template") that aren't in the spec, and the
 user said "Even the updated prompt is incorrect. Lets take a step back and review how we
 are supposed to design this."]

I'm designing a screen for the EMS admin portal — a Spring Boot + Angular SPA
admin tool that lets event operators (race directors) manage participants,
events, members, and operational data.

Context: a tenant operator uploads a CSV (or pastes spreadsheet rows) of
participants or race results. The CSV's column headers don't match our
canonical field names — e.g. "First Name" vs our `firstName`, "Email Address"
vs our `email`. C05 is the shared mapping screen used by every import in
the system: participant import, result import, future entrant imports.

Design a screen that:
- Shows the CSV's detected columns on the left (header row + first 3 sample
  rows of data).
- Shows our canonical fields on the right (about 15 fields for participants:
  firstName, lastName, idNumber, idType, email, phone, dateOfBirth, gender,
  category, raceNumber, t-shirtSize, emergencyContact, etc.). Required fields
  are marked.
- Lets the user drag-link or dropdown-select which CSV column maps to which
  canonical field. Auto-suggests obvious matches (case-insensitive name
  similarity).
- Shows real-time validation: missing required mappings, duplicate mappings,
  type mismatches (e.g. mapping "First Name" column to a `dateOfBirth` field).
- Has a "preview parse" pane below the mapping showing what the first 5 rows
  would look like after the mapping is applied. Errors highlighted inline.
- Has a "Save mapping as template" option — operators import the same shape
  of file weekly and shouldn't have to re-map every time. Templates are
  named and per-event-type.
- Bottom toolbar: Cancel, Save Template, Start Import (disabled until
  required mappings are filled and preview is error-free).

Style consistency: this lives inside a Spring Boot gateway portal modeled
on the JHipster 8 / Angular 16 / PrimeNG / ng-bootstrap stack used in
registration-portal. Existing screens you've designed in this project
(C01 user/tenant switcher, C03 navigation shell, E01 event overview, E05
events control centre) should set the visual language — same fonts,
spacing, color palette, density.

Output: HTML/JSX + matching styles, a screen README explaining the data
contract (input CSV shape, output mapping JSON shape), and a 3-line
summary of how this screen is reused across importers.