8.0 KiB
Spec: Refresh Riot ID by PUUID
Objective
Whenever an account is refreshed manually from the personal match-history page or automatically by the stale-account background scheduler, resolve its 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 profile 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 and every selected stale-account background refresh rather than applying a name TTL.
- Update
gameNameandtagLinetogether 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.
- When a caller does not already know the Riot regional route, resolve it from the
user's community and fall back to
asiaonly when the community has no route. - Do not increment the background failure counter or enter backoff solely because the identity lookup failed; background statistics enrichment retains its existing success and failure semantics.
- 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 - Scheduled stale-account refresh through
BackgroundRefreshScheduler - 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 background-refresh.scheduler.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.tsowns the validated Account-V1 PUUID lookup.apps/api/src/modules/riot/riot-account-enrichment.service.tsowns the persistence boundary for the embedded Riot account.apps/api/src/modules/riot/riot-account-enrichment.service.spec.tsverifies update, no-op, and failure behavior.apps/api/src/modules/riot-job-queue/riot-job-worker.service.tsorchestrates identity, match, and ranked refresh work before completion.apps/api/src/modules/riot-job-queue/riot-job-worker.service.spec.tsverifies that a personal-history refresh job requests the PUUID-based identity refresh.apps/api/src/modules/riot-background-refresh/background-refresh.scheduler.tsorchestrates best-effort identity refresh for stale accounts before statistics enrichment.apps/api/src/modules/riot-background-refresh/background-refresh.scheduler.spec.tsverifies background invocation, ordering, and failure isolation.apps/web/src/pages/UserHistoryPage.tsxalready 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. If
region is omitted, the service resolves the user's community and uses its
configured riotRegion, falling back to asia only when unavailable.
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
unchangedwithout saving. - Verify missing values, PUUID mismatch, and Riot lookup errors return
failedwithout overwriting or saving the stored identity. - Write the worker orchestration expectation before calling the new method.
- Verify a region-less identity refresh uses the user's configured community region.
- Write background scheduler expectations before adding identity refresh to the stale-account loop.
- Verify identity refresh happens before statistics enrichment and that a rejected identity lookup does not increment background failure counters.
- 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.
- Keep background identity failures independent from enrichment failure counters.
- 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. - Selecting a stale account for background refresh also calls Account-V1 by the stored PUUID before statistics enrichment.
- 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.
- Background identity lookup failures do not increment the account failure counter or prevent otherwise successful background enrichment.
- 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.