diff --git a/apps/api/src/modules/analysis/analysis.constants.ts b/apps/api/src/modules/analysis/analysis.constants.ts index 1a4e740..a5155c9 100644 --- a/apps/api/src/modules/analysis/analysis.constants.ts +++ b/apps/api/src/modules/analysis/analysis.constants.ts @@ -5,6 +5,8 @@ export const ANALYSIS_JOB_ID_FACTORY = Symbol('ANALYSIS_JOB_ID_FACTORY'); export const DEFAULT_ANALYSIS_MATCH_COUNT = 20; export const MAX_ANALYSIS_MATCH_COUNT = 50; +export const DEFAULT_SEED_COLLECTION_QUEUE_TYPE = 'RANKED_SOLO_5x5'; +export const DEFAULT_SEED_COLLECTION_SOURCE_LIMIT = 50; export const DEFAULT_FEATURE_RECOMPUTE_BATCH_SIZE = 100; export const MAX_FEATURE_RECOMPUTE_BATCH_SIZE = 500; diff --git a/apps/api/src/modules/analysis/analysis.module.ts b/apps/api/src/modules/analysis/analysis.module.ts index 3451370..aad1890 100644 --- a/apps/api/src/modules/analysis/analysis.module.ts +++ b/apps/api/src/modules/analysis/analysis.module.ts @@ -18,6 +18,7 @@ import { AnalysisProcessor } from './analysis.processor'; import { createBullMqOptions } from './bullmq.config'; import { FeatureExtractorService } from './feature-extractor.service'; import { ProfileBuilderService } from './profile-builder.service'; +import { SeedCollectionService } from './seed-collection.service'; import { TimelineDerivedService } from './timeline-derived.service'; import { TimelineMetricService } from './timeline-metric.service'; @@ -50,10 +51,15 @@ import { TimelineMetricService } from './timeline-metric.service'; AnalysisProcessor, FeatureExtractorService, ProfileBuilderService, + SeedCollectionService, TimelineDerivedService, TimelineMetricService, ], controllers: [AnalysisController], - exports: [AnalysisQueueService, AnalysisPipelineService], + exports: [ + AnalysisQueueService, + AnalysisPipelineService, + SeedCollectionService, + ], }) export class AnalysisModule {} diff --git a/apps/api/src/modules/analysis/seed-collection.service.spec.ts b/apps/api/src/modules/analysis/seed-collection.service.spec.ts new file mode 100644 index 0000000..fde9be8 --- /dev/null +++ b/apps/api/src/modules/analysis/seed-collection.service.spec.ts @@ -0,0 +1,390 @@ +import { Logger } from '@nestjs/common'; +import type { ConnectionService } from '../global/database/connection.service'; +import type { Account } from '../global/database/schemas'; +import type { + RiotAccountDto, + RiotApexLeagueEntryDto, + RiotApexLeagueListDto, + RiotApiClient, + RiotLeagueEntryDto, + RiotSummonerDto, +} from '../riot/riot-api.client'; +import { SeedCollectionService } from './seed-collection.service'; + +interface ExecQuery { + exec: jest.Mock, []>; +} + +type FindOneAndUpdateAccountMock = jest.Mock< + LeanAccountQuery, + [Record, Record, Record?] +>; + +interface LeanAccountQuery { + lean: jest.Mock, []>; +} + +function asRecord(value: unknown): Record { + if (typeof value === 'object' && value !== null && !Array.isArray(value)) { + return value as Record; + } + return {}; +} + +function execResolved(value: T): ExecQuery { + return { exec: jest.fn, []>().mockResolvedValue(value) }; +} + +function leanExecResolved(value: T) { + return { + lean: jest.fn(() => execResolved(value)), + }; +} + +function selectLeanExecResolved(value: T) { + const exec = jest.fn, []>().mockResolvedValue(value); + const lean = jest.fn(() => ({ exec })); + const select = jest.fn(() => ({ lean })); + return { + chain: { select }, + exec, + lean, + select, + }; +} + +function createApexEntry( + puuid: string, + overrides: Partial = {}, +): RiotApexLeagueEntryDto { + return { + freshBlood: false, + hotStreak: false, + inactive: false, + leaguePoints: 100, + losses: 20, + puuid, + queueType: 'RANKED_SOLO_5x5', + rank: '', + tier: 'CHALLENGER', + veteran: false, + wins: 40, + ...overrides, + }; +} + +function createAccount(puuid: string): RiotAccountDto { + return { + puuid, + gameName: `Game ${puuid}`, + tagLine: 'KR1', + }; +} + +function createSummoner(puuid: string): RiotSummonerDto { + return { + profileIconId: 5935, + puuid, + summonerLevel: 550, + }; +} + +function createLeagueEntry( + puuid: string, + overrides: Partial = {}, +): RiotLeagueEntryDto { + return { + freshBlood: false, + hotStreak: false, + inactive: false, + leaguePoints: 123, + losses: 10, + queueType: 'RANKED_SOLO_5x5', + rank: '', + tier: 'CHALLENGER', + veteran: false, + wins: 20, + ...overrides, + }; +} + +function createStoredAccount(overrides: Partial = {}): Account { + return { + createdAt: new Date('2026-07-01T00:00:00.000Z'), + updatedAt: new Date('2026-07-01T00:00:00.000Z'), + puuid: 'seed-puuid', + gameName: 'Seed Player', + tagLine: 'KR1', + platformRoute: 'kr', + regionalRoute: 'asia', + profileIconId: 5935, + summonerLevel: 550, + tiers: [], + isSeed: true, + seedSource: 'challenger', + seedAddedAt: new Date('2026-07-03T00:00:00.000Z'), + lastSeedCollectedAt: new Date('2026-07-03T00:00:00.000Z'), + ...overrides, + }; +} + +function createHarness(options: { existingSeedAddedAt?: Date } = {}) { + const findOneAccount = jest + .fn() + .mockReturnValue( + selectLeanExecResolved( + options.existingSeedAddedAt + ? { seedAddedAt: options.existingSeedAddedAt } + : null, + ).chain, + ); + const findOneAndUpdateAccount: FindOneAndUpdateAccountMock = jest + .fn>() + .mockReturnValue(leanExecResolved(createStoredAccount())); + const accountModel = { + findOne: findOneAccount, + findOneAndUpdate: findOneAndUpdateAccount, + }; + const connectionService = { + getModel: jest.fn().mockResolvedValue(accountModel), + } as unknown as ConnectionService; + + const getAccountByPuuid = jest.fn, [string, string]>( + (puuid) => Promise.resolve(createAccount(puuid)), + ); + const getChallengerLeagueByQueue = jest + .fn, [string, string]>() + .mockResolvedValue({ + entries: [], + queueType: 'RANKED_SOLO_5x5', + tier: 'CHALLENGER', + }); + const getGrandmasterLeagueByQueue = jest + .fn, [string, string]>() + .mockResolvedValue({ + entries: [], + queueType: 'RANKED_SOLO_5x5', + tier: 'GRANDMASTER', + }); + const getLeagueEntriesByPuuid = jest.fn< + Promise, + [string, string] + >((puuid) => Promise.resolve([createLeagueEntry(puuid)])); + const getMasterLeagueByQueue = jest + .fn, [string, string]>() + .mockResolvedValue({ + entries: [], + queueType: 'RANKED_SOLO_5x5', + tier: 'MASTER', + }); + const getSummonerByPuuid = jest.fn< + Promise, + [string, string] + >((puuid) => Promise.resolve(createSummoner(puuid))); + const riotApiClient = { + getAccountByPuuid, + getChallengerLeagueByQueue, + getGrandmasterLeagueByQueue, + getLeagueEntriesByPuuid, + getMasterLeagueByQueue, + getSummonerByPuuid, + } as unknown as RiotApiClient; + + return { + accountModel, + connectionService, + findOneAccount, + findOneAndUpdateAccount, + getAccountByPuuid, + getChallengerLeagueByQueue, + getGrandmasterLeagueByQueue, + getLeagueEntriesByPuuid, + getMasterLeagueByQueue, + getSummonerByPuuid, + riotApiClient, + service: new SeedCollectionService(connectionService, riotApiClient), + }; +} + +describe('SeedCollectionService', () => { + it('collects bounded high-tier seed account metadata', async () => { + const collectedAt = new Date('2026-07-03T12:00:00.000Z'); + const harness = createHarness(); + harness.getChallengerLeagueByQueue.mockResolvedValue({ + entries: [ + createApexEntry('challenger-low', { leaguePoints: 10, wins: 5 }), + createApexEntry('challenger-high', { leaguePoints: 500, wins: 50 }), + ], + queueType: 'RANKED_SOLO_5x5', + tier: 'CHALLENGER', + }); + harness.getGrandmasterLeagueByQueue.mockResolvedValue({ + entries: [createApexEntry('grandmaster-one', { tier: 'GRANDMASTER' })], + queueType: 'RANKED_SOLO_5x5', + tier: 'GRANDMASTER', + }); + harness.getMasterLeagueByQueue.mockResolvedValue({ + entries: [createApexEntry('master-one', { tier: 'MASTER' })], + queueType: 'RANKED_SOLO_5x5', + tier: 'MASTER', + }); + + const result = await harness.service.collectSeedAccounts({ + collectedAt, + platformRoute: 'kr', + sourceLimits: { + challenger: 1, + grandmaster: 1, + master: 1, + }, + }); + + expect(result).toMatchObject({ + platformRoute: 'kr', + regionalRoute: 'asia', + queueType: 'RANKED_SOLO_5x5', + storedAccounts: 3, + skippedAccounts: 0, + sourceResults: [ + { + discoveredEntries: 2, + selectedEntries: 1, + source: 'challenger', + storedAccounts: 1, + }, + { + discoveredEntries: 1, + selectedEntries: 1, + source: 'grandmaster', + storedAccounts: 1, + }, + { + discoveredEntries: 1, + selectedEntries: 1, + source: 'master', + storedAccounts: 1, + }, + ], + }); + expect(harness.getAccountByPuuid).toHaveBeenCalledWith( + 'challenger-high', + 'asia', + ); + expect(harness.findOneAndUpdateAccount).toHaveBeenCalledTimes(3); + const challengerUpdate = harness.findOneAndUpdateAccount.mock.calls.find( + ([query]) => asRecord(query).puuid === 'challenger-high', + ); + expect(challengerUpdate).toBeDefined(); + expect(challengerUpdate?.[1]).toMatchObject({ + $set: { + gameName: 'Game challenger-high', + isSeed: true, + lastSeedCollectedAt: collectedAt, + platformRoute: 'kr', + puuid: 'challenger-high', + regionalRoute: 'asia', + seedAddedAt: collectedAt, + seedSource: 'challenger', + tagLine: 'KR1', + tiers: [ + { + fetchedAt: collectedAt, + leaguePoints: 123, + losses: 10, + queueType: 'RANKED_SOLO_5x5', + rank: '', + tier: 'CHALLENGER', + wins: 20, + }, + ], + tiersFetchedAt: collectedAt, + }, + }); + expect(challengerUpdate?.[2]).toEqual({ + new: true, + setDefaultsOnInsert: true, + upsert: true, + }); + }); + + it('preserves the first seedAddedAt timestamp when refreshing a seed account', async () => { + const existingSeedAddedAt = new Date('2026-07-01T00:00:00.000Z'); + const collectedAt = new Date('2026-07-03T12:00:00.000Z'); + const harness = createHarness({ existingSeedAddedAt }); + harness.getChallengerLeagueByQueue.mockResolvedValue({ + entries: [createApexEntry('challenger-one')], + queueType: 'RANKED_SOLO_5x5', + tier: 'CHALLENGER', + }); + + await harness.service.collectSeedAccounts({ + collectedAt, + platformRoute: 'kr', + sourceLimits: { + challenger: 1, + grandmaster: 0, + master: 0, + }, + }); + + const challengerUpdate = harness.findOneAndUpdateAccount.mock.calls.find( + ([query]) => asRecord(query).puuid === 'challenger-one', + ); + expect(challengerUpdate).toBeDefined(); + expect(challengerUpdate?.[1]).toMatchObject({ + $set: { + lastSeedCollectedAt: collectedAt, + seedAddedAt: existingSeedAddedAt, + }, + }); + }); + + it('skips failed candidate accounts without aborting the collection pass', async () => { + const loggerWarn = jest + .spyOn(Logger.prototype, 'warn') + .mockImplementation(() => undefined); + const harness = createHarness(); + harness.getChallengerLeagueByQueue.mockResolvedValue({ + entries: [ + createApexEntry('broken-puuid', { leaguePoints: 500 }), + createApexEntry('stored-puuid', { leaguePoints: 400 }), + ], + queueType: 'RANKED_SOLO_5x5', + tier: 'CHALLENGER', + }); + harness.getAccountByPuuid.mockImplementation((puuid) => { + if (puuid === 'broken-puuid') { + return Promise.reject(new Error('Riot account lookup failed')); + } + return Promise.resolve(createAccount(puuid)); + }); + + const result = await harness.service.collectSeedAccounts({ + platformRoute: 'kr', + sourceLimits: { + challenger: 2, + grandmaster: 0, + master: 0, + }, + }); + + expect(result).toMatchObject({ + storedAccounts: 1, + skippedAccounts: 1, + sourceResults: [ + expect.objectContaining({ + skippedAccounts: 1, + storedAccounts: 1, + }), + expect.any(Object), + expect.any(Object), + ], + }); + expect(harness.findOneAndUpdateAccount).toHaveBeenCalledTimes(1); + expect(harness.findOneAndUpdateAccount.mock.calls[0]?.[0]).toEqual({ + puuid: 'stored-puuid', + }); + + loggerWarn.mockRestore(); + }); +}); diff --git a/apps/api/src/modules/analysis/seed-collection.service.ts b/apps/api/src/modules/analysis/seed-collection.service.ts new file mode 100644 index 0000000..23c594b --- /dev/null +++ b/apps/api/src/modules/analysis/seed-collection.service.ts @@ -0,0 +1,339 @@ +import { Injectable, Logger } from '@nestjs/common'; +import { ConnectionService } from '../global/database/connection.service'; +import type { Account, SeedSource, TierInfo } from '../global/database/schemas'; +import { SEED_SOURCES } from '../global/database/schemas'; +import { + RiotApiClient, + type RiotApexLeagueEntryDto, + type RiotApexLeagueListDto, + type RiotLeagueEntryDto, +} from '../riot/riot-api.client'; +import { + toRegionalRoute, + type RiotPlatformRoute, + type RiotRegionalRoute, +} from '../riot/riot.types'; +import { + DEFAULT_SEED_COLLECTION_QUEUE_TYPE, + DEFAULT_SEED_COLLECTION_SOURCE_LIMIT, +} from './analysis.constants'; + +export interface SeedCollectionOptions { + collectedAt?: Date; + platformRoute: RiotPlatformRoute; + queueType?: string; + sourceLimits?: Partial>; +} + +export interface SeedCollectionSourceResult { + source: SeedSource; + discoveredEntries: number; + selectedEntries: number; + storedAccounts: number; + skippedAccounts: number; + duplicateAccounts: number; +} + +export interface SeedCollectionResult { + platformRoute: RiotPlatformRoute; + regionalRoute: RiotRegionalRoute; + queueType: string; + sourceResults: SeedCollectionSourceResult[]; + discoveredEntries: number; + selectedEntries: number; + storedAccounts: number; + skippedAccounts: number; + duplicateAccounts: number; +} + +@Injectable() +export class SeedCollectionService { + private readonly logger = new Logger(SeedCollectionService.name); + + constructor( + private readonly connectionService: ConnectionService, + private readonly riotApiClient: RiotApiClient, + ) {} + + public async collectSeedAccounts( + options: SeedCollectionOptions, + ): Promise { + const collectedAt = options.collectedAt ?? new Date(); + const platformRoute = options.platformRoute; + const regionalRoute = toRegionalRoute(platformRoute); + const queueType = options.queueType ?? DEFAULT_SEED_COLLECTION_QUEUE_TYPE; + const sourceResults: SeedCollectionSourceResult[] = []; + const seenPuuids = new Set(); + + for (const source of SEED_SOURCES) { + const sourceLimit = this.normalizeSourceLimit( + options.sourceLimits?.[source], + ); + const leagueList = await this.fetchSeedLeagueList( + source, + queueType, + platformRoute, + ); + const selectedEntries = this.selectCandidateEntries( + source, + leagueList.entries, + sourceLimit, + ); + const sourceResult: SeedCollectionSourceResult = { + source, + discoveredEntries: leagueList.entries.length, + selectedEntries: selectedEntries.length, + storedAccounts: 0, + skippedAccounts: 0, + duplicateAccounts: 0, + }; + + for (const selectedEntry of selectedEntries) { + if (seenPuuids.has(selectedEntry.puuid)) { + sourceResult.duplicateAccounts += 1; + continue; + } + seenPuuids.add(selectedEntry.puuid); + + try { + await this.storeSeedAccount({ + collectedAt, + platformRoute, + puuid: selectedEntry.puuid, + regionalRoute, + source, + }); + sourceResult.storedAccounts += 1; + } catch (error) { + sourceResult.skippedAccounts += 1; + this.logger.warn( + `Skipping seed puuid="${this.safeLogText(selectedEntry.puuid)}" source="${source}" after collection failure: ${this.safeLogText(this.errorMessage(error))}`, + ); + } + } + + sourceResults.push(sourceResult); + } + + return { + platformRoute, + regionalRoute, + queueType, + sourceResults, + discoveredEntries: this.sumSourceResults( + sourceResults, + 'discoveredEntries', + ), + selectedEntries: this.sumSourceResults(sourceResults, 'selectedEntries'), + storedAccounts: this.sumSourceResults(sourceResults, 'storedAccounts'), + skippedAccounts: this.sumSourceResults(sourceResults, 'skippedAccounts'), + duplicateAccounts: this.sumSourceResults( + sourceResults, + 'duplicateAccounts', + ), + }; + } + + private async fetchSeedLeagueList( + source: SeedSource, + queueType: string, + platformRoute: RiotPlatformRoute, + ): Promise { + if (source === 'challenger') { + return this.riotApiClient.getChallengerLeagueByQueue( + queueType, + platformRoute, + ); + } + if (source === 'grandmaster') { + return this.riotApiClient.getGrandmasterLeagueByQueue( + queueType, + platformRoute, + ); + } + return this.riotApiClient.getMasterLeagueByQueue(queueType, platformRoute); + } + + private selectCandidateEntries( + source: SeedSource, + entries: RiotApexLeagueEntryDto[], + sourceLimit: number, + ): RiotApexLeagueEntryDto[] { + if (sourceLimit <= 0) { + return []; + } + + const sortedEntries = this.deduplicateEntries(entries).sort((left, right) => + this.compareApexEntries(left, right), + ); + if (source === 'master' && sortedEntries.length > sourceLimit) { + return this.shuffleEntries(sortedEntries).slice(0, sourceLimit); + } + return sortedEntries.slice(0, sourceLimit); + } + + private deduplicateEntries( + entries: RiotApexLeagueEntryDto[], + ): RiotApexLeagueEntryDto[] { + const bestEntriesByPuuid = new Map(); + for (const entry of entries) { + const existingEntry = bestEntriesByPuuid.get(entry.puuid); + if (!existingEntry || this.compareApexEntries(entry, existingEntry) < 0) { + bestEntriesByPuuid.set(entry.puuid, entry); + } + } + return [...bestEntriesByPuuid.values()]; + } + + private compareApexEntries( + left: RiotApexLeagueEntryDto, + right: RiotApexLeagueEntryDto, + ): number { + if (right.leaguePoints !== left.leaguePoints) { + return right.leaguePoints - left.leaguePoints; + } + if (right.wins !== left.wins) { + return right.wins - left.wins; + } + if (left.losses !== right.losses) { + return left.losses - right.losses; + } + return left.puuid.localeCompare(right.puuid); + } + + private shuffleEntries( + entries: RiotApexLeagueEntryDto[], + ): RiotApexLeagueEntryDto[] { + const shuffledEntries = [...entries]; + for ( + let currentIndex = shuffledEntries.length - 1; + currentIndex > 0; + currentIndex -= 1 + ) { + const swapIndex = Math.floor(Math.random() * (currentIndex + 1)); + const currentEntry = shuffledEntries[currentIndex]; + const swapEntry = shuffledEntries[swapIndex]; + if (!currentEntry || !swapEntry) { + continue; + } + shuffledEntries[currentIndex] = swapEntry; + shuffledEntries[swapIndex] = currentEntry; + } + return shuffledEntries; + } + + private async storeSeedAccount(params: { + collectedAt: Date; + platformRoute: RiotPlatformRoute; + puuid: string; + regionalRoute: RiotRegionalRoute; + source: SeedSource; + }): Promise { + const account = await this.riotApiClient.getAccountByPuuid( + params.puuid, + params.regionalRoute, + ); + const [summoner, leagueEntries] = await Promise.all([ + this.riotApiClient.getSummonerByPuuid( + account.puuid, + params.platformRoute, + ), + this.riotApiClient.getLeagueEntriesByPuuid( + account.puuid, + params.platformRoute, + ), + ]); + + const accountModel = await this.connectionService.getModel('account'); + const existingAccount = await accountModel + .findOne({ puuid: account.puuid }) + .select('seedAddedAt') + .lean | null>() + .exec(); + const seedAddedAt = existingAccount?.seedAddedAt ?? params.collectedAt; + + const storedAccount = await accountModel + .findOneAndUpdate( + { puuid: account.puuid }, + { + $set: { + puuid: account.puuid, + gameName: account.gameName, + tagLine: account.tagLine, + platformRoute: params.platformRoute, + regionalRoute: params.regionalRoute, + profileIconId: summoner.profileIconId, + summonerLevel: summoner.summonerLevel, + tiers: this.toTierInfo(leagueEntries, params.collectedAt), + tiersFetchedAt: params.collectedAt, + isSeed: true, + seedSource: params.source, + seedAddedAt, + lastSeedCollectedAt: params.collectedAt, + }, + }, + { + new: true, + setDefaultsOnInsert: true, + upsert: true, + }, + ) + .lean() + .exec(); + + if (!storedAccount) { + throw new Error('Failed to store seed Riot account.'); + } + return storedAccount; + } + + private toTierInfo( + entries: RiotLeagueEntryDto[], + fetchedAt: Date, + ): TierInfo[] { + return entries.map((entry) => ({ + queueType: entry.queueType, + tier: entry.tier, + rank: entry.rank, + leaguePoints: entry.leaguePoints, + wins: entry.wins, + losses: entry.losses, + fetchedAt, + })); + } + + private normalizeSourceLimit(limit: number | undefined): number { + if (limit === undefined) { + return DEFAULT_SEED_COLLECTION_SOURCE_LIMIT; + } + if (!Number.isFinite(limit) || limit < 0) { + return DEFAULT_SEED_COLLECTION_SOURCE_LIMIT; + } + return Math.trunc(limit); + } + + private sumSourceResults( + sourceResults: SeedCollectionSourceResult[], + key: keyof Pick< + SeedCollectionSourceResult, + | 'discoveredEntries' + | 'selectedEntries' + | 'storedAccounts' + | 'skippedAccounts' + | 'duplicateAccounts' + >, + ): number { + return sourceResults.reduce( + (total, sourceResult) => total + sourceResult[key], + 0, + ); + } + + private errorMessage(error: unknown): string { + return error instanceof Error ? error.message : String(error); + } + + private safeLogText(value: string): string { + return value.replace(/[\n\r\t]/g, ' ').slice(0, 500); + } +}