152 lines
6.3 KiB
Markdown
152 lines
6.3 KiB
Markdown
# 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.
|