Result Import Functional Requirements

Upload endpoint: PUT /api/result-sets/import-bulk

Results endpoint: GET /api/result-sets/import/{jobId}

Rows are grouped by the Registration Event column value

Each group maps to the ResultSet of the Race whose EventCategory.name matches the group value

A group whose category cannot be resolved is reported in unmatchedCategories and its rows are not imported

epid (default): resolve as EventParticipant.id

regid: resolve as EventParticipant.registrationId scoped to the target event (used when the timing system holds legacy / external PKs)

pid: resolve as EventParticipant.person.id scoped to the target event (used when the timing system holds User/Person ids)

The mode is case-insensitive

Unknown values fall back to the default with a log warning

When resolution fails, the row is counted as skipped and must be reported in sufficient detail for the operator to identify the cause

Rows present in the CSV with a matching existing seq update in place

Rows present in the CSV with no matching existing seq are inserted

Existing RaceResult records whose seq is not present in the CSV are deleted

Participants moved between categories (different Registration Event value than previously imported) naturally disappear from the old ResultSet and appear in the new one

No RaceResult state from a prior import survives outside what the CSV dictates

Each RaceResult carries a non-null seq after a successful import

Re-importing the same CSV against the same ResultSet does not change any RaceResult.id

Legacy rows with seq = NULL (from before upsert-by-seq existed) are removed on first import after deploy

Upsert matches on (resultSet, seq), not (resultSet, position) - positions can tie (dead heats) or duplicate (lapped riders)

Response contains fileLines: total lines in the uploaded file

Response contains summary.dataRows, summary.imported, summary.skipped

Response contains summary.nonDataRows.blankLines, summary.nonDataRows.repeatedHeaders, summary.nonDataRows.malformedRows

Invariant: fileLines == 1 (header) + summary.nonDataRows.totalNonData + summary.dataRows

Invariant: summary.dataRows == summary.imported + summary.skipped

If either invariant fails, the response is considered diagnostic rather than complete and the operator must investigate

blankLines: empty or whitespace-only lines (expected in concatenated per-category exports)

repeatedHeaders: rows whose Registration Event cell equals the literal header text (detected dynamically against the actual header cell, not a hardcoded string, so behaviour survives timing-system column renames)

malformedRows: rows with too few fields to reach the category column

The three buckets never overlap

The sum is surfaced as summary.nonDataRows.totalNonData

Genuinely unresolvable category names appear in unmatchedCategories

Rows belonging to an unmatched category are not imported, and are excluded from any summary.imported count

Repeated header rows are not surfaced as unmatched categories (they are counted in nonDataRows.repeatedHeaders instead)

Query parameter pointsCalculator selects the strategy by short code or fully-qualified class name

Default strategy is the SA School Cycling calculator

A calculator exists for the WPCA Road League point scheme (50/45/40/36/34/32/30/28/26/24/22/20 for positions 1–12; 2 participation points for positions 13+; 0 for non-finishers)

Non-finishers (position NULL, status DNF/DNS/DQ/LAPPED) score 0 points regardless of synthetic position

New strategies can be added without modifying the import code

Changes are classified as:

Each change is reported with the EventParticipant id, name, old and new numbers, classification, status, and a human-readable message

Detection is non-destructive: no EventParticipant.number is modified unless applyNumberChanges=true

applyNumberChanges defaults to false

SIMPLE changes are applied through RaceNumberAssignmentServiceEx.addNumberNoLaterThan (same path as UI-driven assignment, preserving validation and history)

The applied change’s status transitions to APPLIED in the response

SWAP changes are reported but not auto-applied (operator decides)

CONFLICT changes are never auto-applied

Apply failures are reported with status=ERROR and a diagnostic message; other rows are unaffected

RaceResult.id values are preserved across identical re-imports

points, laps, position, duration_milli_second, status are recalculated and rewritten on every run (last-write-wins)

Number-change detection is idempotent (re-running reports the same changes)

There is no side-effect that only happens on second import (no "double-apply" of number changes)

If the resolution failure rate for a category exceeds a safety threshold, the reconciliation delete pass is aborted for that category

The response indicates the category was skipped for safety and names the most likely cause (wrong mode, stale file, missing registrationId population)

Successful categories in the same import still commit (partial success is allowed)

Non-numeric Place values (Drop, DNF, DNS, DQ) are parsed and stored as RaceResult.status

Non-finishers receive 0 points regardless of calculator

Synthetic trailing positions are assigned so reports sort consistently (finishers first, then non-finishers at the end)

The original Place string is preserved for audit (pending schema change)

Unknown eventId → results endpoint returns COMPLETED with FAILED status on the job and a diagnostic message (async path) — the upload itself still accepts.

Malformed multipart or missing file → upload returns 400 Bad Request synchronously (before the job is created).

Unparseable CSV (IO error, encoding failure) → upload returns 500 Internal Server Error at creation time, or the job transitions to FAILED if detected during PROCESSING.

Successful import (including partial success with summary.skipped > 0) → job reaches COMPLETED; GET /api/result-sets/import/{jobId} returns 200 OK with BulkResultImportResponseDTO.

Exceptions are logged with the event id and file name; no exception is swallowed silently. Status-transition events are also emitted to the Micrometer counter import.status.transitions tagged with importType, from, to.