AI Implementation feature(865): Scoreboard: Ranking, Matrix, Event Log and Score Graph (#52)

This commit was merged in pull request #52.
This commit is contained in:
2026-07-23 05:13:23 +00:00
parent 49d0930780
commit 7c4843d5cc
26 changed files with 3074 additions and 60 deletions
+218
View File
@@ -0,0 +1,218 @@
process.env.DATABASE_PATH = ':memory:';
process.env.THEMES_DIR = './themes';
process.env.FRONTEND_DIST = './frontend/dist';
process.env.UPLOAD_DIR = '/tmp/hipctf-scoreboard-controller-test';
import { Test } from '@nestjs/testing';
import { INestApplication, ValidationPipe } from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';
import cookieParser from 'cookie-parser';
import * as express from 'express';
import request from 'supertest';
import { getRepositoryToken } from '@nestjs/typeorm';
import { v4 as uuid } from 'uuid';
import * as argon2 from 'argon2';
import { AppModule } from '../../backend/src/app.module';
import { GlobalExceptionFilter } from '../../backend/src/common/filters/global-exception.filter';
import { CsrfMiddleware } from '../../backend/src/common/middleware/csrf.middleware';
import { ConfigService } from '@nestjs/config';
import { initDb } from './db-helper';
import { ChallengeEntity } from '../../backend/src/database/entities/challenge.entity';
import { CategoryEntity } from '../../backend/src/database/entities/category.entity';
import { SolveEntity } from '../../backend/src/database/entities/solve.entity';
import { UserEntity } from '../../backend/src/database/entities/user.entity';
import { SettingsService } from '../../backend/src/modules/settings/settings.module';
import { SETTINGS_KEYS } from '../../backend/src/config/env.schema';
describe('GET /api/v1/scoreboard/*', () => {
let app: INestApplication;
let adminToken: string;
let solveRepo: any;
let userRepo: any;
let challengeRepo: any;
let categoryRepo: any;
let settings: SettingsService;
let challengeA: ChallengeEntity;
let challengeB: ChallengeEntity;
let playerA: string;
let playerB: string;
async function setRunningWindow(): Promise<void> {
await settings.set(SETTINGS_KEYS.EVENT_START_UTC, new Date(Date.now() - 3600_000).toISOString());
await settings.set(SETTINGS_KEYS.EVENT_END_UTC, new Date(Date.now() + 3600_000).toISOString());
}
beforeAll(async () => {
const moduleRef = await Test.createTestingModule({ imports: [AppModule] }).compile();
app = moduleRef.createNestApplication();
app.use(cookieParser());
app.use(express.json({ limit: '1mb' }));
const csrfMw = new CsrfMiddleware(app.get(ConfigService));
app.use((req: any, res: any, next: any) => csrfMw.use(req, res, next));
app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: false, transform: true }));
const httpAdapterHost = app.get(HttpAdapterHost);
app.useGlobalFilters(new GlobalExceptionFilter(httpAdapterHost));
await app.init();
await initDb(app);
settings = app.get(SettingsService);
solveRepo = app.get(getRepositoryToken(SolveEntity));
userRepo = app.get(getRepositoryToken(UserEntity));
challengeRepo = app.get(getRepositoryToken(ChallengeEntity));
categoryRepo = app.get(getRepositoryToken(CategoryEntity));
await setRunningWindow();
const server = app.getHttpServer();
await request(server).post('/api/v1/auth/register-first-admin')
.send({ username: 'admin', password: 'Sup3rSecret!Pass' })
.expect(201);
const csrfPrime = await request(server).get('/api/v1/auth/csrf');
const csrfCookie = (csrfPrime.headers['set-cookie'] as unknown as string[] | undefined)?.find((c) => c.startsWith('csrf='));
const csrf = csrfCookie ? decodeURIComponent(csrfCookie.split(';')[0].split('=')[1]) : '';
const login = await request(server).post('/api/v1/auth/login')
.set('Cookie', `csrf=${csrf}`)
.set('X-CSRF-Token', csrf)
.send({ username: 'admin', password: 'Sup3rSecret!Pass' })
.expect(201);
adminToken = login.body.accessToken;
const cry = await categoryRepo.findOne({ where: { systemKey: 'CRY' } });
if (!cry) throw new Error('expected CRY category');
challengeA = await challengeRepo.save(challengeRepo.create({
id: uuid(),
name: 'chal-a',
descriptionMd: '',
categoryId: cry.id,
difficulty: 'LOW',
initialPoints: 500,
minimumPoints: 100,
decaySolves: 2,
flag: 'flag{a}',
protocol: 'WEB',
port: null,
ipAddress: '',
enabled: true,
}));
challengeB = await challengeRepo.save(challengeRepo.create({
id: uuid(),
name: 'chal-b',
descriptionMd: '',
categoryId: cry.id,
difficulty: 'LOW',
initialPoints: 200,
minimumPoints: 50,
decaySolves: 5,
flag: 'flag{b}',
protocol: 'WEB',
port: null,
ipAddress: '',
enabled: true,
}));
const passwordHash = await argon2.hash('PlayerPass!1Ab', { type: argon2.argon2id });
const a = await userRepo.save(userRepo.create({ id: uuid(), username: 'alice', passwordHash, role: 'player', status: 'enabled' }));
const b = await userRepo.save(userRepo.create({ id: uuid(), username: 'bob', passwordHash, role: 'player', status: 'enabled' }));
const c = await userRepo.save(userRepo.create({ id: uuid(), username: 'carol', passwordHash, role: 'player', status: 'enabled' }));
playerA = a.id;
playerB = b.id;
void c;
await solveRepo.save(solveRepo.create({
id: uuid(),
challengeId: challengeA.id,
userId: playerA,
solvedAt: new Date(Date.now() - 1000).toISOString(),
pointsAwarded: 515,
basePoints: 500,
rankBonus: 15,
isFirst: 1,
isSecond: 0,
isThird: 0,
}));
await solveRepo.save(solveRepo.create({
id: uuid(),
challengeId: challengeB.id,
userId: playerA,
solvedAt: new Date(Date.now() - 500).toISOString(),
pointsAwarded: 210,
basePoints: 200,
rankBonus: 10,
isFirst: 1,
isSecond: 0,
isThird: 0,
}));
await solveRepo.save(solveRepo.create({
id: uuid(),
challengeId: challengeA.id,
userId: playerB,
solvedAt: new Date(Date.now() - 100).toISOString(),
pointsAwarded: 110,
basePoints: 100,
rankBonus: 10,
isFirst: 0,
isSecond: 1,
isThird: 0,
}));
});
afterAll(async () => {
await app.close();
});
function authed(): any {
const r: any = request(app.getHttpServer());
r.set = ((h: string, v: string) => { r.headers = r.headers || {}; r.headers[h] = v; return r; });
return r;
}
it('rejects unauthenticated ranking with 401', async () => {
await request(app.getHttpServer()).get('/api/v1/scoreboard/ranking').expect(401);
});
it('returns competition-ranked ranking including zero-pt player', async () => {
const res = await authed().get('/api/v1/scoreboard/ranking').set('Authorization', `Bearer ${adminToken}`).expect(200);
expect(Array.isArray(res.body)).toBe(true);
expect(res.body.length).toBe(4);
expect(res.body[0]).toMatchObject({ rank: 1, playerName: 'alice' });
expect(res.body[0].points).toBe(725);
expect(res.body[1].rank).toBe(2);
const zeroPointRows = res.body.filter((r: any) => r.points === 0);
expect(zeroPointRows.length).toBe(2);
expect(zeroPointRows[0].rank).toBe(3);
});
it('returns matrix with players and challenges', async () => {
const res = await authed().get('/api/v1/scoreboard/matrix').set('Authorization', `Bearer ${adminToken}`).expect(200);
expect(res.body.players.length).toBe(4);
expect(res.body.challenges.length).toBeGreaterThanOrEqual(2);
const challengeIds = res.body.challenges.map((c: any) => c.id);
expect(challengeIds).toContain(challengeA.id);
expect(challengeIds).toContain(challengeB.id);
const aliceCells = res.body.cells[playerA];
expect(aliceCells[challengeA.id]).toBe(1);
expect(aliceCells[challengeB.id]).toBe(1);
const bobCells = res.body.cells[playerB];
expect(bobCells[challengeA.id]).toBe(2);
expect(bobCells[challengeB.id]).toBeNull();
});
it('returns event-log in DESC order with limit', async () => {
const res = await authed().get('/api/v1/scoreboard/event-log?limit=2').set('Authorization', `Bearer ${adminToken}`).expect(200);
expect(res.body.length).toBe(2);
const ts = res.body.map((r: any) => r.awardedAtUtc);
expect(ts[0] >= ts[1]).toBe(true);
});
it('returns graph with top-10 series and start/end anchors', async () => {
const res = await authed().get('/api/v1/scoreboard/graph').set('Authorization', `Bearer ${adminToken}`).expect(200);
expect(res.body.state).toBe('running');
expect(res.body.startUtc).toBeTruthy();
expect(res.body.endUtc).toBeTruthy();
expect(res.body.series.length).toBeGreaterThan(0);
const top = res.body.series[0];
expect(top.points[0]).toMatchObject({ value: 0 });
expect(top.points[top.points.length - 1].tUtc).toBe(res.body.endUtc);
});
});
+237
View File
@@ -0,0 +1,237 @@
import { ScoreboardService } from '../../backend/src/modules/challenges/scoreboard.service';
import {
computeAwardedPoints,
PLAYER_COLOR_PALETTE,
stablePlayerColorIndex,
} from '../../backend/src/modules/challenges/scoring.util';
function buildMockManager(opts: {
solves?: any[];
challenges?: any[];
users?: any[];
}): any {
const solves = opts.solves ?? [];
const challenges = opts.challenges ?? [];
const users = opts.users ?? [];
function solveRepo() {
return {
createQueryBuilder: () => {
const b: any = {};
b.leftJoin = jest.fn().mockReturnThis();
b.select = jest.fn().mockReturnThis();
b.addSelect = jest.fn().mockReturnThis();
b.orderBy = jest.fn().mockReturnThis();
b.addOrderBy = jest.fn().mockReturnThis();
b.limit = jest.fn().mockReturnThis();
b.getRawMany = jest.fn().mockImplementation(async () => solves);
return b;
},
};
}
function userRepo() {
return {
createQueryBuilder: () => {
const b: any = {};
b.select = jest.fn().mockReturnThis();
b.addSelect = jest.fn().mockReturnThis();
b.getRawMany = jest.fn().mockImplementation(async () => users);
return b;
},
};
}
function challengeRepo() {
return {
createQueryBuilder: () => {
const b: any = {};
b.leftJoin = jest.fn().mockReturnThis();
b.select = jest.fn().mockReturnThis();
b.addSelect = jest.fn().mockReturnThis();
b.where = jest.fn().mockReturnThis();
b.getRawMany = jest.fn().mockImplementation(async () => challenges);
return b;
},
};
}
return {
getRepository: (entity: any) => {
const name = entity?.name ?? '';
if (name === 'SolveEntity') return solveRepo();
if (name === 'UserEntity') return userRepo();
if (name === 'ChallengeEntity') return challengeRepo();
return { createQueryBuilder: () => ({ getRawMany: async () => [] }) };
},
};
}
const fakeSettings: any = { get: jest.fn().mockResolvedValue('') };
const fakeEventStatus: any = {
getState: jest.fn().mockResolvedValue({
state: 'unconfigured',
serverNowUtc: '2025-01-01T00:00:00.000Z',
eventStartUtc: null,
eventEndUtc: null,
secondsToStart: null,
secondsToEnd: null,
}),
};
describe('scoring.util additions', () => {
it('computeAwardedPoints adds rank bonus for 1st/2nd/3rd only', () => {
expect(computeAwardedPoints(500, 100, 10, 0)).toBe(500 + 15);
expect(computeAwardedPoints(500, 100, 10, 1)).toBe(460 + 10);
expect(computeAwardedPoints(500, 100, 10, 2)).toBe(420 + 5);
expect(computeAwardedPoints(500, 100, 10, 3)).toBe(380);
expect(computeAwardedPoints(500, 100, 10, 9)).toBe(140);
});
it('stablePlayerColorIndex is deterministic and in range', () => {
const idx = stablePlayerColorIndex('player-abc');
expect(idx).toBeGreaterThanOrEqual(0);
expect(idx).toBeLessThan(PLAYER_COLOR_PALETTE.length);
expect(stablePlayerColorIndex('player-abc')).toBe(idx);
expect(stablePlayerColorIndex('player-xyz')).not.toBe(idx);
});
});
describe('ScoreboardService.getRanking', () => {
it('returns competition ranks with zero-pt players sorted to the bottom', async () => {
const svc = new ScoreboardService(fakeSettings, fakeEventStatus);
const mgr = buildMockManager({
solves: [
{ id: 's1', challengeId: 'c1', userId: 'u-alice', solvedAt: '2025-01-01T00:00:00.000Z', pointsAwarded: 100, username: 'alice' },
{ id: 's2', challengeId: 'c2', userId: 'u-alice', solvedAt: '2025-01-01T00:01:00.000Z', pointsAwarded: 50, username: 'alice' },
{ id: 's3', challengeId: 'c1', userId: 'u-bob', solvedAt: '2025-01-01T00:02:00.000Z', pointsAwarded: 80, username: 'bob' },
],
users: [
{ id: 'u-alice', username: 'alice' },
{ id: 'u-bob', username: 'bob' },
{ id: 'u-carol', username: 'carol' },
],
});
const ranking = await svc.getRanking(mgr);
expect(ranking).toHaveLength(3);
expect(ranking[0]).toMatchObject({ rank: 1, playerId: 'u-alice', points: 150, solvedCount: 2 });
expect(ranking[1]).toMatchObject({ rank: 2, playerId: 'u-bob', points: 80, solvedCount: 1 });
expect(ranking[2]).toMatchObject({ rank: 3, playerId: 'u-carol', points: 0, solvedCount: 0 });
for (const r of ranking) {
expect(r.colorIndex).toBeGreaterThanOrEqual(0);
expect(r.colorIndex).toBeLessThan(PLAYER_COLOR_PALETTE.length);
}
});
it('uses earliest solve as tiebreaker', async () => {
const svc = new ScoreboardService(fakeSettings, fakeEventStatus);
const mgr = buildMockManager({
solves: [
{ id: 's1', challengeId: 'c1', userId: 'u-bob', solvedAt: '2025-01-01T00:01:00.000Z', pointsAwarded: 100, username: 'bob' },
{ id: 's2', challengeId: 'c1', userId: 'u-alice', solvedAt: '2025-01-01T00:00:00.000Z', pointsAwarded: 100, username: 'alice' },
],
users: [
{ id: 'u-alice', username: 'alice' },
{ id: 'u-bob', username: 'bob' },
],
});
const ranking = await svc.getRanking(mgr);
expect(ranking[0].playerId).toBe('u-alice');
expect(ranking[1].playerId).toBe('u-bob');
});
});
describe('ScoreboardService.getMatrix', () => {
it('marks top-3 positions and sorts challenges by solve count DESC then name', async () => {
const svc = new ScoreboardService(fakeSettings, fakeEventStatus);
const mgr = buildMockManager({
solves: [
{ id: 's1', challengeId: 'c1', userId: 'u-a', solvedAt: '2025-01-01T00:00:00.000Z', pointsAwarded: 50, username: 'a' },
{ id: 's2', challengeId: 'c1', userId: 'u-b', solvedAt: '2025-01-01T00:01:00.000Z', pointsAwarded: 50, username: 'b' },
{ id: 's3', challengeId: 'c1', userId: 'u-c', solvedAt: '2025-01-01T00:02:00.000Z', pointsAwarded: 50, username: 'c' },
{ id: 's4', challengeId: 'c1', userId: 'u-d', solvedAt: '2025-01-01T00:03:00.000Z', pointsAwarded: 50, username: 'd' },
{ id: 's5', challengeId: 'c2', userId: 'u-a', solvedAt: '2025-01-01T00:04:00.000Z', pointsAwarded: 50, username: 'a' },
],
challenges: [
{ id: 'c1', name: 'alpha', initialPoints: 500, minimumPoints: 100, decaySolves: 10, categoryAbbreviation: 'CRY' },
{ id: 'c2', name: 'beta', initialPoints: 300, minimumPoints: 50, decaySolves: 5, categoryAbbreviation: 'WEB' },
],
users: [
{ id: 'u-a', username: 'a' },
{ id: 'u-b', username: 'b' },
{ id: 'u-c', username: 'c' },
{ id: 'u-d', username: 'd' },
],
});
const matrix = await svc.getMatrix(mgr);
expect(matrix.challenges[0].id).toBe('c1');
expect(matrix.challenges[1].id).toBe('c2');
expect(matrix.cells['u-a']?.['c1']).toBe(1);
expect(matrix.cells['u-b']?.['c1']).toBe(2);
expect(matrix.cells['u-c']?.['c1']).toBe(3);
expect(matrix.cells['u-d']?.['c1']).toBe('solved');
expect(matrix.cells['u-a']?.['c2']).toBe(1);
expect(matrix.cells['u-b']?.['c2']).toBeNull();
});
});
describe('ScoreboardService.getGraph', () => {
it('prepends start point and appends end point, limits to top 10', async () => {
const settings: any = {
get: jest.fn().mockImplementation(async (k: string) => {
if (k === 'eventStartUtc') return '2025-01-01T00:00:00.000Z';
if (k === 'eventEndUtc') return '2025-01-02T00:00:00.000Z';
return '';
}),
};
const eventStatus: any = {
getState: jest.fn().mockResolvedValue({
state: 'running',
serverNowUtc: '2025-01-01T12:00:00.000Z',
eventStartUtc: '2025-01-01T00:00:00.000Z',
eventEndUtc: '2025-01-02T00:00:00.000Z',
secondsToStart: null,
secondsToEnd: 43200,
}),
};
const svc = new ScoreboardService(settings, eventStatus);
const mgr = buildMockManager({
solves: [
{ id: 's1', challengeId: 'c1', userId: 'u-a', solvedAt: '2025-01-01T01:00:00.000Z', pointsAwarded: 115, username: 'a' },
{ id: 's2', challengeId: 'c2', userId: 'u-a', solvedAt: '2025-01-01T02:00:00.000Z', pointsAwarded: 60, username: 'a' },
],
challenges: [
{ id: 'c1', name: 'alpha', initialPoints: 500, minimumPoints: 100, decaySolves: 10, categoryAbbreviation: 'CRY' },
{ id: 'c2', name: 'beta', initialPoints: 300, minimumPoints: 50, decaySolves: 5, categoryAbbreviation: 'WEB' },
],
});
const graph = await svc.getGraph(mgr);
expect(graph.series).toHaveLength(1);
const s = graph.series[0];
expect(s.playerId).toBe('u-a');
expect(s.points[0]).toEqual({ tUtc: '2025-01-01T00:00:00.000Z', value: 0 });
expect(s.points[s.points.length - 1]).toEqual({ tUtc: '2025-01-02T00:00:00.000Z', value: 515 + 315 });
});
it('returns empty series when event not configured', async () => {
const svc = new ScoreboardService(fakeSettings, fakeEventStatus);
const graph = await svc.getGraph(buildMockManager({}));
expect(graph.series).toEqual([]);
expect(graph.startUtc).toBeNull();
expect(graph.endUtc).toBeNull();
});
});
describe('ScoreboardService.getEventLog', () => {
it('returns rows with computed position from same-challenge order', async () => {
const svc = new ScoreboardService(fakeSettings, fakeEventStatus);
const solves = [
{ id: 's1', challengeId: 'c1', userId: 'u-a', solvedAt: '2025-01-01T00:00:00.000Z', pointsAwarded: 115, basePoints: 100, rankBonus: 15, username: 'a', challengeName: 'alpha', categoryAbbreviation: 'CRY' },
{ id: 's2', challengeId: 'c1', userId: 'u-b', solvedAt: '2025-01-01T00:01:00.000Z', pointsAwarded: 110, basePoints: 100, rankBonus: 10, username: 'b', challengeName: 'alpha', categoryAbbreviation: 'CRY' },
];
const mgr = buildMockManager({ solves });
const log = await svc.getEventLog(mgr, 10);
expect(log).toHaveLength(2);
const bySolveId = new Map(log.map((r: any) => [r.solveId, r]));
expect((bySolveId.get('s1') as any).position).toBe(1);
expect((bySolveId.get('s2') as any).position).toBe(2);
});
});