Add API endpoint to retry file lines after transaction dispatch failure #813

Summary

Add an API operation that allows an operator or recovery job to retry an individual file line whose transaction dispatch failed.

The existing FileLineTransactionDispatchFailedEvent is audit information only. It increments the dispatch attempt count and records the failure, while leaving the line as NotProcessed so it can be retried.

Proposed API

POST /api/files/{fileId}/lines/{lineNumber}/retry

Request:

{
  "eventId": "<original FileLineAddedEvent GUID>"
}

The endpoint should:

1. Load the file and target line.
2. Confirm the line is still eligible for retry (NotProcessed).
3. Validate that the supplied event ID belongs to the original FileLineAddedEvent for that line.
4. Reuse the existing ProcessTransactionForFileLineCommand processing path.
5. Persist another FileLineTransactionDispatchFailedEvent if dispatch fails again.
6. Return the resulting processing status.

Important design considerations

• Use the original FileLineAddedEvent ID for correlation and transaction metadata; do not use the dispatch-failure event ID.
• Avoid accepting an unvalidated file-line payload as the source of truth. If the payload includes line data, validate it against the aggregate.
• A dispatch failure can mean the remote processor accepted the transaction but the response was lost. Use an idempotency key based on the original event ID, file ID, and line number if supported by the transaction processor.
• Prevent concurrent retries for the same file line.
• Consider a bulk operation later, such as POST /api/files/{fileId}/retry-dispatch-failures.

Known retry candidates from the investigated stream

• Line 6 — original event ID: f1503933-b261-4734-a181-27dec0a67047
• Line 7 — original event ID: 8288bf8a-4633-45c0-ac10-df55b83aaf99
• Line 16 — original event ID: a7eb12d0-c2dc-4b72-bc6a-31c419c599d3

Acceptance criteria

• A targeted retry endpoint is available and authorized.
• Only eligible, not-yet-processed lines can be retried.
• Retry uses the original line event ID and stable file/line identity.
• Successful retry records the appropriate processing result event.
• Repeated dispatch failure remains retryable and records an audit event.
• Concurrent or duplicate retries cannot create duplicate transactions.
• Unit and integration tests cover success, retry failure, invalid event ID, already-processed lines, and idempotency behavior.

Related work: #793 and #794.