import { Injectable, Logger } from '@nestjs/common'; import { ConnectionService } from '../global/database/connection.service'; import type { Account, AnalysisJobStatus, RiotMatch, TierInfo, } from '../global/database/schemas'; import { RiotApiClient, RiotNotFoundError, type RiotLeagueEntryDto, } from '../riot/riot-api.client'; import { normalizeRequestedMatchCount, USER_ANALYSIS_JOB_NAME, } from './analysis.constants'; import type { ExtractedPlayerMatchFeature, UserAnalysisJobData, } from './analysis.types'; import { FeatureExtractorService } from './feature-extractor.service'; import { ProfileBuilderService } from './profile-builder.service'; import { TimelineDerivedService } from './timeline-derived.service'; interface MatchRecord { matchId: string; raw: Record; timeline?: Record; } interface ParsedMatchSummary { gameCreation: number; gameDuration: number; gameVersion?: string; queueId?: number; participantPuuids: string[]; } function asRecord(value: unknown): Record { if (typeof value === 'object' && value !== null && !Array.isArray(value)) { return value as Record; } return {}; } function isRecordValue(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value); } function asNumber(value: unknown, fallback = 0): number { return typeof value === 'number' && Number.isFinite(value) ? value : fallback; } function asString(value: unknown): string | undefined { return typeof value === 'string' ? value : undefined; } function asStringArray(value: unknown): string[] { if (!Array.isArray(value)) return []; return value.filter((item): item is string => typeof item === 'string'); } function errorMessage(error: unknown): string { return error instanceof Error ? error.message : String(error); } @Injectable() export class AnalysisPipelineService { private readonly logger = new Logger(AnalysisPipelineService.name); constructor( private readonly connectionService: ConnectionService, private readonly riotApiClient: RiotApiClient, private readonly featureExtractorService: FeatureExtractorService, private readonly profileBuilderService: ProfileBuilderService, private readonly timelineDerivedService: TimelineDerivedService, ) {} public async processUserAnalysisJob( data: UserAnalysisJobData, jobId: string, options: { isFinalAttempt?: boolean } = {}, ): Promise { const normalizedData = { ...data, requestedMatchCount: normalizeRequestedMatchCount( data.requestedMatchCount, ), }; try { await this.updateJob(jobId, { status: 'processing', stage: 'resolve-account', progress: { fetchedMatches: 0, totalMatches: 0, }, }); const account = await this.resolveAndStoreAccount(normalizedData); await this.updateJob(jobId, { puuid: account.puuid, stage: 'fetch-match-ids', }); const matchIds = await this.riotApiClient.getMatchIds(account.puuid, { count: normalizedData.requestedMatchCount, queue: normalizedData.queueId, regionalRoute: normalizedData.regionalRoute, }); await this.updateJob(jobId, { stage: 'fetch-match-details', progress: { fetchedMatches: 0, totalMatches: matchIds.length, }, }); if (matchIds.length === 0) { await this.completeJob(jobId); return; } const matchRecords = await this.fetchAndStoreMatches( matchIds, normalizedData, jobId, ); await this.updateJob(jobId, { stage: 'extract-features', }); const extractedFeatures = await this.extractAndStoreFeatures( matchRecords, account.puuid, normalizedData.queueId, ); await this.updateJob(jobId, { stage: 'build-profile', }); if (extractedFeatures.length > 0) { await this.buildAndStoreProfile( account, normalizedData, extractedFeatures, ); } await this.completeJob(jobId); } catch (error) { if (options.isFinalAttempt === true) { const publicError = this.publicErrorMessage(error); this.logFinalFailure(normalizedData, jobId, publicError, error); await this.updateJob(jobId, { status: 'failed', error: publicError, }); } throw error; } } private async resolveAndStoreAccount( data: UserAnalysisJobData, ): Promise { const account = await this.riotApiClient.getAccountByRiotId( data.gameName, data.tagLine, data.regionalRoute, ); const [summoner, tiers] = await Promise.all([ this.riotApiClient.getSummonerByPuuid(account.puuid, data.platformRoute), this.riotApiClient.getLeagueEntriesByPuuid( account.puuid, data.platformRoute, ), ]); const accountModel = await this.connectionService.getModel('account'); const tierFetchedAt = new Date(); const storedAccount = await accountModel .findOneAndUpdate( { puuid: account.puuid }, { $set: { puuid: account.puuid, gameName: account.gameName, tagLine: account.tagLine, platformRoute: data.platformRoute, regionalRoute: data.regionalRoute, profileIconId: summoner.profileIconId, summonerLevel: summoner.summonerLevel, tiers: this.toTierInfo(tiers, tierFetchedAt), tiersFetchedAt: tierFetchedAt, }, $setOnInsert: { isSeed: false, }, }, { new: true, setDefaultsOnInsert: true, upsert: true, }, ) .lean() .exec(); if (!storedAccount) { throw new Error('Failed to store Riot account.'); } return storedAccount; } private async fetchAndStoreMatches( matchIds: string[], data: UserAnalysisJobData, jobId: string, ): Promise { const matchRecords: MatchRecord[] = []; const riotMatchModel = await this.connectionService.getModel('riotMatch'); for (const [index, matchId] of matchIds.entries()) { try { const existingMatch = await riotMatchModel .findOne({ matchId }) .lean() .exec(); if (existingMatch) { if (this.isEligibleMatch(existingMatch.raw, data.queueId)) { const timeline = await this.fetchAndStoreMissingTimeline( matchId, existingMatch.timeline, data.regionalRoute, ); matchRecords.push({ matchId, raw: existingMatch.raw, ...(timeline ? { timeline } : {}), }); } } else { const rawMatch = await this.riotApiClient.getMatch( matchId, data.regionalRoute, ); await this.storeRiotMatch(matchId, rawMatch); if (this.isEligibleMatch(rawMatch, data.queueId)) { const timeline = await this.fetchAndStoreMissingTimeline( matchId, undefined, data.regionalRoute, ); matchRecords.push({ matchId, raw: rawMatch, ...(timeline ? { timeline } : {}), }); } } } catch (error) { this.logger.warn( `Skipping matchId="${this.safeLogText(matchId)}" after fetch/store failure: ${this.safeLogText(errorMessage(error))}`, ); } finally { await this.updateJob(jobId, { progress: { fetchedMatches: index + 1, totalMatches: matchIds.length, }, }); } } return matchRecords; } private async storeRiotMatch( matchId: string, rawMatch: Record, ): Promise { const summary = this.parseMatchSummary(rawMatch); const riotMatchModel = await this.connectionService.getModel('riotMatch'); await riotMatchModel .updateOne( { matchId }, { $setOnInsert: { matchId, gameCreation: summary.gameCreation, gameDuration: summary.gameDuration, gameVersion: summary.gameVersion, queueId: summary.queueId, participantPuuids: summary.participantPuuids, raw: rawMatch, fetchedAt: new Date(), }, }, { upsert: true }, ) .exec(); } private async fetchAndStoreMissingTimeline( matchId: string, existingTimeline: unknown, regionalRoute: UserAnalysisJobData['regionalRoute'], ): Promise | undefined> { if (isRecordValue(existingTimeline)) { return existingTimeline; } try { const timeline = await this.riotApiClient.getMatchTimeline( matchId, regionalRoute, ); await this.storeRiotMatchTimeline(matchId, timeline); return timeline; } catch (error) { this.logger.warn( `Skipping timeline fetch for matchId="${this.safeLogText(matchId)}": ${this.safeLogText(errorMessage(error))}`, ); return undefined; } } private async storeRiotMatchTimeline( matchId: string, timeline: Record, ): Promise { const riotMatchModel = await this.connectionService.getModel('riotMatch'); await riotMatchModel .updateOne( { matchId }, { $set: { timeline, timelineFetchedAt: new Date(), }, }, ) .exec(); } private async extractAndStoreFeatures( matchRecords: MatchRecord[], puuid: string, queueId: number, ): Promise { const playerMatchFeatureModel = await this.connectionService.getModel('playerMatchFeature'); const extractedFeatures: ExtractedPlayerMatchFeature[] = []; for (const matchRecord of matchRecords) { try { const feature = this.featureExtractorService.extractPlayerMatchFeature( matchRecord.raw, puuid, ); if (feature.queueId !== queueId) continue; if (matchRecord.timeline) { feature.derived = { ...this.timelineDerivedService.buildDerivedData( matchRecord.timeline, ), }; feature.timelineProcessed = true; } await playerMatchFeatureModel .updateOne( { matchId: feature.matchId, puuid: feature.puuid }, { $set: feature }, { upsert: true }, ) .exec(); extractedFeatures.push(feature); } catch (error) { this.logger.warn( `Skipping feature extraction for matchId="${this.safeLogText(matchRecord.matchId)}": ${this.safeLogText(errorMessage(error))}`, ); } } return extractedFeatures; } private async buildAndStoreProfile( account: Account, data: UserAnalysisJobData, extractedFeatures: ExtractedPlayerMatchFeature[], ): Promise { const profile = this.profileBuilderService.buildProfile({ features: extractedFeatures, isSeed: account.isSeed, puuid: account.puuid, queueId: data.queueId, }); const playerProfileModel = await this.connectionService.getModel('playerProfile'); const accountModel = await this.connectionService.getModel('account'); const analyzedAt = new Date(); await playerProfileModel .updateOne( { puuid: account.puuid, queueId: data.queueId, }, { $set: profile }, { upsert: true }, ) .exec(); await accountModel .updateOne( { puuid: account.puuid }, { $set: { lastAnalyzedAt: analyzedAt, }, }, ) .exec(); } private async completeJob(jobId: string): Promise { await this.updateJob(jobId, { status: 'completed', stage: 'completed', completedAt: new Date(), error: undefined, }); } private async updateJob( jobId: string, patch: { completedAt?: Date; error?: string; progress?: { fetchedMatches: number; totalMatches: number }; puuid?: string; stage?: string; status?: AnalysisJobStatus; }, ): Promise { const analysisJobModel = await this.connectionService.getModel('analysisJob'); const set: Record = { jobId, jobType: USER_ANALYSIS_JOB_NAME, ...patch, }; const unset: Record = {}; if (patch.error === undefined) { delete set.error; } if (patch.status === 'completed') { unset.error = ''; } await analysisJobModel .updateOne( { jobId }, { $set: set, ...(Object.keys(unset).length > 0 ? { $unset: unset } : {}), }, ) .exec(); } private isEligibleMatch( rawMatch: Record, queueId: number, ): boolean { const info = asRecord(rawMatch.info); return ( asNumber(info.queueId) === queueId && asNumber(info.gameDuration) >= 300 ); } private parseMatchSummary( rawMatch: Record, ): ParsedMatchSummary { const metadata = asRecord(rawMatch.metadata); const info = asRecord(rawMatch.info); return { gameCreation: asNumber(info.gameCreation), gameDuration: asNumber(info.gameDuration), gameVersion: asString(info.gameVersion), queueId: typeof info.queueId === 'number' && Number.isFinite(info.queueId) ? info.queueId : undefined, participantPuuids: asStringArray(metadata.participants), }; } 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 publicErrorMessage(error: unknown): string { if ( error instanceof Error && (error.name === 'RiotApiKeyError' || error.message.includes('Riot API key')) ) { return 'Riot API key is invalid or expired.'; } if (error instanceof RiotNotFoundError) { return 'Riot account was not found for the selected region.'; } return 'Analysis failed during processing.'; } private logFinalFailure( data: UserAnalysisJobData, jobId: string, publicError: string, error: unknown, ): void { this.logger.error( [ `Analysis job failed jobId="${this.safeLogText(jobId)}"`, `gameName="${this.safeLogText(data.gameName)}"`, `tagLine="${this.safeLogText(data.tagLine)}"`, `platformRoute="${data.platformRoute}"`, `publicError="${this.safeLogText(publicError)}"`, `cause="${this.safeLogText(errorMessage(error))}"`, ].join(' '), error instanceof Error ? error.stack : undefined, ); } private safeLogText(value: string): string { return value.replace(/[\r\n\t]/gu, ' ').slice(0, 300); } }