# Review/correction API implementation mapping for financial systems

Use this checklist when mapping a bounded backend PR for a financial review inbox or confirmed-transaction correction flow.

## Trace before proposing

Ground the map in the exact commit and clean/dirty tree. Follow the complete route → service → SQL/migration → audit → frontend contract → test path. Identify and reuse existing opaque-token, baseline fingerprint, data-version, cursor, savepoint, and write-lock patterns, but verify their exact semantics before reuse.

Inspect all inputs that can change action safety: the target row, category registry, account mapping, counterpart rows, relationship tables, classifier/rule lookups, and transaction lifecycle. A row `updated_at` value alone is not a sufficient optimistic-concurrency boundary when these relations influence the result.

If list APIs intentionally remove internal IDs, add a stable opaque token and server-side resolver for detail/action routes. Never restore candidate, transaction, source-row, or relationship foreign keys to the public contract.

## Item action protocol

Bind every preview fingerprint to:

- opaque item/entity token;
- client data version;
- normalized action and parameters;
- item-specific current version;
- relevant global baseline;
- classifier/contract version.

Preview is side-effect-free and returns baseline/current versions, impact, warnings, and `can_confirm`. Confirm requires explicit confirmation, recomputes after acquiring the write lock/savepoint, and returns structured `409` stale information with zero writes on drift.

Do not treat an audit lookup as concurrency-safe idempotency unless uniqueness is enforced. Prefer a durable action receipt with a unique request fingerprint, stored result, and foreign key to exactly one audit event. Identical retries replay the result; retries with changed action parameters must fail.

## Duplicate decisions

Model candidate-to-candidate and candidate-to-confirmed-transaction lineage separately. Keep public `duplicate_of` data opaque. Persist decisions such as `keep`, `exclude`, and `later` even if the candidate stays open; otherwise `keep`/`later` are indistinguishable from no decision. Define reopen semantics that restore the special decision state without erasing lineage or audit history.

When duplicate detection salts a colliding logical fingerprint to retain both genuine rows, capture the predecessor relationship before salting it.

## Settlements and partial amounts

Trace the actual transfer writer and downstream financial read models before proposing settlement writes. If the existing model validates exact equal-amount opposite-sign pairs, do not weaken that invariant for a UI feature.

A bounded first PR may classify settlement previews as `exact`, `partial`, `ambiguous`, or `missing`, while allowing confirm only for a unique exact pair. Partial/ambiguous/missing confirms fail closed. True partial allocation requires explicit allocated-amount and residual lineage; it must not be simulated by unequal transfer legs, silently truncated amounts, or destructive candidate edits.

## Confirmed transaction corrections

Add an opaque transaction token to list rows when a drawer/detail endpoint is required. A category correction must use preview → confirm → audit rather than a direct updater. Define specialty guards for transfers, reversals, linked refunds whose effective category comes from an origin transaction, reversed/archived rows, and malformed relationship membership. Validate active category and transaction/category type compatibility.

## Implementation-map output

Return:

1. analyzed revision/tree state;
2. existing reusable safeguards and concrete gaps;
3. representative request/response contracts;
4. additive migration map, state semantics, indexes, and uniqueness;
5. exact file-by-file changes;
6. focused tests for read-only preview, stale versions, changed retry payload, concurrent consumption, exact-one audit, no raw-ID leakage, specialty guards, and write-disabled HTTP behavior;
7. explicit assumptions and deferred semantics.

Do not claim tests were run during read-only analysis. Label uncertain product semantics and choose the narrow fail-closed interpretation rather than presenting speculation as a settled contract.