feat(api): refresh Riot ID by PUUID

This commit is contained in:
dahyeon committed 2026-07-25 08:37:42 -07:00
1 parent 79534cf43c
commit 9cd5850d43
6 files changed
+508 -3

No files matched your search

+151
View File
@@ -0,0 +1,151 @@
# 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`:
```ts
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:
```ts
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.