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

6.3 KiB

Spec: Refresh Riot ID by PUUID

Objective

When a user clicks 정보 갱신 on the personal match-history page, resolve the account's current Riot ID through Riot Account-V1 using the stored PUUID. If the player changed either their game name or tag line, persist the latest values on the same embedded Riot account so the refreshed profile header displays the new Riot ID.

The existing refresh job remains the single user-facing operation. It continues to refresh matches and ranked data, and additionally refreshes identity before emitting its completion event.

Approved Product Decisions

  • Use the stored PUUID as the stable identity key; never look up the account by the possibly stale game name and tag line.
  • Query Riot Account-V1 on every manually queued user-history refresh job rather than applying a name TTL.
  • Update gameName and tagLine together only when Riot returns a matching PUUID and both values are non-empty.
  • Preserve the previous Riot ID if the Account-V1 lookup fails or returns an incomplete or mismatched response.
  • Treat identity refresh as best effort, matching the existing ranked-data refresh policy: log a failure but allow successful match refresh work to complete.
  • Reuse the existing refresh completion event and profile-query invalidation; do not add a new endpoint, response field, socket event, or frontend state path.
  • Update only the embedded Riot account used by the personal profile. Historical match snapshots retain the names recorded by Riot for those games.

Tech Stack

  • NestJS 11, TypeScript 5, Mongoose 9, and Jest under apps/api
  • Riot Account-V1 through the existing RiotAccountService
  • Redis stream jobs through the existing RiotJobWorkerService
  • React Query profile invalidation already present in UserHistoryPage

Commands

  • Focused tests: pnpm --filter api exec jest --runInBand riot-account-enrichment.service.spec.ts riot-job-worker.service.spec.ts
  • API lint: pnpm --filter api lint
  • API build: pnpm --filter api build
  • Web lint: pnpm --filter web lint
  • Web production build: pnpm --filter web build:prod

Project Structure

  • apps/api/src/modules/riot/riot-account.service.ts owns the validated Account-V1 PUUID lookup.
  • apps/api/src/modules/riot/riot-account-enrichment.service.ts owns the persistence boundary for the embedded Riot account.
  • apps/api/src/modules/riot/riot-account-enrichment.service.spec.ts verifies update, no-op, and failure behavior.
  • apps/api/src/modules/riot-job-queue/riot-job-worker.service.ts orchestrates identity, match, and ranked refresh work before completion.
  • apps/api/src/modules/riot-job-queue/riot-job-worker.service.spec.ts verifies that a personal-history refresh job requests the PUUID-based identity refresh.
  • apps/web/src/pages/UserHistoryPage.tsx already invalidates the profile query when the refresh socket reports completion and is not modified in this scope.

Internal Contract

Add one focused method to RiotAccountEnrichmentService:

type RefreshRiotIdentityResult = "updated" | "unchanged" | "failed";

refreshRiotIdentity(params: {
  userId: mongoose.Types.ObjectId;
  puuid: string;
  region?: RiotRegionalRoute;
}): Promise<RefreshRiotIdentityResult>;

updated means both persisted Riot ID fields now match Account-V1. unchanged means the validated response matched the stored values and no database write was needed. failed means no stored account could be resolved or the external lookup could not safely provide a complete identity; stored values remain unchanged.

Code Style

Keep the external validation and persistence decision explicit:

const identity = await this.accountService.getByPuuid(puuid, { region });
if (identity.puuid !== puuid || !identity.gameName || !identity.tagLine) {
  return "failed";
}

Use existing single quotes, NestJS logging, Mongoose document mutation, and Prettier formatting. Do not add a generic identity abstraction or new dependency.

Testing Strategy

  • Write the enrichment-service tests first and confirm they fail before adding the new method.
  • Verify a changed game name and tag line are persisted together.
  • Verify identical values return unchanged without saving.
  • Verify missing values, PUUID mismatch, and Riot lookup errors return failed without overwriting or saving the stored identity.
  • Write the worker orchestration expectation before calling the new method.
  • Run focused API tests after each slice, then API lint/build and web lint/build to verify the existing client integration remains valid.

Boundaries

Always

  • Use the stored PUUID for Account-V1 lookup and verify the returned PUUID.
  • Validate both Riot ID fields before mutating the database.
  • Preserve the current Riot ID on any unsafe or failed response.
  • Keep the existing refresh route, enqueue response, and socket event compatible.
  • Run focused tests before broader lint and build verification.

Ask First

  • Add a database field or migration.
  • Change refresh failure semantics so an identity lookup failure fails the whole user-history job.
  • Update historical match snapshots or active match participant display names.
  • Add a new API response field, endpoint, dependency, or Redis job type.
  • Commit, push, deploy, or alter CI configuration.

Never

  • Resolve identity from the stale stored Riot ID.
  • Partially update only the game name or only the tag line.
  • Replace a valid stored identity with empty or mismatched Account-V1 data.
  • Expose Riot API errors or credentials to the browser.
  • Mix the change with the separate past-history result-column PR.

Success Criteria

  • Clicking 정보 갱신 causes the queued worker to call Account-V1 by the stored PUUID.
  • A changed Riot game name or tag line is persisted on the matching embedded account before the completion event is broadcast.
  • The completion event triggers the existing profile-query invalidation, so the personal history header displays the latest gameName#tagLine.
  • Failed, incomplete, or mismatched Riot identity responses do not overwrite the existing Riot ID and do not prevent otherwise successful match refresh work.
  • Focused tests, API lint/build, and web lint/production build pass.

Open Questions

None. The user approved this specification and requested implementation. The existing queue and UI invalidation paths support the behavior without a public contract change.