chore(api): add data migrations

This commit is contained in:
dahyeon committed 2026-05-02 22:23:00 +09:00
1 parent b5aa58dde8
commit 9c05850cba
6 files changed
+1438

No files matched your search

@@ -0,0 +1,100 @@
interface MigrationCollection {
find(filter: Record<string, unknown>): {
limit(limit: number): AsyncIterable<AnyDoc>;
};
bulkWrite(
writes: Array<{
updateOne: {
filter: { _id: unknown };
update: { $set: Record<string, unknown> };
};
}>,
options: { ordered: boolean },
): Promise<unknown>;
}
interface MigrationDb {
collection(name: string): MigrationCollection;
}
interface MigrationOptions {
dryRun?: boolean;
limit?: number;
}
interface MigrationStats {
scannedAuctions: number;
changedAuctions: number;
}
type AnyDoc = Record<string, unknown> & { _id: unknown };
export async function migrateAuctionPassHistory(
db: MigrationDb,
options: MigrationOptions = {},
): Promise<MigrationStats> {
const dryRun = options.dryRun ?? true;
const stats: MigrationStats = {
scannedAuctions: 0,
changedAuctions: 0,
};
const writes: Array<{
updateOne: {
filter: { _id: unknown };
update: { $set: Record<string, unknown> };
};
}> = [];
for await (const doc of db.collection('auction').find({}).limit(options.limit ?? 0)) {
stats.scannedAuctions += 1;
const set: Record<string, unknown> = {};
let changed = false;
if (!Array.isArray(doc.passedQueue)) {
set.passedQueue = [];
changed = true;
}
if (typeof doc.auctionRound !== 'number') {
set.auctionRound = 1;
changed = true;
}
if (typeof doc.topTierThreshold !== 'string') {
set.topTierThreshold = 'NONE';
changed = true;
}
if (!Array.isArray(doc.manualTopTierUserIds)) {
set.manualTopTierUserIds = [];
changed = true;
}
const order = Array.isArray(doc.order)
? doc.order.map((player) => {
if (!isRecord(player) || typeof player.passCount === 'number') {
return player;
}
changed = true;
return { ...player, passCount: 0 };
})
: [];
if (changed && order.length > 0) set.order = order;
if (!changed) continue;
stats.changedAuctions += 1;
writes.push({
updateOne: {
filter: { _id: doc._id },
update: { $set: set },
},
});
}
if (!dryRun && writes.length > 0) {
await db.collection('auction').bulkWrite(writes, { ordered: false });
}
return stats;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value && typeof value === 'object' && !Array.isArray(value));
}
@@ -0,0 +1,160 @@
import { migrateTeamIndex } from './20260502-team-index';
function createDb(params: {
auctions?: Array<Record<string, unknown>>;
matches?: Array<Record<string, unknown>>;
}) {
const collections = {
auction: params.auctions ?? [],
match: params.matches ?? [],
};
return {
collections,
db: {
collection(name: string) {
const key = name === 'auction' ? 'auction' : 'match';
const docs = collections[key];
return {
find() {
return {
limit() {
return {
async *[Symbol.asyncIterator]() {
for (const doc of docs) yield doc;
},
};
},
};
},
async bulkWrite(writes: Array<{
updateOne: {
filter: { _id: unknown };
update: {
$set: Record<string, unknown>;
$unset: Record<string, ''>;
};
};
}>) {
for (const write of writes) {
const doc = docs.find((item) => item._id === write.updateOne.filter._id);
if (!doc) continue;
Object.assign(doc, write.updateOne.update.$set);
for (const key of Object.keys(write.updateOne.update.$unset)) {
delete doc[key];
}
}
},
};
},
},
};
}
describe('migrateTeamIndex', () => {
it('migrates auction and match team identity fields', async () => {
const { db, collections } = createDb({
auctions: [
{
_id: 'auction-1',
teams: [{ side: 'blue', groupIndex: 1 }, { side: 'red', groupIndex: 1 }],
bids: [{ side: 'red', groupIndex: 1, amount: 100 }],
currentBidder: 'red',
currentBidderGroupIndex: 1,
},
],
matches: [
{
_id: 'match-1',
teams: [{ side: 'blue', groupIndex: 1 }, { side: 'red', groupIndex: 1 }],
result: {
winnerSide: 'blue',
blueScore: 1,
redScore: 0,
games: [
{
gameNumber: 1,
riotMatchId: 'KR_1',
winnerSide: 'blue',
blueGroupIndex: 1,
redGroupIndex: 1,
participants: [
{ userId: 'u1', side: 'blue' },
{ userId: 'u2', side: 'red' },
],
},
],
seriesResults: [
{
blueGroupIndex: 1,
redGroupIndex: 1,
blueScore: 1,
redScore: 0,
winnerSide: 'blue',
},
],
},
},
],
});
const stats = await migrateTeamIndex(db, { dryRun: false });
expect(stats).toEqual({
scannedAuctions: 1,
changedAuctions: 1,
scannedMatches: 1,
changedMatches: 1,
});
expect(collections.auction[0]).toMatchObject({
teams: [{ teamIndex: 1 }, { teamIndex: 2 }],
bids: [{ teamIndex: 2, amount: 100 }],
currentBidderTeamIndex: 2,
});
expect(collections.match[0]).toMatchObject({
teams: [{ teamIndex: 1, name: '1팀' }, { teamIndex: 2, name: '2팀' }],
result: {
winnerTeamIndex: 1,
games: [
{
blueTeamIndex: 1,
redTeamIndex: 2,
winnerTeamIndex: 1,
participants: [
{ teamIndex: 1, side: 'blue' },
{ teamIndex: 2, side: 'red' },
],
},
],
seriesResults: [
{
teamAIndex: 1,
teamBIndex: 2,
teamAWins: 1,
teamBWins: 0,
winnerTeamIndex: 1,
},
],
},
});
expect(collections.auction[0]).not.toHaveProperty('currentBidder');
expect(collections.match[0].result).not.toHaveProperty('blueScore');
});
it('is idempotent after applying updates', async () => {
const { db } = createDb({
matches: [
{
_id: 'match-1',
teams: [{ side: 'blue', groupIndex: 1 }],
},
],
});
await migrateTeamIndex(db, { dryRun: false });
const stats = await migrateTeamIndex(db, { dryRun: false });
expect(stats.changedMatches).toBe(0);
expect(stats.changedAuctions).toBe(0);
});
});
@@ -0,0 +1,335 @@
type LegacySide = 'blue' | 'red';
interface MigrationCollection {
find(filter: Record<string, unknown>): {
limit(limit: number): AsyncIterable<AnyDoc>;
};
bulkWrite(
writes: Array<{
updateOne: {
filter: { _id: unknown };
update: { $set: Record<string, unknown>; $unset: Record<string, ''> };
};
}>,
options: { ordered: boolean },
): Promise<unknown>;
}
interface MigrationDb {
collection(name: string): MigrationCollection;
}
interface MigrationOptions {
dryRun?: boolean;
limit?: number;
}
interface MigrationStats {
scannedAuctions: number;
changedAuctions: number;
scannedMatches: number;
changedMatches: number;
}
type AnyDoc = Record<string, unknown> & { _id: unknown };
export async function migrateTeamIndex(
db: MigrationDb,
options: MigrationOptions = {},
): Promise<MigrationStats> {
const dryRun = options.dryRun ?? true;
const stats: MigrationStats = {
scannedAuctions: 0,
changedAuctions: 0,
scannedMatches: 0,
changedMatches: 0,
};
await migrateCollection(db.collection('auction'), options.limit, dryRun, stats, 'auction');
await migrateCollection(db.collection('match'), options.limit, dryRun, stats, 'match');
return stats;
}
async function migrateCollection(
collection: MigrationCollection,
limit: number | undefined,
dryRun: boolean,
stats: MigrationStats,
kind: 'auction' | 'match',
) {
const cursor = collection.find({}).limit(limit ?? 0);
const writes: Array<{
updateOne: {
filter: { _id: unknown };
update: { $set: Record<string, unknown>; $unset: Record<string, ''> };
};
}> = [];
for await (const doc of cursor) {
if (kind === 'auction') stats.scannedAuctions += 1;
if (kind === 'match') stats.scannedMatches += 1;
const update = kind === 'auction' ? migrateAuction(doc) : migrateMatch(doc);
if (!update) continue;
if (kind === 'auction') stats.changedAuctions += 1;
if (kind === 'match') stats.changedMatches += 1;
writes.push({
updateOne: {
filter: { _id: doc._id },
update,
},
});
}
if (!dryRun && writes.length > 0) {
await collection.bulkWrite(writes, { ordered: false });
}
}
function migrateAuction(doc: AnyDoc) {
const set: Record<string, unknown> = {};
const unset: Record<string, ''> = {};
let changed = false;
const teams = asArray(doc.teams).map((team) => {
const migrated = { ...team };
const teamIndex = readTeamIndex(migrated);
if (teamIndex !== undefined) migrated.teamIndex = teamIndex;
if ('side' in migrated || 'groupIndex' in migrated) changed = true;
delete migrated.side;
delete migrated.groupIndex;
return migrated;
});
if (changed) set.teams = teams;
const bids = asArray(doc.bids).map((bid) => {
const migrated = { ...bid };
const teamIndex = readTeamIndex(migrated);
if (teamIndex !== undefined) migrated.teamIndex = teamIndex;
if ('side' in migrated || 'groupIndex' in migrated) changed = true;
delete migrated.side;
delete migrated.groupIndex;
return migrated;
});
if (changed) set.bids = bids;
if (
typeof doc.currentBidderTeamIndex !== 'number' &&
isSide(doc.currentBidder)
) {
set.currentBidderTeamIndex = sideGroupToTeamIndex(
doc.currentBidder,
numberOrDefault(doc.currentBidderGroupIndex, 1),
);
changed = true;
}
if ('currentBidder' in doc || 'currentBidderGroupIndex' in doc) {
unset.currentBidder = '';
unset.currentBidderGroupIndex = '';
changed = true;
}
return changed ? { $set: set, $unset: unset } : null;
}
function migrateMatch(doc: AnyDoc) {
const set: Record<string, unknown> = {};
const unset: Record<string, ''> = {};
let changed = false;
const teams = asArray(doc.teams).map((team) => {
const migrated = { ...team };
const teamIndex = readTeamIndex(migrated);
if (teamIndex !== undefined) migrated.teamIndex = teamIndex;
if (!migrated.name && typeof teamIndex === 'number') migrated.name = `${teamIndex}팀`;
if ('side' in migrated || 'groupIndex' in migrated) changed = true;
delete migrated.side;
delete migrated.groupIndex;
return migrated;
});
if (changed) set.teams = teams;
const result = isRecord(doc.result) ? migrateResult(doc.result) : null;
if (result) {
set.result = result;
changed = true;
}
return changed ? { $set: set, $unset: unset } : null;
}
function migrateResult(result: Record<string, unknown>) {
let changed = false;
const migrated = { ...result };
const games = asArray(result.games).map((game) => {
const next = { ...game };
const blueTeamIndex =
numberOrUndefined(next.blueTeamIndex) ??
sideGroupToTeamIndex('blue', numberOrDefault(next.blueGroupIndex, 1));
const redTeamIndex =
numberOrUndefined(next.redTeamIndex) ??
sideGroupToTeamIndex('red', numberOrDefault(next.redGroupIndex, 1));
const winnerSide = isSide(next.winnerSide) ? next.winnerSide : undefined;
const winnerTeamIndex =
numberOrUndefined(next.winnerTeamIndex) ??
(winnerSide === 'blue'
? blueTeamIndex
: winnerSide === 'red'
? redTeamIndex
: undefined);
next.blueTeamIndex = blueTeamIndex;
next.redTeamIndex = redTeamIndex;
if (winnerTeamIndex !== undefined) next.winnerTeamIndex = winnerTeamIndex;
next.participants = asArray(next.participants).map((participant) => {
const migratedParticipant = { ...participant };
if (typeof migratedParticipant.teamIndex !== 'number') {
migratedParticipant.teamIndex =
migratedParticipant.side === 'blue' ? blueTeamIndex : redTeamIndex;
}
return migratedParticipant;
});
if ('blueGroupIndex' in next || 'redGroupIndex' in next) changed = true;
delete next.blueGroupIndex;
delete next.redGroupIndex;
return next;
});
migrated.games = games;
const seriesResults = asArray(result.seriesResults).map((series) => {
if (typeof series.teamAIndex === 'number' && typeof series.teamBIndex === 'number') {
return series;
}
changed = true;
const legacyBlueTeamIndex = sideGroupToTeamIndex(
'blue',
numberOrDefault(series.blueGroupIndex, 1),
);
const legacyRedTeamIndex = sideGroupToTeamIndex(
'red',
numberOrDefault(series.redGroupIndex, 1),
);
const teamAIndex = Math.min(legacyBlueTeamIndex, legacyRedTeamIndex);
const teamBIndex = Math.max(legacyBlueTeamIndex, legacyRedTeamIndex);
const blueScore = numberOrDefault(series.blueScore, 0);
const redScore = numberOrDefault(series.redScore, 0);
const winnerSide = isSide(series.winnerSide) ? series.winnerSide : undefined;
const winnerTeamIndex =
winnerSide === 'blue'
? legacyBlueTeamIndex
: winnerSide === 'red'
? legacyRedTeamIndex
: undefined;
return {
teamAIndex,
teamBIndex,
teamAWins: teamAIndex === legacyBlueTeamIndex ? blueScore : redScore,
teamBWins: teamBIndex === legacyBlueTeamIndex ? blueScore : redScore,
winnerTeamIndex,
};
});
migrated.seriesResults = seriesResults.length > 0 ? seriesResults : buildSeries(games);
if (typeof migrated.winnerTeamIndex !== 'number') {
const migratedSeriesResults = Array.isArray(migrated.seriesResults)
? migrated.seriesResults
: [];
migrated.winnerTeamIndex =
resolveWinnerTeamIndex(migratedSeriesResults) ??
(isSide(migrated.winnerSide)
? sideGroupToTeamIndex(migrated.winnerSide, 1)
: undefined);
}
if ('winnerSide' in migrated || 'blueScore' in migrated || 'redScore' in migrated) {
changed = true;
}
delete migrated.winnerSide;
delete migrated.blueScore;
delete migrated.redScore;
return changed ? migrated : null;
}
function buildSeries(games: Record<string, unknown>[]) {
const bySeries = new Map<
string,
{
teamAIndex: number;
teamBIndex: number;
teamAWins: number;
teamBWins: number;
winnerTeamIndex?: number;
}
>();
for (const game of games) {
const blueTeamIndex = numberOrDefault(game.blueTeamIndex, 1);
const redTeamIndex = numberOrDefault(game.redTeamIndex, 2);
const winnerTeamIndex = numberOrUndefined(game.winnerTeamIndex);
const teamAIndex = Math.min(blueTeamIndex, redTeamIndex);
const teamBIndex = Math.max(blueTeamIndex, redTeamIndex);
const key = `${teamAIndex}:${teamBIndex}`;
const current =
bySeries.get(key) ?? { teamAIndex, teamBIndex, teamAWins: 0, teamBWins: 0 };
if (winnerTeamIndex === teamAIndex) current.teamAWins += 1;
if (winnerTeamIndex === teamBIndex) current.teamBWins += 1;
current.winnerTeamIndex =
current.teamAWins > current.teamBWins
? teamAIndex
: current.teamBWins > current.teamAWins
? teamBIndex
: undefined;
bySeries.set(key, current);
}
return [...bySeries.values()];
}
function resolveWinnerTeamIndex(
seriesResults: Array<Record<string, unknown>>,
): number | undefined {
const wins = new Map<number, number>();
for (const series of seriesResults) {
const winnerTeamIndex = numberOrUndefined(series.winnerTeamIndex);
if (!winnerTeamIndex) continue;
wins.set(winnerTeamIndex, (wins.get(winnerTeamIndex) ?? 0) + 1);
}
const sorted = [...wins.entries()].sort((left, right) => right[1] - left[1]);
if (sorted.length === 0) return undefined;
if (sorted.length > 1 && sorted[0][1] === sorted[1][1]) return undefined;
return sorted[0][0];
}
function readTeamIndex(value: Record<string, unknown>): number | undefined {
if (typeof value.teamIndex === 'number') return value.teamIndex;
if (!isSide(value.side)) return undefined;
return sideGroupToTeamIndex(value.side, numberOrDefault(value.groupIndex, 1));
}
function sideGroupToTeamIndex(side: LegacySide, groupIndex: number) {
return (Math.max(1, groupIndex) - 1) * 2 + (side === 'blue' ? 1 : 2);
}
function asArray(value: unknown): Record<string, unknown>[] {
return Array.isArray(value)
? value.filter(isRecord).map((item) => ({ ...item }))
: [];
}
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value && typeof value === 'object' && !Array.isArray(value));
}
function isSide(value: unknown): value is LegacySide {
return value === 'blue' || value === 'red';
}
function numberOrDefault(value: unknown, fallback: number) {
return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
}
function numberOrUndefined(value: unknown) {
return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
}
@@ -0,0 +1,167 @@
import 'reflect-metadata';
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { NestFactory } from '@nestjs/core';
import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { ConnectionService, resolveMongoDbName } from '../connection.service';
import { SecretModule } from '../../secret/secret.module';
import { migrateTeamIndex } from './20260502-team-index';
interface CliOptions {
dryRun: boolean;
limit?: number;
nodeEnv: string;
}
@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
envFilePath: [
resolve(__dirname, '../../../../../../project.env'),
resolve(process.cwd(), '../project.env'),
resolve(process.cwd(), 'apps/project.env'),
resolve(process.cwd(), 'project.env'),
],
}),
SecretModule,
],
providers: [ConnectionService],
})
class MigrationModule {}
async function loadMachineEnvFile() {
const homeDir = process.env.HOME ?? process.env.USERPROFILE;
if (!homeDir) return;
const machineEnvFile = resolve(homeDir, 'source/global-env-vars.txt');
try {
const file = await readFile(machineEnvFile, 'utf8');
for (const rawLine of file.split(/\r?\n/)) {
const line = rawLine.trim();
if (!line || line.startsWith('#')) continue;
const matched = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
if (!matched) continue;
const [, key, rawValue] = matched;
process.env[key] = rawValue.replace(/^["']|["']$/g, '');
}
} catch {
// 로컬 machine env 파일이 없으면 그냥 지나간다.
}
}
function parseArgs(argv: string[]): CliOptions {
let dryRun = true;
let limit: number | undefined;
let nodeEnv = process.env.NODE_ENV ?? 'dev';
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
if (arg === '--apply') {
dryRun = false;
continue;
}
if (arg === '--dry-run') {
dryRun = true;
continue;
}
if (arg === '--env') {
const value = argv[index + 1];
if (!value) throw new Error('--env requires dev, test, or prod.');
nodeEnv = value;
index += 1;
continue;
}
if (arg.startsWith('--env=')) {
nodeEnv = arg.slice('--env='.length);
continue;
}
if (arg === '--limit') {
const value = Number(argv[index + 1]);
if (!Number.isInteger(value) || value < 1) {
throw new Error('--limit requires a positive integer.');
}
limit = value;
index += 1;
continue;
}
if (arg.startsWith('--limit=')) {
const value = Number(arg.slice('--limit='.length));
if (!Number.isInteger(value) || value < 1) {
throw new Error('--limit requires a positive integer.');
}
limit = value;
continue;
}
if (arg === '--help' || arg === '-h') {
printHelp();
process.exit(0);
}
throw new Error(`Unknown argument: ${arg}`);
}
if (!['dev', 'test', 'prod'].includes(nodeEnv)) {
throw new Error('--env must be dev, test, or prod.');
}
return { dryRun, limit, nodeEnv };
}
function printHelp() {
console.log(`Usage:
pnpm --filter api exec ts-node src/modules/global/database/migrations/run-team-index.ts [--dry-run]
pnpm --filter api exec ts-node src/modules/global/database/migrations/run-team-index.ts --apply
Options:
--dry-run Print affected counts without writing. Default.
--apply Apply updates to MongoDB.
--env <env> dev | test | prod. Default: NODE_ENV or dev.
--limit <n> Only scan first n documents per collection.
`);
}
async function main() {
const options = parseArgs(process.argv.slice(2));
process.env.NODE_ENV = options.nodeEnv;
await loadMachineEnvFile();
const app = await NestFactory.createApplicationContext(MigrationModule, {
logger: options.dryRun ? ['log', 'warn', 'error'] : ['log', 'warn', 'error'],
});
try {
const connectionService = app.get(ConnectionService);
const connection = await connectionService.getConnection();
if (!connection.db) {
throw new Error('MongoDB connection has no db handle.');
}
const dbName = resolveMongoDbName(options.nodeEnv);
console.log(
`[team-index migration] mode=${options.dryRun ? 'dry-run' : 'apply'} env=${options.nodeEnv} db=${dbName}`,
);
const stats = await migrateTeamIndex(connection.db as Parameters<typeof migrateTeamIndex>[0], {
dryRun: options.dryRun,
limit: options.limit,
});
console.table(stats);
if (options.dryRun) {
console.log('No writes were made. Re-run with --apply to update documents.');
} else {
console.log('Migration applied.');
}
} finally {
await app.close();
}
}
void main().catch((error: unknown) => {
console.error(error instanceof Error ? error.message : error);
process.exitCode = 1;
});