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

5.8 KiB

Implementation Plan: Refresh Riot ID by PUUID

Overview

Deliver the behavior in three 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. Finally reuse it from stale-account background refresh with community-aware region resolution and failure isolation. 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.

Phase 3: Background Refresh Integration

  • Add a failing enrichment-service test proving that an omitted region is resolved from the user's community.
    • Acceptance: a non-Asia community route reaches Account-V1 without changing the public method signature.
    • 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
  • Resolve the community Riot region for region-less identity refresh calls.
    • Acceptance: explicit caller regions remain unchanged; missing community routes use the existing asia fallback.
    • Verify: the focused enrichment-service test passes.
    • Files: apps/api/src/modules/riot/riot-account-enrichment.service.ts
  • Add failing background scheduler tests for identity refresh ordering and failure isolation.
    • Acceptance: stale accounts request identity refresh before statistics enrichment, while identity rejection does not increment failure counters.
    • Verify: pnpm --filter api exec jest --runInBand background-refresh.scheduler.spec.ts
    • Files: apps/api/src/modules/riot-background-refresh/background-refresh.scheduler.spec.ts
  • Invoke best-effort identity refresh from the stale-account loop.
    • Acceptance: each processed candidate gets one PUUID identity lookup, statistics enrichment still determines processed/failed/backoff state, and no new Redis or database contract is added.
    • Verify: the focused background scheduler tests pass.
    • Files: apps/api/src/modules/riot-background-refresh/background-refresh.scheduler.ts

Checkpoint: Background Refresh Complete

  • Focused identity, manual worker, and background scheduler suites pass.
  • API lint, full tests, and build pass.
  • Final diff remains limited to the existing feature documents, identity service/tests, and background scheduler/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.
Background community uses a non-Asia Riot route High Resolve omitted regions from the user's community before falling back to asia.
Identity lookup failure triggers background backoff Medium Isolate identity exceptions and let existing statistics enrichment alone control failure counters.
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
  -> manual refresh worker -> existing completion event -> profile invalidation
  -> background scheduler -> existing statistics enrichment and backoff policy

Open Questions

None. The user approved the specification and requested implementation.