# 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 - [x] 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` - [x] 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 - [x] The enrichment service has a typed three-state result and all focused tests pass. - [x] No schema, endpoint, queue payload, or frontend changes exist. ### Phase 2: Refresh Worker Integration - [x] 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` - [x] 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 - [x] Focused API suites pass without skipped tests. - [x] API lint and build pass. - [x] Web lint and production build pass, confirming the existing profile invalidation integration remains compatible. - [x] Final diff contains only the specification, plan, enrichment service, worker, and their tests. ### Phase 3: Background Refresh Integration - [x] 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` - [x] 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` - [x] 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` - [x] 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 - [x] Focused identity, manual worker, and background scheduler suites pass. - [x] API lint, full tests, and build pass. - [x] 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 ```text 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.