Rename mentor matching to similar players

This commit is contained in:
dahyeon committed 2026-07-03 03:18:59 -07:00
1 parent cfbc74d882
commit ce00bc84b5
14 files changed
+529 -388

No files matched your search

@@ -3,9 +3,9 @@ import {
FEATURE_SCHEMA_VERSION, FEATURE_SCHEMA_VERSION,
METRICS, METRICS,
type AnalysisJobStatusDto, type AnalysisJobStatusDto,
type MentorMatchesDto,
type MetricValueDto, type MetricValueDto,
type PlayerAnalysisDto, type PlayerAnalysisDto,
type SimilarPlayersDto,
} from '@persona-lenz/shared'; } from '@persona-lenz/shared';
import { ConnectionService } from '../global/database/connection.service'; import { ConnectionService } from '../global/database/connection.service';
import type { import type {
@@ -14,8 +14,8 @@ import type {
PlayerProfile, PlayerProfile,
TierInfo, TierInfo,
} from '../global/database/schemas'; } from '../global/database/schemas';
import { MentorMatchService } from './mentor-match.service'; import { SimilarPlayerService } from './similar-player.service';
import type { MentorMatch } from './analysis.types'; import type { SimilarPlayer } from './analysis.types';
type JobStatusRecord = Pick< type JobStatusRecord = Pick<
AnalysisJob, AnalysisJob,
@@ -27,7 +27,7 @@ type AccountSummaryRecord = Pick<
'gameName' | 'profileIconId' | 'tagLine' | 'tiers' 'gameName' | 'profileIconId' | 'tagLine' | 'tiers'
>; >;
type MentorAccountRecord = Pick<Account, 'gameName' | 'puuid' | 'tagLine'>; type CounterpartAccountRecord = Pick<Account, 'gameName' | 'puuid' | 'tagLine'>;
type PlayerProfileRecord = Pick< type PlayerProfileRecord = Pick<
PlayerProfile, PlayerProfile,
@@ -45,7 +45,7 @@ type PlayerProfileRecord = Pick<
export class AnalysisReadService { export class AnalysisReadService {
constructor( constructor(
private readonly connectionService: ConnectionService, private readonly connectionService: ConnectionService,
private readonly mentorMatchService?: MentorMatchService, private readonly similarPlayerService?: SimilarPlayerService,
) {} ) {}
public async getJobStatus(jobId: string): Promise<AnalysisJobStatusDto> { public async getJobStatus(jobId: string): Promise<AnalysisJobStatusDto> {
@@ -113,34 +113,27 @@ export class AnalysisReadService {
}; };
} }
public async getMentorMatches( public async getSimilarPlayers(
puuid: string, puuid: string,
queueId: number, queueId: number,
limit: number, limit: number,
): Promise<MentorMatchesDto> { ): Promise<SimilarPlayersDto> {
if (!this.mentorMatchService) { if (!this.similarPlayerService) {
throw new Error('MentorMatchService is not configured.'); throw new Error('SimilarPlayerService is not configured.');
} }
const mentorMatchesResult = await this.mentorMatchService.findMentorMatches( const similarPlayersResult =
puuid, await this.similarPlayerService.findSimilarPlayers(puuid, queueId, limit);
queueId, const accountsByPuuid = await this.findCounterpartAccounts(
limit, similarPlayersResult.matches.map((match) => match.puuid),
);
const mentorAccountsByPuuid = await this.findMentorAccounts(
mentorMatchesResult.matches.map((match) => match.puuid),
); );
return { return {
puuid: mentorMatchesResult.puuid, puuid: similarPlayersResult.puuid,
queueId: mentorMatchesResult.queueId, queueId: similarPlayersResult.queueId,
profileUpdatedAt: mentorMatchesResult.profileUpdatedAt.toISOString(), profileUpdatedAt: similarPlayersResult.profileUpdatedAt.toISOString(),
matches: mentorMatchesResult.matches.map((match, index) => matches: similarPlayersResult.matches.map((match, index) =>
this.toMentorMatchDto( this.toSimilarPlayerDto(match, accountsByPuuid.get(match.puuid), index),
match,
mentorAccountsByPuuid.get(match.puuid),
index,
),
), ),
}; };
} }
@@ -152,16 +145,16 @@ export class AnalysisReadService {
return accountModel.findOne({ puuid }).lean<AccountSummaryRecord>().exec(); return accountModel.findOne({ puuid }).lean<AccountSummaryRecord>().exec();
} }
private async findMentorAccounts( private async findCounterpartAccounts(
puuids: string[], puuids: string[],
): Promise<Map<string, MentorAccountRecord>> { ): Promise<Map<string, CounterpartAccountRecord>> {
const uniquePuuids = Array.from(new Set(puuids)); const uniquePuuids = Array.from(new Set(puuids));
if (uniquePuuids.length === 0) return new Map(); if (uniquePuuids.length === 0) return new Map();
const accountModel = await this.connectionService.getModel('account'); const accountModel = await this.connectionService.getModel('account');
const accounts = await accountModel const accounts = await accountModel
.find({ puuid: { $in: uniquePuuids } }) .find({ puuid: { $in: uniquePuuids } })
.lean<MentorAccountRecord[]>() .lean<CounterpartAccountRecord[]>()
.exec(); .exec();
return new Map(accounts.map((account) => [account.puuid, account])); return new Map(accounts.map((account) => [account.puuid, account]));
@@ -224,13 +217,13 @@ export class AnalysisReadService {
}; };
} }
private toMentorMatchDto( private toSimilarPlayerDto(
match: MentorMatch, match: SimilarPlayer,
account: MentorAccountRecord | undefined, account: CounterpartAccountRecord | undefined,
index: number, index: number,
): MentorMatchesDto['matches'][number] { ): SimilarPlayersDto['matches'][number] {
return { return {
mentorDisplayId: `mentor-${index + 1}`, displayId: `similar-${index + 1}`,
riotId: account riotId: account
? { ? {
gameName: account.gameName, gameName: account.gameName,
@@ -242,11 +235,13 @@ export class AnalysisReadService {
tier: match.tier, tier: match.tier,
division: match.division, division: match.division,
leaguePoints: match.leaguePoints, leaguePoints: match.leaguePoints,
tierComparison: match.tierComparison,
mainRole: match.mainRole, mainRole: match.mainRole,
mainChampions: match.mainChampions, mainChampions: match.mainChampions,
sampleGameCount: match.sampleGameCount, sampleGameCount: match.sampleGameCount,
similarMetrics: match.similarMetrics, similarMetrics: match.similarMetrics,
gapMetrics: match.gapMetrics, strongerMetrics: match.strongerMetrics,
weakerMetrics: match.weakerMetrics,
}; };
} }
@@ -12,8 +12,8 @@ import {
import type { import type {
AnalysisJobStatusDto, AnalysisJobStatusDto,
AnalysisRequestAcceptedDto, AnalysisRequestAcceptedDto,
MentorMatchesDto,
PlayerAnalysisDto, PlayerAnalysisDto,
SimilarPlayersDto,
} from '@persona-lenz/shared'; } from '@persona-lenz/shared';
import { import {
RIOT_PLATFORM_ROUTES, RIOT_PLATFORM_ROUTES,
@@ -70,16 +70,16 @@ export class AnalysisController {
); );
} }
@Get('players/:puuid/mentor-matches') @Get('players/:puuid/similar-players')
public async getMentorMatches( public async getSimilarPlayers(
@Param('puuid') puuid: string, @Param('puuid') puuid: string,
@Query('queueId') rawQueueId?: string, @Query('queueId') rawQueueId?: string,
@Query('limit') rawLimit?: string, @Query('limit') rawLimit?: string,
): Promise<MentorMatchesDto> { ): Promise<SimilarPlayersDto> {
return this.analysisReadService.getMentorMatches( return this.analysisReadService.getSimilarPlayers(
this.parsePuuid(puuid), this.parsePuuid(puuid),
this.parseQueueId(rawQueueId), this.parseQueueId(rawQueueId),
this.parseMentorMatchLimit(rawLimit), this.parseSimilarPlayersLimit(rawLimit),
); );
} }
@@ -165,7 +165,7 @@ export class AnalysisController {
return queueId; return queueId;
} }
private parseMentorMatchLimit(value?: string): number { private parseSimilarPlayersLimit(value?: string): number {
if (value === undefined) return 10; if (value === undefined) return 10;
const limit = Number(value); const limit = Number(value);
if (!Number.isInteger(limit) || limit < 1) { if (!Number.isInteger(limit) || limit < 1) {
@@ -20,10 +20,10 @@ import { createBullMqOptions } from './bullmq.config';
import { FeatureExtractorService } from './feature-extractor.service'; import { FeatureExtractorService } from './feature-extractor.service';
import { MetricBaselineService } from './metric-baseline.service'; import { MetricBaselineService } from './metric-baseline.service';
import { MetricNormalizationService } from './metric-normalization.service'; import { MetricNormalizationService } from './metric-normalization.service';
import { MentorMatchService } from './mentor-match.service';
import { ProfileBuilderService } from './profile-builder.service'; import { ProfileBuilderService } from './profile-builder.service';
import { SeedCollectionProcessor } from './seed-collection.processor'; import { SeedCollectionProcessor } from './seed-collection.processor';
import { SeedCollectionService } from './seed-collection.service'; import { SeedCollectionService } from './seed-collection.service';
import { SimilarPlayerService } from './similar-player.service';
import { TimelineDerivedService } from './timeline-derived.service'; import { TimelineDerivedService } from './timeline-derived.service';
import { TimelineMetricService } from './timeline-metric.service'; import { TimelineMetricService } from './timeline-metric.service';
@@ -61,9 +61,9 @@ import { TimelineMetricService } from './timeline-metric.service';
FeatureExtractorService, FeatureExtractorService,
MetricBaselineService, MetricBaselineService,
MetricNormalizationService, MetricNormalizationService,
MentorMatchService,
ProfileBuilderService, ProfileBuilderService,
SeedCollectionService, SeedCollectionService,
SimilarPlayerService,
TimelineDerivedService, TimelineDerivedService,
TimelineMetricService, TimelineMetricService,
], ],
@@ -73,8 +73,8 @@ import { TimelineMetricService } from './timeline-metric.service';
AnalysisPipelineService, AnalysisPipelineService,
MetricBaselineService, MetricBaselineService,
MetricNormalizationService, MetricNormalizationService,
MentorMatchService,
SeedCollectionService, SeedCollectionService,
SimilarPlayerService,
], ],
}) })
export class AnalysisModule {} export class AnalysisModule {}
+15 -13
View File
@@ -1,4 +1,4 @@
import type { MetricId, Role } from '@persona-lenz/shared'; import type { MetricId, Role, TierComparison } from '@persona-lenz/shared';
import type { import type {
BaselineCohort, BaselineCohort,
LaneOpponentRef, LaneOpponentRef,
@@ -97,43 +97,45 @@ export interface BuiltPlayerProfile {
leaguePoints?: number; leaguePoints?: number;
} }
export interface MentorChampionPoolEntry { export interface ChampionPoolEntry {
championId: number; championId: number;
games: number; games: number;
wins: number; wins: number;
} }
export interface SimilarMentorMetric { export interface SimilarMetric {
metricId: MetricId; metricId: MetricId;
currentValue: number; currentValue: number;
mentorValue: number; otherValue: number;
absoluteGap: number; absoluteGap: number;
} }
export interface GapMentorMetric { export interface LeadMetric {
metricId: MetricId; metricId: MetricId;
currentValue: number; currentValue: number;
mentorValue: number; otherValue: number;
mentorAdvantage: number; lead: number;
} }
export interface MentorMatch { export interface SimilarPlayer {
puuid: string; puuid: string;
similarityScore: number; similarityScore: number;
finalScore: number; finalScore: number;
tier?: string; tier?: string;
division?: string; division?: string;
leaguePoints?: number; leaguePoints?: number;
tierComparison: TierComparison;
mainRole: Role; mainRole: Role;
mainChampions: MentorChampionPoolEntry[]; mainChampions: ChampionPoolEntry[];
sampleGameCount: number; sampleGameCount: number;
similarMetrics: SimilarMentorMetric[]; similarMetrics: SimilarMetric[];
gapMetrics: GapMentorMetric[]; strongerMetrics: LeadMetric[];
weakerMetrics: LeadMetric[];
} }
export interface MentorMatchesResult { export interface SimilarPlayersResult {
puuid: string; puuid: string;
queueId: number; queueId: number;
profileUpdatedAt: Date; profileUpdatedAt: Date;
matches: MentorMatch[]; matches: SimilarPlayer[];
} }
@@ -1,6 +1,6 @@
import { FEATURE_SCHEMA_VERSION, VECTOR_DIMENSION } from '@persona-lenz/shared'; import { FEATURE_SCHEMA_VERSION, VECTOR_DIMENSION } from '@persona-lenz/shared';
import type { ConnectionService } from '../global/database/connection.service'; import type { ConnectionService } from '../global/database/connection.service';
import { MentorMatchService } from './mentor-match.service'; import { SimilarPlayerService } from './similar-player.service';
function createLeanExec<T>(value: T) { function createLeanExec<T>(value: T) {
return { return {
@@ -64,7 +64,7 @@ function createProfile(overrides: Record<string, unknown> = {}) {
}; };
} }
describe('MentorMatchService', () => { describe('SimilarPlayerService', () => {
beforeEach(() => { beforeEach(() => {
jest.useFakeTimers().setSystemTime(new Date('2026-07-03T00:00:00.000Z')); jest.useFakeTimers().setSystemTime(new Date('2026-07-03T00:00:00.000Z'));
}); });
@@ -73,7 +73,7 @@ describe('MentorMatchService', () => {
jest.useRealTimers(); jest.useRealTimers();
}); });
it('queries high-tier seed profiles with Atlas Vector Search and reranks candidates', async () => { it('queries similar profiles without tier filters and ranks by style similarity', async () => {
const currentProfile = createProfile(); const currentProfile = createProfile();
const findOne = jest.fn(() => createLeanExec(currentProfile)); const findOne = jest.fn(() => createLeanExec(currentProfile));
const recommendationFindOne = jest.fn(() => createSortedLeanExec(null)); const recommendationFindOne = jest.fn(() => createSortedLeanExec(null));
@@ -81,7 +81,7 @@ describe('MentorMatchService', () => {
const aggregate = jest.fn(() => const aggregate = jest.fn(() =>
createAggregateExec([ createAggregateExec([
createProfile({ createProfile({
puuid: 'mentor-low-style-better-context', puuid: 'lower-style-better-context',
championPool: [ championPool: [
{ championId: 103, games: 12, wins: 8 }, { championId: 103, games: 12, wins: 8 },
{ championId: 84, games: 5, wins: 4 }, { championId: 84, games: 5, wins: 4 },
@@ -101,7 +101,7 @@ describe('MentorMatchService', () => {
score: 0.8, score: 0.8,
}), }),
createProfile({ createProfile({
puuid: 'mentor-high-style-weaker-context', puuid: 'higher-style-similar-player',
championPool: [{ championId: 222, games: 30, wins: 20 }], championPool: [{ championId: 222, games: 30, wins: 20 }],
profile: { profile: {
kda: 0.4, kda: 0.4,
@@ -111,13 +111,13 @@ describe('MentorMatchService', () => {
deathsPerMin: 0.6, deathsPerMin: 0.6,
}, },
sampleGameCount: 30, sampleGameCount: 30,
tier: 'MASTER', tier: 'PLATINUM',
lastMatchAt: new Date('2026-06-19T00:00:00.000Z'), lastMatchAt: new Date('2026-06-19T00:00:00.000Z'),
score: 0.9, score: 0.9,
}), }),
]), ]),
); );
const service = new MentorMatchService({ const service = new SimilarPlayerService({
getModel: jest.fn((modelKey: string) => getModel: jest.fn((modelKey: string) =>
Promise.resolve( Promise.resolve(
modelKey === 'playerProfile' modelKey === 'playerProfile'
@@ -127,7 +127,7 @@ describe('MentorMatchService', () => {
), ),
} as unknown as ConnectionService); } as unknown as ConnectionService);
const result = await service.findMentorMatches('target-puuid', 420, 2); const result = await service.findSimilarPlayers('target-puuid', 420, 2);
expect(findOne).toHaveBeenCalledWith({ expect(findOne).toHaveBeenCalledWith({
puuid: 'target-puuid', puuid: 'target-puuid',
@@ -145,8 +145,6 @@ describe('MentorMatchService', () => {
filter: { filter: {
mainRole: 'MIDDLE', mainRole: 'MIDDLE',
queueId: 420, queueId: 420,
tier: { $in: ['MASTER', 'GRANDMASTER', 'CHALLENGER'] },
isSeed: true,
sampleGameCount: { $gte: 20 }, sampleGameCount: { $gte: 20 },
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
}, },
@@ -173,63 +171,89 @@ describe('MentorMatchService', () => {
expect(result.profileUpdatedAt).toEqual( expect(result.profileUpdatedAt).toEqual(
new Date('2026-07-02T00:00:00.000Z'), new Date('2026-07-02T00:00:00.000Z'),
); );
// 스타일 유사도(0.9)가 컨텍스트(챔피언 풀·최근성)보다 랭킹을 지배한다.
expect(result.matches.map((match) => match.puuid)).toEqual([ expect(result.matches.map((match) => match.puuid)).toEqual([
'mentor-low-style-better-context', 'higher-style-similar-player',
'mentor-high-style-weaker-context', 'lower-style-better-context',
]);
expect(result.matches[0].finalScore).toBeGreaterThan(
result.matches[1].finalScore,
);
expect(result.matches[0].mainChampions).toEqual([
{ championId: 103, games: 12, wins: 8 },
{ championId: 84, games: 5, wins: 4 },
{ championId: 777, games: 5, wins: 3 },
]); ]);
expect(result.matches[0].finalScore).toBeCloseTo(0.69, 6);
expect(result.matches[1].finalScore).toBeCloseTo(0.67, 6);
expect(result.matches[0].tierComparison).toBe('lower');
expect(result.matches[1].tierComparison).toBe('higher');
expect(result.matches[0].similarMetrics).toEqual([ expect(result.matches[0].similarMetrics).toEqual([
{ {
metricId: 'killParticipation', metricId: 'killParticipation',
currentValue: 0.5, currentValue: 0.5,
mentorValue: 0.49, otherValue: 0.52,
absoluteGap: 0.01, absoluteGap: 0.02,
},
{
metricId: 'csPerMin',
currentValue: 0.5,
mentorValue: 0.51,
absoluteGap: 0.01,
}, },
{ {
metricId: 'goldPerMin', metricId: 'goldPerMin',
currentValue: 0.5, currentValue: 0.5,
mentorValue: 0.8, otherValue: 0.55,
absoluteGap: 0.3, absoluteGap: 0.05,
}, },
]);
expect(result.matches[0].gapMetrics).toEqual([
{ {
metricId: 'kda', metricId: 'kda',
currentValue: 0.3, currentValue: 0.3,
mentorValue: 0.9, otherValue: 0.4,
mentorAdvantage: 0.6, absoluteGap: 0.1,
},
]);
expect(result.matches[0].strongerMetrics).toEqual([
{
metricId: 'csPerMin',
currentValue: 0.5,
otherValue: 0.7,
lead: 0.2,
},
{
metricId: 'kda',
currentValue: 0.3,
otherValue: 0.4,
lead: 0.1,
}, },
{ {
metricId: 'deathsPerMin', metricId: 'deathsPerMin',
currentValue: 0.7, currentValue: 0.7,
mentorValue: 0.2, otherValue: 0.6,
mentorAdvantage: 0.5, lead: 0.1,
},
]);
expect(result.matches[0].weakerMetrics).toEqual([]);
expect(result.matches[1].strongerMetrics).toEqual([
{
metricId: 'kda',
currentValue: 0.3,
otherValue: 0.9,
lead: 0.6,
},
{
metricId: 'deathsPerMin',
currentValue: 0.7,
otherValue: 0.2,
lead: 0.5,
}, },
{ {
metricId: 'goldPerMin', metricId: 'goldPerMin',
currentValue: 0.5, currentValue: 0.5,
mentorValue: 0.8, otherValue: 0.8,
mentorAdvantage: 0.3, lead: 0.3,
},
]);
expect(result.matches[1].weakerMetrics).toEqual([
{
metricId: 'killParticipation',
currentValue: 0.5,
otherValue: 0.49,
lead: 0.01,
}, },
]); ]);
expect(updateOne).toHaveBeenCalledWith( expect(updateOne).toHaveBeenCalledWith(
{ {
puuid: 'target-puuid', puuid: 'target-puuid',
queueId: 420, queueId: 420,
type: 'mentor-match', type: 'similar-player',
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
profileUpdatedAt: new Date('2026-07-02T00:00:00.000Z'), profileUpdatedAt: new Date('2026-07-02T00:00:00.000Z'),
}, },
@@ -237,7 +261,7 @@ describe('MentorMatchService', () => {
$set: { $set: {
puuid: 'target-puuid', puuid: 'target-puuid',
queueId: 420, queueId: 420,
type: 'mentor-match', type: 'similar-player',
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
profileUpdatedAt: new Date('2026-07-02T00:00:00.000Z'), profileUpdatedAt: new Date('2026-07-02T00:00:00.000Z'),
result: { matches: result.matches }, result: { matches: result.matches },
@@ -252,13 +276,14 @@ describe('MentorMatchService', () => {
); );
}); });
it('returns a fresh cached mentor recommendation without running vector search', async () => { it('returns a fresh cached similar-player recommendation without running vector search', async () => {
const currentProfile = createProfile(); const currentProfile = createProfile();
const cachedMatch = { const cachedMatch = {
puuid: 'cached-mentor', puuid: 'cached-similar-player',
similarityScore: 0.87, similarityScore: 0.87,
finalScore: 0.81, finalScore: 0.81,
tier: 'CHALLENGER', tier: 'CHALLENGER',
tierComparison: 'higher',
mainRole: 'MIDDLE', mainRole: 'MIDDLE',
mainChampions: [{ championId: 103, games: 20, wins: 14 }], mainChampions: [{ championId: 103, games: 20, wins: 14 }],
sampleGameCount: 40, sampleGameCount: 40,
@@ -266,18 +291,19 @@ describe('MentorMatchService', () => {
{ {
metricId: 'kda', metricId: 'kda',
currentValue: 0.3, currentValue: 0.3,
mentorValue: 0.31, otherValue: 0.31,
absoluteGap: 0.01, absoluteGap: 0.01,
}, },
], ],
gapMetrics: [ strongerMetrics: [
{ {
metricId: 'goldPerMin', metricId: 'goldPerMin',
currentValue: 0.5, currentValue: 0.5,
mentorValue: 0.8, otherValue: 0.8,
mentorAdvantage: 0.3, lead: 0.3,
}, },
], ],
weakerMetrics: [],
}; };
const findOne = jest.fn(() => createLeanExec(currentProfile)); const findOne = jest.fn(() => createLeanExec(currentProfile));
const aggregate = jest.fn(); const aggregate = jest.fn();
@@ -288,7 +314,7 @@ describe('MentorMatchService', () => {
}), }),
); );
const updateOne = jest.fn(); const updateOne = jest.fn();
const service = new MentorMatchService({ const service = new SimilarPlayerService({
getModel: jest.fn((modelKey: string) => getModel: jest.fn((modelKey: string) =>
Promise.resolve( Promise.resolve(
modelKey === 'playerProfile' modelKey === 'playerProfile'
@@ -298,12 +324,12 @@ describe('MentorMatchService', () => {
), ),
} as unknown as ConnectionService); } as unknown as ConnectionService);
const result = await service.findMentorMatches('target-puuid', 420, 10); const result = await service.findSimilarPlayers('target-puuid', 420, 10);
expect(recommendationFindOne).toHaveBeenCalledWith({ expect(recommendationFindOne).toHaveBeenCalledWith({
puuid: 'target-puuid', puuid: 'target-puuid',
queueId: 420, queueId: 420,
type: 'mentor-match', type: 'similar-player',
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
profileUpdatedAt: new Date('2026-07-02T00:00:00.000Z'), profileUpdatedAt: new Date('2026-07-02T00:00:00.000Z'),
}); });
@@ -320,12 +346,12 @@ describe('MentorMatchService', () => {
it('throws when the player profile has not been built yet', async () => { it('throws when the player profile has not been built yet', async () => {
const findOne = jest.fn(() => createLeanExec(null)); const findOne = jest.fn(() => createLeanExec(null));
const aggregate = jest.fn(); const aggregate = jest.fn();
const service = new MentorMatchService({ const service = new SimilarPlayerService({
getModel: jest.fn().mockResolvedValue({ findOne, aggregate }), getModel: jest.fn().mockResolvedValue({ findOne, aggregate }),
} as unknown as ConnectionService); } as unknown as ConnectionService);
await expect( await expect(
service.findMentorMatches('missing-puuid', 420), service.findSimilarPlayers('missing-puuid', 420),
).rejects.toThrow('Player profile not found.'); ).rejects.toThrow('Player profile not found.');
expect(aggregate).not.toHaveBeenCalled(); expect(aggregate).not.toHaveBeenCalled();
}); });
@@ -6,33 +6,51 @@ import {
VECTOR_DIMENSION, VECTOR_DIMENSION,
type MetricDefinition, type MetricDefinition,
type Role, type Role,
type TierComparison,
} from '@persona-lenz/shared'; } from '@persona-lenz/shared';
import type { PipelineStage } from 'mongoose'; import type { PipelineStage } from 'mongoose';
import { ConnectionService } from '../global/database/connection.service'; import { ConnectionService } from '../global/database/connection.service';
import type { import type {
GapMentorMetric, ChampionPoolEntry,
MentorChampionPoolEntry, LeadMetric,
MentorMatch, SimilarMetric,
MentorMatchesResult, SimilarPlayer,
SimilarMentorMetric, SimilarPlayersResult,
} from './analysis.types'; } from './analysis.types';
const MENTOR_VECTOR_SEARCH_INDEX_NAME = 'player_profile_vector_index'; const SIMILAR_PLAYER_VECTOR_SEARCH_INDEX_NAME = 'player_profile_vector_index';
const MENTOR_VECTOR_SEARCH_NUM_CANDIDATES = 200; const SIMILAR_PLAYER_VECTOR_SEARCH_NUM_CANDIDATES = 200;
const MENTOR_VECTOR_SEARCH_LIMIT = 50; const SIMILAR_PLAYER_VECTOR_SEARCH_LIMIT = 50;
const DEFAULT_MENTOR_MATCH_LIMIT = 10; const DEFAULT_SIMILAR_PLAYER_LIMIT = 10;
const MINIMUM_MENTOR_SAMPLE_GAME_COUNT = 20; const MINIMUM_SAMPLE_GAME_COUNT = 20;
const LOW_SAMPLE_GAME_COUNT_THRESHOLD = 30; const LOW_SAMPLE_GAME_COUNT_THRESHOLD = 30;
const LOW_SAMPLE_PENALTY = 0.1; const LOW_SAMPLE_PENALTY = 0.1;
const RECENCY_HALF_LIFE_MS = 14 * 24 * 60 * 60 * 1000; const RECENCY_HALF_LIFE_MS = 14 * 24 * 60 * 60 * 1000;
const HIGH_TIER_MENTOR_TIERS = ['MASTER', 'GRANDMASTER', 'CHALLENGER']; const TIER_ORDER = [
'IRON',
'BRONZE',
'SILVER',
'GOLD',
'PLATINUM',
'EMERALD',
'DIAMOND',
'MASTER',
'GRANDMASTER',
'CHALLENGER',
];
const TIER_COMPARISONS: TierComparison[] = [
'higher',
'same',
'lower',
'unknown',
];
interface MentorProfileRecord { interface PlayerProfileRecord {
puuid: string; puuid: string;
queueId: number; queueId: number;
mainRole: Role; mainRole: Role;
sampleGameCount: number; sampleGameCount: number;
championPool: MentorChampionPoolEntry[]; championPool: ChampionPoolEntry[];
profile: Record<string, number>; profile: Record<string, number>;
vector: number[]; vector: number[];
updatedAt: Date; updatedAt: Date;
@@ -42,23 +60,29 @@ interface MentorProfileRecord {
leaguePoints?: number; leaguePoints?: number;
} }
interface MentorVectorSearchRecord extends Omit<MentorProfileRecord, 'vector'> { interface VectorSearchRecord extends Omit<PlayerProfileRecord, 'vector'> {
score?: number; score?: number;
} }
interface MentorRecommendationCacheRecord { interface RecommendationCacheRecord {
result?: Record<string, unknown>; result?: Record<string, unknown>;
} }
/**
* 나와 플레이스타일 벡터가 가까운 유저를 찾는다. 목적은 "따라 할 멘토"가 아니라
* "스타일은 비슷한데 왜 점수(티어)가 다른가"라는 인사이트 제공이므로,
* 후보를 티어로 거르지 않고 유사도 중심으로 랭킹한 뒤 티어 관계와
* 지표 우위(양방향)를 함께 반환한다.
*/
@Injectable() @Injectable()
export class MentorMatchService { export class SimilarPlayerService {
constructor(private readonly connectionService: ConnectionService) {} constructor(private readonly connectionService: ConnectionService) {}
public async findMentorMatches( public async findSimilarPlayers(
puuid: string, puuid: string,
queueId: number, queueId: number,
requestedLimit = DEFAULT_MENTOR_MATCH_LIMIT, requestedLimit = DEFAULT_SIMILAR_PLAYER_LIMIT,
): Promise<MentorMatchesResult> { ): Promise<SimilarPlayersResult> {
const playerProfileModel = const playerProfileModel =
await this.connectionService.getModel('playerProfile'); await this.connectionService.getModel('playerProfile');
const recommendationModel = const recommendationModel =
@@ -66,14 +90,14 @@ export class MentorMatchService {
const normalizedLimit = this.normalizeLimit(requestedLimit); const normalizedLimit = this.normalizeLimit(requestedLimit);
const currentProfile = await playerProfileModel const currentProfile = await playerProfileModel
.findOne({ puuid, queueId, featureSchemaVersion: FEATURE_SCHEMA_VERSION }) .findOne({ puuid, queueId, featureSchemaVersion: FEATURE_SCHEMA_VERSION })
.lean<MentorProfileRecord>() .lean<PlayerProfileRecord>()
.exec(); .exec();
if (!currentProfile) { if (!currentProfile) {
throw new NotFoundException('Player profile not found.'); throw new NotFoundException('Player profile not found.');
} }
const cacheFilter = this.createMentorRecommendationFilter( const cacheFilter = this.createRecommendationFilter(
puuid, puuid,
queueId, queueId,
currentProfile.updatedAt, currentProfile.updatedAt,
@@ -81,9 +105,9 @@ export class MentorMatchService {
const cachedRecommendation = await recommendationModel const cachedRecommendation = await recommendationModel
.findOne(cacheFilter) .findOne(cacheFilter)
.sort({ generatedAt: -1 }) .sort({ generatedAt: -1 })
.lean<MentorRecommendationCacheRecord>() .lean<RecommendationCacheRecord>()
.exec(); .exec();
const cachedMatches = this.extractCachedMentorMatches(cachedRecommendation); const cachedMatches = this.extractCachedMatches(cachedRecommendation);
if (cachedMatches) { if (cachedMatches) {
return { return {
puuid, puuid,
@@ -103,13 +127,13 @@ export class MentorMatchService {
} }
const candidates = await playerProfileModel const candidates = await playerProfileModel
.aggregate<MentorVectorSearchRecord>( .aggregate<VectorSearchRecord>(
this.createMentorCandidatePipeline(currentProfile, puuid, queueId), this.createCandidatePipeline(currentProfile, puuid, queueId),
) )
.exec(); .exec();
const matches = candidates const matches = candidates
.map((candidate) => this.toMentorMatch(currentProfile, candidate)) .map((candidate) => this.toSimilarPlayer(currentProfile, candidate))
.sort((left, right) => right.finalScore - left.finalScore) .sort((left, right) => right.finalScore - left.finalScore)
.slice(0, normalizedLimit); .slice(0, normalizedLimit);
@@ -120,13 +144,13 @@ export class MentorMatchService {
$set: { $set: {
puuid, puuid,
queueId, queueId,
type: 'mentor-match', type: 'similar-player',
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
profileUpdatedAt: currentProfile.updatedAt, profileUpdatedAt: currentProfile.updatedAt,
result: { matches }, result: { matches },
evidence: { evidence: {
candidateCount: candidates.length, candidateCount: candidates.length,
vectorSearchIndex: MENTOR_VECTOR_SEARCH_INDEX_NAME, vectorSearchIndex: SIMILAR_PLAYER_VECTOR_SEARCH_INDEX_NAME,
}, },
generatedAt: new Date(), generatedAt: new Date(),
}, },
@@ -143,45 +167,43 @@ export class MentorMatchService {
}; };
} }
private createMentorRecommendationFilter( private createRecommendationFilter(
puuid: string, puuid: string,
queueId: number, queueId: number,
profileUpdatedAt: Date, profileUpdatedAt: Date,
): { ): {
puuid: string; puuid: string;
queueId: number; queueId: number;
type: 'mentor-match'; type: 'similar-player';
featureSchemaVersion: number; featureSchemaVersion: number;
profileUpdatedAt: Date; profileUpdatedAt: Date;
} { } {
return { return {
puuid, puuid,
queueId, queueId,
type: 'mentor-match', type: 'similar-player',
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
profileUpdatedAt, profileUpdatedAt,
}; };
} }
private createMentorCandidatePipeline( private createCandidatePipeline(
currentProfile: MentorProfileRecord, currentProfile: PlayerProfileRecord,
puuid: string, puuid: string,
queueId: number, queueId: number,
): PipelineStage[] { ): PipelineStage[] {
return [ return [
{ {
$vectorSearch: { $vectorSearch: {
index: MENTOR_VECTOR_SEARCH_INDEX_NAME, index: SIMILAR_PLAYER_VECTOR_SEARCH_INDEX_NAME,
path: 'vector', path: 'vector',
queryVector: currentProfile.vector, queryVector: currentProfile.vector,
numCandidates: MENTOR_VECTOR_SEARCH_NUM_CANDIDATES, numCandidates: SIMILAR_PLAYER_VECTOR_SEARCH_NUM_CANDIDATES,
limit: MENTOR_VECTOR_SEARCH_LIMIT, limit: SIMILAR_PLAYER_VECTOR_SEARCH_LIMIT,
filter: { filter: {
mainRole: currentProfile.mainRole, mainRole: currentProfile.mainRole,
queueId, queueId,
tier: { $in: HIGH_TIER_MENTOR_TIERS }, sampleGameCount: { $gte: MINIMUM_SAMPLE_GAME_COUNT },
isSeed: true,
sampleGameCount: { $gte: MINIMUM_MENTOR_SAMPLE_GAME_COUNT },
featureSchemaVersion: FEATURE_SCHEMA_VERSION, featureSchemaVersion: FEATURE_SCHEMA_VERSION,
}, },
}, },
@@ -206,81 +228,99 @@ export class MentorMatchService {
]; ];
} }
private toMentorMatch( private toSimilarPlayer(
currentProfile: MentorProfileRecord, currentProfile: PlayerProfileRecord,
mentorProfile: MentorVectorSearchRecord, candidate: VectorSearchRecord,
): MentorMatch { ): SimilarPlayer {
const similarityScore = this.clamp01(mentorProfile.score ?? 0); const similarityScore = this.clamp01(candidate.score ?? 0);
return { return {
puuid: mentorProfile.puuid, puuid: candidate.puuid,
similarityScore, similarityScore,
finalScore: this.calculateFinalScore( finalScore: this.calculateFinalScore(
currentProfile, currentProfile,
mentorProfile, candidate,
similarityScore, similarityScore,
), ),
tier: mentorProfile.tier, tier: candidate.tier,
division: mentorProfile.division, division: candidate.division,
leaguePoints: mentorProfile.leaguePoints, leaguePoints: candidate.leaguePoints,
mainRole: mentorProfile.mainRole, tierComparison: this.compareTier(currentProfile.tier, candidate.tier),
mainChampions: mentorProfile.championPool.slice(0, 3), mainRole: candidate.mainRole,
sampleGameCount: mentorProfile.sampleGameCount, mainChampions: candidate.championPool.slice(0, 3),
sampleGameCount: candidate.sampleGameCount,
similarMetrics: this.resolveSimilarMetrics( similarMetrics: this.resolveSimilarMetrics(
currentProfile.profile, currentProfile.profile,
mentorProfile.profile, candidate.profile,
), ),
gapMetrics: this.resolveGapMetrics( strongerMetrics: this.resolveLeadMetrics(
currentProfile.profile, currentProfile.profile,
mentorProfile.profile, candidate.profile,
'other',
),
weakerMetrics: this.resolveLeadMetrics(
currentProfile.profile,
candidate.profile,
'current',
), ),
}; };
} }
private calculateFinalScore( private calculateFinalScore(
currentProfile: MentorProfileRecord, currentProfile: PlayerProfileRecord,
mentorProfile: MentorVectorSearchRecord, candidate: VectorSearchRecord,
similarityScore: number, similarityScore: number,
): number { ): number {
const championPoolSimilarity = this.calculateChampionPoolSimilarity( const championPoolSimilarity = this.calculateChampionPoolSimilarity(
currentProfile.championPool, currentProfile.championPool,
mentorProfile.championPool, candidate.championPool,
); );
const recencyScore = this.calculateRecencyScore(mentorProfile.lastMatchAt); const recencyScore = this.calculateRecencyScore(candidate.lastMatchAt);
const tierScore = this.resolveTierScore(mentorProfile.tier);
const lowSamplePenalty = const lowSamplePenalty =
mentorProfile.sampleGameCount < LOW_SAMPLE_GAME_COUNT_THRESHOLD candidate.sampleGameCount < LOW_SAMPLE_GAME_COUNT_THRESHOLD
? LOW_SAMPLE_PENALTY ? LOW_SAMPLE_PENALTY
: 0; : 0;
// 유사도가 랭킹을 지배해야 한다 — 티어는 랭킹 요소가 아니라 인사이트(tierComparison)로만 쓴다.
return this.clamp01( return this.clamp01(
0.6 * similarityScore + 0.7 * similarityScore +
0.2 * championPoolSimilarity + 0.18 * championPoolSimilarity +
0.12 * recencyScore + 0.12 * recencyScore -
0.08 * tierScore -
lowSamplePenalty, lowSamplePenalty,
); );
} }
private compareTier(
currentTier: string | undefined,
otherTier: string | undefined,
): TierComparison {
const currentTierRank = TIER_ORDER.indexOf(currentTier ?? '');
const otherTierRank = TIER_ORDER.indexOf(otherTier ?? '');
if (currentTierRank < 0 || otherTierRank < 0) return 'unknown';
if (otherTierRank > currentTierRank) return 'higher';
if (otherTierRank < currentTierRank) return 'lower';
return 'same';
}
private calculateChampionPoolSimilarity( private calculateChampionPoolSimilarity(
currentChampionPool: MentorChampionPoolEntry[], currentChampionPool: ChampionPoolEntry[],
mentorChampionPool: MentorChampionPoolEntry[], otherChampionPool: ChampionPoolEntry[],
): number { ): number {
const currentChampionIds = new Set( const currentChampionIds = new Set(
currentChampionPool.slice(0, 5).map((entry) => entry.championId), currentChampionPool.slice(0, 5).map((entry) => entry.championId),
); );
const mentorChampionIds = new Set( const otherChampionIds = new Set(
mentorChampionPool.slice(0, 5).map((entry) => entry.championId), otherChampionPool.slice(0, 5).map((entry) => entry.championId),
); );
const unionChampionIds = new Set([ const unionChampionIds = new Set([
...currentChampionIds, ...currentChampionIds,
...mentorChampionIds, ...otherChampionIds,
]); ]);
if (unionChampionIds.size === 0) return 0; if (unionChampionIds.size === 0) return 0;
let sharedChampionCount = 0; let sharedChampionCount = 0;
currentChampionIds.forEach((championId) => { currentChampionIds.forEach((championId) => {
if (mentorChampionIds.has(championId)) sharedChampionCount += 1; if (otherChampionIds.has(championId)) sharedChampionCount += 1;
}); });
return sharedChampionCount / unionChampionIds.size; return sharedChampionCount / unionChampionIds.size;
@@ -293,21 +333,14 @@ export class MentorMatchService {
return this.clamp01(Math.pow(0.5, ageMs / RECENCY_HALF_LIFE_MS)); return this.clamp01(Math.pow(0.5, ageMs / RECENCY_HALF_LIFE_MS));
} }
private resolveTierScore(tier: string | undefined): number {
if (tier === 'CHALLENGER') return 1;
if (tier === 'GRANDMASTER') return 0.8;
if (tier === 'MASTER') return 0.6;
return 0;
}
private resolveSimilarMetrics( private resolveSimilarMetrics(
currentProfile: Record<string, number>, currentProfile: Record<string, number>,
mentorProfile: Record<string, number>, otherProfile: Record<string, number>,
): SimilarMentorMetric[] { ): SimilarMetric[] {
return METRICS.flatMap((metric) => { return METRICS.flatMap((metric) => {
const comparison = this.createMetricValues( const comparison = this.createMetricValues(
currentProfile, currentProfile,
mentorProfile, otherProfile,
metric, metric,
); );
if (!comparison) return []; if (!comparison) return [];
@@ -315,9 +348,9 @@ export class MentorMatchService {
return { return {
metricId: metric.id, metricId: metric.id,
currentValue: comparison.currentValue, currentValue: comparison.currentValue,
mentorValue: comparison.mentorValue, otherValue: comparison.otherValue,
absoluteGap: this.roundMetricGap( absoluteGap: this.roundMetricGap(
Math.abs(comparison.mentorValue - comparison.currentValue), Math.abs(comparison.otherValue - comparison.currentValue),
), ),
}; };
}) })
@@ -325,57 +358,59 @@ export class MentorMatchService {
.slice(0, 3); .slice(0, 3);
} }
private resolveGapMetrics( private resolveLeadMetrics(
currentProfile: Record<string, number>, currentProfile: Record<string, number>,
mentorProfile: Record<string, number>, otherProfile: Record<string, number>,
): GapMentorMetric[] { leader: 'current' | 'other',
): LeadMetric[] {
return METRICS.flatMap((metric) => { return METRICS.flatMap((metric) => {
const comparison = this.createMetricValues( const comparison = this.createMetricValues(
currentProfile, currentProfile,
mentorProfile, otherProfile,
metric, metric,
); );
if (!comparison) return []; if (!comparison) return [];
const rawMentorAdvantage = const otherAdvantage =
metric.direction === 'lowerIsBetter' metric.direction === 'lowerIsBetter'
? comparison.currentValue - comparison.mentorValue ? comparison.currentValue - comparison.otherValue
: comparison.mentorValue - comparison.currentValue; : comparison.otherValue - comparison.currentValue;
if (rawMentorAdvantage <= 0) return []; const lead = leader === 'other' ? otherAdvantage : -otherAdvantage;
if (lead <= 0) return [];
return { return {
metricId: metric.id, metricId: metric.id,
currentValue: comparison.currentValue, currentValue: comparison.currentValue,
mentorValue: comparison.mentorValue, otherValue: comparison.otherValue,
mentorAdvantage: this.roundMetricGap(rawMentorAdvantage), lead: this.roundMetricGap(lead),
}; };
}) })
.sort((left, right) => right.mentorAdvantage - left.mentorAdvantage) .sort((left, right) => right.lead - left.lead)
.slice(0, 3); .slice(0, 3);
} }
private createMetricValues( private createMetricValues(
currentProfile: Record<string, number>, currentProfile: Record<string, number>,
mentorProfile: Record<string, number>, otherProfile: Record<string, number>,
metric: MetricDefinition, metric: MetricDefinition,
): { currentValue: number; mentorValue: number } | null { ): { currentValue: number; otherValue: number } | null {
const currentValue = currentProfile[metric.id]; const currentValue = currentProfile[metric.id];
const mentorValue = mentorProfile[metric.id]; const otherValue = otherProfile[metric.id];
if (!Number.isFinite(currentValue) || !Number.isFinite(mentorValue)) { if (!Number.isFinite(currentValue) || !Number.isFinite(otherValue)) {
return null; return null;
} }
return { return {
currentValue: this.clamp01(currentValue), currentValue: this.clamp01(currentValue),
mentorValue: this.clamp01(mentorValue), otherValue: this.clamp01(otherValue),
}; };
} }
private normalizeLimit(requestedLimit: number): number { private normalizeLimit(requestedLimit: number): number {
if (!Number.isInteger(requestedLimit) || requestedLimit < 1) { if (!Number.isInteger(requestedLimit) || requestedLimit < 1) {
return DEFAULT_MENTOR_MATCH_LIMIT; return DEFAULT_SIMILAR_PLAYER_LIMIT;
} }
return Math.min(requestedLimit, DEFAULT_MENTOR_MATCH_LIMIT); return Math.min(requestedLimit, DEFAULT_SIMILAR_PLAYER_LIMIT);
} }
private roundMetricGap(value: number): number { private roundMetricGap(value: number): number {
@@ -387,18 +422,18 @@ export class MentorMatchService {
return Math.max(0, Math.min(1, value)); return Math.max(0, Math.min(1, value));
} }
private extractCachedMentorMatches( private extractCachedMatches(
recommendation: MentorRecommendationCacheRecord | null, recommendation: RecommendationCacheRecord | null,
): MentorMatch[] | null { ): SimilarPlayer[] | null {
const matches = recommendation?.result?.matches; const matches = recommendation?.result?.matches;
if (!Array.isArray(matches)) return null; if (!Array.isArray(matches)) return null;
if (!matches.every((match) => this.isCachedMentorMatch(match))) { if (!matches.every((match) => this.isCachedSimilarPlayer(match))) {
return null; return null;
} }
return matches; return matches;
} }
private isCachedMentorMatch(value: unknown): value is MentorMatch { private isCachedSimilarPlayer(value: unknown): value is SimilarPlayer {
const record = this.asRecord(value); const record = this.asRecord(value);
if (!record) return false; if (!record) return false;
@@ -406,6 +441,8 @@ export class MentorMatchService {
typeof record.puuid === 'string' && typeof record.puuid === 'string' &&
this.isFiniteNumber(record.similarityScore) && this.isFiniteNumber(record.similarityScore) &&
this.isFiniteNumber(record.finalScore) && this.isFiniteNumber(record.finalScore) &&
typeof record.tierComparison === 'string' &&
TIER_COMPARISONS.includes(record.tierComparison as TierComparison) &&
typeof record.mainRole === 'string' && typeof record.mainRole === 'string' &&
ROLES.includes(record.mainRole as Role) && ROLES.includes(record.mainRole as Role) &&
Array.isArray(record.mainChampions) && Array.isArray(record.mainChampions) &&
@@ -414,13 +451,14 @@ export class MentorMatchService {
record.similarMetrics, record.similarMetrics,
'absoluteGap', 'absoluteGap',
) && ) &&
this.isCachedMetricComparisonArray(record.gapMetrics, 'mentorAdvantage') this.isCachedMetricComparisonArray(record.strongerMetrics, 'lead') &&
this.isCachedMetricComparisonArray(record.weakerMetrics, 'lead')
); );
} }
private isCachedMetricComparisonArray( private isCachedMetricComparisonArray(
value: unknown, value: unknown,
scoreFieldName: 'absoluteGap' | 'mentorAdvantage', scoreFieldName: 'absoluteGap' | 'lead',
): boolean { ): boolean {
return ( return (
Array.isArray(value) && Array.isArray(value) &&
@@ -430,7 +468,7 @@ export class MentorMatchService {
record !== null && record !== null &&
typeof record.metricId === 'string' && typeof record.metricId === 'string' &&
this.isFiniteNumber(record.currentValue) && this.isFiniteNumber(record.currentValue) &&
this.isFiniteNumber(record.mentorValue) && this.isFiniteNumber(record.otherValue) &&
this.isFiniteNumber(record[scoreFieldName]) this.isFiniteNumber(record[scoreFieldName])
); );
}) })
@@ -107,7 +107,7 @@ export const PlayerProfileSchema = new Schema<PlayerProfile>(
); );
PlayerProfileSchema.index({ puuid: 1, queueId: 1 }, { unique: true }); PlayerProfileSchema.index({ puuid: 1, queueId: 1 }, { unique: true });
// 운영 조회용 (멘토 검색 자체는 Atlas Vector Search 인덱스 사용) // 운영 조회용 (유사 유저 검색 자체는 Atlas Vector Search 인덱스 사용)
PlayerProfileSchema.index({ isSeed: 1, mainRole: 1, tier: 1 }); PlayerProfileSchema.index({ isSeed: 1, mainRole: 1, tier: 1 });
export type PlayerProfileDocument = HydratedDocument<PlayerProfile>; export type PlayerProfileDocument = HydratedDocument<PlayerProfile>;
@@ -2,14 +2,14 @@ import { HydratedDocument, Schema } from 'mongoose';
import { MongooseTimestamps } from './common'; import { MongooseTimestamps } from './common';
/** /**
* - mentor-match: 유사 고티어 유저 Top-K (MVP 3) * - similar-player: 플레이스타일이 비슷한 유저 Top-K (MVP 3)
* - champion-recommendation: Fit/Growth/Stretch 챔피언 추천 (MVP 4) * - champion-recommendation: Fit/Growth/Stretch 챔피언 추천 (MVP 4)
* - llm-feedback: LLM 생성 피드백 (MVP 5) * - llm-feedback: LLM 생성 피드백 (MVP 5)
*/ */
export type RecommendationType = export type RecommendationType =
'mentor-match' | 'champion-recommendation' | 'llm-feedback'; 'similar-player' | 'champion-recommendation' | 'llm-feedback';
export const RECOMMENDATION_TYPES: RecommendationType[] = [ export const RECOMMENDATION_TYPES: RecommendationType[] = [
'mentor-match', 'similar-player',
'champion-recommendation', 'champion-recommendation',
'llm-feedback', 'llm-feedback',
]; ];
+43 -25
View File
@@ -3,8 +3,8 @@ import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common'; import { INestApplication } from '@nestjs/common';
import { import {
FEATURE_SCHEMA_VERSION, FEATURE_SCHEMA_VERSION,
type MentorMatchesDto,
type PlayerAnalysisDto, type PlayerAnalysisDto,
type SimilarPlayersDto,
} from '@persona-lenz/shared'; } from '@persona-lenz/shared';
import request from 'supertest'; import request from 'supertest';
import { App } from 'supertest/types'; import { App } from 'supertest/types';
@@ -15,7 +15,7 @@ import {
ANALYSIS_QUEUE_NAME, ANALYSIS_QUEUE_NAME,
SEED_COLLECTION_QUEUE_NAME, SEED_COLLECTION_QUEUE_NAME,
} from './../src/modules/analysis/analysis.constants'; } from './../src/modules/analysis/analysis.constants';
import { MentorMatchService } from './../src/modules/analysis/mentor-match.service'; import { SimilarPlayerService } from './../src/modules/analysis/similar-player.service';
import { ConnectionService } from './../src/modules/global/database/connection.service'; import { ConnectionService } from './../src/modules/global/database/connection.service';
import { REDIS_CLIENT } from './../src/modules/global/redis/redis.constants'; import { REDIS_CLIENT } from './../src/modules/global/redis/redis.constants';
import { SecretService } from './../src/modules/global/secret/secret.service'; import { SecretService } from './../src/modules/global/secret/secret.service';
@@ -25,8 +25,8 @@ describe('AppController (e2e)', () => {
let analysisQueueService: { let analysisQueueService: {
enqueueUserAnalysis: jest.Mock; enqueueUserAnalysis: jest.Mock;
}; };
let mentorMatchService: { let similarPlayerService: {
findMentorMatches: jest.Mock; findSimilarPlayers: jest.Mock;
}; };
let connectionService: { let connectionService: {
getModel: jest.Mock; getModel: jest.Mock;
@@ -44,8 +44,8 @@ describe('AppController (e2e)', () => {
analysisQueueService = { analysisQueueService = {
enqueueUserAnalysis: jest.fn(), enqueueUserAnalysis: jest.fn(),
}; };
mentorMatchService = { similarPlayerService = {
findMentorMatches: jest.fn(), findSimilarPlayers: jest.fn(),
}; };
connectionService = { connectionService = {
getModel: jest.fn(), getModel: jest.fn(),
@@ -57,8 +57,8 @@ describe('AppController (e2e)', () => {
.useValue(connectionService) .useValue(connectionService)
.overrideProvider(AnalysisQueueService) .overrideProvider(AnalysisQueueService)
.useValue(analysisQueueService) .useValue(analysisQueueService)
.overrideProvider(MentorMatchService) .overrideProvider(SimilarPlayerService)
.useValue(mentorMatchService) .useValue(similarPlayerService)
.overrideProvider(SecretService) .overrideProvider(SecretService)
.useValue({ .useValue({
get: jest.fn((key: string) => { get: jest.fn((key: string) => {
@@ -446,18 +446,19 @@ describe('AppController (e2e)', () => {
}); });
}); });
it('/api/players/:puuid/mentor-matches (GET) returns mentor matches with display Riot IDs', async () => { it('/api/players/:puuid/similar-players (GET) returns similar players with display Riot IDs', async () => {
mentorMatchService.findMentorMatches.mockResolvedValue({ similarPlayerService.findSimilarPlayers.mockResolvedValue({
puuid: 'target-puuid', puuid: 'target-puuid',
queueId: 420, queueId: 420,
profileUpdatedAt: new Date('2026-07-02T00:00:00.000Z'), profileUpdatedAt: new Date('2026-07-02T00:00:00.000Z'),
matches: [ matches: [
{ {
puuid: 'mentor-puuid', puuid: 'similar-player-puuid',
similarityScore: 0.87, similarityScore: 0.87,
finalScore: 0.81, finalScore: 0.81,
tier: 'CHALLENGER', tier: 'CHALLENGER',
leaguePoints: 900, leaguePoints: 900,
tierComparison: 'higher',
mainRole: 'MIDDLE', mainRole: 'MIDDLE',
mainChampions: [{ championId: 103, games: 20, wins: 14 }], mainChampions: [{ championId: 103, games: 20, wins: 14 }],
sampleGameCount: 40, sampleGameCount: 40,
@@ -465,16 +466,24 @@ describe('AppController (e2e)', () => {
{ {
metricId: 'kda', metricId: 'kda',
currentValue: 0.3, currentValue: 0.3,
mentorValue: 0.31, otherValue: 0.31,
absoluteGap: 0.01, absoluteGap: 0.01,
}, },
], ],
gapMetrics: [ strongerMetrics: [
{ {
metricId: 'goldPerMin', metricId: 'goldPerMin',
currentValue: 0.5, currentValue: 0.5,
mentorValue: 0.8, otherValue: 0.8,
mentorAdvantage: 0.3, lead: 0.3,
},
],
weakerMetrics: [
{
metricId: 'visionScorePerMin',
currentValue: 0.6,
otherValue: 0.4,
lead: 0.2,
}, },
], ],
}, },
@@ -483,7 +492,7 @@ describe('AppController (e2e)', () => {
const accountFind = jest.fn(() => const accountFind = jest.fn(() =>
createLeanExec([ createLeanExec([
{ {
puuid: 'mentor-puuid', puuid: 'similar-player-puuid',
gameName: '프리리', gameName: '프리리',
tagLine: 'KR1', tagLine: 'KR1',
}, },
@@ -494,17 +503,17 @@ describe('AppController (e2e)', () => {
}); });
const response = await request(app.getHttpServer()) const response = await request(app.getHttpServer())
.get('/api/players/target-puuid/mentor-matches?limit=3') .get('/api/players/target-puuid/similar-players?limit=3')
.expect(200); .expect(200);
const responseBody = response.body as MentorMatchesDto; const responseBody = response.body as SimilarPlayersDto;
expect(mentorMatchService.findMentorMatches).toHaveBeenCalledWith( expect(similarPlayerService.findSimilarPlayers).toHaveBeenCalledWith(
'target-puuid', 'target-puuid',
420, 420,
3, 3,
); );
expect(accountFind).toHaveBeenCalledWith({ expect(accountFind).toHaveBeenCalledWith({
puuid: { $in: ['mentor-puuid'] }, puuid: { $in: ['similar-player-puuid'] },
}); });
expect(responseBody).toEqual({ expect(responseBody).toEqual({
puuid: 'target-puuid', puuid: 'target-puuid',
@@ -512,7 +521,7 @@ describe('AppController (e2e)', () => {
profileUpdatedAt: '2026-07-02T00:00:00.000Z', profileUpdatedAt: '2026-07-02T00:00:00.000Z',
matches: [ matches: [
{ {
mentorDisplayId: 'mentor-1', displayId: 'similar-1',
riotId: { riotId: {
gameName: '프리리', gameName: '프리리',
tagLine: 'KR1', tagLine: 'KR1',
@@ -521,6 +530,7 @@ describe('AppController (e2e)', () => {
finalScore: 0.81, finalScore: 0.81,
tier: 'CHALLENGER', tier: 'CHALLENGER',
leaguePoints: 900, leaguePoints: 900,
tierComparison: 'higher',
mainRole: 'MIDDLE', mainRole: 'MIDDLE',
mainChampions: [{ championId: 103, games: 20, wins: 14 }], mainChampions: [{ championId: 103, games: 20, wins: 14 }],
sampleGameCount: 40, sampleGameCount: 40,
@@ -528,16 +538,24 @@ describe('AppController (e2e)', () => {
{ {
metricId: 'kda', metricId: 'kda',
currentValue: 0.3, currentValue: 0.3,
mentorValue: 0.31, otherValue: 0.31,
absoluteGap: 0.01, absoluteGap: 0.01,
}, },
], ],
gapMetrics: [ strongerMetrics: [
{ {
metricId: 'goldPerMin', metricId: 'goldPerMin',
currentValue: 0.5, currentValue: 0.5,
mentorValue: 0.8, otherValue: 0.8,
mentorAdvantage: 0.3, lead: 0.3,
},
],
weakerMetrics: [
{
metricId: 'visionScorePerMin',
currentValue: 0.6,
otherValue: 0.4,
lead: 0.2,
}, },
], ],
}, },
+41 -30
View File
@@ -107,7 +107,7 @@
.chart-section, .chart-section,
.champion-section, .champion-section,
.insight-section, .insight-section,
.mentor-section, .similar-section,
.dashboard-summary { .dashboard-summary {
border: 1px solid var(--border); border: 1px solid var(--border);
border-radius: 8px; border-radius: 8px;
@@ -344,7 +344,7 @@
.chart-section, .chart-section,
.champion-section, .champion-section,
.insight-section, .insight-section,
.mentor-section { .similar-section {
padding: 24px; padding: 24px;
} }
@@ -466,28 +466,28 @@
line-height: 1.55; line-height: 1.55;
} }
.mentor-message { .similar-message {
margin-top: 16px; margin-top: 16px;
} }
.mentor-table-wrap { .similar-table-wrap {
margin-top: 18px; margin-top: 18px;
overflow-x: auto; overflow-x: auto;
} }
.mentor-table-wrap:focus-visible { .similar-table-wrap:focus-visible {
outline: 3px solid color-mix(in srgb, var(--accent) 42%, transparent); outline: 3px solid color-mix(in srgb, var(--accent) 42%, transparent);
outline-offset: 3px; outline-offset: 3px;
} }
.mentor-table { .similar-table {
width: 100%; width: 100%;
min-width: 780px; min-width: 780px;
border-collapse: separate; border-collapse: separate;
border-spacing: 0 10px; border-spacing: 0 10px;
} }
.mentor-table th { .similar-table th {
padding: 0 12px; padding: 0 12px;
color: var(--text-subtle); color: var(--text-subtle);
font-size: 12px; font-size: 12px;
@@ -497,7 +497,7 @@
text-transform: uppercase; text-transform: uppercase;
} }
.mentor-table td { .similar-table td {
min-width: 0; min-width: 0;
padding: 14px 12px; padding: 14px 12px;
border-block: 1px solid var(--border); border-block: 1px solid var(--border);
@@ -505,51 +505,51 @@
vertical-align: top; vertical-align: top;
} }
.mentor-table td:first-child { .similar-table td:first-child {
border-left: 1px solid var(--border); border-left: 1px solid var(--border);
border-radius: 8px 0 0 8px; border-radius: 8px 0 0 8px;
} }
.mentor-table td:last-child { .similar-table td:last-child {
border-right: 1px solid var(--border); border-right: 1px solid var(--border);
border-radius: 0 8px 8px 0; border-radius: 0 8px 8px 0;
} }
.mentor-player, .similar-player,
.mentor-score, .similar-score,
.mentor-metric-groups, .similar-metric-groups,
.mentor-metric-group { .similar-metric-group {
min-width: 0; min-width: 0;
display: grid; display: grid;
gap: 6px; gap: 6px;
} }
.mentor-player strong, .similar-player strong,
.mentor-score strong, .similar-score strong,
.mentor-chip strong { .similar-chip strong {
overflow: hidden; overflow: hidden;
color: var(--text-strong); color: var(--text-strong);
text-overflow: ellipsis; text-overflow: ellipsis;
white-space: nowrap; white-space: nowrap;
} }
.mentor-player span, .similar-player span,
.mentor-score span, .similar-score span,
.mentor-chip span, .similar-chip span,
.mentor-metric-group > span, .similar-metric-group > span,
.mentor-empty { .similar-empty {
color: var(--text-subtle); color: var(--text-subtle);
font-size: 12px; font-size: 12px;
font-weight: 700; font-weight: 700;
line-height: 1.35; line-height: 1.35;
} }
.mentor-score strong { .similar-score strong {
font-size: 22px; font-size: 22px;
line-height: 1; line-height: 1;
} }
.mentor-chip-list { .similar-chip-list {
display: flex; display: flex;
flex-wrap: wrap; flex-wrap: wrap;
gap: 6px; gap: 6px;
@@ -558,7 +558,7 @@
list-style: none; list-style: none;
} }
.mentor-chip { .similar-chip {
max-width: 100%; max-width: 100%;
display: inline-flex; display: inline-flex;
align-items: center; align-items: center;
@@ -569,23 +569,34 @@
padding: 5px 8px; padding: 5px 8px;
} }
.mentor-chip strong { .similar-chip strong {
min-width: 0; min-width: 0;
} }
.mentor-chip span { .similar-chip span {
flex: 0 0 auto; flex: 0 0 auto;
white-space: nowrap; white-space: nowrap;
} }
.mentor-chip-accent { .similar-chip-accent {
border-color: color-mix(in srgb, var(--accent) 48%, var(--border)); border-color: color-mix(in srgb, var(--accent) 48%, var(--border));
} }
.mentor-chip-muted { .similar-chip-muted {
background: color-mix(in srgb, var(--surface) 74%, var(--surface-soft)); background: color-mix(in srgb, var(--surface) 74%, var(--surface-soft));
} }
.similar-tier-badge {
justify-self: start;
border: 1px solid color-mix(in srgb, var(--accent) 48%, var(--border));
border-radius: 999px;
padding: 3px 8px;
color: var(--text-strong);
font-size: 11px;
font-weight: 700;
line-height: 1.2;
}
.empty-view { .empty-view {
min-height: calc(100svh - 240px); min-height: calc(100svh - 240px);
display: grid; display: grid;
@@ -685,7 +696,7 @@
.chart-section, .chart-section,
.champion-section, .champion-section,
.insight-section, .insight-section,
.mentor-section, .similar-section,
.dashboard-summary { .dashboard-summary {
padding: 18px; padding: 18px;
} }
+5 -5
View File
@@ -2,8 +2,8 @@ import type {
AnalysisJobStatusDto, AnalysisJobStatusDto,
AnalysisRequestAcceptedDto, AnalysisRequestAcceptedDto,
AnalysisRequestDto, AnalysisRequestDto,
MentorMatchesDto,
PlayerAnalysisDto, PlayerAnalysisDto,
SimilarPlayersDto,
} from '@persona-lenz/shared'; } from '@persona-lenz/shared';
export class ApiClientError extends Error { export class ApiClientError extends Error {
@@ -99,12 +99,12 @@ export async function getLatestPlayerAnalysis(
); );
} }
export async function getMentorMatches( export async function getSimilarPlayers(
puuid: string, puuid: string,
limit = 10, limit = 10,
): Promise<MentorMatchesDto> { ): Promise<SimilarPlayersDto> {
const params = new URLSearchParams({ limit: String(limit) }); const params = new URLSearchParams({ limit: String(limit) });
return fetchJson<MentorMatchesDto>( return fetchJson<SimilarPlayersDto>(
`/api/players/${encodeURIComponent(puuid)}/mentor-matches?${params}`, `/api/players/${encodeURIComponent(puuid)}/similar-players?${params}`,
); );
} }
+112 -73
View File
@@ -3,13 +3,14 @@ import { Link, useParams } from 'react-router-dom';
import { import {
METRICS, METRICS,
type ChampionPoolEntryDto, type ChampionPoolEntryDto,
type GapMentorMetricDto, type LeadMetricDto,
type MentorMatchDto,
type MentorMatchesDto,
type MetricId, type MetricId,
type MetricValueDto, type MetricValueDto,
type PlayerAnalysisDto, type PlayerAnalysisDto,
type SimilarMentorMetricDto, type SimilarMetricDto,
type SimilarPlayerDto,
type SimilarPlayersDto,
type TierComparison,
type TierInfoDto, type TierInfoDto,
} from '@persona-lenz/shared'; } from '@persona-lenz/shared';
import { import {
@@ -23,8 +24,8 @@ import {
} from 'recharts'; } from 'recharts';
import { import {
getLatestPlayerAnalysis, getLatestPlayerAnalysis,
getMentorMatches,
getReadableErrorMessage, getReadableErrorMessage,
getSimilarPlayers,
} from '../api/analysis'; } from '../api/analysis';
import { import {
loadChampionCatalog, loadChampionCatalog,
@@ -45,19 +46,18 @@ interface RadarMetricDatum {
value: number; value: number;
} }
const MENTOR_MATCH_LIMIT = 10; const SIMILAR_PLAYER_LIMIT = 10;
export function DashboardPage() { export function DashboardPage() {
const { puuid } = useParams<{ puuid: string }>(); const { puuid } = useParams<{ puuid: string }>();
const [analysis, setAnalysis] = useState<PlayerAnalysisDto | null>(null); const [analysis, setAnalysis] = useState<PlayerAnalysisDto | null>(null);
const [championCatalog, setChampionCatalog] = const [championCatalog, setChampionCatalog] =
useState<ChampionCatalog | null>(null); useState<ChampionCatalog | null>(null);
const [mentorMatches, setMentorMatches] = const [similarPlayers, setSimilarPlayers] =
useState<MentorMatchesDto | null>(null); useState<SimilarPlayersDto | null>(null);
const [errorMessage, setErrorMessage] = useState<string | null>(null); const [errorMessage, setErrorMessage] = useState<string | null>(null);
const [mentorErrorMessage, setMentorErrorMessage] = useState<string | null>( const [similarPlayersErrorMessage, setSimilarPlayersErrorMessage] =
null, useState<string | null>(null);
);
const [isLoading, setIsLoading] = useState(true); const [isLoading, setIsLoading] = useState(true);
const missingPuuidMessage = puuid ? null : '플레이어 식별자가 없습니다.'; const missingPuuidMessage = puuid ? null : '플레이어 식별자가 없습니다.';
@@ -73,12 +73,12 @@ export function DashboardPage() {
setIsLoading(true); setIsLoading(true);
setAnalysis(null); setAnalysis(null);
setErrorMessage(null); setErrorMessage(null);
setMentorErrorMessage(null); setSimilarPlayersErrorMessage(null);
setMentorMatches(null); setSimilarPlayers(null);
const mentorMatchesResultPromise = getMentorMatches( const similarPlayersResultPromise = getSimilarPlayers(
currentPuuid, currentPuuid,
MENTOR_MATCH_LIMIT, SIMILAR_PLAYER_LIMIT,
).then( ).then(
(value) => ({ status: 'fulfilled', value }) as const, (value) => ({ status: 'fulfilled', value }) as const,
(reason: unknown) => ({ status: 'rejected', reason }) as const, (reason: unknown) => ({ status: 'rejected', reason }) as const,
@@ -105,17 +105,17 @@ export function DashboardPage() {
setIsLoading(false); setIsLoading(false);
} }
const mentorMatchesResult = await mentorMatchesResultPromise; const similarPlayersResult = await similarPlayersResultPromise;
if (!isActive) { if (!isActive) {
return; return;
} }
if (mentorMatchesResult.status === 'fulfilled') { if (similarPlayersResult.status === 'fulfilled') {
setMentorMatches(mentorMatchesResult.value); setSimilarPlayers(similarPlayersResult.value);
} else { } else {
setMentorErrorMessage( setSimilarPlayersErrorMessage(
getReadableErrorMessage(mentorMatchesResult.reason), getReadableErrorMessage(similarPlayersResult.reason),
); );
} }
} }
@@ -289,10 +289,10 @@ export function DashboardPage() {
)} )}
</section> </section>
<MentorMatchSection <SimilarPlayerSection
catalog={championCatalog} catalog={championCatalog}
errorMessage={mentorErrorMessage} errorMessage={similarPlayersErrorMessage}
mentorMatches={mentorMatches} similarPlayers={similarPlayers}
/> />
</article> </article>
); );
@@ -380,87 +380,104 @@ function ChampionPoolRow({
); );
} }
function MentorMatchSection({ function SimilarPlayerSection({
catalog, catalog,
errorMessage, errorMessage,
mentorMatches, similarPlayers,
}: { }: {
catalog: ChampionCatalog | null; catalog: ChampionCatalog | null;
errorMessage: string | null; errorMessage: string | null;
mentorMatches: MentorMatchesDto | null; similarPlayers: SimilarPlayersDto | null;
}) { }) {
const matches = mentorMatches?.matches ?? []; const matches = similarPlayers?.matches ?? [];
return ( return (
<section className="mentor-section" aria-labelledby="mentor-title"> <section className="similar-section" aria-labelledby="similar-title">
<div className="section-heading"> <div className="section-heading">
<div> <div>
<h2 id="mentor-title">유사 상위 티어 비교</h2> <h2 id="similar-title">나와 비슷한 플레이어</h2>
<p className="section-copy"> <p className="section-copy">
당신과 비슷한 상위 티어 그룹은 이런 경향을 보입니다. 플레이스타일 벡터가 가장 가까운 유저들입니다. 티어가 다르다면 어떤
지표에서 차이가 나는지 확인해보세요.
</p> </p>
</div> </div>
<span className="status-pill"> <span className="status-pill">
{mentorMatches ? `${matches.length} matches` : 'mentor match'} {similarPlayers ? `${matches.length} players` : 'similar players'}
</span> </span>
</div> </div>
{errorMessage ? ( {errorMessage ? (
<p className="message message-warning mentor-message" role="status"> <p className="message message-warning similar-message" role="status">
멘토 비교를 불러오지 못했습니다. {errorMessage} 비슷한 플레이어 목록을 불러오지 못했습니다. {errorMessage}
</p> </p>
) : null} ) : null}
{!errorMessage && mentorMatches && matches.length === 0 ? ( {!errorMessage && similarPlayers && matches.length === 0 ? (
<p className="empty-copy"> <p className="empty-copy">
조건에 맞는 상위 티어 seed 프로필이 아직 없습니다. 비교 가능한 프로필이 아직 충분히 수집되지 않았습니다.
</p> </p>
) : null} ) : null}
{!errorMessage && !mentorMatches ? ( {!errorMessage && !similarPlayers ? (
<p className="empty-copy">멘토 비교 결과를 준비 중입니다.</p> <p className="empty-copy">비슷한 플레이어를 찾는 중입니다.</p>
) : null} ) : null}
{matches.length > 0 ? ( {matches.length > 0 ? (
<div <div
aria-label="유사 상위 티어 비교 테이블" aria-label="나와 비슷한 플레이어 테이블"
className="mentor-table-wrap" className="similar-table-wrap"
role="region" role="region"
tabIndex={0} tabIndex={0}
> >
<table className="mentor-table"> <table className="similar-table">
<thead> <thead>
<tr> <tr>
<th scope="col">플레이어</th> <th scope="col">플레이어</th>
<th scope="col">점수</th> <th scope="col">유사도</th>
<th scope="col">주요 챔피언</th> <th scope="col">주요 챔피언</th>
<th scope="col">비교 지표</th> <th scope="col">비교 지표</th>
</tr> </tr>
</thead> </thead>
<tbody> <tbody>
{matches.map((match) => ( {matches.map((match) => (
<tr key={match.mentorDisplayId}> <tr key={match.displayId}>
<td> <td>
<div className="mentor-player"> <div className="similar-player">
<strong>{formatMentorName(match)}</strong> <strong>{formatSimilarPlayerName(match)}</strong>
<span> <span>
{formatMentorTier(match)} · {ROLE_LABELS[match.mainRole]} ·{' '} {formatSimilarPlayerTier(match)} ·{' '}
{ROLE_LABELS[match.mainRole]} ·{' '}
{match.sampleGameCount}게임 {match.sampleGameCount}게임
</span> </span>
{formatTierComparison(match.tierComparison) ? (
<span className="similar-tier-badge">
{formatTierComparison(match.tierComparison)}
</span>
) : null}
</div> </div>
</td> </td>
<td> <td>
<div className="mentor-score"> <div className="similar-score">
<strong>{formatPercent(match.finalScore)}</strong> <strong>{formatPercent(match.similarityScore)}</strong>
<span>스타일 {formatPercent(match.similarityScore)}</span> <span>종합 {formatPercent(match.finalScore)}</span>
</div> </div>
</td> </td>
<td> <td>
<MentorChampionList catalog={catalog} match={match} /> <SimilarPlayerChampionList catalog={catalog} match={match} />
</td> </td>
<td> <td>
<div className="mentor-metric-groups"> <div className="similar-metric-groups">
<GapMetricChips values={match.gapMetrics} /> <LeadMetricChips
accent
emptyLabel="이 유저가 앞서는 지표 없음"
title="이 유저가 앞서는 지표"
values={match.strongerMetrics}
/>
<LeadMetricChips
emptyLabel={null}
title="내가 앞서는 지표"
values={match.weakerMetrics}
/>
<SimilarMetricChips values={match.similarMetrics} /> <SimilarMetricChips values={match.similarMetrics} />
</div> </div>
</td> </td>
@@ -474,21 +491,21 @@ function MentorMatchSection({
); );
} }
function MentorChampionList({ function SimilarPlayerChampionList({
catalog, catalog,
match, match,
}: { }: {
catalog: ChampionCatalog | null; catalog: ChampionCatalog | null;
match: MentorMatchDto; match: SimilarPlayerDto;
}) { }) {
if (match.mainChampions.length === 0) { if (match.mainChampions.length === 0) {
return <span className="mentor-empty">챔피언 기록 없음</span>; return <span className="similar-empty">챔피언 기록 없음</span>;
} }
return ( return (
<ul className="mentor-chip-list"> <ul className="similar-chip-list">
{match.mainChampions.map((entry) => ( {match.mainChampions.map((entry) => (
<li className="mentor-chip" key={entry.championId}> <li className="similar-chip" key={entry.championId}>
<strong>{formatChampionName(catalog, entry.championId)}</strong> <strong>{formatChampionName(catalog, entry.championId)}</strong>
<span>{entry.games}게임</span> <span>{entry.games}게임</span>
</li> </li>
@@ -497,19 +514,34 @@ function MentorChampionList({
); );
} }
function GapMetricChips({ values }: { values: GapMentorMetricDto[] }) { function LeadMetricChips({
accent = false,
emptyLabel,
title,
values,
}: {
accent?: boolean;
emptyLabel: string | null;
title: string;
values: LeadMetricDto[];
}) {
if (values.length === 0) { if (values.length === 0) {
return <span className="mentor-empty">뚜렷한 우위 지표 없음</span>; return emptyLabel ? (
<span className="similar-empty">{emptyLabel}</span>
) : null;
} }
return ( return (
<div className="mentor-metric-group"> <div className="similar-metric-group">
<span>앞서는 지표</span> <span>{title}</span>
<ul className="mentor-chip-list"> <ul className="similar-chip-list">
{values.map((value) => ( {values.map((value) => (
<li className="mentor-chip mentor-chip-accent" key={value.metricId}> <li
className={`similar-chip ${accent ? 'similar-chip-accent' : ''}`}
key={value.metricId}
>
<strong>{getMetricLabel(value.metricId)}</strong> <strong>{getMetricLabel(value.metricId)}</strong>
<span>+{formatPercent(value.mentorAdvantage)}</span> <span>+{formatPercent(value.lead)}</span>
</li> </li>
))} ))}
</ul> </ul>
@@ -517,17 +549,17 @@ function GapMetricChips({ values }: { values: GapMentorMetricDto[] }) {
); );
} }
function SimilarMetricChips({ values }: { values: SimilarMentorMetricDto[] }) { function SimilarMetricChips({ values }: { values: SimilarMetricDto[] }) {
if (values.length === 0) { if (values.length === 0) {
return null; return null;
} }
return ( return (
<div className="mentor-metric-group"> <div className="similar-metric-group">
<span>비슷한 지표</span> <span>비슷한 지표</span>
<ul className="mentor-chip-list"> <ul className="similar-chip-list">
{values.map((value) => ( {values.map((value) => (
<li className="mentor-chip mentor-chip-muted" key={value.metricId}> <li className="similar-chip similar-chip-muted" key={value.metricId}>
<strong>{getMetricLabel(value.metricId)}</strong> <strong>{getMetricLabel(value.metricId)}</strong>
<span>차이 {formatPercent(value.absoluteGap)}</span> <span>차이 {formatPercent(value.absoluteGap)}</span>
</li> </li>
@@ -537,21 +569,28 @@ function SimilarMetricChips({ values }: { values: SimilarMentorMetricDto[] }) {
); );
} }
function formatMentorName(match: MentorMatchDto): string { function formatSimilarPlayerName(match: SimilarPlayerDto): string {
if (match.riotId) { if (match.riotId) {
return `${match.riotId.gameName}#${match.riotId.tagLine}`; return `${match.riotId.gameName}#${match.riotId.tagLine}`;
} }
return formatMentorDisplayId(match.mentorDisplayId); return formatSimilarPlayerDisplayId(match.displayId);
} }
function formatMentorDisplayId(mentorDisplayId: string): string { function formatSimilarPlayerDisplayId(displayId: string): string {
const numericSuffix = mentorDisplayId.match(/^mentor-(\d+)$/)?.[1]; const numericSuffix = displayId.match(/^similar-(\d+)$/)?.[1];
return numericSuffix ? `상위 티어 멘토 #${numericSuffix}` : '상위 티어 멘토'; return numericSuffix ? `비슷한 플레이어 #${numericSuffix}` : '비슷한 플레이어';
} }
function formatMentorTier(match: MentorMatchDto): string { function formatTierComparison(tierComparison: TierComparison): string | null {
if (tierComparison === 'higher') return '나보다 높은 티어';
if (tierComparison === 'lower') return '나보다 낮은 티어';
if (tierComparison === 'same') return '같은 티어';
return null;
}
function formatSimilarPlayerTier(match: SimilarPlayerDto): string {
const tier = [match.tier, match.division].filter(Boolean).join(' '); const tier = [match.tier, match.division].filter(Boolean).join(' ');
if (!tier) { if (!tier) {
+25 -21
View File
@@ -319,7 +319,7 @@ interface MetricBaseline extends MongooseTimestamps {
```ts ```ts
type RecommendationType = type RecommendationType =
| "mentor-match" // MVP 3 | "similar-player" // MVP 3
| "champion-recommendation" // MVP 4 | "champion-recommendation" // MVP 4
| "llm-feedback"; // MVP 5 | "llm-feedback"; // MVP 5
@@ -675,8 +675,8 @@ DB 스키마가 이 단계를 미리 견디도록 상세화한 스펙이다. 구
지표를 전부 유사도 벡터에 넣으면 희귀 이벤트 기반의 노이즈 축이 코사인 유사도를 오염시킨다. 두 계층으로 나눈다: 지표를 전부 유사도 벡터에 넣으면 희귀 이벤트 기반의 노이즈 축이 코사인 유사도를 오염시킨다. 두 계층으로 나눈다:
- **vector 지표** (`includeInVector: true`): 게임마다 안정적으로 관측되는 핵심 스타일 축. 벡터·레이더 차트·멘토 매칭에 사용 - **vector 지표** (`includeInVector: true`): 게임마다 안정적으로 관측되는 핵심 스타일 축. 벡터·레이더 차트·유사 유저 탐색에 사용
- **insight 지표** (`includeInVector: false`): 희귀 이벤트 기반 비율. 강점/약점 분석, 멘토와의 gap 비교, LLM evidence에 사용. 벡터에는 미포함 - **insight 지표** (`includeInVector: false`): 희귀 이벤트 기반 비율. 강점/약점 분석, 유사 유저와의 gap 비교, LLM evidence에 사용. 벡터에는 미포함
**ratio 지표 저장 규칙**: 게임당 발생 횟수가 적은 비율 지표는 매치 단위 rate가 0/1로 튄다. 매치의 `features`에는 `{metricId}Numerator` / `{metricId}Denominator`로 **횟수만** 저장하고, rate는 profile builder가 `Σ분자/Σ분모`로 계산해 `profile`에 저장한다. registry의 `kind: 'scalar' | 'ratio'`가 이를 결정한다 (§5.1). **ratio 지표 저장 규칙**: 게임당 발생 횟수가 적은 비율 지표는 매치 단위 rate가 0/1로 튄다. 매치의 `features`에는 `{metricId}Numerator` / `{metricId}Denominator`로 **횟수만** 저장하고, rate는 profile builder가 `Σ분자/Σ분모`로 계산해 `profile`에 저장한다. registry의 `kind: 'scalar' | 'ratio'`가 이를 결정한다 (§5.1).
@@ -759,7 +759,9 @@ DB 스키마가 이 단계를 미리 견디도록 상세화한 스펙이다. 구
--- ---
## 12. MVP 3 상세 — 고티어 pool · percentile 정규화 · 멘토 매칭 ## 12. MVP 3 상세 — 고티어 pool · percentile 정규화 · 유사 유저 탐색
> **컨셉 (2026-07-03 재정의)**: 이 기능은 "멘토 매칭"이 아니라 **나와 플레이스타일이 비슷한 유저 찾기**다. 목적은 따라 할 상위 티어 유저를 지정해주는 것이 아니라, "스타일은 비슷한데 왜 저 유저는 점수(티어)가 더 높거나/낮은가"라는 인사이트를 주는 것. 따라서 후보를 티어로 거르지 않고 유사도 중심으로 랭킹하며, 티어 관계(tierComparison)와 지표 우위(양방향)를 함께 제공한다. seed pool(§12.1)은 필터 조건이 아니라 **비교 후보군의 주 공급원**이다.
### 12.1 고티어 seed pool 수집 ### 12.1 고티어 seed pool 수집
@@ -800,35 +802,37 @@ DB 스키마가 이 단계를 미리 견디도록 상세화한 스펙이다. 구
filter로 쓰는 필드(tier, isSeed 등)가 `player_profile`에 **비정규화되어 있어야** `$vectorSearch` 단계에서 join 없이 거를 수 있다 — §4.4 스키마가 이를 전제한다. filter로 쓰는 필드(tier, isSeed 등)가 `player_profile`에 **비정규화되어 있어야** `$vectorSearch` 단계에서 join 없이 거를 수 있다 — §4.4 스키마가 이를 전제한다.
### 12.4 멘토 매칭 파이프라인 ### 12.4 유사 유저 탐색 파이프라인
```text ```text
1. 내 player_profile 조회 (없으면 404) 1. 내 player_profile 조회 (없으면 404)
2. $vectorSearch: 2. $vectorSearch:
queryVector = 내 vector, numCandidates = 200, limit = 50 queryVector = 내 vector, numCandidates = 200, limit = 50
filter: { mainRole: eq 내 mainRole, queueId: eq 420, filter: { mainRole: eq 내 mainRole, queueId: eq 420,
tier: in [MASTER, GRANDMASTER, CHALLENGER], isSeed: eq true,
sampleGameCount: gte 20, featureSchemaVersion: eq 현재 버전 } sampleGameCount: gte 20, featureSchemaVersion: eq 현재 버전 }
※ tier/isSeed 필터 없음 — "비슷한 유저"가 목적이므로 어느 티어든 후보.
(인덱스의 tier/isSeed filter 필드는 유지 — 추후 옵션 필터용)
3. 앱 레벨 re-rank (Top 50 → Top K): 3. 앱 레벨 re-rank (Top 50 → Top K):
final = 0.60 * styleSim # $vectorSearch score (cosine) final = 0.70 * styleSim # $vectorSearch score (cosine) — 유사도가 랭킹을 지배
+ 0.20 * championPoolSim # 양쪽 championPool 상위 5개 Jaccard + 0.18 * championPoolSim # 양쪽 championPool 상위 5개 Jaccard
+ 0.12 * recencyScore # lastMatchAt 지수 감쇠 (half-life 14일) + 0.12 * recencyScore # lastMatchAt 지수 감쇠 (half-life 14일)
+ 0.08 * tierScore # CHALLENGER 1.0 / GM 0.8 / MASTER 0.6
- lowSamplePenalty # sampleGameCount < 30이면 0.1 - lowSamplePenalty # sampleGameCount < 30이면 0.1
(mainRole은 filter로 보장되므로 별도 가중치 없음) (tierScore 없음 — 티어는 랭킹 요소가 아니라 인사이트. mainRole은 filter로 보장)
4. 각 멘토에 대해 지표 비교 계산: 4. 각 유사 유저에 대해 비교 계산:
- 비슷한 지표 Top 3: |내 profile[m] - 멘토 profile[m]| 최소 - tierComparison: 내 tier 대비 higher | same | lower | unknown
- 멘토가 앞서는 지표 Top 3: direction 반영 gap 최대 (lowerIsBetter는 반전) - 비슷한 지표 Top 3: |내 profile[m] - 상대 profile[m]| 최소
5. recommendation 컬렉션에 캐시 (type: 'mentor-match', profileUpdatedAt 기록) - 상대가 앞서는 지표 Top 3 (strongerMetrics): direction 반영 gap 최대 (lowerIsBetter는 반전)
- 내가 앞서는 지표 Top 3 (weakerMetrics): 위와 대칭 — 상대가 나보다 낮은 티어일 때의 인사이트
5. recommendation 컬렉션에 캐시 (type: 'similar-player', profileUpdatedAt 기록)
→ 내 프로필이 갱신되면 stale로 보고 재계산 → 내 프로필이 갱신되면 stale로 보고 재계산
``` ```
### 12.5 API / UI ### 12.5 API / UI
- `GET /api/players/:puuid/mentor-matches?limit=10` — 캐시 있으면 캐시, stale이면 재계산 - `GET /api/players/:puuid/similar-players?limit=10` — 캐시 있으면 캐시, stale이면 재계산
- 응답 항목: similarityScore, finalScore, Riot ID(표시용), tier, mainRole, mainChampions(top 3), sampleGameCount, similarMetrics[3], gapMetrics[3] - 응답 항목: similarityScore, finalScore, Riot ID(표시용), tier, tierComparison, mainRole, mainChampions(top 3), sampleGameCount, similarMetrics[3], strongerMetrics[3], weakerMetrics[3]
- 대시보드에 멘토 비교 테이블 추가. 화법: "따라 하라"가 아니라 "당신과 비슷한 상위 티어 그룹은 이런 경향" 유지 (§1.3, §14) - 대시보드에 "나와 비슷한 플레이어" 테이블 추가. 화법: "따라 하라"가 아니라 "나와 비슷한 이 유저는 이런 지표에서 차이가 난다" 유지 (§1.3, §14). 상대가 높은 티어면 strongerMetrics가, 낮은 티어면 weakerMetrics가 인사이트의 중심
- seed 유저의 Riot ID 표시는 공개 데이터이지만, 표시 형식은 전적 사이트 관례 수준으로 유지 - 유저 Riot ID 표시는 공개 데이터이지만, 표시 형식은 전적 사이트 관례 수준으로 유지
--- ---
@@ -837,13 +841,13 @@ filter로 쓰는 필드(tier, isSeed 등)가 `player_profile`에 **비정규화
### MVP 4: 챔피언 추천 ### MVP 4: 챔피언 추천
- 챔피언 스타일 벡터: 초기엔 수동 taxonomy(주요 챔피언 ~60개), 이후 seed 유저 match data 기반 자동화. **스키마는 `champion_style_profile`(§4.8)로 이미 준비됨** - 챔피언 스타일 벡터: 초기엔 수동 taxonomy(주요 챔피언 ~60개), 이후 seed 유저 match data 기반 자동화. **스키마는 `champion_style_profile`(§4.8)로 이미 준비됨**
- Fit(현 스타일 유사) / Growth(약점 보완) / Stretch(폭 확장) 3종 추천 + 근거(유사도, 유사 고티어 유저 pool 등장 빈도) 표시. 결과는 `recommendation`(type: 'champion-recommendation')에 캐시 - Fit(현 스타일 유사) / Growth(약점 보완) / Stretch(폭 확장) 3종 추천 + 근거(유사도, 유사 유저 pool 등장 빈도) 표시. 결과는 `recommendation`(type: 'champion-recommendation')에 캐시
- Data Dragon 연동 (챔피언 이름/이미지, 패치별 static data) - Data Dragon 연동 (챔피언 이름/이미지, 패치별 static data)
### MVP 5: LLM 피드백 ### MVP 5: LLM 피드백
- `FeedbackGenerator` 인터페이스로 provider 추상화 (provider는 이 시점에 결정) - `FeedbackGenerator` 인터페이스로 provider 추상화 (provider는 이 시점에 결정)
- 입력: 백엔드가 만든 evidence JSON만 (user profile 지표, 멘토 그룹과의 gap Top-N, `derived`의 데스 위치 요약). raw match JSON 입력 금지 - 입력: 백엔드가 만든 evidence JSON만 (user profile 지표, 유사 유저와의 gap Top-N, `derived`의 데스 위치 요약). raw match JSON 입력 금지
- 출력: strict JSON schema 검증. 모든 피드백 항목은 metricId 참조 필수, 검증 실패/LLM 장애 시 rule-based fallback 문장 사용. 결과는 `recommendation`(type: 'llm-feedback')에 캐시 - 출력: strict JSON schema 검증. 모든 피드백 항목은 metricId 참조 필수, 검증 실패/LLM 장애 시 rule-based fallback 문장 사용. 결과는 `recommendation`(type: 'llm-feedback')에 캐시
- 화법 규칙: 비난 금지, "다음 5게임에서 실험할 행동" 형태, 실시간 지시·MMR 추정 표현 금지 - 화법 규칙: 비난 금지, "다음 5게임에서 실험할 행동" 형태, 실시간 지시·MMR 추정 표현 금지
@@ -853,5 +857,5 @@ filter로 쓰는 필드(tier, isSeed 등)가 `player_profile`에 **비정규화
- **데이터 품질이 AI보다 중요하다.** feature extraction이 틀리면 앱 전체 신뢰가 무너진다. 파이프라인 안정화가 항상 우선. - **데이터 품질이 AI보다 중요하다.** feature extraction이 틀리면 앱 전체 신뢰가 무너진다. 파이프라인 안정화가 항상 우선.
- **비교군 설계가 핵심이다.** 전체 평균이 아니라 같은 포지션·유사 챔피언·비슷한 패치·충분한 sample size 기준으로 비교한다. - **비교군 설계가 핵심이다.** 전체 평균이 아니라 같은 포지션·유사 챔피언·비슷한 패치·충분한 sample size 기준으로 비교한다.
- **결과는 항상 근거와 함께.** "운영이 약합니다"(X) → "10분 골드 리드 게임에서 첫 전령 관여율이 유사 고티어 그룹보다 낮습니다"(O). - **결과는 항상 근거와 함께.** "운영이 약합니다"(X) → "10분 골드 리드 게임에서 첫 전령 관여율이 유사 유저 그룹보다 낮습니다"(O).
- **추천은 단정하지 않는다.** "이 챔피언을 해야 티어가 오릅니다"(X) → "현재 스타일과 잘 맞을 가능성이 높은 후보입니다. 다음 10게임에서 비교해보세요"(O). - **추천은 단정하지 않는다.** "이 챔피언을 해야 티어가 오릅니다"(X) → "현재 스타일과 잘 맞을 가능성이 높은 후보입니다. 다음 10게임에서 비교해보세요"(O).
+21 -13
View File
@@ -97,43 +97,51 @@ export interface PlayerAnalysisDto {
updatedAt: string; updatedAt: string;
} }
export interface MentorRiotIdDto { export interface SimilarPlayerRiotIdDto {
gameName: string; gameName: string;
tagLine: string; tagLine: string;
} }
export interface SimilarMentorMetricDto { /** 상대 유저의 티어가 내 티어 대비 어느 쪽인지. 티어 정보가 없으면 unknown. */
export type TierComparison = 'higher' | 'same' | 'lower' | 'unknown';
export interface SimilarMetricDto {
metricId: MetricId; metricId: MetricId;
currentValue: number; currentValue: number;
mentorValue: number; otherValue: number;
absoluteGap: number; absoluteGap: number;
} }
export interface GapMentorMetricDto { export interface LeadMetricDto {
metricId: MetricId; metricId: MetricId;
currentValue: number; currentValue: number;
mentorValue: number; otherValue: number;
mentorAdvantage: number; /** direction 반영 우위 폭. 항상 양수. */
lead: number;
} }
export interface MentorMatchDto { export interface SimilarPlayerDto {
mentorDisplayId: string; displayId: string;
riotId: MentorRiotIdDto | null; riotId: SimilarPlayerRiotIdDto | null;
similarityScore: number; similarityScore: number;
finalScore: number; finalScore: number;
tier?: string; tier?: string;
division?: string; division?: string;
leaguePoints?: number; leaguePoints?: number;
tierComparison: TierComparison;
mainRole: Role; mainRole: Role;
mainChampions: ChampionPoolEntryDto[]; mainChampions: ChampionPoolEntryDto[];
sampleGameCount: number; sampleGameCount: number;
similarMetrics: SimilarMentorMetricDto[]; similarMetrics: SimilarMetricDto[];
gapMetrics: GapMentorMetricDto[]; /** 이 유저가 나보다 앞서는 지표 Top 3 */
strongerMetrics: LeadMetricDto[];
/** 내가 이 유저보다 앞서는 지표 Top 3 */
weakerMetrics: LeadMetricDto[];
} }
export interface MentorMatchesDto { export interface SimilarPlayersDto {
puuid: string; puuid: string;
queueId: number; queueId: number;
profileUpdatedAt: string; profileUpdatedAt: string;
matches: MentorMatchDto[]; matches: SimilarPlayerDto[];
} }