fix: close competition cutover integrity gaps
This commit is contained in:
1 parent
7ea2002975
commit
683d602d63
57 files changed
+4805
-1582
No files matched your search
@@ -44,7 +44,7 @@ causing team 3 to advance despite team 8 winning two games.
|
||||
## Commands
|
||||
|
||||
- API unit/integration tests: `pnpm --filter api test`
|
||||
- Focused API test: `pnpm --filter api test -- --runInBand <test-path>`
|
||||
- Focused API test: `pnpm --filter api exec jest --runInBand <test-path>`
|
||||
- API build: `pnpm --filter api build`
|
||||
- Web build/typecheck: `pnpm --filter web build`
|
||||
- Migration dry-run: `pnpm --filter api competition:migrate -- --dry-run`
|
||||
@@ -80,6 +80,22 @@ and scheduling metadata. It receives a unique optional `competitionId`.
|
||||
|
||||
Exactly one Competition may reference a Match.
|
||||
|
||||
Competition creation is an explicit side effect of the finalized team-building
|
||||
workflow. Read endpoints never create state. If a finalized Match is observed before
|
||||
its Competition has been linked, the API reports that initialization is still in
|
||||
progress instead of attempting a lazy bootstrap.
|
||||
|
||||
After `competitionId` is linked, the Match cannot return to recruiting, change its
|
||||
game count, reset or undo its auction, or be hard-deleted through ordinary Match
|
||||
operations. Corrections happen through Competition facts and reversals; replacing the
|
||||
event requires a new Match. The legacy-import bulk-delete operation is the one
|
||||
explicit destructive exception and removes the whole aggregate and its dependent
|
||||
read models transactionally.
|
||||
|
||||
Joining a Match is an authenticated self-service action. The normal participant
|
||||
endpoint always derives the participant from the authenticated user; only the
|
||||
administrator endpoint may add another community member.
|
||||
|
||||
### Identifiers
|
||||
|
||||
- `CompetitionId`, `TeamId`, `SeriesId`, `GameSlotId`, `GameId`, and `FactId` are
|
||||
@@ -188,6 +204,13 @@ history. Active code and active GameSlot assignments are uniquely indexed.
|
||||
Accepting a code-backed Riot game atomically commits the accepted fact, assignment
|
||||
use, code consumption, Competition revision/projection, and outbox events.
|
||||
|
||||
Reversal releases only codes that are in a releasable terminal state and removes all
|
||||
obsolete Match code bindings in the same transaction. Public/team reads validate the
|
||||
active assignment, code state, and Match binding instead of returning stale codes.
|
||||
Expired reserved codes also terminate their active assignment and Match binding
|
||||
atomically so the slot can be provisioned again without an administrative replacement
|
||||
endpoint.
|
||||
|
||||
## Command Semantics
|
||||
|
||||
All Competition mutations require an idempotency key and expected revision.
|
||||
@@ -202,6 +225,11 @@ Within a MongoDB transaction, the shared command runner:
|
||||
6. inserts outbox records;
|
||||
7. commits atomically.
|
||||
|
||||
Transient transaction/write-conflict failures use a bounded retry. Idempotency is
|
||||
rechecked on every attempt, so a concurrent successful command is replayed rather
|
||||
than duplicated. Outbox delivery uses bounded attempts and moves permanently failing
|
||||
events to an explicit `dead-letter` state for operator recovery.
|
||||
|
||||
External Riot fetches occur before the transaction. A stale revision returns HTTP 412,
|
||||
a valid-state conflict returns 409, and invalid input returns 422.
|
||||
|
||||
@@ -214,6 +242,9 @@ individual reversal facts joined by one causation ID.
|
||||
|
||||
- Public Match and Competition responses are explicit DTOs, never spread Mongoose
|
||||
documents.
|
||||
- The shared Match contract is the single wire definition used by API presenters and
|
||||
web consumers. Authentication is optional on public Match reads solely to compute
|
||||
the required `joined` flag; anonymous reads receive `joined: false`.
|
||||
- Public responses exclude tournament codes, audit actors, and internal fact payloads.
|
||||
- Team view exposes only the authenticated user's team slots and code assignments.
|
||||
- Administrator fact view exposes the audit ledger.
|
||||
@@ -241,6 +272,19 @@ Migration builds new collections without dual canonical writes.
|
||||
- Dry-run is the default and emits machine-readable and human-readable reports.
|
||||
- Apply is resumable, idempotent, transactionally scoped per Match, and verifies fact
|
||||
replay equality after every write.
|
||||
- Apply explicitly creates or verifies every Competition unique/partial index before
|
||||
migrating a Match. Existing target-data/index-definition conflicts block apply with
|
||||
a machine-readable preflight report; source Matches that collide with an already
|
||||
accepted global identity are quarantined rather than guessed or partially written.
|
||||
- Limited apply runs persist the last terminal Match `_id` in a migration checkpoint.
|
||||
The next run resumes strictly after that cursor; a failed Match does not advance the
|
||||
cursor, and an explicit `--after` cursor may override the checkpoint for recovery.
|
||||
- An explicit limited-apply `--after` cursor durably replaces an older checkpoint
|
||||
before scanning, so a failure on the first overridden Match is retried by the next
|
||||
ordinary limited apply.
|
||||
- Dry-run never creates indexes, uses a persisted resume checkpoint, or updates
|
||||
checkpoints; it always audits the requested source range from the beginning unless
|
||||
an explicit `--after` cursor is supplied.
|
||||
|
||||
Legacy Match fields remain untouched for rollback until the new runtime is verified,
|
||||
then a separate cleanup migration removes them.
|
||||
@@ -263,9 +307,9 @@ Prefer explicit discriminated unions and pure functions:
|
||||
|
||||
```ts
|
||||
switch (series.rule.type) {
|
||||
case 'first-to':
|
||||
case "first-to":
|
||||
return projectFirstToSeries(series, facts);
|
||||
case 'fixed-games':
|
||||
case "fixed-games":
|
||||
return projectFixedGamesSeries(series, facts);
|
||||
}
|
||||
```
|
||||
@@ -298,6 +342,8 @@ its `teamId` in the same object.
|
||||
- Delete facts to implement correction.
|
||||
- Fabricate Riot evidence for legacy results.
|
||||
- Expose tournament codes on a public endpoint.
|
||||
- Reintroduce legacy seed reshuffling, positional bracket mutation, or unauthenticated
|
||||
tournament-code replacement endpoints.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
@@ -310,7 +356,13 @@ its `teamId` in the same object.
|
||||
- Pair, round-robin, and double-elimination flows complete end to end.
|
||||
- Reversal preview/cascade is revision- and hash-protected.
|
||||
- Statistics cannot regress to an older source revision.
|
||||
- A legacy stats builder cannot overwrite a Competition-backed fragment, and a late
|
||||
builder cannot resurrect stats after its Match/Competition has been deleted.
|
||||
- Double-elimination seeds are persisted before the finalized team-build timestamp is
|
||||
exposed, and an expired reserved code can be provisioned again automatically.
|
||||
- Migration dry-run reports zero unclassified documents before apply.
|
||||
- Competition unique/partial indexes are verified before the first apply write, and
|
||||
repeated limited apply runs advance without rescanning the first page.
|
||||
- API tests and API/web production builds pass.
|
||||
- Legacy result writers, serializers, and frontend code are removed after cutover.
|
||||
|
||||
|
||||
Reference in new issue
Block a user