Files
lolympus-tournament-support/docs/plans/riot-id-refresh-by-puuid.md
T

3.4 KiB

Implementation Plan: Refresh Riot ID by PUUID

Overview

Deliver the behavior in two backend slices. First add and prove the safe Account-V1-to-user persistence operation. Then invoke it from the existing personal-history refresh worker before completion is broadcast. No database or frontend contract change is required.

Task List

Phase 1: Identity Refresh Boundary

  • Add failing tests for changed, unchanged, incomplete, mismatched, and failed PUUID identity lookups.
    • Acceptance: tests describe state outcomes and fail because the focused method is not implemented.
    • Verify: pnpm --filter api exec jest --runInBand riot-account-enrichment.service.spec.ts
    • Files: apps/api/src/modules/riot/riot-account-enrichment.service.spec.ts
  • Implement refreshRiotIdentity using RiotAccountService.getByPuuid.
    • Acceptance: valid changed values persist together; invalid results preserve existing values; unchanged values avoid a write.
    • Verify: the Phase 1 focused test passes.
    • Files: apps/api/src/modules/riot/riot-account-enrichment.service.ts

Checkpoint: Phase 1

  • The enrichment service has a typed three-state result and all focused tests pass.
  • No schema, endpoint, queue payload, or frontend changes exist.

Phase 2: Refresh Worker Integration

  • Add a failing worker test proving that a user-history job requests identity refresh with its user ID, PUUID, and region.
    • Acceptance: the test fails before worker orchestration is updated.
    • Verify: pnpm --filter api exec jest --runInBand riot-job-worker.service.spec.ts
    • Files: apps/api/src/modules/riot-job-queue/riot-job-worker.service.spec.ts
  • Invoke best-effort identity refresh before job completion.
    • Acceptance: the worker logs identity failure without aborting successful match refresh work, and broadcasts completion only after identity refresh returns.
    • Verify: the Phase 2 focused test passes.
    • Files: apps/api/src/modules/riot-job-queue/riot-job-worker.service.ts

Checkpoint: Complete

  • Focused API suites pass without skipped tests.
  • API lint and build pass.
  • Web lint and production build pass, confirming the existing profile invalidation integration remains compatible.
  • Final diff contains only the specification, plan, enrichment service, worker, and their tests.

Risks and Mitigations

Risk Impact Mitigation
Account-V1 returns an incomplete identity High Require matching PUUID and two non-empty Riot ID fields before mutation.
Riot Account-V1 is temporarily unavailable Medium Preserve stored identity, log the failure, and retain existing best-effort job semantics.
Multiple queue groups repeat identity lookup Low The personal page requests one queue group; avoid a new dedup mechanism until a measured need exists.
UI keeps the stale profile cached High Identity update completes before the existing completion event invalidates the profile query.
Historical names are unexpectedly rewritten Medium Restrict persistence to the embedded Riot account and leave match snapshots untouched.

Dependencies

validated Account-V1 lookup
  -> focused identity persistence method
  -> refresh worker orchestration
  -> existing completion event
  -> existing React Query profile invalidation

Open Questions

None. The user approved the specification and requested implementation.