Compare commits

..
124 Commits
Author SHA1 Message Date
dahyeon bb336391ff docs: make readme demo loop 2026-06-09 06:28:15 -07:00
dahyeon 3f4ddead72 docs: update release readme media 2026-06-09 06:25:41 -07:00
dahyeon 168e0eca66 docs: refresh readme for release 77 2026-06-09 06:17:45 -07:00
dahyeon e7eaa4f67d fix(web): stack mobile tier badges 2026-06-09 04:51:37 -07:00
dahyeon ad9bf93b52 fix(web): increase light mode text contrast 2026-06-09 04:48:18 -07:00
dahyeon 774707de65 fix(web): enlarge desktop position text 2026-06-09 04:03:00 -07:00
dahyeon e28a2646bf fix(web): add slight tier badge spacing 2026-06-09 04:01:37 -07:00
dahyeon 2916333d71 fix(web): align tier queue columns 2026-06-09 03:59:53 -07:00
dahyeon d3d5f2b348 fix(web): prevent logout button overflow 2026-06-09 03:54:11 -07:00
dahyeon 4657cd453c fix(web): scale match participant icons with text 2026-06-09 03:38:13 -07:00
dahyeon 577ce45b64 fix(web): align header and match badges with brand styling 2026-06-09 03:37:11 -07:00
dahyeon ee3e5935d6 fix(web): stabilize recruiting mobile participant list 2026-06-09 03:17:49 -07:00
dahyeon 5ba68ea134 fix(web): improve compact UI readability 2026-06-09 03:12:00 -07:00
dahyeon 12869a7e9e fix(web): stabilize participant filter table 2026-06-08 23:10:39 -07:00
dahyeon d10e2ab011 fix(web): keep history table shell during loading 2026-06-08 22:48:16 -07:00
dahyeon 170e42098a fix(web): stabilize history table columns 2026-06-08 22:32:22 -07:00
dahyeon fe7a482969 fix(web): localize history pagination loading 2026-06-08 22:24:20 -07:00
dahyeon aa07ec0304 feat(api): add dakao schedule links 2026-06-08 21:44:28 -07:00
dahyeon cd5a82aa93 fix(web): refine mobile history cards 2026-06-08 05:39:22 -07:00
dahyeon 7a62e52d60 fix(web): improve mobile team layout 2026-06-08 05:24:14 -07:00
dahyeon 6fc58fec1d feat(web): add legal footer 2026-06-08 04:50:29 -07:00
dahyeon f586542dc3 fix(web): split home matches by schedule 2026-06-08 04:44:12 -07:00
dahyeon 6697cd8ea1 feat(api): add dakao primary account command 2026-06-08 03:29:55 -07:00
dahyeon c435e8a6a5 fix(web): stabilize match tier queue alignment 2026-06-08 02:32:11 -07:00
dahyeon 15ae680ec7 fix(web): bind dark utilities to theme toggle 2026-06-08 02:25:59 -07:00
dahyeon bdea0287a5 refactor(web): centralize rank badge display 2026-06-08 02:20:34 -07:00
dahyeon b56728f843 fix(web): align match team table columns 2026-06-08 02:07:56 -07:00
dahyeon 7f2b34fd4b fix(web): stabilize layout when scrollbar changes 2026-06-08 02:02:03 -07:00
dahyeon 146349beb8 fix(web): tone down login link 2026-06-08 01:49:20 -07:00
dahyeon 326e0c66b6 feat(web): add persistent theme toggle 2026-06-08 01:46:59 -07:00
dahyeon edfb960e97 fix(web): highlight shared current peak tier 2026-06-08 01:41:23 -07:00
dahyeon b2d438785b fix(web): pad compact tier chart domain 2026-06-08 01:34:09 -07:00
dahyeon b6dad78d02 fix(web): add adaptive compact tier guides 2026-06-08 01:28:10 -07:00
dahyeon 42d4854f9c fix(web): center compact tier chart labels 2026-06-08 01:15:55 -07:00
dahyeon e9081d77c9 fix(web): keep auction tier labels inside chart 2026-06-08 01:07:39 -07:00
dahyeon 181beb85e5 refactor(web): simplify auction tier chart 2026-06-08 01:02:52 -07:00
dahyeon ebca348723 feat: show tier history in auction spotlight 2026-06-08 00:34:04 -07:00
dahyeon de8bc87940 fix: unify riot refresh rate gating 2026-06-07 11:11:12 -07:00
dahyeon 25f3ccad57 fix: delete acknowledged riot job stream entries 2026-06-07 10:13:29 -07:00
dahyeon 55ab5b27dc chore: update Cloudflare Pages deploy branch handling 2026-06-07 09:54:10 -07:00
dahyeon 1c0af891fa feat: run Riot background refresh by default 2026-06-07 09:51:51 -07:00
dahyeon 528744ebf6 fix: accept Riot league entries without leagueId 2026-06-07 09:51:37 -07:00
dahyeon bd52160d91 fix(web): resolve recharts vite interop 2026-06-07 09:01:02 -07:00
dahyeon c3a3eb46dd feat(web): add tier history chart 2026-06-07 08:11:43 -07:00
dahyeon be5383a2e9 fix(riot): persist refreshed tier state 2026-06-07 07:59:11 -07:00
dahyeon ef693fcf4a feat(auction): cancel active auction 2026-06-07 07:44:59 -07:00
dahyeon 8a9dd37755 chore(release): bump build number to 68 2026-06-07 07:44:32 -07:00
dahyeon 5ad0f8a1c2 feat: add auction chat 2026-06-07 07:20:35 -07:00
dahyeon c4f19d256d fix: refresh riot tiers from history jobs 2026-06-07 07:16:31 -07:00
dahyeon ad84bf1f89 feat(web): show participant position counts 2026-06-07 07:07:48 -07:00
dahyeon b711c63dcd fix(api): keep zero-bid auction passes open 2026-06-07 07:01:01 -07:00
dahyeon 6a192276e8 feat(admin): manage match participants 2026-06-07 06:51:35 -07:00
dahyeon 994a9fcad0 feat(web): filter match participants 2026-06-07 06:28:11 -07:00
dahyeon 2dae3c7cae chore(web): add start scripts for modes 2026-06-07 06:27:51 -07:00
dahyeon a896342429 chore(web): limit upcoming match cards 2026-06-07 06:03:30 -07:00
dahyeon 7b636ee793 fix: preserve dakao result subjects on outbox retry 2026-06-07 05:57:44 -07:00
dahyeon e63fba0286 feat: include dakao send result subjects 2026-06-07 05:30:53 -07:00
dahyeon 245a096606 chore(web): hide api live indicator 2026-06-07 05:00:20 -07:00
dahyeon 6e0afe84cd chore(deploy): add build number release flow 2026-06-07 04:54:08 -07:00
dahyeon 6accb4b166 chore(api): allow pages dev cors origins 2026-06-07 01:26:07 -07:00
dahyeon f3d05004ce chore(env): update staging api origin 2026-06-07 01:24:21 -07:00
dahyeon eadae789c8 chore(env): rename test environment to staging 2026-06-07 01:01:13 -07:00
dahyeon d0d578b2b0 feat(dakao): add jetstream outbox delivery flow 2026-06-07 00:35:18 -07:00
dahyeon 4ab3c3a135 chore(auction): remove unused chat panel prop 2026-06-06 21:58:19 -07:00
dahyeon 251eb6deb9 fix(api): send bearer tokens for authenticated requests 2026-06-06 21:57:52 -07:00
dahyeon b7886589cb chore(docker): let runtime set node env 2026-06-06 21:57:07 -07:00
dahyeon 33abda997f Default secrets to environment source 2026-06-06 13:12:48 -07:00
dahyeonandClaude Opus 4.7 85ba8044da feat(web): add pool sidebar and chat skeleton to auction page
Surface the remaining player pool (waiting + passed) on a left sidebar
so captains can see who still needs a team without revealing the auction
order — entries are sorted by summoner name. Reserve a right sidebar
for the upcoming chat integration.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-30 03:53:24 -07:00
dahyeon e306d696a9 feat: randomize auction player order 2026-05-30 03:15:01 -07:00
dahyeon da5f542292 feat: add agent skill workflows 2026-05-30 18:45:09 +09:00
dahyeon f62e0db849 docs: update project README 2026-05-13 14:12:35 +09:00
dahyeon 3176db8c48 docs: add project README 2026-05-13 13:51:05 +09:00
dahyeon 7620b1677a chore(repo): ignore local artifacts 2026-05-08 02:42:00 +09:00
dahyeon 1d7fdc9622 chore(app): wire remaining modules 2026-05-05 23:19:00 +09:00
dahyeon 9c05850cba chore(api): add data migrations 2026-05-02 22:23:00 +09:00
dahyeon b5aa58dde8 feat(api): handle Dakao match commands 2026-04-29 03:02:00 +09:00
dahyeon 3b2ac601a0 feat(api): handle Dakao registrations 2026-04-29 01:35:00 +09:00
dahyeon 404f7713b9 feat(api): parse Dakao commands 2026-04-28 23:58:00 +09:00
dahyeon ba3894cba2 feat(api): add Dakao integration 2026-04-28 22:37:00 +09:00
dahyeon 9ebdc9b61f feat(web): add team progress page 2026-04-27 02:51:00 +09:00
dahyeon 5fda22c36a feat(web): add match admin page 2026-04-27 01:26:00 +09:00
dahyeon 1e304f48e5 feat(web): add legacy import admin 2026-04-26 23:44:00 +09:00
dahyeon ad3c37c48c feat(api): add legacy import service 2026-04-26 22:16:00 +09:00
dahyeon f266d1de83 feat(web): add community stats pages 2026-04-25 01:38:00 +09:00
dahyeon 956e45ee59 feat(api): add match stats fragments 2026-04-24 23:53:00 +09:00
dahyeon b3b59d37fc feat(api): add community stats API 2026-04-24 22:28:00 +09:00
dahyeon fc81beec45 feat(api): add match history endpoints 2026-04-23 01:07:00 +09:00
dahyeon 3447162aa5 feat(api): collect tournament results 2026-04-22 23:48:00 +09:00
dahyeon 06c190a41f feat(api): add tournament result mapping 2026-04-22 22:21:00 +09:00
dahyeon 862d662a51 feat(web): add tournament code admin 2026-04-21 01:34:00 +09:00
dahyeon 95c8ed3c8b feat(api): add tournament code pool 2026-04-20 23:59:00 +09:00
dahyeon 6bad4861e6 feat(api): add tournament code helpers 2026-04-20 22:42:00 +09:00
dahyeon 422472a641 feat(web): add user history page 2026-04-19 03:10:00 +09:00
dahyeon 7e78b1f92d feat(api): add background refresh 2026-04-19 01:29:00 +09:00
dahyeon 4bc2df7bcc feat(api): add Riot refresh queue 2026-04-18 23:57:00 +09:00
dahyeon c212505ffe feat(api): add recent stats summaries 2026-04-18 22:24:00 +09:00
dahyeon 9ac777b5a4 feat(api): add recent match sync 2026-04-17 01:46:00 +09:00
dahyeon c07b040467 feat(api): add Riot rate limiter 2026-04-17 00:14:00 +09:00
dahyeon 78a8f136d0 feat(web): add auction page 2026-04-16 22:33:00 +09:00
dahyeon 3c8dce1e9b feat(api): add auction gateway 2026-04-15 02:18:00 +09:00
dahyeon b12f44424e feat(api): add auction service 2026-04-15 00:51:00 +09:00
dahyeon b4be06ae83 feat(web): add match detail page 2026-04-14 23:28:00 +09:00
dahyeon 041b1fc8b9 feat(web): add API hooks and mappers 2026-04-14 22:09:00 +09:00
dahyeon 87447a4f09 feat(api): add match management 2026-04-13 02:40:00 +09:00
dahyeon 6cd213a462 feat(api): add community endpoints 2026-04-13 01:12:00 +09:00
dahyeon caf517123b feat(api): add user profile endpoints 2026-04-12 23:46:00 +09:00
dahyeon d4b790fd86 feat(api): add auth guards 2026-04-12 22:17:00 +09:00
dahyeon 3a86676a12 feat(web): add auth and home pages 2026-04-11 02:31:00 +09:00
dahyeon 9fbb11c634 feat(web): add app shell 2026-04-11 00:58:00 +09:00
dahyeon 39f3221640 feat(web): add client utilities 2026-04-10 23:39:00 +09:00
dahyeon a796620b7f feat(web): add static assets 2026-04-10 22:26:00 +09:00
dahyeon 3a3e7938f5 feat(web): configure Vite app 2026-04-09 03:08:00 +09:00
dahyeon 9f6974c577 feat(api): add Riot webhook 2026-04-09 01:24:00 +09:00
dahyeon d6f52a8b15 feat(api): enrich Riot accounts 2026-04-08 23:55:00 +09:00
dahyeon 463c839782 feat(api): add Riot match and ddragon services 2026-04-08 22:41:00 +09:00
dahyeon 5361dc8adb feat(api): add Riot account services 2026-04-07 02:36:00 +09:00
dahyeon 54db90b0df feat(api): add Riot client types 2026-04-07 01:09:00 +09:00
dahyeon 2e311d9cbf feat(api): add shared infrastructure 2026-04-06 23:48:00 +09:00
dahyeon f24674b12c feat(api): add database schema 2026-04-06 22:34:00 +09:00
dahyeon 714349d519 feat(api): add database connection 2026-04-05 03:12:00 +09:00
dahyeon 7cde555bef feat(api): add app bootstrap 2026-04-05 01:43:00 +09:00
dahyeon a7820444fc chore(api): configure Nest app 2026-04-05 00:21:00 +09:00
dahyeon fa13bc48d4 chore(repo): add runtime config 2026-04-04 23:06:00 +09:00
dahyeon 6f891c36af chore(repo): set workspace baseline 2026-04-04 22:18:00 +09:00
232 changed files with 27544 additions and 12458 deletions

No files matched your search

+11 -2
View File
@@ -1,5 +1,5 @@
bin/
lib/
/lib/
dist/
node_modules/
.pnpm-store/
@@ -23,4 +23,13 @@ website/LICENSE
*.temp.MD
*.md
*.md
!README.md
!AGENTS.md
!agents/**/*.md
!skills/**/*.md
/tmp/
/user-game-history/
/*.txt
/*.png
BIN
View File
Binary file not shown.

Before

Width:  |  Height:  |  Size: 383 KiB

+189
View File
@@ -0,0 +1,189 @@
# AGENTS.md
This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, Antigravity, etc.) when working with code in this repository.
## Repository Overview
A collection of skills for Claude.ai and Claude Code for senior software engineers. Skills are packaged instructions and scripts that extend Claude and your coding agents capabilities.
## OpenCode Integration
OpenCode uses a **skill-driven execution model** powered by the `skill` tool and this repository's `/skills` directory.
### Core Rules
- If a task matches a skill, you MUST invoke it
- Skills are located in `skills/<skill-name>/SKILL.md`
- Never implement directly if a skill applies
- Always follow the skill instructions exactly (do not partially apply them)
### Intent → Skill Mapping
The agent should automatically map user intent to skills:
- Feature / new functionality → `spec-driven-development`, then `incremental-implementation`, `test-driven-development`
- Planning / breakdown → `planning-and-task-breakdown`
- Bug / failure / unexpected behavior → `debugging-and-error-recovery`
- Code review → `code-review-and-quality`
- Refactoring / simplification → `code-simplification`
- API or interface design → `api-and-interface-design`
- UI work → `frontend-ui-engineering`
### Lifecycle Mapping (Implicit Commands)
OpenCode does not support slash commands like `/spec` or `/plan`.
Instead, the agent must internally follow this lifecycle:
- DEFINE → `spec-driven-development`
- PLAN → `planning-and-task-breakdown`
- BUILD → `incremental-implementation` + `test-driven-development`
- VERIFY → `debugging-and-error-recovery`
- REVIEW → `code-review-and-quality`
- SHIP → `shipping-and-launch`
### Execution Model
For every request:
1. Determine if any skill applies (even 1% chance)
2. Invoke the appropriate skill using the `skill` tool
3. Follow the skill workflow strictly
4. Only proceed to implementation after required steps (spec, plan, etc.) are complete
### Anti-Rationalization
The following thoughts are incorrect and must be ignored:
- "This is too small for a skill"
- "I can just quickly implement this"
- "I’ll gather context first"
Correct behavior:
- Always check for and use skills first
This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement.
## Orchestration: Personas, Skills, and Commands
This repo has three composable layers. They have different jobs and should not be confused:
- **Skills** (`skills/<name>/SKILL.md`) — workflows with steps and exit criteria. The *how*. Mandatory hops when an intent matches.
- **Personas** (`agents/<role>.md`) — roles with a perspective and an output format. The *who*.
- **Slash commands** (`.claude/commands/*.md`) — user-facing entry points. The *when*. The orchestration layer.
Composition rule: **the user (or a slash command) is the orchestrator. Personas do not invoke other personas.** A persona may invoke skills.
The only multi-persona orchestration pattern this repo endorses is **parallel fan-out with a merge step** — used by `/ship` to run `code-reviewer`, `security-auditor`, and `test-engineer` concurrently and synthesize their reports. Do not build a "router" persona that decides which other persona to call; that's the job of slash commands and intent mapping.
See [agents/README.md](agents/README.md) for the decision matrix and [references/orchestration-patterns.md](references/orchestration-patterns.md) for the full pattern catalog.
**Claude Code interop:** the personas in `agents/` work as Claude Code subagents (auto-discovered from this plugin's `agents/` directory) and as Agent Teams teammates (referenced by name when spawning). Two platform constraints align with our rules: subagents cannot spawn other subagents, and teams cannot nest. Plugin agents silently ignore the `hooks`, `mcpServers`, and `permissionMode` frontmatter fields.
## Creating a New Skill
### Directory Structure
```
skills/
{skill-name}/ # kebab-case directory name
SKILL.md # Required: skill definition
scripts/ # Required: executable scripts
{script-name}.sh # Bash scripts (preferred)
{skill-name}.zip # Required: packaged for distribution
```
### Naming Conventions
- **Skill directory**: `kebab-case` (e.g. `web-quality`)
- **SKILL.md**: Always uppercase, always this exact filename
- **Scripts**: `kebab-case.sh` (e.g., `deploy.sh`, `fetch-logs.sh`)
- **Zip file**: Must match directory name exactly: `{skill-name}.zip`
### SKILL.md Format
```markdown
---
name: {skill-name}
description: {One sentence describing what the skill does, followed by one or more "Use when" trigger conditions. Include trigger phrases like "Deploy my app" or "Check logs" when helpful.}
---
# {Skill Title}
{Brief overview of what the skill does and why it matters.}
## How It Works
{Numbered list explaining the skill's workflow}
Equivalent headings like `Workflow`, `Core Process`, or `When to Use` are fine when they communicate the same structure clearly.
## Usage (Optional)
Include this section only if the skill ships runnable helpers under `scripts/`. Markdown-only skills can omit both the section and the directory entirely.
```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]
```
**Arguments:**
- `arg1` - Description (defaults to X)
**Examples:**
{Show 2-3 common usage patterns}
## Output
{Show example output users will see}
## Present Results to User
{Template for how Claude should format results when presenting to users}
## Troubleshooting
{Common issues and solutions, especially network/permissions errors}
```
### Best Practices for Context Efficiency
Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:
- **Keep SKILL.md under 500 lines** — put detailed reference material in separate files
- **Write specific descriptions** — helps the agent know exactly when to activate the skill
- **Use progressive disclosure** — reference supporting files that get read only when needed
- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
- **File references work one level deep** — link directly from SKILL.md to supporting files
### Script Requirements
- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`
### Creating the Zip Package
After creating or updating a skill:
```bash
cd skills
zip -r {skill-name}.zip {skill-name}/
```
### End-User Installation
Document these two installation methods for users:
**Claude Code:**
```bash
cp -r skills/{skill-name} ~/.claude/skills/
```
**claude.ai:**
Add the skill to project knowledge or paste SKILL.md contents into the conversation.
If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.
+1
View File
@@ -0,0 +1 @@
77
-43
View File
@@ -1,43 +0,0 @@
# Cloudflare Pages 배포
## 최초 1회 준비
```bash
pnpm --filter web pages:login
pnpm --filter web exec wrangler pages project create lolympus --production-branch main
```
프로젝트명을 바꾸려면 배포 시 `CF_PAGES_PROJECT_NAME` 환경변수로 지정한다.
## 환경 파일
Vite는 빌드 시점에 환경변수를 번들에 포함한다.
```bash
cp apps/web/.env.test.example apps/web/.env.test
cp apps/web/.env.production.example apps/web/.env.production
```
각 파일에서 API URL, community ID, MSAL 설정을 실제 값으로 채운다.
## 배포
```bash
pnpm deploy:web:test
pnpm deploy:web:prod
```
- `test`: `vite build --mode test` 후 Cloudflare Pages `test` preview branch로 배포
- `prod`: `vite build --mode production` 후 Cloudflare Pages production으로 배포
기본 Cloudflare Pages project name은 `lolympus`다.
```bash
CF_PAGES_PROJECT_NAME=lolympus-web pnpm deploy:web:prod
CF_PAGES_TEST_BRANCH=staging pnpm deploy:web:test
```
## SPA / 캐시
- `apps/web/public/_redirects`: React Router 경로 새로고침을 `/index.html`로 fallback
- `apps/web/public/_headers`: fingerprinted `/assets/*`는 1년 immutable 캐시, `index.html`은 no-cache
-481
View File
@@ -1,481 +0,0 @@
# Dakao NATS Command API
dakao는 NATS를 통해 외부 시스템으로부터 command를 받아 LOCO 세션에 반영할 수 있다.
현재 구현 기준으로 지원하는 command는 아래 2종이다.
- `chat.send-text`
기존 API. `text`와 `extra`를 그대로 받아 전송한다.
점진적으로 deprecated 예정.
- `chat.send-message`
신규 권장 API. `segments` 기반으로 텍스트, 멘션, 카카오톡 이모티콘을 조합해서 전송한다.
builder를 거치면서 semantic validation까지 수행한다.
## 개요
### 기본 subject
| 용도 | 기본 subject | 비고 |
| ------------------ | ------------------------------------ | --------------- |
| 레거시 텍스트 전송 | `dakao.command.chat.send-text.v1` | deprecated 예정 |
| 신규 메시지 전송 | `dakao.command.chat.send-message.v1` | 권장 |
### 관련 환경변수
| 키 | 의미 |
| ---------------------------------------------- | ------------------------------- |
| `DAKAO_NATS_COMMANDS_ENABLED` | `1`이면 command consumer 활성화 |
| `DAKAO_NATS_COMMAND_CHAT_SEND_TEXT_SUBJECT` | 레거시 subject override |
| `DAKAO_NATS_COMMAND_CHAT_SEND_MESSAGE_SUBJECT` | 신규 subject override |
### 전송 포맷
- NATS payload는 JSON object여야 한다.
- 내부 구현은 `JSON.stringify(...)`로 publish하고, subscribe 시 `JSON.parse(...)`로 역직렬화한다.
- 응답은 NATS의 transport-level reply가 아니라, command object 내부의 `replySubject` 필드를 사용해 별도 publish된다.
### subject와 `type`의 관계
운영 규약상 아래처럼 맞춰서 보내는 것을 권장한다.
- `dakao.command.chat.send-text.v1` 에는 `type: "chat.send-text"`
- `dakao.command.chat.send-message.v1` 에는 `type: "chat.send-message"`
현재 구현은 두 subject를 모두 구독한 뒤 `type`으로 실제 처리를 분기한다.
즉 subject와 type이 어긋나도 처리될 수 있지만, 운영 혼선을 막기 위해 반드시 맞춰서 보내는 것을 권장한다.
## 공통 Envelope
모든 command는 아래 envelope를 사용한다.
```json
{
"schema": "dakao.command.v1",
"id": "cmd-001",
"type": "chat.send-message",
"source": "my-service",
"correlationId": "trace-001",
"replySubject": "dakao.result.my-service",
"payload": {}
}
```
### 공통 필드
| 필드 | 타입 | 필수 | 설명 |
| --------------- | ------ | ---- | -------------------------------- |
| `schema` | string | Y | 현재는 반드시 `dakao.command.v1` |
| `id` | string | Y | command 고유 ID |
| `type` | string | Y | command 종류 |
| `source` | string | Y | producer 식별자 |
| `correlationId` | string | N | 추적용 상관관계 ID |
| `replySubject` | string | N | 결과를 publish할 subject |
| `payload` | object | Y | command 본문 |
### 공통 검증
- 문자열 필드인 `id`, `type`, `source`, `correlationId`, `replySubject`는 trim 후 빈 문자열이면 거부된다.
- 최상위 object와 payload는 정의되지 않은 필드를 허용하지 않는다.
- `replySubject`가 없으면 처리 결과는 publish되지 않는다.
## Command: `chat.send-text`
### 상태
- 레거시 API
- 기존 producer 호환성을 위해 유지 중
- `text`와 `extra`를 그대로 전달하므로, 멘션/이모티콘 semantic validation은 수행하지 않는다
### 권장 subject
```text
dakao.command.chat.send-text.v1
```
### Payload
```json
{
"chatroomId": "123456789012345678",
"text": "hello",
"attachment": {
"example": true
},
"extra": "{}"
}
```
| 필드 | 타입 | 필수 | 설명 |
| ------------ | ---------------- | ---- | ------------------------------------------------------- |
| `chatroomId` | string | Y | 채팅방 ID. 실운영에서는 decimal string 사용 권장 |
| `text` | string | Y | 보낼 메시지 본문 |
| `attachment` | string or object | N | 첨부 payload. object면 전송 직전에 JSON string으로 변환 |
| `extra` | string | N | LOCO `WRITE.extra` raw 값 |
### 동작
- 내부적으로 `client.sendMessage(chatroomId, text, { attachment, extra })` 로 전송한다.
- `extra`를 생략하면 최종 LOCO 전송 시 기본값 `"{}"` 가 사용된다.
- 이 API는 `extra` 구조를 검증하지 않는다.
### 예시
```json
{
"schema": "dakao.command.v1",
"id": "cmd-text-001",
"type": "chat.send-text",
"source": "admin-panel",
"replySubject": "dakao.result.admin-panel",
"payload": {
"chatroomId": "123456789012345678",
"text": "plain text message",
"extra": "{}"
}
}
```
## Command: `chat.send-message`
### 상태
- 신규 권장 API
- 텍스트, 멘션, 카카오톡 이모티콘을 조합해서 전송할 수 있다
- `buildLocoMessage(...)` 를 통해 최종 `text`와 `extra`를 생성한다
- Joi schema validation 이후 builder semantic validation이 한 번 더 수행된다
### 권장 subject
```text
dakao.command.chat.send-message.v1
```
### Payload
```json
{
"chatroomId": "123456789012345678",
"segments": [
{ "kind": "text", "text": "안녕하세요 " },
{
"kind": "mention",
"userId": "6215844374579825921",
"displayText": "날으는꼴뚜기/95/여/D"
},
{ "kind": "text", "text": " " },
{ "kind": "emoticon", "id": "1200281_004", "altText": "플라워" }
],
"attachment": {
"example": true
},
"type": 1,
"noSeen": false,
"scope": 1,
"silence": false
}
```
| 필드 | 타입 | 필수 | 설명 |
| ------------ | ---------------- | ---- | ------------------------------------------------------- |
| `chatroomId` | string | Y | 채팅방 ID. 실운영에서는 decimal string 사용 권장 |
| `segments` | array | Y | 메시지 세그먼트 배열. 최소 1개 이상 |
| `attachment` | string or object | N | 첨부 payload. object면 전송 직전에 JSON string으로 변환 |
| `type` | integer | N | LOCO `WRITE.type`. 기본값 `1` |
| `noSeen` | boolean | N | LOCO `WRITE.noSeen`. 기본값 `false` |
| `scope` | integer | N | LOCO `WRITE.scope`. 기본값 `1` |
| `silence` | boolean | N | LOCO `WRITE.silence`. 기본값 `false` |
### Segment 종류
#### `text`
```json
{ "kind": "text", "text": "안녕하세요 " }
```
| 필드 | 타입 | 필수 | 설명 |
| ------ | ------ | ---- | -------------------------------------- |
| `kind` | string | Y | 반드시 `text` |
| `text` | string | Y | 일반 텍스트. 빈 문자열은 허용되지 않음 |
#### `mention`
```json
{
"kind": "mention",
"userId": "6215844374579825921",
"displayText": "날으는꼴뚜기/95/여/D"
}
```
| 필드 | 타입 | 필수 | 설명 |
| ------------- | ------ | ---- | --------------------------------------------------------- |
| `kind` | string | Y | 반드시 `mention` |
| `userId` | string | Y | 양의 정수 문자열 권장. int64 손실 방지를 위해 문자열 사용 |
| `displayText` | string | Y | 화면에 표시될 이름. builder가 앞의 `@`를 자동 정리 |
멘션은 최종 메시지에서 아래처럼 렌더링된다.
```text
@{displayText}
```
예를 들어 `displayText: "홍길동"` 이면 `@홍길동` 으로 전송된다.
`displayText`를 `@홍길동`처럼 보내도 builder가 앞의 `@` 하나를 제거한 뒤 다시 렌더링한다.
#### `emoticon`
```json
{
"kind": "emoticon",
"id": "1200281_004",
"altText": "플라워"
}
```
| 필드 | 타입 | 필수 | 설명 |
| --------- | ------ | ---- | --------------------------------------- |
| `kind` | string | Y | 반드시 `emoticon` |
| `id` | string | Y | 카카오톡 이모티콘 item ID |
| `altText` | string | Y | 대체 텍스트. builder가 괄호를 자동 정리 |
이모티콘은 최종 메시지에서 아래처럼 렌더링된다.
```text
({altText})
```
예를 들어 `altText: "플라워"` 이면 `(플라워)` 로 전송된다.
`altText`를 `(플라워)`처럼 보내도 builder가 바깥 괄호를 제거한 뒤 다시 렌더링한다.
### Builder semantic validation
`chat.send-message`는 schema validation 외에 아래 규칙도 검사한다.
#### 공통
- 최종적으로 만들어진 메시지 전체 텍스트는 비어 있으면 안 된다
- `segments`가 모두 비어 있거나 렌더링 결과가 빈 문자열이면 거부된다
#### mention 규칙
- `userId`는 양의 정수여야 한다
- producer에서는 숫자 대신 문자열 사용을 권장한다
- `displayText`는 비어 있으면 안 된다
- 같은 `userId`를 여러 번 멘션하면 `extra.mentions[].at` 배열로 합쳐진다
- 같은 `userId`를 서로 다른 길이의 `displayText`로 섞어 보내면 거부된다
#### emoticon 규칙
- `id`는 trim 후 비어 있으면 안 된다
- `altText`는 trim 후 비어 있으면 안 된다
- `altText` 내부에는 `@`, `(`, `)` 문자가 들어가면 안 된다
- 같은 `(id, 렌더링 길이)` 조합의 이모티콘은 `extra.emojis.items[].at` 배열로 합쳐진다
#### `extra` 생성 규칙
producer가 `extra`를 직접 만들지 않는다.
builder가 최종 텍스트를 기준으로 아래 구조를 자동 생성한다.
```json
{
"mentions": [
{
"user_id": 6215844374579825921,
"at": [1],
"len": 13
}
],
"emojis": {
"total_item": 1,
"total_len": 5,
"items": [
{
"id": "1200281_004",
"len": 5,
"at": [1]
}
]
}
}
```
주의:
- `mentions[].at` 는 메시지 안의 `@` anchor 순번이다
- `emojis.items[].at` 는 메시지 안의 `(` anchor 순번이다
- `len` 은 렌더링된 문자열 길이 기준이다
- `total_item` 은 이모티콘 총 출현 횟수다
- `total_len` 은 각 이모티콘 렌더링 길이의 합이다
### 예시: 추천 전송
```json
{
"schema": "dakao.command.v1",
"id": "cmd-msg-001",
"type": "chat.send-message",
"source": "admin-panel",
"correlationId": "trace-20260417-001",
"replySubject": "dakao.result.admin-panel",
"payload": {
"chatroomId": "123456789012345678",
"segments": [
{ "kind": "text", "text": "😄 " },
{
"kind": "mention",
"userId": "6215844374579825921",
"displayText": "날으는꼴뚜기/95/여/D"
},
{ "kind": "text", "text": " " },
{ "kind": "emoticon", "id": "1200281_004", "altText": "플라워" },
{ "kind": "emoticon", "id": "1200281_003", "altText": "네잎클로버" }
],
"type": 1,
"noSeen": false,
"scope": 1,
"silence": false
}
}
```
위 payload는 내부적으로 대략 아래 LOCO 메시지로 변환된다.
```json
{
"text": "😄 @날으는꼴뚜기/95/여/D (플라워)(네잎클로버)",
"extra": "{\"mentions\":[{\"user_id\":6215844374579825921,\"at\":[1],\"len\":13}],\"emojis\":{\"total_item\":2,\"total_len\":12,\"items\":[{\"id\":\"1200281_004\",\"len\":5,\"at\":[1]},{\"id\":\"1200281_003\",\"len\":7,\"at\":[2]}]}}"
}
```
## Result API
응답이 필요한 경우 producer는 command에 `replySubject`를 포함해야 한다.
consumer는 처리 후 `replySubject`로 결과 object를 publish한다.
### 공통 Result envelope
```json
{
"schema": "dakao.result.v1",
"id": "cmd-msg-001",
"type": "chat.send-message",
"status": "succeeded",
"handledAt": "2026-04-17T12:34:56.789Z",
"correlationId": "trace-20260417-001",
"result": {}
}
```
### 공통 필드
| 필드 | 타입 | 설명 |
| --------------- | ------ | --------------------------------------- |
| `schema` | string | 현재는 반드시 `dakao.result.v1` |
| `id` | string | 원본 command ID |
| `type` | string | 원본 command type |
| `status` | string | `succeeded` 또는 `failed` |
| `handledAt` | string | ISO-8601 timestamp |
| `correlationId` | string | 원본 correlationId가 있으면 그대로 전달 |
| `result` | object | 성공 시 포함 |
| `error` | object | 실패 시 포함 |
### Success result
`chat.send-text`와 `chat.send-message`의 성공 응답 구조는 동일하다.
```json
{
"schema": "dakao.result.v1",
"id": "cmd-msg-001",
"type": "chat.send-message",
"status": "succeeded",
"handledAt": "2026-04-17T12:34:56.789Z",
"correlationId": "trace-20260417-001",
"result": {
"chatroomId": "123456789012345678",
"messageLength": 31,
"hasAttachment": true
}
}
```
| 필드 | 타입 | 설명 |
| --------------- | ------- | ---------------------------- |
| `chatroomId` | string | 대상 채팅방 ID |
| `messageLength` | number | 실제 전송된 최종 메시지 길이 |
| `hasAttachment` | boolean | attachment가 있으면 포함 |
### Failure result
```json
{
"schema": "dakao.result.v1",
"id": "cmd-msg-001",
"type": "chat.send-message",
"status": "failed",
"handledAt": "2026-04-17T12:34:56.789Z",
"correlationId": "trace-20260417-001",
"error": {
"code": "invalid_command",
"message": "emoticon.altText must not contain '@', '(' or ')': \"(bad@text)\"",
"retryable": false
}
}
```
| 필드 | 타입 | 설명 |
| ----------- | ------- | ------------------------------- |
| `code` | string | 오류 코드 |
| `message` | string | 사람이 읽을 수 있는 오류 메시지 |
| `retryable` | boolean | 재시도 권장 여부 |
### 현재 사용되는 오류 코드
| 코드 | retryable | 의미 |
| -------------------------- | --------- | ----------------------------------------------- |
| `invalid_command` | `false` | envelope/payload/schema/builder validation 실패 |
| `command_execution_failed` | `true` | LOCO 전송 등 실행 단계 실패 |
## 응답 publish 조건
아래 조건이 모두 충족될 때만 실패 응답을 publish할 수 있다.
- `replySubject` 존재
- `id` 존재
- `type` 존재
따라서 malformed payload를 보내더라도 `replySubject`가 없으면 실패 응답은 발행되지 않는다.
producer가 처리 결과를 반드시 받아야 한다면 `replySubject`를 항상 넣는 것을 권장한다.
## 운영 권장사항
### 새 producer는 `chat.send-message`만 사용
권장 이유:
- 멘션과 이모티콘을 구조적으로 표현할 수 있다
- `extra`를 producer가 직접 조립하지 않아도 된다
- semantic validation이 추가로 수행된다
- 향후 레거시 `chat.send-text` 제거 시 마이그레이션 부담이 적다
### `chatroomId`와 `userId`는 문자열 사용
- `userId`는 int64 범위일 수 있으므로 JSON number 대신 string 사용을 권장한다
- `chatroomId`도 실운영에서는 decimal string으로 통일하는 것이 안전하다
### `replySubject`는 항상 지정
- 성공/실패를 추적하려면 `replySubject`를 항상 넣는 것이 좋다
- `correlationId`도 함께 넣어두면 producer 로그와 결과 로그를 쉽게 연결할 수 있다
### `send-text` 사용 시 주의
- `extra` 구조를 잘못 만들면 consumer 단계에서는 걸러지지 않는다
- 멘션, 유니코드 이모지, 카카오톡 이모티콘 혼합 메시지는 `send-message` 사용을 권장한다
## 요약
- 레거시: `dakao.command.chat.send-text.v1` + `type: "chat.send-text"`
- 권장: `dakao.command.chat.send-message.v1` + `type: "chat.send-message"`
- 결과 스키마는 공통으로 `dakao.result.v1`
- 신규 API는 `segments`를 받아 builder 기반으로 `text`와 `extra`를 안전하게 생성한다
+1 -1
View File
@@ -35,7 +35,7 @@ FROM gcr.io/distroless/nodejs24-debian13:nonroot AS runtime
WORKDIR /app
ENV NODE_ENV=prod
# ENV NODE_ENV=prod
COPY --from=prod-deps --chown=nonroot:nonroot /app/package.json ./package.json
COPY --from=prod-deps --chown=nonroot:nonroot /app/node_modules ./node_modules
-433
View File
@@ -1,433 +0,0 @@
# Frontend ↔ Backend 통합 플랜 (Lolympus Tournament Support)
> **대상**: codex에 이어서 작업 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-24
---
## 1. Context
`apps/web`(React 19 + Vite + React Router 7)은 현재 `src/mock.ts`와 `src/auction-mock.ts`의 하드코딩된 더미 데이터로만 화면을 그립니다. 경매 페이지는 `setInterval` 기반 클라이언트 사이드 시뮬레이터(`createMockAuction()`)로 동작합니다.
`apps/api`(NestJS 11 + Mongoose 9)는 Community/User/Match/Auction 스키마와 CRUD 엔드포인트, RBAC 가드(`@Roles`), 글로벌 `ValidationPipe`, `X-Auth-User-Id` 헤더 기반 임시 인증까지 구축되어 있습니다. 하지만 **경매 실시간 푸시(WebSocket) 미구현, CORS 미설정, `MatchParticipant` 스냅샷에 티어 정보 없음, `/me` 같은 편의 엔드포인트 없음**이 통합의 걸림돌입니다.
### 이번 작업의 목표
1. 경매 페이지가 서버 주도 타이머·상태로 10명 관전 + 2명 입찰을 실시간 동기화하도록 **WebSocket 게이트웨이**를 API에 추가
2. 프론트엔드의 모든 mock import를 제거하고 **API 클라이언트 + React Query + Socket.IO 클라이언트**로 교체
3. 초기 MVP는 **단일 기본 커뮤니티** 전제 (env `VITE_DEFAULT_COMMUNITY_ID`)
4. **로그인 UI는 이번 범위에서 제외**. admin 기능은 개발자용 "User ID 수동 입력" 위젯으로 임시 처리
5. `MatchParticipant` 스냅샷에 `tier` 필드 추가 (참여 시점의 primary RiotAccount tier를 복사)
### 비목표 (이번 작업에 포함하지 않음)
- 카카오/디스코드 OAuth 로그인 플로우
- 다중 커뮤니티 전환 UI
- Riot API 실시간 동기화 UI (기존 `RiotAccountService`는 그대로 둠)
- 매치 결과 기록 UI (`MatchResult`)
- 포스트-경매 Riot 토너먼트 코드 발급
---
## 2. 현재 상태 정리 (실사 결과)
### 2.1 백엔드에 이미 있는 것
| 영역 | 파일 | 상태 |
| ----------------------------------------------- | ------------------------------------------------ | ----------- |
| Community CRUD + owner 트랜잭션 | `apps/api/src/modules/community/*` | ✅ |
| Match CRUD + 참여(join) | `apps/api/src/modules/match/*` | ✅ |
| Auction 시작/입찰/낙찰/다음/리셋 | `apps/api/src/modules/auction/*` | ✅ (HTTP만) |
| 스키마 (Community/User/Match/Auction/RiotMatch) | `apps/api/src/modules/global/database/schema.ts` | ✅ |
| `@Roles` + `RolesGuard` + `CurrentUser` | `apps/api/src/modules/auth/*` | ✅ |
| 글로벌 `ValidationPipe` | `apps/api/src/main.ts` | ✅ |
### 2.2 백엔드에 없는 것 (이번에 추가)
1. **CORS** — Vite dev는 `http://localhost:5173`, API는 `http://localhost:3000`. `app.enableCors()` 필요
2. **WebSocket (Socket.IO) 게이트웨이** — auction 상태 푸시 + 클라이언트 입찰 수신
3. **서버 주도 타이머** — 현재 auction 문서에 `maxTimerSeconds`만 있음. 입찰 시 갱신되는 `currentDeadline: Date` 필드 + 만료 자동 `markSold` 스케줄러 필요
4. **`MatchParticipant.tier`** — 참여 시 primary RiotAccount의 primary queue tier(solo 5x5)를 snapshot으로 복사
5. **`GET /me`** — 현재 `X-Auth-User-Id` 헤더의 User 반환 (헤더 없으면 `null`). 프론트에서 admin 기능 가시성 판단용
6. **`GET /communities/:communityId`** — 프론트 헤더에 커뮤니티 이름 표시용
7. `mapId: number` → 프론트 라벨 매핑 유틸(프론트 쪽). 백엔드는 그대로
### 2.3 프론트엔드에 없는 것 (이번에 추가)
1. API 클라이언트 (`src/lib/api.ts`) — fetch 래퍼, `X-Auth-User-Id` 주입
2. `@tanstack/react-query` + `QueryClientProvider`
3. `socket.io-client` + `useAuctionSocket` 훅
4. `src/config.ts` — `VITE_API_BASE_URL`, `VITE_DEFAULT_COMMUNITY_ID`, localStorage `X-Auth-User-Id` 관리
5. 백엔드 스키마에 대응하는 **프론트 타입** (`src/api/types.ts`)
6. 백엔드 `Match`/`Auction` → 프론트 `MatchDetail`/`AuctionState` **매핑 함수** (`src/api/mappers.ts`)
7. 개발자용 "User ID 주입" 토글 UI (admin 기능 테스트용, 프로덕션 빌드에선 숨김)
### 2.4 데이터 모델 차이 요약
| 프론트 모델 | 백엔드 모델 | 매핑 전략 |
| --------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `MatchDetail.date`/`time` (한국어 string) | `Match.scheduledAt: Date` | 프론트에서 `Intl.DateTimeFormat('ko-KR')`로 포맷 |
| `MatchDetail.map: string` ("소환사의 협곡") | `Match.mapId: number` (11) | 프론트 `mapIdToLabel` 유틸 |
| `Participant.tier: {previousSeason, current, peak}` | 추가 필요: `MatchParticipant.tier` 스냅샷 | 백엔드에 필드 추가 후 프론트가 그대로 읽음 (프론트 `TierInfo`는 백엔드 원본 형태로 리팩터) |
| `Team.participants[].assignedPosition` | `MatchTeam.members[].assignedPosition` | 프론트가 `match.participants`와 `match.teams`를 조합해서 표시 |
| `AuctionPlayer.tier` (단일) | `AuctionPlayerSnapshot.tiers: TierInfo[]` | 프론트에서 `queueType === 'RANKED_SOLO_5x5'` 필터 후 대표 선택 |
| `AuctionPlayer.masteries[].championName` | `ChampionMasteryEntry.championName` (optional) | 프론트가 fallback 처리 |
| `AuctionState.timer` (초, 카운트다운) | 서버 `currentDeadline: Date` | 프론트가 `deadline - now`로 매 틱 계산 |
---
## 3. 실행 계획
> 단계는 독립적이지 않고 순차 진행 권장. Phase 0 → 1 → 2 → 3 순서.
### Phase 0 — 백엔드 선행 보강 (`apps/api`)
#### 0.1 CORS 활성화
**파일**: `apps/api/src/main.ts`
```ts
app.enableCors({
origin: process.env.WEB_ORIGIN?.split(",") ?? ["http://localhost:5173"],
credentials: true,
allowedHeaders: ["Content-Type", "X-Auth-User-Id"],
});
```
프로덕션용 origin은 `project.env`의 `WEB_ORIGIN`으로 주입.
#### 0.2 `MatchParticipant.tier` 스냅샷 필드 추가
**파일**: `apps/api/src/modules/global/database/schema.ts`
- `MatchParticipant` interface + sub-schema에 `tier?: TierInfo` 추가 (optional — Riot 계정이 없는 유저도 참여 가능해야 하면)
- `MatchService.join()` (`apps/api/src/modules/match/match.service.ts` 라인 93~)에서 `primaryRiot.tiers.find(t => t.queueType === 'RANKED_SOLO_5x5') ?? primaryRiot.tiers[0]`를 복사
- 기존 데이터 마이그레이션 없이 optional이라 호환성 유지
#### 0.3 `/me` + `/communities/:id` 편의 엔드포인트
**신규 파일**: `apps/api/src/modules/user/user.controller.ts`, `user.module.ts`
```ts
@Controller("me")
class MeController {
@Get()
me(@CurrentUser() user: UserDocument | undefined) {
return user ? { user } : { user: null };
}
}
```
**Community 쪽** (`community.controller.ts`):
```ts
@Get(':communityId')
async getCommunity(@Param('communityId', ParseObjectIdPipe) id) {
return this.communityService.getById(id); // 서비스에 메서드 추가
}
```
#### 0.4 Auction WebSocket 게이트웨이 (핵심)
**의존성 설치**: `pnpm --filter api add @nestjs/websockets @nestjs/platform-socket.io socket.io`
**신규 파일**: `apps/api/src/modules/auction/auction.gateway.ts`
네임스페이스·룸 구조:
- 네임스페이스: `/auction`
- 룸 이름: `matchId` 문자열
이벤트 스펙:
| 방향 | 이벤트 | payload |
| --- | --- | --- |
| server→client | `state` | `AuctionDocument` (직렬화) |
| server→client | `tick` | `{ deadline: string, serverTime: string }` |
| server→client | `error` | `{ message: string }` |
| client→server | `join` | `{ matchId: string }` |
| client→server | `bid` | `{ side, amount, bidderUserId? }` |
| client→server | `open-bidding` | `{}` |
| client→server | `sold` | `{ assignedPosition? }` |
| client→server | `next` | `{}` |
구현 포인트:
- `handleConnection`/`handleDisconnect`에서 Socket.IO의 rooms 표준 사용
- 클라이언트 `join` 시 해당 matchId 룸에 입장 + 현재 `state` 푸시
- 입찰/낙찰/다음 이벤트는 **기존 `AuctionService` 메서드 재사용**. 결과 상태를 해당 룸에 브로드캐스트
- `AuctionService`가 phase 전이 시마다 `deadline: Date` 계산해서 Auction 문서에 저장 (`AuctionSchema`에 `currentDeadline?: Date` 추가)
- 타이머 만료 자동 처리는 **Phase 0에선 생략**하고, 클라이언트가 deadline 지나면 "시간 종료" 표시만. 자동 `markSold`는 후속 작업 (`SchedulerRegistry` + `setTimeout` 필요). 트러스트 전제라 팀장이 수동 sold 하면 충분.
**AuthMiddleware는 socket.io 연결에 적용되지 않음**: 게이트웨이 자체에서 `@ConnectedSocket()`의 handshake headers 또는 auth payload에서 `x-auth-user-id`를 읽어 옵션으로 취급. 권한 필요한 이벤트(`open-bidding`, `sold`, `next`)는 일단 무검증 유지 (트러스트 전제). `bid`만 payload의 `bidderUserId`를 검증해서 해당 팀의 `captainUserId`와 일치하는지 정도 체크하면 고의 방해 방지 최소선은 만족.
#### 0.5 `AuctionSchema.currentDeadline` 추가
**파일**: `apps/api/src/modules/global/database/schema.ts`
- interface `Auction`에 `currentDeadline?: Date`
- Schema 필드 추가
- `AuctionService.openBidding()`과 `placeBid()`에서 `new Date(Date.now() + auction.maxTimerSeconds * 1000)`로 갱신
- `placeBid` 시엔 `Math.max(5, remainingSeconds)` 보장 (기존 프론트 mock 로직과 동일: 최소 5초)
- `markSold` / `next` 시엔 `undefined`로 리셋
#### 0.6 AppModule 등록
**파일**: `apps/api/src/app.module.ts`
- `UserModule` import
- `AuctionModule`에서 게이트웨이 providers 등록 (`AuctionGateway` + `AuctionService`는 그대로)
#### 0.7 검증 (Phase 0 종료 시)
```bash
cd apps/api
./node_modules/.bin/tsc --noEmit
pnpm start:dev
```
- `curl -H "X-Auth-User-Id: <id>" http://localhost:3000/me`로 `/me` 확인
- socket.io 클라이언트(또는 `wscat`)로 `ws://localhost:3000/auction` 연결 + `join` 이벤트 → `state` 수신 확인
---
### Phase 1 — 프론트엔드 인프라 구축 (`apps/web`)
#### 1.1 의존성 설치
```bash
pnpm --filter web add @tanstack/react-query socket.io-client
pnpm --filter web add -D @tanstack/react-query-devtools
```
#### 1.2 환경 변수
**신규 파일**: `apps/web/.env.development` (기존 있으면 추가)
```
VITE_API_BASE_URL=http://localhost:3000
VITE_DEFAULT_COMMUNITY_ID=<Phase 3에서 생성한 커뮤니티 _id>
```
**신규 파일**: `apps/web/src/config.ts`
- `API_BASE_URL`, `DEFAULT_COMMUNITY_ID` export
- `getAuthUserId()` / `setAuthUserId(id | null)` (localStorage `lolympus.authUserId`)
#### 1.3 API 클라이언트
**신규 파일**: `apps/web/src/lib/api.ts`
- `apiFetch<T>(path, init?)`: 베이스 URL 붙이고, `X-Auth-User-Id` 자동 주입, JSON 파싱, 4xx/5xx는 `ApiError` throw
- 응답 타입은 제네릭
#### 1.4 타입 정의 (백엔드 미러)
**신규 파일**: `apps/web/src/api/types.ts`
- `Position`, `TeamSide`, `MatchStatus`, `AuctionPhase` 같은 유니온은 복붙
- `TierInfo`, `ChampionMasteryEntry`, `RiotRecentStatsSummary` 등 sub-type
- `ApiCommunity`, `ApiUser`, `ApiMatch`, `ApiAuction` — 응답 형태 그대로
- `_id: string` (ObjectId 직렬화), `createdAt/updatedAt: string` (ISO)
> 타입 중복은 MVP에선 감수. 나중에 `packages/shared-types` 생성 고려.
#### 1.5 매핑 레이어
**신규 파일**: `apps/web/src/api/mappers.ts`
- `mapApiMatchToMatchDetail(match: ApiMatch): MatchDetail`
- `mapApiAuctionToAuctionState(auction: ApiAuction, serverNow?: Date): AuctionState`
- `mapIdToLabel(mapId: number): string` — `11 → '소환사의 협곡'`, `12 → '칼바람 나락'`, ...
- `formatKoreanDate(date: Date): { date, time }`
- `selectPrimaryTier(tiers: TierInfo[]): TierInfo | undefined`
> 기존 `apps/web/src/mock.ts`의 `MatchDetail`/`Participant` 타입은 유지한 채로 매퍼가 채움. 이후 Phase 2에서 점진 삭제.
#### 1.6 React Query 설정
**파일 수정**: `apps/web/src/main.tsx`
- `QueryClientProvider`로 감싸기
- staleTime 10s, cacheTime 5min 기본값
#### 1.7 Socket 훅
**신규 파일**: `apps/web/src/api/useAuctionSocket.ts`
- `useAuctionSocket(matchId: string)` 훅
- 내부: `useEffect`로 `io(API_BASE_URL + '/auction', { auth: { 'x-auth-user-id': getAuthUserId() } })`
- `join` emit 후 `state`/`tick`/`error` 이벤트 구독
- state는 `useState`로 저장, 반환: `{ state, placeBid, openBidding, markSold, next, connectionStatus }`
#### 1.8 개발자용 User 주입 위젯
**신규 파일**: `apps/web/src/components/DevAuthSwitcher.tsx`
- 우하단 플로팅 패널. input + "Set"/"Clear" 버튼. localStorage 값 표시
- `import.meta.env.DEV`일 때만 렌더
---
### Phase 2 — 페이지 교체 (`apps/web`)
#### 2.1 HomePage
**파일**: `apps/web/src/pages/HomePage.tsx`
- mock import 제거
- `useQuery(['matches', communityId, 'upcoming'])` → `GET /communities/:id/matches?status=recruiting&limit=20`
- `useQuery(['matches', communityId, 'finished'])` → `GET /communities/:id/matches?status=finished&limit=10`
- "다음 내전"은 upcoming의 첫 요소
- 각 카드는 `mapApiMatchToMatchDetail`의 축약 버전으로
#### 2.2 MatchDetailPage
**파일**: `apps/web/src/pages/MatchDetailPage.tsx`
- `useQuery(['match', matchId])` → `GET /communities/:id/matches/:matchId`
- `mapApiMatchToMatchDetail()` 적용
- 참가자 티어는 `participant.tier` 직접 사용 (백엔드 snapshot)
- "경매 시작" 버튼은 `/me` 결과의 role이 admin/owner일 때만 보여주기 (admin 전용)
#### 2.3 AuctionPage
**파일**: `apps/web/src/pages/AuctionPage.tsx`
- `createMockAuction` import 제거
- 초기 상태: `useQuery(['auction', matchId])` → `GET /communities/:id/matches/:matchId/auction`
- 이후: `useAuctionSocket(matchId)`로 실시간 갱신
- 타이머: `state.currentDeadline`과 `Date.now()` 차이로 클라이언트 카운트다운
- "입찰" 버튼: `placeBid({side, amount})` 호출 (내부적으로 socket emit)
- "공개"/"낙찰"/"다음" 버튼(팀장용): socket emit — 페이지에 세 버튼 노출 (트러스트 전제)
- **localStorage에 자기가 어느 팀장인지 저장하는 토글** 추가 (dev 편의)
#### 2.4 mock 파일 제거
- `apps/web/src/mock.ts` — Position/TierInfo/Participant 같은 타입만 `src/api/types.ts`로 흡수 후 삭제
- `apps/web/src/auction-mock.ts` — 전부 삭제
- `apps/web/src/auction-types.ts` — 프론트 전용 파생 타입만 남기고 백엔드 응답 타입은 `api/types.ts`로
---
### Phase 3 — E2E 검증 및 시드
#### 3.1 시드 데이터 생성 스크립트
**신규 파일**: `apps/api/src/seed.ts` (또는 ad-hoc)
- `CommunityService.createCommunityWithOwner({ name: 'Dev Community', owner: { kakaoTalkNickname: 'DevOwner' } })`
- 참가자 유저 10명 생성 (Riot 계정 더미 + tiers 채움 — 기존 mock 데이터를 DB로 이식)
- 매치 3개 (recruiting 1, team-built 1, finished 1)
- 반환된 `communityId`를 `.env.development`에 복사
실행:
```bash
pnpm --filter api exec ts-node src/seed.ts
```
#### 3.2 통합 smoke test
1. `pnpm --filter api start:dev`
2. `pnpm --filter web dev`
3. 브라우저에서 `http://localhost:5173`:
- HomePage에 시드 매치 3개 표시되는지
- MatchDetailPage에서 참가자 티어 정보 렌더링되는지
- DevAuthSwitcher로 owner User ID 주입 → 경매 시작 버튼 보이는지
- AuctionPage 두 탭 열어서 한쪽 입찰 시 다른 쪽 실시간 반영되는지
4. `tsc --noEmit`과 `pnpm --filter web build` 무오류 확인
---
## 4. 파일별 수정/신규 체크리스트
### `apps/api` 수정
- [ ] `src/main.ts` — CORS
- [ ] `src/modules/global/database/schema.ts` — `MatchParticipant.tier?`, `Auction.currentDeadline?`
- [ ] `src/modules/match/match.service.ts::join` — tier 스냅샷 복사
- [ ] `src/modules/auction/auction.service.ts` — `openBidding`/`placeBid`에서 `currentDeadline` 갱신, `markSold`/`next`에서 리셋
- [ ] `src/modules/community/community.controller.ts` + `community.service.ts` — `getById` + `GET /communities/:id`
- [ ] `src/app.module.ts` — `UserModule`, `AuctionGateway` provider 등록
### `apps/api` 신규
- [ ] `src/modules/user/user.module.ts`
- [ ] `src/modules/user/user.controller.ts` (`GET /me`)
- [ ] `src/modules/auction/auction.gateway.ts`
- [ ] `src/seed.ts` (선택)
### `apps/web` 수정
- [ ] `src/main.tsx` — `QueryClientProvider`
- [ ] `src/App.tsx` — DevAuthSwitcher 마운트
- [ ] `src/pages/HomePage.tsx` — react-query 연동
- [ ] `src/pages/MatchDetailPage.tsx` — react-query 연동
- [ ] `src/pages/AuctionPage.tsx` — socket 훅 연동
### `apps/web` 신규
- [ ] `.env.development`
- [ ] `src/config.ts`
- [ ] `src/lib/api.ts`
- [ ] `src/api/types.ts`
- [ ] `src/api/mappers.ts`
- [ ] `src/api/useAuctionSocket.ts`
- [ ] `src/api/hooks.ts` (선택 — `useMatches`, `useMatch`, `useAuction`, `useMe`)
- [ ] `src/components/DevAuthSwitcher.tsx`
### `apps/web` 삭제
- [ ] `src/mock.ts` (타입은 `src/api/types.ts`로 흡수 후)
- [ ] `src/auction-mock.ts`
---
## 5. 재사용할 기존 유틸
| 용도 | 위치 | 재사용 포인트 |
| ---------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------- |
| ObjectId 파라미터 파싱 | `apps/api/src/modules/common/parse-object-id.pipe.ts` | 새 엔드포인트(`getCommunity`, `me`)에도 적용 |
| 트랜잭션 세션 생성 | `apps/api/src/modules/global/database/connection.service.ts::createSession` | `AuctionGateway`에서 원자적 상태 전이가 필요한 경우 |
| `@CurrentUser()` | `apps/api/src/modules/auth/current-user.decorator.ts` | `/me`에서 그대로 사용 |
| Role 매핑 | `apps/api/src/modules/auth/permissions.ts::roleHasPermission` | 프론트에 권한 표시 JSON 내려줄 때 참고 |
| 포지션 라벨/아이콘 | `apps/web/src/assets/position/*` + `mock.ts`의 `positionLabel`/`positionIcon` | `src/api/mappers.ts`로 이동 |
---
## 6. 위험 요소 & 주의사항
1. **Socket.IO 인증 미적용**: MVP에선 WebSocket 연결에 인증을 강제하지 않음. 고의 방해 시나리오 대비는 `bid` 이벤트의 `bidderUserId`가 해당 팀 `captainUserId`와 일치하는지만 체크. 프로덕션 전환 전에 JWT 핸드셰이크로 교체.
2. **타이머 만료 자동 sold 미구현**: 팀장이 수동으로 "낙찰" 누르는 흐름. 이게 불편하면 후속 작업으로 `SchedulerRegistry` 타이머 추가.
3. **Mongoose `HydratedDocument` 직렬화**: `JSON.stringify`는 `toJSON`을 거치지만 `_id`가 ObjectId 객체로 나올 수 있음. 엔드포인트에서 `.lean()` 또는 `toObject({ versionKey: false })` 적용 고려 — 또는 프론트에서 `String(_id)` 처리.
4. **프론트 타입 중복**: `apps/web/src/api/types.ts`가 백엔드 스키마와 갈라질 수 있음. Phase 3 이후 `packages/shared-types` 워크스페이스로 승격 권장.
5. **시드 데이터의 communityId 동기화**: `.env.development`에 하드코딩되므로 재시드 시 값 바뀜. `seed.ts` 마지막에 `.env.development`를 갱신하도록 하면 편함.
6. **`forbidNonWhitelisted: true`**: DTO에 없는 필드는 400. 프론트 요청 페이로드 구성 시 주의.
7. **Riot 계정 없는 유저 참여**: `MatchService.join`은 현재 `primaryRiot` 없어도 `undefined`로 저장. `tier` 필드도 optional로 유지해야 기존 흐름 유지.
---
## 7. 검증 체크리스트 (최종)
- [ ] `pnpm --filter api run build` 무오류
- [ ] `pnpm --filter web run build` 무오류
- [ ] `curl -i http://localhost:3000/me` → `{user: null}`, 헤더 넣으면 user 객체
- [ ] `curl http://localhost:3000/communities/<id>/matches` → 시드 매치 목록
- [ ] 브라우저 HomePage 렌더 OK
- [ ] MatchDetailPage에 티어 표시 OK
- [ ] AuctionPage 두 탭 open → 한쪽 bid 하면 다른 쪽 `state` 이벤트로 즉시 갱신
- [ ] DevAuthSwitcher로 owner ID 주입 시에만 "경매 시작" 버튼 노출
- [ ] 비 admin 상태에선 admin 엔드포인트 호출 시 401/403 응답이 UI에 에러 토스트로 노출
---
## 8. 작업 순서 (codex 핸드오프용)
1. **Phase 0** (백엔드 보강) — 스키마 변경 → 서비스 갱신 → 게이트웨이 → CORS/ME. 빌드 확인.
2. **Phase 1** (프론트 인프라) — deps 설치 → config/api/types/mappers → QueryClientProvider.
3. **Phase 3의 3.1 시드** 먼저 돌려서 `communityId` 확보 → `.env.development` 업데이트.
4. **Phase 2** (페이지 교체) — HomePage → MatchDetailPage → AuctionPage 순서.
5. **Phase 3의 3.2** E2E 스모크 테스트.
각 Phase 종료마다 `tsc --noEmit`으로 타입 검증, 필요시 `pnpm lint` 실행.
+480
View File
@@ -0,0 +1,480 @@
GNU LIBRARY GENERAL PUBLIC LICENSE
Version 2, June 1991
Copyright (C) 1991 Free Software Foundation, Inc.
<https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the library GPL. It is
numbered 2 because it goes with version 2 of the ordinary GPL.]
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
This license, the Library General Public License, applies to some
specially designated Free Software Foundation software, and to any
other libraries whose authors decide to use it. You can use it for
your libraries, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if
you distribute copies of the library, or if you modify it.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link a program with the library, you must provide
complete object files to the recipients so that they can relink them
with the library, after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
Our method of protecting your rights has two steps: (1) copyright
the library, and (2) offer you this license which gives you legal
permission to copy, distribute and/or modify the library.
Also, for each distributor's protection, we want to make certain
that everyone understands that there is no warranty for this free
library. If the library is modified by someone else and passed on, we
want its recipients to know that what they have is not the original
version, so that any problems introduced by others will not reflect on
the original authors' reputations.
Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that companies distributing free
software will individually obtain patent licenses, thus in effect
transforming the program into proprietary software. To prevent this,
we have made it clear that any patent must be licensed for everyone's
free use or not licensed at all.
Most GNU software, including some libraries, is covered by the ordinary
GNU General Public License, which was designed for utility programs. This
license, the GNU Library General Public License, applies to certain
designated libraries. This license is quite different from the ordinary
one; be sure to read it in full, and don't assume that anything in it is
the same as in the ordinary license.
The reason we have a separate public license for some libraries is that
they blur the distinction we usually make between modifying or adding to a
program and simply using it. Linking a program with a library, without
changing the library, is in some sense simply using the library, and is
analogous to running a utility program or application program. However, in
a textual and legal sense, the linked executable is a combined work, a
derivative of the original library, and the ordinary General Public License
treats it as such.
Because of this blurred distinction, using the ordinary General
Public License for libraries did not effectively promote software
sharing, because most developers did not use the libraries. We
concluded that weaker conditions might promote sharing better.
However, unrestricted linking of non-free programs would deprive the
users of those programs of all benefit from the free status of the
libraries themselves. This Library General Public License is intended to
permit developers of non-free programs to use free libraries, while
preserving your freedom as a user of such programs to change the free
libraries that are incorporated in them. (We have not seen how to achieve
this as regards changes in header files, but we have achieved it as regards
changes in the actual functions of the Library.) The hope is that this
will lead to faster development of free libraries.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
"work based on the library" and a "work that uses the library". The
former contains code derived from the library, while the latter only
works together with the library.
Note that it is possible for a library to be covered by the ordinary
General Public License rather than by this special one.
GNU LIBRARY GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library which
contains a notice placed by the copyright holder or other authorized
party saying it may be distributed under the terms of this Library
General Public License (also called "this License"). Each licensee is
addressed as "you".
A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work
which has been distributed under these terms. A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library". Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library". The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also compile or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
a) Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable "work that
uses the Library", as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
b) Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
c) If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
d) Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the source code distributed need not include anything that is normally
distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
a) Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
b) Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.
11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
13. The Free Software Foundation may publish revised and/or new
versions of the Library General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
To apply these terms, attach the following notices to the library. It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
<one line to give the library's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, see <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James Random Hacker.
<signature of Moe Ghoul>, 1 April 1990
Moe Ghoul, President of Vice
That's all there is to it!
-465
View File
@@ -1,465 +0,0 @@
# Legacy 내전 데이터 백필 (Import) 플랜
> **대상**: codex 가 이어서 작업 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-27
> **선행 작업**:
> - `Riot-최근경기-플랜.md` (RiotRateLimiterService, RiotMatch 영구 저장)
> - `Riot-소환사전적-플랜.md` (Redis Stream 작업 큐, leader election, ETA, deferUntil)
> - `Tournament-Result-수집-플랜.md` (Match.result.games 매핑 로직, team-mapping 유틸, advanceMatchIfReady)
> - `커뮤니티-내전-전적.md` / `stateful-stirring-moler.md` (커뮤니티 통계 페이지 — 본 plan 의 결과 데이터 소비처)
---
## 1. Context
본 시스템 도입 이전에 진행된 내전 매치는 우리 DB 에 없습니다. 그러나 Riot 은 `match-v5` raw 매치 데이터를 ~2년간 보관하므로, **커뮤니티 멤버 puuid 로 `type=tourney` 매치를 검색**해 backfill 할 수 있습니다.
목표:
- **2024-05-01 부터** 모든 커뮤니티 멤버의 토너먼트 코드 매치를 import 해 우리 `Match` 도큐먼트로 변환
- 임계값 휴리스틱은 사용하지 않음 — **검색된 모든 매치 import** (외부 토너먼트가 섞여도 OK)
- 추후 admin UI 에서 운영자가 잘못 들어온 매치를 직접 삭제 (사후 cleanup 정책)
- 1 match-v5 = 1 Match 도큐먼트 (시리즈 묶음 X)
- 야간/유휴 시간대 권장
선행 인프라가 갖춘 부분:
- `RiotMatchService.getMatchIdsByPuuid({type: 'tourney', startTime, ...})` 가 이미 동작
- `RiotMatch.raw` 영구 저장 + `participantPuuids` 인덱스
- Redis Stream 작업 큐 (`riot:queue:high/low`) + RiotRateLimiterService 글로벌 throttle
- `Tournament-Result-수집-플랜.md` 의 `team-mapping.util.ts` (puuid 합집합 다수결 → blue/red 매핑) 그대로 재사용
---
## 2. 결정사항 (사용자 결정 2026-04-27)
- **검색 시작일**: 2024-05-01 (UTC)
- **검색 종료일**: 멤버별 `isActivated=false` 면 `user.updatedAt`, 활성이면 현재
- **멤버별 startTime override**: `max(2024-05-01, user.createdAt)` 자동 채움. 운영자가 admin UI 에서 멤버별 수정 가능
- **임계값 필터 사용 X**: 검색된 모든 `type=tourney` 매치 import (외부 토너먼트도 포함)
- **시리즈 묶음 X**: 1 match-v5 = 1 Match 도큐먼트, `gameCount=1`
- **사후 cleanup**: admin UI 에서 legacy 매치 목록 보고 단일/bulk 삭제 가능
- **idempotent**: 같은 `riotMatchId` 두 번 import 안 됨
- **부하**: 야간 batch 권장. 운영자가 명시적으로 트리거
---
## 3. 데이터 모델 보강
### 3.1 Match 확장 (legacy 추적)
```ts
// schema.ts Match 추가
legacyImported?: boolean; // true 면 본 import 로 들어온 매치
legacyImportSource?: {
importedAt: Date;
importedBy: mongoose.Types.ObjectId; // 트리거한 admin userId
triggeringPuuid: string; // 어떤 멤버 검색으로 처음 발견됐는지 audit
jobId?: string;
};
// MatchSchema
legacyImported: { type: Boolean, default: false, index: true },
legacyImportSource: {
importedAt: { type: Date },
importedBy: { type: Schema.Types.ObjectId, ref: 'user' },
triggeringPuuid: { type: String },
jobId: { type: String },
}
```
### 3.2 RiotMatch unique 검사
이미 `RiotMatch.matchId` 가 unique 인덱스 (선행 plan 가정). 신규 import 시 이미 있으면 detail 재호출 skip.
### 3.3 Match `riotMatchId` 단위 unique
같은 match-v5 가 두 Match 도큐먼트로 들어오는 사고 방지:
- Mongo aggregation 단계에서 `result.games[].riotMatchId` 가 이미 다른 Match 에 존재하면 skip
- 또는 신규 sparse 인덱스: `Match.result.games.riotMatchId` (배열 인덱스, sparse)
```ts
MatchSchema.index({ 'result.games.riotMatchId': 1 }, { sparse: true, unique: false });
```
- unique 는 배열 element 단위로 보장하기 어려우니 application 레벨 검사 권장
### 3.4 신규 컬렉션 — `LegacyImportJob` (운영 추적)
```ts
export interface LegacyImportJob {
jobId: string;
communityId: mongoose.Types.ObjectId;
triggeredBy: mongoose.Types.ObjectId;
startedAt: Date;
completedAt?: Date;
state: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
// 입력 파라미터
windowStart: Date; // 기본 2024-05-01
windowEnd: Date;
memberOverrides: Array<{ // 운영자가 수정한 멤버별 윈도우
userId: mongoose.Types.ObjectId;
puuid: string;
startTime: Date;
endTime: Date;
}>;
// 진행 상황
totalMembers: number;
processedMembers: number;
totalDiscoveredMatchIds: number; // dedup 후
totalImportedMatches: number;
totalSkippedDuplicate: number;
totalErrors: number;
errors?: Array<{ puuid?: string; matchId?: string; reason: string; at: Date }>;
}
```
운영 가시성: admin UI 에서 import job 진행률 표시 + 실패 매치 재시도.
---
## 4. Import 흐름
### 4.1 트리거
```
admin UI → POST /communities/:cid/legacy-import
body: {
windowStart?: '2024-05-01T00:00:00Z',
windowEnd?: ISO,
memberOverrides?: [{ userId, startTime, endTime }, ...]
}
응답: { jobId, totalMembers, etaSeconds }
```
`@Roles('owner', 'admin')` 가드. 동시 동일 community 에 대한 job 1개로 제한 (Garnet `legacy-import:lock:<cid>` NX EX 6h).
### 4.2 sub-job 분할
선행 plan 의 작업 큐 패턴 그대로:
- parent job: `LegacyImportJob` 생성
- 멤버별 sub-job N개 enqueue → `riot:queue:low` (priority low — 사용자 갱신/prefetch 보다 뒤)
- payload:
```ts
{
kind: 'legacy-import-member',
parentJobId,
communityId,
userId,
puuid,
startTime, // epoch seconds
endTime,
triggeredBy,
}
```
### 4.3 worker — 멤버 1명 처리
```ts
async function processLegacyImportMember(job: LegacyImportMemberJob) {
let start = 0;
const collectedMatchIds = new Set<string>();
// 1. type=tourney list 페이지네이션 (count=100, region 'asia')
while (true) {
const ids = await matchService.getMatchIdsByPuuid(job.puuid, {
type: 'tourney',
startTime: Math.floor(job.startTime.getTime() / 1000),
endTime: Math.floor(job.endTime.getTime() / 1000),
start,
count: 100,
region: 'asia',
});
ids.forEach((id) => collectedMatchIds.add(id));
if (ids.length < 100) break;
start += 100;
// throttle 통과 — 별도 sleep 불필요
}
// 2. 각 matchId detail + Match 변환
for (const matchV5Id of collectedMatchIds) {
await importSingleMatch(matchV5Id, {
communityId: job.communityId,
triggeringPuuid: job.puuid,
importedBy: job.triggeredBy,
parentJobId: job.parentJobId,
});
}
await updateLegacyImportJobProgress(job.parentJobId, {
processedMembers: 1,
discovered: collectedMatchIds.size,
});
}
async function importSingleMatch(matchV5Id: string, ctx) {
// dedup: 이미 우리 Match 에 있는지
const existing = await MatchModel.findOne({ 'result.games.riotMatchId': matchV5Id });
if (existing) {
await incrementCounter('totalSkippedDuplicate');
return;
}
// RiotMatch raw 페치 (이미 있으면 cache hit)
const detail = await ensureRiotMatchPersisted(matchV5Id);
if (!detail.info.tournamentCode) return; // 안전: tourney 인데 코드 없는 비정상 케이스 skip
// 우리 멤버 매핑
const community = await CommunityModel.findById(ctx.communityId);
const userByPuuid = await buildUserByPuuidMap(ctx.communityId);
const teams100Puuids = detail.info.participants.filter((p) => p.teamId === 100).map((p) => p.puuid);
const teams200Puuids = detail.info.participants.filter((p) => p.teamId === 200).map((p) => p.puuid);
const team100MembersInOurs = teams100Puuids.filter((p) => userByPuuid.has(p)).length;
const team200MembersInOurs = teams200Puuids.filter((p) => userByPuuid.has(p)).length;
// 외부 매치(우리 멤버 0명) 는 import 하지 않음 — 검색 결과에 잘못 들어온 케이스 가드
if (team100MembersInOurs + team200MembersInOurs === 0) return;
// teamId → blue/red: 우리 멤버 더 많은 쪽이 blue (관습), 동수면 100=blue
const team100IsBlue = team100MembersInOurs >= team200MembersInOurs;
// Match 도큐먼트 생성
const match = await MatchModel.create({
communityId: ctx.communityId,
title: `[Legacy] ${formatDate(detail.info.gameCreation)}`,
description: 'Legacy import (자동 생성)',
mapId: detail.info.mapId ?? 11,
status: 'finished',
scheduledAt: new Date(detail.info.gameCreation),
teamBuiltAt: new Date(detail.info.gameCreation),
maxParticipants: 10,
gameCount: 1,
tournamentCodeIds: [], // legacy 라 우리 풀 코드 없음
participants: buildParticipantsSnapshot(detail, userByPuuid),
teams: buildTeams(detail, userByPuuid, team100IsBlue),
result: {
blueScore: 0,
redScore: 0,
games: [
buildGameResult(detail, userByPuuid, team100IsBlue, 1),
],
riotMatchIds: [matchV5Id],
},
legacyImported: true,
legacyImportSource: {
importedAt: new Date(),
importedBy: ctx.importedBy,
triggeringPuuid: ctx.triggeringPuuid,
jobId: ctx.parentJobId,
},
});
// result.winnerSide / blueScore / redScore 산정
const winnerSide = match.result!.games[0].winnerSide;
match.result!.blueScore = winnerSide === 'blue' ? 1 : 0;
match.result!.redScore = winnerSide === 'red' ? 1 : 0;
match.result!.winnerSide = winnerSide;
await match.save();
await incrementCounter('totalImportedMatches');
}
```
핵심 헬퍼:
- `ensureRiotMatchPersisted(matchV5Id)`: RiotMatch 컬렉션에 upsert. 이미 있으면 그대로 반환 (Riot API 호출 0회).
- `buildUserByPuuidMap(communityId)`: 커뮤니티 멤버 puuid → User 역인덱스 (in-memory cache, job 단위).
- `buildGameResult(detail, userByPuuid, team100IsBlue, gameNumber)`: 선행 plan `Tournament-Result-수집-플랜.md` `§4.4 computeGameResult` 함수 그대로 재사용. team mapping 만 override.
### 4.4 동시성 / dedup
- **멤버 sub-job 간 동시성**: 두 멤버가 같은 매치에 있으면 두 worker 가 같은 matchV5Id 를 동시에 처리하려고 함. `importSingleMatch` 진입 시 Garnet `legacy-import:match:<matchV5Id>` NX EX 60s 락. 이미 잡혔으면 skip.
- **재실행**: 같은 jobId 재실행 시 이미 처리된 멤버는 `LegacyImportJob.processedMembers` 기준 skip.
### 4.5 진행률 / ETA
- worker 가 sub-job 끝낼 때마다 `LegacyImportJob.processedMembers++`
- ETA: `(totalMembers - processedMembers) × avgMemberSeconds`
- avgMemberSeconds 기본 60 (멤버당 list 1~3 페이지 + detail 10~50건 가정), 실제 처리 시간으로 EWMA 갱신
- admin UI 가 5초 polling 으로 진행률 표시
### 4.6 cancel
- `POST /legacy-import-jobs/:jobId/cancel` (admin)
- `LegacyImportJob.state='cancelled'` 마킹 → worker 가 sub-job pickup 직후 state 확인 → cancelled 면 즉시 ack 후 skip
---
## 5. Admin UI
### 5.1 신규 페이지
`apps/web/src/pages/admin/LegacyImportPage.tsx`
- 라우트: `/admin/communities/:cid/legacy-import`
- `@Roles('owner', 'admin')` 가드 (useMe + role 분기)
#### 화면 구성
```
┌────────────────────────────────────────────┐
│ Legacy 내전 백필 │
├────────────────────────────────────────────┤
│ 검색 윈도우 │
│ 시작일 [2024-05-01 ▾] 종료일 [지금 ▾] │
├────────────────────────────────────────────┤
│ 멤버별 윈도우 (자동 채움 + 수정 가능) │
│ ┌──────────┬─────────────┬──────────┐ │
│ │ 멤버명 │ 시작일 │ 종료일 │ │
│ │ 홍길동 │ 2024-05-01 │ 지금 │ │
│ │ 이순신 │ 2024-08-15 │ 2025-12-31│ │
│ └──────────┴─────────────┴──────────┘ │
├────────────────────────────────────────────┤
│ [백필 시작] (확인 모달 → 예상 ETA 표시) │
├────────────────────────────────────────────┤
│ 진행 중인 작업 │
│ - jobId xxx: 23/100 멤버 처리 중... │
│ 발견 매치 142개 / import 89개 / 중복 53 │
├────────────────────────────────────────────┤
│ 과거 작업 (최근 10개) │
│ - jobId yyy: 완료, 100/100, import 412 │
└────────────────────────────────────────────┘
```
### 5.2 신규 페이지 — Legacy 매치 cleanup
`apps/web/src/pages/admin/LegacyMatchesPage.tsx`
- 라우트: `/admin/communities/:cid/legacy-matches`
- legacy 매치 목록 (`legacyImported=true` 필터) — 시간순 / 멤버 인원수 정렬
- 각 row: 매치 ID / 시간 / 우리 멤버 N명 / 외부 puuid 수 / 챔피언 미니 + **삭제 버튼**
- bulk select + 일괄 삭제
- 확인 모달 ("이 매치는 영구 삭제됩니다. RiotMatch raw 는 유지됩니다.")
### 5.3 신규 엔드포인트
| Method | Path | 권한 | 용도 |
|---|---|---|---|
| POST | `/communities/:cid/legacy-import` | `owner/admin` | import 트리거 |
| GET | `/communities/:cid/legacy-import-jobs` | `owner/admin` | job 목록 |
| GET | `/communities/:cid/legacy-import-jobs/:jobId` | `owner/admin` | job 상세 |
| POST | `/communities/:cid/legacy-import-jobs/:jobId/cancel` | `owner/admin` | 취소 |
| GET | `/communities/:cid/legacy-matches` | `owner/admin` | legacy 매치 목록 (페이지네이션) |
| DELETE | `/matches/:id` | `owner/admin` | 단일 매치 삭제 (legacy 외 일반 매치도 가능) |
| POST | `/communities/:cid/legacy-matches/bulk-delete` | `owner/admin` | bulk 삭제 |
`Match` 삭제 시 부수 효과:
- `tournamentCodeIds` 가 비어있으므로 풀 release 불필요
- `MatchHistoryCache` invalidate (`riot:communitystats:*:<cid>:*` prefix scan delete) — `community-stats.service` 의 invalidate 헬퍼 재사용
---
## 6. 변경 사항 (파일 단위)
### 6.1 백엔드
```
apps/api/src/modules/legacy-import/
legacy-import.module.ts
legacy-import.service.ts # enqueue + status + cancel
legacy-import.worker.ts # 작업 큐 dispatch (kind=legacy-import-member)
legacy-import.controller.ts
legacy-import.types.ts
match-builder.util.ts # buildParticipantsSnapshot / buildTeams / buildGameResult
```
수정:
- `apps/api/src/modules/global/database/schema.ts` — `Match.legacyImported`, `Match.legacyImportSource`, 신규 인덱스, `LegacyImportJob` 컬렉션 등록
- `apps/api/src/modules/riot-job-queue/riot-job-worker.service.ts` — `kind === 'legacy-import-member'` dispatch 추가
- `apps/api/src/modules/match/match.service.ts` — `delete(matchId)` 메서드 + community-stats invalidate 호출
- `apps/api/src/modules/match/match.controller.ts` — `DELETE /matches/:id` 엔드포인트
- `apps/api/src/app.module.ts` — `LegacyImportModule` import
### 6.2 프런트
```
apps/web/src/pages/admin/LegacyImportPage.tsx
apps/web/src/pages/admin/LegacyMatchesPage.tsx
apps/web/src/components/admin/legacy/
MemberWindowTable.tsx # 멤버별 윈도우 수정 폼
LegacyImportJobProgress.tsx
LegacyMatchListRow.tsx
```
수정:
- `apps/web/src/App.tsx` — 2 신규 admin 라우트
- `apps/web/src/api/hooks.ts` — `useLegacyImportTrigger / useLegacyImportJobs / useLegacyMatches / useDeleteMatch`
- `apps/web/src/api/types.ts` — 응답 타입
---
## 7. 단위 테스트
- `legacy-import.service.spec.ts`
- parent job 생성 + 멤버별 sub-job N개 enqueue
- 동일 cid 동시 트리거 시 두 번째 거부 (Garnet 락)
- cancel 호출 시 state='cancelled', worker 가 다음 pickup 시 skip
- `legacy-import.worker.spec.ts`
- `importSingleMatch`: 이미 있는 riotMatchId → totalSkippedDuplicate++
- 외부 매치 (우리 멤버 0명) → import 안 됨 + 에러 카운트 X
- 우리 멤버 1명만 + 외부 9명 → 정상 import (휴리스틱 X 라 통과)
- team mapping: team100 우리 3명 vs team200 우리 0명 → team100=blue
- `match-builder.util.spec.ts`
- `buildGameResult` (Tournament-Result `computeGameResult` 재사용 검증)
- `buildTeams`: 우리 멤버 puuid → userId 매핑, 외부 puuid 는 teams 에서 제외
- `match.service.spec.ts`
- `delete(matchId)`: 매치 삭제 + cache invalidate 호출 확인
---
## 8. Rollout
1. (PR-1) `Match` 스키마 확장 (legacy 필드 + 인덱스) + `LegacyImportJob` 컬렉션 + 모델 등록
2. (PR-2) `match-builder.util.ts` (선행 plan `computeGameResult` 재사용 wrapping) + 단위 테스트
3. (PR-3) `LegacyImportService.enqueue / cancel / status` + parent job + sub-job 분할
4. (PR-4) `LegacyImportWorker` (worker dispatch + `importSingleMatch`) + 단위 테스트
5. (PR-5) `DELETE /matches/:id` 엔드포인트 + community-stats cache invalidate 통합
6. (PR-6) admin 트리거 페이지 (`LegacyImportPage`) — 윈도우 폼 + ETA 표시 + 진행률 polling
7. (PR-7) admin cleanup 페이지 (`LegacyMatchesPage`) — 매치 목록 + bulk 삭제
8. (PR-8) 운영 모니터링 (job 진행률 / 멤버당 처리 시간 / 외부 매치 비율 로그)
9. (Phase 후속) 자동 주기 재실행 (월 1회 등) — 1차에선 manual only
---
## 9. 추가 고려사항
### 확정 (사용자 결정 2026-04-27)
- **검색 시작일 2024-05-01**, 종료일 멤버 활성/비활성 따라 자동
- **멤버별 startTime override**: admin UI 에서 자동 채움 + 수정 가능
- **임계값 필터 X**: 검색된 모든 매치 import (외부 매치도 포함)
- **시리즈 묶음 X**: 1 match-v5 = 1 Match, gameCount=1
- **사후 cleanup**: admin UI 에서 단일/bulk 삭제
- **idempotent**: 같은 riotMatchId 두 번 import 안 됨
### 권장 (운영 후 확인)
1. **외부 매치 비율 로그** — `team100MembersInOurs + team200MembersInOurs` 별 분포를 import job 끝에 통계로 남기기. 운영자가 cleanup 우선순위 잡기 좋음.
2. **백필 매치의 title 컨벤션** — `[Legacy] 2024-08-15` 형식. 운영자가 cleanup 페이지에서 한눈에 식별.
3. **DELETE /matches/:id 가드** — `legacyImported=true` 외 일반 매치 삭제는 무서운 작업. 일반 매치 삭제 시 추가 확인 모달 또는 별도 엔드포인트로 분리.
4. **백필 매치의 participants snapshot** — `Match.participants[]` 는 보통 매치 신청 단계에서 채워지지만, legacy 라 신청 흐름이 없음. detail.info.participants 에서 우리 멤버만 추출해 채움. preferredPositions / tier 는 비움 (필수 아님 가정).
5. **mapId 결정** — `detail.info.mapId` 가 11(소협) 외 다른 값일 수 있음. 그대로 저장. 통계 페이지에서 mapId 필터로 분리 가능.
6. **시간대 권장** — admin UI 에 "야간 배치 권장" 안내 + 큐가 비어있는 시간대 표시 (Phase 후속).
7. **에러 매치 격리** — `LegacyImportJob.errors[]` 에 puuid+matchId+reason 보관. admin UI 에서 재시도 버튼.
8. **선행 plan 의 결과 수집 워커와의 충돌** — legacy import 가 만든 Match 는 `tournamentCodeIds=[]` 라 결과 수집 워커 (`maybeAdvanceMatch`) 가 트리거되지 않음. 자연 분리.
### 추후 (Phase 후속)
- 자동 주기 재실행 (월 1회 cron)
- 외부 매치 자동 분류 / 분리 (예: 멤버 ≥ 4명 = 우리 내전, < 4명 = 외부) 옵션 — UI 토글
- legacy 매치도 stateful-stirring-moler.md 의 community 통계 페이지에 자동 포함됨 (별도 분기 필요 없음 — `result.games[]` 형태가 같음)
---
## 10. Done 정의
- `Match.legacyImported` + `Match.legacyImportSource` + `LegacyImportJob` 컬렉션 + 인덱스 추가
- admin 이 `LegacyImportPage` 에서 윈도우/멤버 override 입력 후 트리거 → ETA 토스트 + 진행률 polling
- worker 가 멤버별 `type=tourney` list + detail 페치 → Match 도큐먼트 생성, `result.games[0]` 채워짐
- 같은 매치 두 번 import 안 됨 (Garnet 락 + Match application 검사)
- 우리 멤버 0명 매치는 자동 skip (외부 매치 가드)
- import job 진행률 / 발견 / import / 중복 / 에러 카운트 정확
- admin 이 `LegacyMatchesPage` 에서 잘못된 매치 단일/bulk 삭제 가능, 삭제 시 community-stats 캐시 invalidate
- 동일 cid 에 대한 동시 import 트리거 거부 (Garnet 락)
- cancel 동작
- Riot 429 0건 (글로벌 throttle 통과)
- 단위 테스트 통과
- legacy 매치가 `stateful-stirring-moler.md` 의 community 통계 페이지에 자동 포함됨
+143
View File
@@ -0,0 +1,143 @@
# LOLYMPUS
LOLYMPUS는 리그 오브 레전드 커뮤니티의 여러 이벤트 중 내전(사용자 설정 게임)을 운영할 때 필요한 일정 관리, 참여자 모집, 팀 빌딩, 토너먼트 코드 배정, 경기 진행, 실시간 라이브 방송(추후 지원 예정), 결과 수집, 전적 확인을 한곳에서 처리하기 위한 웹 애플리케이션입니다.
<p align="center">
<video
src="https://git.dahyeon.us/dahyeon/lolympus-tournament-support/raw/branch/release/77/docs/screenshots/lolympus-demo.mp4"
poster="docs/screenshots/lolympus-auction.png"
width="960"
autoplay="autoplay"
muted="muted"
loop="loop"
playsinline="playsinline"
controls
>
<a href="https://git.dahyeon.us/dahyeon/lolympus-tournament-support/raw/branch/release/77/docs/screenshots/lolympus-demo.mp4">3초 간격 데모 영상 보기</a>
</video>
</p>
<p align="center">
<a href="https://git.dahyeon.us/dahyeon/lolympus-tournament-support/raw/branch/release/77/docs/screenshots/lolympus-demo.mp4">3초 간격 데모 영상 보기</a>
</p>
## 배포 주소
| Environment | Version | URL |
| ----------- | ------- | -------------------------------------- |
| Production | v77 | <https://lolympus.dahyeon.us/> |
| Staging | v77 | <https://890c50be.lolympus.pages.dev/> |
## 개요
내전 운영은 사람을 모으는 것에서 끝나지 않습니다. 참가자의 티어와 포지션을 확인하고, 팀장을 정하고, 팀을 나누고, 경기마다 토너먼트 코드를 전달하고, 끝난 뒤 결과와 전적까지 정리해야 합니다.
LOLYMPUS는 이 반복 작업을 줄이는 데 초점을 맞췄습니다. 운영자는 전체 진행 상황을 한눈에 보고, 참가자는 카카오톡 연동을 통해 쉽게 일정 확인/참가 신청하고 본인이 속한 팀과 다음 경기 정보를 빠르게 확인할 수 있습니다.
## 워크플로우
1. **내전 개설과 모집**
내전 일정, 진행 방식, 정원, 공지사항을 등록하고 참가 신청 현황을 확인합니다.
2. **참가자 정보 확인**
Riot 계정 기반으로 소환사명, 태그, 프로필 아이콘, 솔로랭크/자유랭크 티어, 선호 포지션을 보여줍니다.
3. **팀 빌딩과 경매**
팀장을 기준으로 팀을 구성하거나, 경매 방식으로 참가자를 배정합니다. 현재 입찰가, 팀별 포인트, 낙찰 기록을 함께 관리합니다.
4. **팀별 진행 페이지**
각 팀은 예정 경기, 상대 팀, 라인업, 토너먼트 코드를 한 화면에서 확인하고 복사할 수 있습니다.
5. **결과 수집과 통계**
Riot Match-V5 데이터를 이용해 경기 결과를 수집하고, 소환사별 전적과 커뮤니티 리더보드를 제공합니다.
## 스크린샷
상단의 경매 화면은 LOLYMPUS가 단순 참가자 목록을 넘어서 실제 팀빌딩 운영까지 다루는 대표 화면입니다. 3초 간격 데모 영상은 README 렌더러가 video 태그를 지원하면 자동/반복 재생되고, 세부 화면은 아래 PNG 원본을 기준으로 볼 수 있습니다.
| 경매 팀빌딩 |
| ----------------------------------------------------------------------------------------------------------------------------------------- |
| <a href="docs/screenshots/lolympus-demo.mp4"><img src="docs/screenshots/lolympus-auction.png" alt="LOLYMPUS 경매 팀빌딩" width="840"></a> |
| 내전 목록 | 모집 상세 |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| <img src="docs/screenshots/lolympus-match-list.png" alt="LOLYMPUS 내전 목록" width="420"> | <img src="docs/screenshots/lolympus-match-recruiting.png" alt="LOLYMPUS 모집 상세" width="420"> |
| 단판 경기 결과 | 개인 전적 |
| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| <img src="docs/screenshots/lolympus-match-result(pair).png" alt="LOLYMPUS 단판 경기 결과" width="420"> | <img src="docs/screenshots/lolympus-player-stats.png" alt="LOLYMPUS 소환사 전적" width="420"> |
| 경기 상세 |
| ------------------------------------------------------------------------------------------- |
| <img src="docs/screenshots/lolympus-match-detail.png" alt="LOLYMPUS 경기 상세" width="840"> |
## 기능
- 내전 생성, 수정, 모집 상태 변경, 참가자 목록 확인
- 카카오톡 명령어를 통한 일정 조회, 내전 참가, 취소, 계정 등록 등 기능 제공
- Riot 계정 기반 참가자 프로필, 티어, 포지션 확인
- 팀장 지정, 포지션 기반 팀 구성, 다팀 내전 지원
- 팀장 경매 방식의 참가자 낙찰과 입찰 기록 관리
- 경기별 토너먼트 코드 배정과 팀별 복사 UI
- 팀별 경기 일정, 상대 팀, 라인업, 결과 확인
- Riot Match-V5 기반 결과 수집, 개인 전적, 리더보드 제공
- Dakao/NATS 기반 커뮤니티 명령 연동
## 기술 스택
- React
- Vite
- TypeScript
- TanStack Query
- NestJS
- MongoDB
- Redis/Garnet
- NATS
- Riot API
- pnpm workspace
- Kubernetes
- ArgoCD
## 디렉터리 구조
```text
apps/
api/ NestJS API server
web/ React + Vite client
docs/
screenshots/ README and project screenshots
scripts/ deployment and maintenance scripts
```
## 사전 요구사항
- Node.js 24 이상
- pnpm 10.4.1 (`packageManager` 기준, `corepack enable`로 활성화 권장)
- MongoDB 7.0, Redis 5.0 이상, NATS 실행 환경
## 실행 방법
```bash
pnpm install
pnpm start:api:dev
pnpm start:web:dev
```
웹 앱은 기본적으로 `apps/web/.env.development` 값을 사용합니다. API 환경값은 `apps/project.env`와 실행 환경의 시크릿 설정을 함께 확인합니다.
카카오톡 기반 명령어 기능은 Dakao(커스텀 카카오톡 게이트웨이) 연동이 필요합니다. Dakao가 실행 중이 아니거나 NATS를 통해 API 서버와 연결되어 있지 않으면 일정 조회, 내전 참가, 참가 취소, 계정 등록 같은 카카오톡 명령어는 사용할 수 없습니다.
## 커맨드
| Command | Description |
| --------------------------------- | -------------------------------- |
| `pnpm start:web:dev` | 웹 앱 개발 서버 실행 |
| `pnpm start:api:dev` | API 서버 dev 환경 실행 |
| `pnpm --filter api test` | API 테스트 실행 |
| `pnpm --filter web build:staging` | 웹 staging 빌드 검증 |
| `pnpm deploy:web:staging` | Cloudflare Pages staging 배포 |
| `pnpm deploy:web:prod` | Cloudflare Pages production 배포 |
## 라이선스
This project is licensed under the GNU Library General Public License v2.0. See [LICENSE](LICENSE) for details.
-628
View File
@@ -1,628 +0,0 @@
# 소환사 전적 페이지 플랜
> **대상**: codex 가 이어서 작업 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-26
> **선행 작업**: `Riot-최근경기-플랜.md` (Throttle / RecentMatches / Scheduler / 시즌·region 인프라) 가 깔려 있어야 함.
> **참고 이미지**: `user-game-history/statistics.png`, `123123.png` (poro.gg 스타일 매치 카드)
---
## 1. Context
`AuctionPage.tsx`, `MatchDetailPage.tsx` 에서 소환사 프로필 클릭 → 신규 **개인 전적 페이지** 로 이동.
핵심 정책 (사용자 결정 2026-04-26):
1. **서버 가진 데이터만 표시.** 페이지 진입 시 Riot API 호출 0회. 야간 prefetch + 명시적 "갱신" 버튼 만 enrichment 트리거.
2. 즉각 갱신은 **전역 Riot API 작업 큐** 에 enqueue → consumer 가 throttle 통과시키며 직렬 처리. UI 는 "예상 ~초 후 갱신" 피드백.
3. 시즌 history 는 추후 구현. 다만 **schema/응답에 seasonId 자리** 미리 마련.
표시 항목:
- **챔피언 통계** (`statistics.png`): 큐 탭 / 랭크 필터 / 시즌 필터 / 정렬 가능 표
- **최근 전적** (`123123.png`, poro.gg 스타일): win/lose 좌측 라벨 · 챔프+룬+소주 · KDA · CS · KP% · 양 팀 5명 미니 · 펼치기 시 상세
---
## 2. 설계
### 2.1 라우팅 / 트리거
- 신규 라우트: `/users/:userId/history`
- query param: `?queue=summoners-rift&rank=solo&season=current`
- 클릭 트리거: AuctionPage TeamPanel 멤버 row, PlayerSpotlight 헤더, MatchDetailPage ParticipantRow — **소환사명+아이콘 묶음만** Link (행 전체 X — 입찰 버튼 충돌)
- ACL 없음 (외부 공유 OK — 선행 결정)
### 2.2 큐 매핑
```ts
// apps/web/src/lib/riot-queue.ts (신규) + apps/api/src/modules/riot/riot-queue.constants.ts (신규)
export const RIOT_QUEUE_GROUPS = {
'summoners-rift': {
label: '소환사의 협곡',
queues: { all: [400, 420, 430, 440], solo: [420], flex: [440], normal: [400, 430] },
},
'aram': { label: '칼바람 나락', queues: { all: [450], solo: [], flex: [], normal: [450] } },
'urf': { label: '우르프', queues: { all: [900, 1900], solo: [], flex: [], normal: [900, 1900] } },
'arena': { label: '아레나', queues: { all: [1700, 1710], solo: [], flex: [], normal: [1700, 1710] } },
} as const;
```
`랭크 전체 = solo ∪ flex`. `일반 = 400/430`. queueId 는 [queues.json](https://static.developer.riotgames.com/docs/lol/queues.json) 1차 기준 — §6.B 검증.
### 2.3 enrichment 정책 — server-only + on-demand 큐잉
페이지 진입 시 **API 호출 0**. 다음 두 경로로만 데이터가 채워짐:
| 경로 | 트리거 | 우선순위 |
|---|---|---|
| 야간 prefetch (선행 plan §3.8) | 03~07시 KST | low |
| 사용자 "갱신" 버튼 | 명시적 클릭 | high |
| 신규 RiotAccount 등록 | dakao 명령 | high (동기 — 큐 우회) |
→ **서버 데이터만** 보여줌. 큐 미사용 데이터(예: 첫 방문 사용자, 한 번도 prefetch 안 된 큐) 는 빈 상태 placeholder + "갱신" 버튼 강조.
#### schema 확장
```ts
// RiotAccount 에 추가
matchIdsByQueueFetchedAt?: Map<number, Date>; // 큐별 마지막 list 페치 시각
lastRefreshRequestedAt?: Date; // refresh budget 추적
```
### 2.4 전역 Riot API 작업 큐 (핵심)
#### 왜 Redis Stream (Garnet)
NATS JetStream 과 비교 검토 결과 **Redis Stream 채택**:
| 항목 | Redis Stream (Garnet) | NATS JetStream |
|---|---|---|
| 추가 셋업 | **0** (이미 사용 중) | stream/consumer 활성화 필요 |
| 클라이언트 코드 | `garnet.ts` 의 `xAdd/xReadGroup/xAck/xPending/xClaim` wrapping 재사용 | 신규 작성 |
| ack / redelivery | PEL + `xClaim` 기본 | 기본 |
| consumer group | 지원 | 지원 |
| 운영 부담 | Redis 모니터링만 | NATS + JetStream 둘 다 |
→ 단일 작업 종류 + 우선순위 2단계 + dedup 워크로드에 Redis Stream 충분. 우리 `GarnetClient` 의 stream 메서드 그대로 활용.
#### 스트림 구조
```
stream: riot:queue:high # 사용자 갱신 요청
stream: riot:queue:low # 야간 prefetch
consumer group: riot-refresh-worker (양 stream 공통)
```
- **우선순위 = stream 분리**. worker 한 사이클에서 high `xReadGroup` 먼저 → 비면 low `xReadGroup` (BLOCK 1s).
- **단일 active worker 인스턴스**. rate limit 자체가 글로벌 직렬화라 분산해도 의미 없음. Garnet `setStringIfAbsent('riot:worker:leader', ..., 60s)` 로 leader election, leader 만 loop. lease 갱신은 worker tick 마다.
- **PEL/xClaim 으로 crash recovery**: leader 가 죽으면 30분 idle 후 새 leader 가 PEL 메시지 claim → 재처리.
#### 작업 단위 — sub-job 분할 (큐 그룹별 1 job)
사용자가 `queueGroup='all'` 같은 다중 큐를 요청해도 **백엔드가 큐 그룹 단위로 sub-job 으로 쪼개 enqueue**. 이유:
- 한 사용자 갱신이 큐를 길게 점유하지 않음 → fairness 향상
- 큐 그룹 1개 끝나는 즉시 부분 결과 표시 가능 (소협 끝 → 소협 데이터부터 보임)
- ETA 표시가 자연스러움 ("소협 12초 / 칼바람 8초 / ... 합 36초")
```ts
interface RefreshSubJob {
jobId: string; // uuid
parentJobId?: string; // 그룹 묶음 식별 (UI 진행률 합산용)
userId: string;
puuid: string;
region: RiotRegionalRoute;
platform: RiotPlatformRoute;
queueGroup: keyof typeof RIOT_QUEUE_GROUPS; // 'summoners-rift' 등
queueIds: number[]; // 그룹 내 모든 큐
requestedAt: number;
requestedBy?: string;
priority: 'high' | 'low';
}
```
dedup 키:
- `riot:job:dedup:<puuid>:<queueGroup>` NX EX 5분
- 이미 있으면 기존 jobId 반환, 새 enqueue 안 함
#### 신규 모듈
```
apps/api/src/modules/riot-job-queue/
riot-job-queue.module.ts
riot-job-queue.service.ts # enqueue / dedup / status / ETA / parent 그룹
riot-job-worker.service.ts # leader election + xReadGroup loop
riot-job-queue.types.ts
riot-job-queue.controller.ts # GET /riot/jobs/:jobId, /riot/jobs/stats
```
`RiotJobQueueService.enqueueRefresh(params: { puuid, userId, queueGroups: string[], priority, ... }): Promise<EnqueueResult>`
- 입력 큐 그룹별 sub-job 생성
- 각 sub-job dedup → 기존 또는 신규 publish (`xAdd`)
- 응답:
```ts
interface EnqueueResult {
parentJobId: string;
subJobs: { jobId: string; queueGroup: string; alreadyQueued: boolean; etaSeconds: number; queuePosition: number }[];
totalEtaSeconds: number;
}
```
`RiotJobQueueService.getStatus(jobId): Promise<JobStatus>`
- Garnet `riot:job:status:<jobId>` (state, enqueuedAt, startedAt, finishedAt, error, etaSeconds)
`RiotJobQueueService.getParentStatus(parentJobId): Promise<ParentStatus>`
- 모든 sub-job 합쳐서 진행률 (`done / total`) + 남은 ETA 계산
`RiotJobWorkerService`:
- leader 만 동작. follower 는 lease 만 polling.
- pseudo:
```ts
while (alive) {
const msg = await garnet.readGroup('riot:queue:high', GROUP, consumer, '>', { count: 1, blockMs: 100 });
const target = msg ?? await garnet.readGroup('riot:queue:low', GROUP, consumer, '>', { count: 1, blockMs: 1000 });
if (!target) continue;
await processSubJob(target); // ensureFreshForQueue + 그룹 페치 dedup
await garnet.acknowledgeStream(stream, GROUP, target.id);
await refreshLeaderLease();
}
```
- 작업 시작 → 끝 까지 RiotClientService 가 throttle 통과. 별도 sleep 없음.
- 완료/실패 시 status 업데이트 + Garnet pub `riot:refresh:events` 채널 publish → socket.io 게이트가 broadcast (§2.5.2 참고).
- EWMA 로 평균 작업 시간 갱신 (key: `riot:job:avg-seconds`).
#### 운영자 controls
- `GET /riot/jobs/stats` — high/low 큐 길이, 평균 처리 시간, 최근 실패율, 현재 leader instance id
- `POST /riot/jobs/drain` (admin) — 큐 비우기
### 2.5 UX 피드백 — 채택 정책 (사용자 결정)
세 가지 권장안 모두 채택: **(1) Stale-while-revalidate + (2) Refresh broadcast + (3) 그룹 페치 dedup**.
#### 2.5.1 Stale-while-revalidate
- 페이지 진입 시 서버 데이터 **즉시 표시** (Riot API 호출 0).
- 동시에 백그라운드로 `enqueueRefresh({puuid, queueGroups: [현재 탭], priority: 'low', requestedBy: 'page-view'})` 자동 호출 — refresh budget 통과 시에만.
- 사용자가 "갱신" 버튼을 누르면 동일 enqueue 를 `priority: 'high'` 로 재발행 (dedup 으로 중복 방지, 단 priority 격상).
- 결과 도착 시 broadcast 로 자동 reload (§2.5.2).
→ 사용자가 갱신을 의식하지 않아도 자연 신선화. 명시적 클릭은 "지금 당장 + high 우선순위" 의미.
#### 2.5.2 Refresh broadcast (socket.io)
- 기존 `useAuctionSocket` 패턴 재활용. 신규 namespace `/riot-refresh` 또는 같은 socket 의 `riot-refresh` event.
- 클라가 페이지 진입 시 `subscribe('puuid:<puuid>')` join.
- worker 가 sub-job 완료 시 `emit('riot-refresh', { parentJobId, jobId, queueGroup, puuid, state })` broadcast.
- 같은 puuid 페이지를 보는 **모든 클라**가 React Query invalidate → 자동 reload.
- per-queue-group 단위 invalidate 라 부분 결과 점진 표시 가능 (소협 끝 → 소협 표/카드만 reload).
#### 2.5.3 그룹 페치 dedup
- worker 가 sub-job (puuid, queueGroup) 처리 시:
1. `RiotRecentMatchesService.ensureFreshForQueue` 가 큐별 list call (그룹 N큐 면 N call)
2. **detail call 은 그룹 내 모든 큐의 matchId 합집합에서 RiotMatch 미존재분만** 페치 — 큐 사이 중복 매치 dedup
3. 같은 puuid 의 이미 처리된 sub-job(같은 parentJobId) 이 동일 detail 을 가져왔으면 skip
- 4개 그룹 동시 갱신 시 detail 호출량 ~30% 감소 추정.
#### 2.5.4 "갱신" 클릭 흐름
```
[갱신 버튼] 클릭
│
├─→ POST /communities/:cid/users/:uid/refresh
│ body: { queueGroups: ['summoners-rift', ...], priority: 'high' }
│ resp: { parentJobId, subJobs: [{jobId, queueGroup, etaSeconds, queuePosition, alreadyQueued}], totalEtaSeconds }
│
├─→ 즉시 토스트: "갱신을 요청했어요. 약 36초 후 반영됩니다 (대기열 4번째)"
│ - alreadyQueued 면 "이미 요청 중입니다 (남은 시간 ~)"
│
├─→ socket.io 'riot-refresh' subscribe (parentJobId/puuid 필터)
│ - sub-job 완료 도착마다 해당 큐 그룹 React Query invalidate
│
└─→ 모든 sub-job 완료 시 토스트 "갱신 완료"
실패 시 토스트: "갱신 실패: <reason>. 잠시 후 다시 시도해 주세요."
```
#### 2.5.5 Refresh budget — 폭주 방지
- 사용자당 **5분에 1회** (`RiotAccount.lastRefreshRequestedAt` 검사). 단, page-view 로 자동 enqueue 된 low priority 는 별도 카운터 (사용자당 1시간 1회).
- 글로벌 high 큐 길이가 50 초과면 새 high enqueue 거부 (`429 { reason: 'queue-full', retryAfterSeconds }`)
- IP 단위 rate limit 은 Phase 후속.
#### 2.5.6 빈 데이터 placeholder
- 챔피언 통계 0 행: "아직 수집된 매치가 없습니다. [갱신 요청] 을 눌러 가져오세요." (Stale-while-revalidate 가 이미 백그라운드로 fetch 중이면 "갱신 중..." 으로 자동 변경)
- 최근 전적 0 건: 동일.
- 마지막 갱신 시각 항상 표시: "마지막 업데이트: 3시간 전"
### 2.6 시즌 정책 (history 추후 구현, 설계 고려)
#### 현재
- `Community.seasonStartedAt: Date?` (선행 plan) — 단일 시즌 경계.
#### 미래 호환 schema 자리 (지금 추가)
```ts
// schema.ts Community
seasons?: Array<{
id: string; // ex: '2026-split-1'
label: string; // ex: '2026 시즌'
startedAt: Date;
endedAt?: Date;
}>;
// 'current' 시즌 = endedAt 없는 마지막 entry
```
본 plan 1차에서는 `seasons` 미사용, 응답에 `seasonId: 'current' | string` 만 노출. 추후 history 도입 시 dropdown 만 채우면 됨.
#### API 응답에 미리 자리 잡기
```ts
interface ChampionStatsResponse {
// ...
season: { id: string; label: string; startedAt: string | null; endedAt: string | null };
}
```
→ 클라 dropdown 이 `[{id: 'current', label: '현재 시즌'}]` 한 개만 받지만 구조는 list. 추후 backend 가 history 풀 때 client 코드 무수정.
### 2.7 백엔드 aggregate API
#### A. 챔피언 통계
```
GET /communities/:cid/users/:uid/champion-stats
?queueGroup=summoners-rift
&rank=solo|flex|all|normal
&seasonId=current (현재 'current' 만)
```
응답:
```ts
interface ChampionStatsResponse {
queueIds: number[];
season: { id: 'current' | string; label: string; startedAt: string | null; endedAt: string | null };
lastFetchedAt: string | null; // 큐별 fetchedAt 중 가장 오래된 값
champions: ChampionStatsRow[];
totals: ChampionStatsRow;
}
interface ChampionStatsRow {
championId: number;
games: number; wins: number; losses: number; winRate: number;
avgKills: number; avgDeaths: number; avgAssists: number; kda: number;
totalKills: number; totalDeaths: number; totalAssists: number;
doubleKills: number; tripleKills: number; quadraKills: number; pentaKills: number;
avgCs: number; avgCsPerMin: number;
}
```
집계: MongoDB aggregation pipeline. `$match: {participantPuuids, queueId: {$in}, gameCreation: {$gte: seasonStartedAt}}` → `$project participant slice` → `$group by championId`.
캐시: Garnet `riot:champstats:<puuid>:<queueGroup>:<rank>:<seasonId>` TTL 1h.
#### B. 최근 전적 (페이지네이션) — poro.gg 카드
`poro.gg-html.txt` 분석 기준 카드 항목:
- 좌측 라벨: `승리 / 패배 / 다시 둠(remake)` + 큐 종류 ("자유 랭크") + 날짜 ("4월 19일") + 게임 시간 ("28:52")
- 챔피언 아이콘(52px) + 챔피언 레벨 + 룬 키스톤 + 부 룬 스타일 + 소환사 주문 2개
- KDA 큰 숫자 ("4 / 14 / 6") + **평점** ("0.71 평점")
- 우측 통계 컬럼: **킬 관여 %** + **CS** (분당 CS 병기) + **시야점수** + (제어와드 / 와드 설치 / 와드 파괴 아이콘 + 숫자)
- 아이템 6칸 + 트링킷 1칸
- **자주 함께한 챔피언 / 자주 함께한 소환사** 2열 (각 5명, 미니 챔피언 14px + 소환사명)
- 우측 토글 버튼 "매치 상세 정보 열기"
```
GET /communities/:cid/users/:uid/recent-matches
?queueGroup=summoners-rift
&rank=all
&championId=84 (선택, 챔피언 검색 필터)
&limit=10
&cursor=<gameCreation>
```
응답:
```ts
interface RecentMatchesResponse {
matches: RecentMatchView[];
nextCursor: number | null;
lastFetchedAt: string | null;
season: { id: string; label: string; startedAt: string | null; endedAt: string | null };
}
interface RecentMatchView {
matchId: string;
queueId: number;
queueLabel: string; // '자유 랭크' 등
gameCreation: number;
gameDuration: number; // 초
win: boolean;
remake: boolean; // gameEndedInEarlySurrender 또는 duration < 240s
// 본인 participant
championId: number;
championLevel: number;
teamPosition: string; // 'TOP' | 'JUNGLE' | 'MIDDLE' | 'BOTTOM' | 'UTILITY' | ''
kills: number; deaths: number; assists: number;
kda: number; // (k+a)/d, deaths=0 이면 (k+a)
rating: number; // 평점 — § 2.7.B.1 산식
totalCs: number; // totalMinionsKilled + neutralMinionsKilled
csPerMin: number;
killParticipation: number; // 0~100, 본인 (k+a) / 팀 총킬
visionScore: number;
controlWardsBought: number; // visionWardsBoughtInGame
wardsPlaced: number;
wardsKilled: number;
damageDealtToChampions: number;
damageTaken: number;
goldEarned: number;
items: number[]; // 6칸 (item0~5)
trinket: number; // item6
summonerSpells: [number, number]; // summoner1Id, summoner2Id
perks: { primaryStyle?: number; subStyle?: number; keystone?: number };
// 양 팀 5명씩 미니 (poro.gg 우측 두 컬럼)
teams: Array<{
side: 100 | 200;
win: boolean;
objectives?: { baron?: number; dragon?: number; tower?: number };
participants: Array<{
puuid: string;
gameName: string;
tagLine: string;
championId: number;
teamPosition: string;
kills: number; deaths: number; assists: number;
}>;
}>;
}
```
##### 2.7.B.1 평점 (rating) 산식
poro.gg/op.gg 의 정확한 산식은 비공개. 1차 근사:
```
rating = 0.4 * normalize(kda) // KDA 기여
+ 0.2 * normalize(killParticipation)
+ 0.2 * normalize(csPerMin)
+ 0.1 * normalize(damageShare) // damage / 팀 총damage
+ 0.1 * normalize(visionScore) // jungle/support 가중
```
- normalize 는 라인별 평균 대비 z-score → 0~10 사이 클램프
- "Perfect" = deaths === 0 일 때 최대값 표시 (poro.gg 동일)
- 정확한 산식은 Phase 후속에서 운영자 캘리브레이션
#### B'. 최근 N게임 요약 박스 (poro.gg 헤더)
이미지 상단의 "최근 20게임 전적 요약" 박스 응답:
```
GET /communities/:cid/users/:uid/recent-summary
?queueGroup=summoners-rift
&rank=all
&championId=84 (선택, 검색 필터와 연동)
&limit=20 (기본 20)
```
```ts
interface RecentSummaryResponse {
windowSize: number; // 실제 사용된 매치 수 (≤ limit)
winRate: number; wins: number; losses: number;
streak: { type: 'win' | 'loss'; count: number }; // "2 연패"
kda: number; // 총합 기준
avgKills: number; avgDeaths: number; avgAssists: number;
bestRating: { rating: number | 'Perfect'; kills: number; deaths: number; assists: number; matchId: string };
positionRates: Partial<Record<RiotLane, number>>; // "비드 100%" 등 라인별 픽률
topChampions: Array<{ // 자주 플레이하는 챔프 상위 3
championId: number;
games: number;
winRate: number; // %
pickRate: number; // 본 큐 그룹 내 비율 %
avgRating: number;
}>;
lastFetchedAt: string | null;
}
```
서버 aggregate. Garnet 캐시 1h TTL. 키: `riot:recentsummary:<puuid>:<queueGroup>:<rank>:<championId|none>:<limit>`.
#### C. 갱신 요청
```
POST /communities/:cid/users/:uid/refresh
body: { queueGroups: string[], priority: 'high' | 'low' }
응답: EnqueueResult (§2.4)
또는 429 { reason: 'cooldown' | 'queue-full', retryAfterSeconds }
```
#### D. 작업 상태
```
GET /riot/jobs/:jobId
응답: { state: 'queued' | 'processing' | 'completed' | 'failed',
etaSeconds: number, enqueuedAt, startedAt, finishedAt, error? }
```
### 2.8 인덱스 보강
`RiotMatch` schema 에 추가:
- `{ participantPuuids: 1, queueId: 1, gameCreation: -1 }` (queue 필터 + 정렬)
---
## 3. 변경 사항 (파일 단위)
### 3.1 백엔드 신규
```
apps/api/src/modules/riot/riot-queue.constants.ts
apps/api/src/modules/riot-job-queue/
riot-job-queue.module.ts
riot-job-queue.service.ts
riot-job-worker.service.ts
riot-job-queue.types.ts
riot-job-queue.controller.ts # GET /riot/jobs/:jobId, /riot/jobs/stats
apps/api/src/modules/match-history/
match-history.module.ts
match-history.controller.ts # champion-stats, recent-matches, refresh
match-history.service.ts
match-history-cache.service.ts
match-history.types.ts
```
### 3.2 백엔드 수정
- `schema.ts`:
- `RiotAccount.matchIdsByQueueFetchedAt: Map<number, Date>`
- `RiotAccount.lastRefreshRequestedAt: Date`
- `Community.seasons` (자리만)
- `RiotMatch` 신규 인덱스
- `riot-recent-matches.service.ts`:
- `ensureFreshForQueue({puuid, queueId, ttlMs, limit})` — worker 가 호출
- `RiotJobWorkerService` 가 `RiotRecentMatchesService.ensureFreshForQueue` 직접 호출
- `app.module.ts`: `RiotJobQueueModule`, `MatchHistoryModule` import
### 3.3 프런트 신규
```
apps/web/src/lib/riot-queue.ts
apps/web/src/pages/UserHistoryPage.tsx
apps/web/src/components/history/
UserHistoryHeader.tsx # 프로필 + 마지막 갱신 + 갱신 버튼
QueueTabs.tsx # 전체/솔로/자유/일반/칼바람/우르프/아레나
RankFilter.tsx
SeasonSelector.tsx # 'current' 1개만 — 미래 list 호환
ChampionSearchFilter.tsx # 챔피언 검색 (한글 초성/별명 매칭) — 클라사이드 + ddragon manifest
RecentSummaryBox.tsx # "최근 20게임 전적 요약" (승률/KDA/최고평점/포지션픽률/자주픽챔)
ChampionStatsTable.tsx # 정렬 가능
RecentMatchesList.tsx # useInfiniteQuery
RecentMatchCard.tsx # poro.gg 스타일 (요약/펼치기)
RecentMatchDetail.tsx # 펼친 상세 (양 팀 5명 풀 정보)
RefreshButton.tsx # ETA 토스트 + socket invalidate
EmptyState.tsx
```
> 챔피언 검색: 한글/영문/초성/별명 매칭(가렌, ㄱㄹ, garen 등). ddragon manifest 의 `name` + 별명 사전(별도 정적 파일 `apps/web/src/lib/champion-aliases.ts`)으로 클라사이드 필터. 백엔드는 `championId` 만 받음.
### 3.4 프런트 수정
- `App.tsx`: `<Route path="/users/:userId/history" element={<UserHistoryPage />} />`
- `api/hooks.ts`: `useChampionStats`, `useRecentMatches` (`useInfiniteQuery`), `useRefreshAccount`, `useJobStatus`
- `api/types.ts`: 응답 타입들
- `AuctionPage.tsx`, `MatchDetailPage.tsx`: 소환사명+아이콘 묶음을 `<Link>`
### 3.5 socket.io 통합
기존 `useAuctionSocket` 패턴 재활용. 신규 namespace `/riot-refresh` 권장 (auction socket 분리):
- 클라가 페이지 진입 시 `socket.emit('subscribe', { puuid })`
- worker 가 sub-job 완료 시 `gateway.to(`puuid:${puuid}`).emit('riot-refresh', { parentJobId, jobId, queueGroup, state })`
- 클라가 메시지 수신 시 해당 큐 그룹 React Query (`['champion-stats', puuid, queueGroup, ...]`, `['recent-matches', ...]`, `['recent-summary', ...]`) invalidate
- 같은 puuid 페이지를 보는 모든 클라가 동시에 새로고침됨 (broadcast 효과)
---
## 4. 단위 테스트
- `riot-job-queue.service.spec.ts`
- dedup: 같은 (puuid, queueIds) enqueue 시 동일 jobId 반환
- ETA 계산: 큐 길이 × avg → seconds
- refresh budget: 5분 안 재요청 시 429
- `riot-job-worker.service.spec.ts`
- high subject 우선 처리, high 비면 low fetch
- throttle wait 시 작업 그대로 진행
- `match-history.service.spec.ts`
- queueGroup → queueIds 매핑
- aggregate 결과 sums/avgs 정확
- season 필터 적용 (gameCreation < startedAt 제외)
- cursor 페이지네이션 nextCursor 정확
- `match-history-cache.service.spec.ts`
- 같은 키 두 번째 호출 aggregate 0회
- 프런트
- `RefreshButton` 토스트 ETA 문구
- `ChampionStatsTable` 정렬 토글
- `RecentMatchCard` win/lose 색상, remake 표시
---
## 5. Rollout
1. (PR-1) `riot-queue.constants.ts` + schema 확장 (`matchIdsByQueueFetchedAt`, `lastRefreshRequestedAt`, `Community.seasons` 자리, RiotMatch 인덱스 보강) + `ensureFreshForQueue`
2. (PR-2) `RiotJobQueueModule` (Redis Stream consumer + leader election + dedup + sub-job 분할 + status) + 테스트
3. (PR-3) `MatchHistoryModule` champion-stats + recent-summary + Garnet 캐시
4. (PR-4) recent-matches + cursor 페이지네이션 + 평점 산식
5. (PR-5) refresh 엔드포인트 + budget + socket `/riot-refresh` namespace
6. (PR-6) 그룹 페치 dedup 로직 (worker 내부)
7. (PR-7) 프런트 라우트 + `UserHistoryPage` 골격 + `QueueTabs` + `RankFilter` + `SeasonSelector`
8. (PR-8) `RecentSummaryBox` + `ChampionStatsTable` (정렬)
9. (PR-9) `RecentMatchCard` (poro.gg 스타일) + `RecentMatchDetail` 펼치기
10. (PR-10) `ChampionSearchFilter` (별명 사전 + 초성 매칭)
11. (PR-11) `RefreshButton` + Stale-while-revalidate 자동 enqueue + ETA 토스트 + socket invalidate
12. (PR-12) AuctionPage / MatchDetailPage 클릭 트리거
13. (PR-13) 운영 모니터링 (큐 길이 / aggregate 응답 시간 / Garnet hit / leader 상태)
---
## 6. 추가 고려사항
### 확정 (사용자 결정 2026-04-26)
- **서버 데이터만 표시**: 페이지 진입 시 Riot API 호출 0회
- **전역 작업 큐**: **Redis Stream (Garnet)** — high/low stream 분리 + dedup + leader election + PEL/xClaim 재처리
- **작업 단위**: queueGroup 단위 sub-job 분할 (한 사용자가 큐 길게 점유 X)
- **UX 정책**: (1) Stale-while-revalidate + (2) Refresh broadcast + (3) 그룹 페치 dedup 모두 채택
- **Refresh budget**: 5분당 1회 high, 1시간당 1회 low(자동)
- **카드 스타일**: poro.gg (`poro.gg-html.txt` 분석 기준 — 평점/킬관여/시야/와드/자주함께한 챔피언·소환사 포함)
- **챔피언 검색 필터**: 클라사이드 (한글/영문/초성/별명)
- **시즌 history**: 본 plan 1차 미구현, schema/응답에 자리만 마련
### 미결 (가벼운 확인 권장)
#### A. 평점 산식 캘리브레이션
§2.7.B.1 의 1차 근사 가중치는 추측. 실제 사용자 데이터로 분포 확인 후 조정 필요. 운영 후 Phase 후속에서 처리.
#### B. 큐 매핑 검증
`RIOT_QUEUE_GROUPS` 의 큐 id 는 [queues.json](https://static.developer.riotgames.com/docs/lol/queues.json) 1차 추정. 운영 사용자 데이터로 검증 필요.
#### C. Refresh 폭주 시나리오
큐가 길 때 "현재 갱신 요청이 많습니다 (대기 12분)" 표시 + 야간 prefetch 안내. 너무 길면 갱신 자체를 비활성화.
#### D. socket.io 가드
`/riot-refresh` namespace 가 외부 공개라 puuid subscribe 가 무제한이면 broadcast 비대화 가능. 동일 socket 당 max subscribe 수 제한 (예: 5) 추가 권장.
### 추후 (Phase 후속)
- 시즌 history 본격 도입 (`Community.seasons` 활용 + dropdown)
- 평점 산식 캘리브레이션
- IP 단위 rate limit
- admin 페이지 (큐 모니터링 / drain)
- aggregation 결과 mat-view (큐가 매우 길어질 때)
---
## 7. Done 정의
- AuctionPage 멤버 / PlayerSpotlight, MatchDetailPage 참가자 소환사명 클릭 → `/users/:userId/history` 이동
- 페이지에 큐 7탭(전체/솔로/자유/일반/칼바람/우르프/아레나) + 챔피언 검색 + 시즌 dropdown(현재 1개) + 최근 N게임 요약 박스 + 챔피언 통계 표 + 최근 전적 무한 스크롤(poro.gg 카드)
- 페이지 진입 시 **Riot API 호출 0회** (서버 로그로 확인)
- 페이지 진입 시 자동 백그라운드 enqueue (low priority) — 1시간 budget 안에서만
- "갱신" 클릭 시 ETA 토스트 ("약 ~초 후 반영, 대기열 N번째") + sub-job 완료 도착마다 해당 큐 그룹 React Query invalidate (점진 표시)
- 같은 puuid 페이지 보는 다른 클라도 socket broadcast 로 자동 reload
- 같은 사용자 5분 안 high 재요청 시 429 cooldown
- Redis Stream worker 1 인스턴스만 active (leader election 동작), 큐 길이/처리 시간 로그
- 그룹 페치 dedup: 4개 큐 그룹 동시 갱신 시 detail 호출 중복 0건 (로그 metric)
- 챔피언 통계 컬럼 정렬 토글 (게임수 / 승률 / KDA / CS)
- 챔피언 검색 input 에 "ㄱㄹ" 입력 시 가렌·갈리오·갱플랭크 등 hits
- 같은 (puuid, 큐, 랭크, 시즌) 1h 안 재요청 시 aggregation 0회 (Garnet hit)
- `Community.seasons` schema 자리 추가 (1차 empty, 응답 `season.id = 'current'` 고정)
- 단위 테스트 통과 (sub-job 분할 / leader election / 그룹 페치 dedup / 평점 산식 / 챔피언 검색 매칭)
-673
View File
@@ -1,673 +0,0 @@
# Riot 최근 솔로랭크 통계 통합 플랜
> **대상**: codex가 이어서 진행 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-26
> **선행 작업**: Riot-캐싱-Phase2-플랜.md, Riot-DDragon Manifest 도입(`RiotDdragonService` + Garnet 캐시) 완료
---
## 1. Context
`AuctionPage.tsx` 의 "최근 솔로랭크" 카드(승률/전적/KDA/평균 CS)가 현재 모두 `0`/`NaN` 으로 표시됩니다. 백엔드는 이미 `RiotAccount.recentStatsSummary` 필드를 노출하고 있고 mapper도 이를 전달하지만, **이 필드를 채우는 enrichment 단계가 비어 있습니다.**
이번 작업은 다음을 추가합니다.
1. **Match-V5 by-puuid (queue=420)** 으로 솔로랭크 matchId 목록 동기화
2. **Match-V5 detail** 호출 → `RiotMatch` 컬렉션에 raw 보관 (이미 schema 존재)
3. 사용자별 `RiotAccount.recentStatsSummary` 재계산 + `recentStatsFetchedAt` 갱신
4. enrichment 트리거(수동 / 신규 등록 / 경매 직전) 와 TTL/Garnet dedup 적용
5. 클라가 0/NaN 대신 실제 값을 표시하도록 mapper 점검
이미 다음이 갖춰져 있어 추가 인프라가 거의 필요 없습니다.
- `RiotMatchService.getMatchIdsByPuuid({queue, count, ...})` (`riot-match.service.ts`)
- `RiotMatchService.getMatch(matchId)` 가 `RiotMatchDto` 파싱까지 포함
- `RiotMatch` 컬렉션(`riot_match`) + `participantPuuids` 인덱스(`schema.ts:573`)
- `RiotAccount.matchIds`, `matchIdsFetchedAt`, `recentStatsSummary`, `recentStatsFetchedAt` 필드(`schema.ts:128-148`)
- `GarnetService` (in-flight dedup / TTL 락 용도)
---
## 2. 결정된 설계 사항
### 2.1 큐 정책
- **1차 대상은 솔로랭크(`queueId=420`) 만**.
- 자유랭크(`440`)/노말은 추후 Phase 확장. 코드는 `queueId` 를 인자로 받는 형태로 짜되 호출부는 420 고정.
### 2.2 "최근" 의 정의
- **최근 20경기** 고정 윈도우 (사용자 결정). 상수 `RIOT_RECENT_MATCH_LIMIT = 20` 으로 service 모듈에 정의, 환경변수화 하지 않음.
- 시즌 경계 보정은 하지 않음. `mostPlayedChampionIds` 가 시즌 패치에 따라 의미가 흔들릴 수 있다는 한계를 README/주석에 명시.
### 2.3 캐시 / TTL
- `RiotAccount.recentStatsFetchedAt` 기반 staleness 검사. TTL 기본 **6h** (mastery와 동일).
- enrichment 진행 중 동일 (userId, puuid) 키 중복 호출 방지: 메모리 + Garnet **NX 락**.
- 메모리 dedup: `RiotAccountEnrichmentService.inFlight` 패턴 그대로 확장
- Garnet 락: `riot:enrich:matches:<puuid>` 키 + `setStringIfAbsent(..., 60)` (다중 인스턴스 안전망)
- ddragon manifest 패턴(`Riot-DDragon`)과 동일하게 in-flight 후 **TTL 캐시 갱신** → 다음 호출은 즉시 fresh 반환.
### 2.4 RiotMatch 저장 정책
- `RiotMatch.matchId` 기준 upsert. **이미 존재하면 API 재호출하지 않음** (다른 사용자가 이미 가져왔을 가능성).
- `participantPuuids` 인덱스 활용 → 한 puuid 의 최근 N경기를 DB에서 즉시 조회 가능.
- Riot raw 응답은 `raw` 필드(Mixed) 에 통째로 저장. 핵심 메타(`gameCreation`, `gameDuration`, `gameVersion`, `queueId`) 는 top-level 으로 복제(필터/정렬용).
- 페이로드 크기 우려: 한 경기 ≈ 30~80KB. 활성 사용자 100명 × 20경기 = 최대 2k 도큐먼트 ≈ 100MB 미만, 같은 매치 dedup 으로 실제는 더 작음.
- **TTL/prune 없음 (사용자 결정).** 무한 누적 정책. 추후 컬렉션 비대화 시 별도 prune job 검토.
### 2.5 통계 계산 규칙 (라인별 분리)
**사용자 결정 2026-04-26**: 탑/정글/미드/바텀/서폿 라인별로 데이터 구분 필요.
#### 라인 식별
- Match-V5 participant 의 `teamPosition` 필드 (`TOP` | `JUNGLE` | `MIDDLE` | `BOTTOM` | `UTILITY`) 사용.
- 빈 문자열인 경우 `individualPosition` 으로 fallback.
- 둘 다 비어있거나 `Invalid` 면 통계에서 제외 (집계 카운트 안 함).
#### 우리 측 enum 매핑
```ts
// schema 신규
export type RiotLane = 'TOP' | 'JUNGLE' | 'MIDDLE' | 'BOTTOM' | 'UTILITY';
const POSITION_TO_LANE: Record<Position, RiotLane> = {
TOP: 'TOP',
JGL: 'JUNGLE',
MID: 'MIDDLE',
ADC: 'BOTTOM',
SUP: 'UTILITY',
};
```
#### 새 데이터 구조
```ts
export interface RiotLaneStats {
games: number;
wins: number;
losses: number;
avgKills: number; // 소수 1자리
avgDeaths: number;
avgAssists: number;
avgCs: number; // (totalMinionsKilled + neutralMinionsKilled) / games
avgCsPerMin: number; // 분당 CS — 라인 비교용 (서폿 비교 한계 보정)
mostPlayedChampionIds: number[]; // 상위 3, Riot DTO 와 동일 number
}
export interface RiotRecentStatsSummary {
overall: RiotLaneStats;
byLane: Partial<Record<RiotLane, RiotLaneStats>>; // 게임이 1회 이상 있는 라인만 entry
// 기존 flat 필드들은 schema 마이그레이션을 통해 제거. § 2.5.1 참고.
}
```
`mostPlayedChampionIds` 는 **`number[]`** (Riot DTO 와 동일). 클라는 ddragon manifest 로 표시명 풀이. § 2.5.3 참고.
### 2.5.3 championId 타입 통일 (전체 number)
기존 정합성 깨진 곳: `RiotRecentStatsSummary.mostPlayedChampionIds: string[]` (`schema.ts:123`) — Phase2 에서 mastery 는 number 로 바꿨는데 이 한 줄만 string 으로 잔존. Riot 모든 응답이 number 이므로 **number 로 통일**.
영향 받는 위치:
- `apps/api/src/modules/global/database/schema.ts:123` — `string[]` → `number[]`
- `apps/api/src/modules/riot/riot.types.ts` — `RiotRecentStatsSummary` 동일 변경
- `apps/web/src/api/types.ts` — `ApiRiotRecentStatsSummary.mostPlayedChampionIds`, 그리고 §3.7 신규 `ApiRiotLaneStats` 도 처음부터 `number[]`
- `apps/web/src/lib/ddragon.ts` — 이미 `string | number` 둘 다 받게 만들어둠. 변경 불필요.
기존 DB 도큐먼트에 `string[]` 으로 저장된 게 있을 가능성: enrichment 한 번 돌면 새 구조로 통째 교체되므로 자동 정리. 별도 마이그레이션 스크립트 불필요.
#### 2.5.1 schema 마이그레이션 메모
- 기존 `RiotRecentStatsSummary` (flat) 는 사용처가 mapper 한 곳뿐 (`mappers.ts:184~`).
- DB 에 이미 저장된 도큐먼트는 옛 형태일 수 있으나 enrichment 가 한 번 돌면 자동 덮어씀.
- 안전한 전환: enrichment service 가 응답 직전 항상 새 구조로 만들어 `account.recentStatsSummary = newSummary` 통째 교체. partial merge 안 함.
- 별도 마이그레이션 스크립트 불필요 (TTL 6h 안에 자연 갱신).
### 2.5.4 시즌 경계 — 자동 리셋
LoL 시즌(splits/sets) 시작 시점에는 누적 통계의 의미가 변하므로 자동 리셋 필요. Riot 이 명시적 "season started at" API 를 제공하지 않으므로 **community 단위 수동 설정 + 자동 필터링** 의 하이브리드.
#### Schema 추가
```ts
// schema.ts Community
seasonStartedAt?: Date; // 운영자/admin 이 시즌 시작 시점 등록
```
#### 동작
1. enrichment 진입 시 `community.seasonStartedAt` 조회.
2. `account.recentStatsFetchedAt < community.seasonStartedAt` 이면 **force=true** 로 진행 (TTL 무시).
3. `computeSummary` 가 매치 필터링: `match.info.gameCreation >= seasonStartedAt.getTime()` 인 것만 사용.
4. `account.matchIds` 도 시즌 경계 이전 것은 통계에서 제외 (DB 자체에서는 제거 안 함 — 무한 저장 정책).
#### Trigger
- 운영자가 새 시즌 시작 시 community 의 `seasonStartedAt` 을 수동 갱신 → 다음 enrichment 부터 자동 적용.
- 야간 prefetch 가 다음 사이클에 일괄 갱신.
#### Phase 후속 (자동화 검토)
- Riot patch notes RSS 또는 ddragon `versions.json` 의 major bump 감지로 자동 갱신 — 본 플랜 범위 외.
### 2.5.5 다국가 region 지원 (구조)
현재 enrichment 가 `region: 'asia'`, `platform: 'kr'` 하드코딩. 이미 `Community.riotPlatform`, `Community.riotRegion` 필드는 schema 에 존재하지만 enrichment 호출부에서 사용 안 함.
#### 변경
1. **호출자 책임 모델**: `enrichRiotAccount` 의 `EnrichOptions.platform/region` 으로 community 값을 명시 전달.
2. enrichment 트리거 지점 (`auction.service`, `dakao-user.service`, `prefetch.scheduler`) 에서 community 조회 후 platform/region 을 옵션에 주입.
3. fallback 기본값은 `kr` / `asia` 유지 (community 미지정 시).
4. **Throttle 분리**: §2.7 의 sliding-window 키가 이미 region 별로 분리됨 (`riot:rl:<region>:1s`) — 추가 변경 없음.
5. **DDragon 영향**: `realms/<region>.json` 별 자체 dd 버전이 다를 수 있음. 현재 `RiotDdragonService` 는 글로벌 versions[0] 사용 중 — 한국 클라이언트 dd 버전이 글로벌과 차이 거의 없어 OK. 다른 region 추가 시 region 별 manifest 캐시로 분리 검토.
#### 호출 패턴
```ts
// auction.service.ts:start
const community = await CommunityModel.findById(params.communityId);
const platform = community?.riotPlatform ?? 'kr';
const region = community?.riotRegion ?? 'asia';
const limit = pLimit(3);
await Promise.allSettled(
order.map(p => limit(() => this.enrichmentService.enrichRiotAccount({
userId: p.userId,
puuid: p.puuid,
options: { platform, region, force: false },
}))),
);
```
`prefetch.scheduler` 는 사용자별 community 를 cursor 단계에서 함께 로드 (또는 community → user 양방향 join).
### 2.5.2 0-state UX (사용자 결정: 적당히 제안)
| 상황 | 표시 |
|---|---|
| `overall.games === 0` (enrichment 실패 또는 신규 사용자) | "최근 솔로랭크 기록이 없습니다" placeholder |
| 주 라인(`mainPosition`) 게임 ≥ 1 | 헤더에 주 라인 통계 강조 표시 |
| 주 라인 게임 = 0, 다른 라인 있음 | 헤더에 `overall` 통계 + "주 라인 기록 없음 / 전체 기준" 보조 라벨 |
| 라인별 미니 row | 게임 ≥ 1 라인은 W-L · KDA · CS/min, 0 게임 라인은 회색 dash |
### 2.6 트리거 시점
| 시점 | 호출 방식 | force |
|---|---|---|
| 신규 RiotAccount 등록 (dakao 명령) | 동기 enrich 호출 | true |
| 사용자 수동 갱신 (Phase2 엔드포인트 추가됨) | 동기 호출 | true |
| 경매 `start` 직전 | 참가자 puuid 일괄 enrich (`p-limit` 적용, §2.7 throttle 참조) | false |
| 야간 스케줄러 (Phase 2 후속) | force=false 로 stale 만 갱신 | false |
→ 본 플랜에서는 **트리거 4개 지점만 호출 추가**. 스케줄러는 Phase 2 트랙에서 처리.
### 2.7 Rate Limit / Throttle (개인키 가정)
**전제**: 개인 API 키 — Riot 공식 한도 `20 req / 1s` + `100 req / 120s` (앱 단위, region 별).
#### A. 사전 차단 — `RiotClientService` 통합 throttle
모든 Riot 호출이 `RiotClientService.get()` 을 통과하므로 여기에 한 곳에서 게이트를 건다. **Garnet 기반 sliding-window** 로 다중 인스턴스 안전성 확보.
키 구조:
```
riot:rl:<region>:1s -- ZSET (score=timestampMs, member=uuid)
riot:rl:<region>:120s -- ZSET (동일)
```
호출 시 의사코드:
```ts
async function acquire(region: string): Promise<void> {
const now = Date.now();
for (;;) {
const wait = await checkAndAdd(region, now); // Lua script 추천
if (wait === 0) return;
await sleep(wait);
}
}
```
`checkAndAdd` 는 **Lua script 1회 호출**(원자성):
1. `ZREMRANGEBYSCORE key 0 (now - windowMs)` 로 윈도우 밖 제거
2. `ZCARD key` 로 현재 카운트
3. 한도 초과 시 `ZRANGE key 0 0 WITHSCORES` 로 가장 오래된 항목의 만료 시각 → 대기 시간 반환
4. 가능하면 `ZADD key now uuid` + `EXPIRE key windowMs` 후 0 반환
두 윈도우(1s/120s) 모두 통과해야 진행. 하나라도 막히면 더 큰 wait 반환.
`apps/api/src/modules/riot/riot-rate-limiter.service.ts` 신규:
```ts
@Injectable()
export class RiotRateLimiterService {
constructor(private readonly garnet: GarnetService) {}
public async acquire(region: RiotRegionalRoute | RiotPlatformRoute): Promise<void>;
// 옵션: per-method 한도 추가 시 추가 인자
}
```
설정 상수(코드 상수, 환경변수화 안 함):
```ts
const APP_LIMITS = [
{ windowMs: 1_000, max: 20 },
{ windowMs: 120_000, max: 100 },
];
```
> 안전 마진을 위해 max 를 **18 / 95** 로 살짝 낮추는 옵션을 코드 주석으로 남김 — 다른 클라이언트(예: 로컬 개발기)와 키를 공유할 때 충돌 방지.
#### B. 사후 처리 — 429 backoff
`RiotClientService.get()` 응답이 429 일 때:
1. 기존 `Retry-After` 캡처 로직(`riot.client.service.ts:125`) 활용
2. `Retry-After` 만큼 대기 후 **최대 1회 재시도**
3. 재시도도 429 면 `RiotApiError` throw (현재 동작 유지)
#### C. 클라이언트단 동시성 제한
Auction `start` 트리거에서 5명 동시 enrichment × (1 list + 최대 20 detail) = burst 가 가장 큼. 사전 차단만으로도 Riot 한도는 지켜지지만, 처리 시간이 길어지므로 **fairness 를 위한 동시성 한도** 도 추가:
- `p-limit` 의존성 추가 (`pnpm --filter api add p-limit`)
- enrichment service 내부에서 `recentMatches` 페치 시 detail 호출을 `pLimit(2)` 로 직렬화
- auction.service 트리거에서도 사용자별 enrichment 자체에 `pLimit(3)` 적용
#### D. 메서드 한도(Method Rate Limit)
Match-V5 `getMatch` 는 `2000 req / 10s` 라 앱 한도가 먼저 걸린다 — **본 플랜에서는 method 한도는 별도 추적 안 함**. 추후 다른 method 추가 시 `RiotRateLimiterService` 가 method 단위 카운터도 받도록 확장.
#### E. 운영 가시성
- `RiotRateLimiterService.acquire()` 가 100ms 이상 대기하면 `logger.warn` (throttle 발생 추적)
- 응답 헤더 `X-App-Rate-Limit-Count` 를 매 호출마다 디버그 로그(샘플링) → 실제 사용량 vs 우리 카운터 drift 확인
---
## 3. 변경 사항 (파일 단위)
### 3.1 신규: `apps/api/src/modules/riot/riot-recent-matches.service.ts`
```ts
@Injectable()
export class RiotRecentMatchesService {
constructor(
private readonly connectionService: ConnectionService,
private readonly matchService: RiotMatchService,
private readonly garnetService: GarnetService,
) {}
/** queue=420 기준 최근 N matchId 동기화 + raw 저장. 새로 가져온 RiotMatch 도큐먼트들 반환 */
public async syncRecentMatches(params: {
puuid: string;
region?: RiotRegionalRoute;
limit?: number; // 기본 20
queueId?: number; // 기본 420
}): Promise<RiotMatchDocument[]>;
/** DB 에서 puuid 기준 최근 N matchInfo 조회 (API 호출 없음) */
public async loadFromDb(params: {
puuid: string;
limit?: number;
queueId?: number;
}): Promise<RiotMatchDocument[]>;
}
```
핵심 로직:
1. `getMatchIdsByPuuid({queue, count, region: 'asia'})`
2. 받은 ids 를 `riot_match.find({matchId: {$in: ids}}, {matchId: 1})` 로 존재 여부 조회
3. 없는 것만 `getMatch(matchId)` → upsert (`updateOne({matchId}, {$setOnInsert: {...}}, {upsert: true})`)
4. Garnet 락: `riot:enrich:matches:<puuid>` NX EX 60. 락 획득 실패 시 즉시 return DB 캐시.
5. queueId 필터: list API 의 `queue` 파라미터로 한 번 거르고, detail 응답의 `info.queueId` 로 한 번 더 검증.
### 3.2 신규: `RiotRecentStatsService` (또는 위 service에 합쳐도 OK)
```ts
public computeSummary(matches: RiotMatchDto[], puuid: string): RiotRecentStatsSummary;
```
- 순수 함수. 단위 테스트 추가(`*.spec.ts`).
- 입력 매치에서 `info.participants.find(p => p.puuid === puuid)` 로 본인 participant 찾기.
- 라인 결정: `teamPosition || individualPosition`. 빈 값이면 `byLane` 집계에서 제외하되 `overall` 에는 포함.
- 0경기 입력 시 `overall` 은 모든 수치 0 으로 채운 객체, `byLane` 은 빈 객체 `{}`. 클라 NaN 회피.
- `avgCsPerMin = ((totalMinionsKilled + neutralMinionsKilled) / (gameDuration / 60))` 의 평균. `gameDuration` 은 초 단위.
### 3.3 `riot-account-enrichment.service.ts` 확장
`EnrichOptions` 에 `recentMatchesTtlMs` (기본 6h) 추가.
`EnrichResult` 에 `recentMatches: 'updated' | 'fresh' | 'failed'` 추가.
`doEnrichRiotAccount` 에:
```ts
const recentMatchesStale =
force ||
!account.recentStatsFetchedAt ||
now - account.recentStatsFetchedAt.getTime() > recentMatchesTtl;
const recentOutcome = recentMatchesStale
? await this.fetchRecentMatchesSafe(params.puuid, region)
: { status: 'fresh' as const, summary: null };
if (recentOutcome.status === 'updated' && recentOutcome.summary) {
account.recentStatsSummary = recentOutcome.summary;
account.recentStatsFetchedAt = new Date();
account.matchIds = recentOutcome.matchIds;
account.matchIdsFetchedAt = new Date();
}
```
`fetchRecentMatchesSafe`:
1. `recentMatchesService.syncRecentMatches({puuid, region})`
2. `recentMatchesService.loadFromDb({puuid, limit: 20, queueId: 420})`
3. `computeSummary(matches, puuid)`
4. 실패 시 `failed` 반환 (기존 patterns와 동일).
### 3.4 `riot.module.ts`
`RiotRecentMatchesService`, `RiotRateLimiterService` 를 providers/exports 에 추가. `GarnetModule` 은 `@Global` 이라 별도 import 불필요.
### 3.4.1 `riot.client.service.ts` 변경
- 생성자에 `RiotRateLimiterService` 주입.
- `get()` 진입 시 `await this.rateLimiter.acquire(options.platform ?? options.region ?? 'asia')`.
- 응답이 429 일 때 `Retry-After` 캡처 후 `await sleep(retryAfterMs)` → 한 번 재시도. 재시도도 429 면 throw.
- (기존 동작과의 차이: throttle/재시도 추가, 그 외 인터페이스 동일.)
### 3.5 트리거 지점
- `apps/api/src/modules/dakao/dakao-user.service.ts`: 신규 RiotAccount 등록 직후 `enrichRiotAccount({force: true})` 호출 흐름이 이미 있는지 확인하고 동일 흐름 유지(별도 호출 추가 불필요).
- `apps/api/src/modules/auction/auction.service.ts:start`: order 구성 직후, 참가자 puuid 들에 대해 `p-limit(3)` 으로 동시성 제한:
```ts
const limit = pLimit(3);
await Promise.allSettled(
order.map(p => limit(() => this.enrichmentService.enrichRiotAccount({
userId: p.userId, puuid: p.puuid, options: {force: false}
}))),
);
```
이미 fresh 면 즉시 return 이라 비용 거의 없음. throttle 은 `RiotClientService` 단에서 추가로 보호.
### 3.6 수동 갱신 엔드포인트
Phase 2 플랜의 `POST /me/riot-accounts/:puuid/refresh` 가 추가되면 동일 enrichment 가 호출되므로, **본 플랜에서 별도 엔드포인트는 만들지 않고** Phase 2 와 합류.
### 3.7 클라 — 변경 큼
#### types.ts
```ts
export interface ApiRiotLaneStats {
games: number;
wins: number;
losses: number;
avgKills: number;
avgDeaths: number;
avgAssists: number;
avgCs: number;
avgCsPerMin: number;
mostPlayedChampionIds: string[];
}
export type RiotLane = 'TOP' | 'JUNGLE' | 'MIDDLE' | 'BOTTOM' | 'UTILITY';
export interface ApiRiotRecentStatsSummary {
overall: ApiRiotLaneStats;
byLane: Partial<Record<RiotLane, ApiRiotLaneStats>>;
}
```
기존 flat 필드는 제거. 클라는 enrichment 한 번 돌고 난 새 구조 가정.
#### mappers.ts
`AuctionPlayerView.recentStats` 를 새 구조로 정렬. 추가로 `pickPrimary(stats, mainPosition)` 헬퍼:
```ts
const POSITION_TO_LANE: Record<Position, RiotLane> = {
TOP: 'TOP', JGL: 'JUNGLE', MID: 'MIDDLE', ADC: 'BOTTOM', SUP: 'UTILITY',
};
function pickPrimary(summary, mainPosition) {
const lane = POSITION_TO_LANE[mainPosition];
const lanePrimary = summary.byLane[lane];
if (lanePrimary && lanePrimary.games > 0) return { stats: lanePrimary, source: 'lane' };
if (summary.overall.games > 0) return { stats: summary.overall, source: 'overall' };
return { stats: null, source: 'none' };
}
```
#### AuctionPage.tsx — "최근 솔로랭크" 카드 재설계
```
┌ 최근 솔로랭크 ─ 미드 ───────┐ ← 헤더에 표시 기준 라인
│ 승률 56% · 28W 22L │
│ KDA 7.1/3.4/8.2 (4.50) │
│ 분당 CS 7.2 │
├──────────────────────────── │
│ 탑 2W 1L · 5.0/3.3/4.7 │ ← byLane 미니 row
│ 정글 — │ ← 0 게임 dash
│ 미드 25W 19L · 7.1/3.4/8.2 │ ← 강조
│ 바텀 — │
│ 서폿 1W 2L · 1.0/4.0/15.7 │
└─────────────────────────────┘
```
- 헤더: `pickPrimary` 결과의 `stats` + `source === 'overall'` 이면 "(전체 기준)" 보조 라벨.
- 미니 row: 5개 라인 고정 순서 (TOP/JGL/MID/ADC/SUP), 게임 0 인 라인은 회색 dash, 주 라인은 텍스트 굵게.
- `pickPrimary` 결과가 `none` 이면 placeholder ("최근 솔로랭크 기록이 없습니다").
- KDA Perfect 처리(deaths=0) 는 기존 로직 유지.
신규 컴포넌트 분리 권장: `RecentSoloStats` 별 파일이 깔끔.
### 3.8 신규: 야간 prefetch 스케줄러 (5슬롯 분산)
`@nestjs/schedule` 의존성 추가 (`pnpm --filter api add @nestjs/schedule`). app.module 에 `ScheduleModule.forRoot()` 등록.
#### 슬롯 분산 정책 (사용자 결정 2026-04-26)
- 03/04/05/06/07 시 KST **5개 슬롯** 으로 분산.
- 사용자 그룹핑: `userId.hash % 5` 로 슬롯 결정 (decimal index 0~4 → 03시~07시 매핑).
- 안전 마진: 각 슬롯 종료 ≤ 다음 슬롯 시작 (1시간 안에 처리 끝나야). 활성 사용자 100명 / 5슬롯 = 20명/슬롯, throttle 100req/120s 안에서 충분.
- 슬롯별 Garnet 락 키 분리: `riot:cron:nightly-prefetch:slot-<idx>` (NX EX 50m). 다중 인스턴스 leader election + 슬롯 간 독립 실행.
```ts
@Injectable()
export class RiotPrefetchScheduler {
private readonly logger = new Logger(RiotPrefetchScheduler.name);
private readonly LOCK_TTL_S = 50 * 60;
private readonly STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
private readonly SLOTS = 5;
private readonly USER_CAP_PER_SLOT = 1000;
constructor(
private readonly connectionService: ConnectionService,
private readonly enrichment: RiotAccountEnrichmentService,
private readonly garnet: GarnetService,
) {}
// 03,04,05,06,07 시 매시 정각
@Cron('0 0 3-7 * * *', { timeZone: 'Asia/Seoul' })
async runSlot() {
const hour = new Date().getHours(); // KST 가정 (TZ 환경 일치 필요)
const slotIndex = hour - 3; // 0..4
if (slotIndex < 0 || slotIndex >= this.SLOTS) return;
const lockKey = `riot:cron:nightly-prefetch:slot-${slotIndex}`;
const acquired = await this.garnet.setStringIfAbsent(
lockKey,
`${process.pid}-${Date.now()}`,
this.LOCK_TTL_S,
);
if (!acquired) {
this.logger.log(`Slot ${slotIndex} skipped — lock held by another instance.`);
return;
}
await this.processSlot(slotIndex);
}
private async processSlot(slotIndex: number) {
const cutoff = new Date(Date.now() - this.STALE_THRESHOLD_MS);
const UserModel = await this.connectionService.getModel('user');
const CommunityModel = await this.connectionService.getModel('community');
const cursor = UserModel.find({
'riotAccounts.recentStatsFetchedAt': { $lt: cutoff },
}).cursor();
const limit = pLimit(2);
let processed = 0;
for await (const user of cursor) {
// 슬롯 분산: hash(userId) % SLOTS
if (this.slotOfUser(user._id.toString()) !== slotIndex) continue;
const community = await CommunityModel.findById(user.communityId).lean();
const platform = community?.riotPlatform ?? 'kr';
const region = community?.riotRegion ?? 'asia';
for (const account of user.riotAccounts) {
const seasonStart = community?.seasonStartedAt;
const seasonStale =
!!seasonStart &&
(!account.recentStatsFetchedAt ||
account.recentStatsFetchedAt < seasonStart);
const ttlStale =
!account.recentStatsFetchedAt || account.recentStatsFetchedAt < cutoff;
if (!ttlStale && !seasonStale) continue;
await limit(() =>
this.enrichment
.enrichRiotAccount({
userId: user._id,
puuid: account.puuid,
options: { platform, region, force: seasonStale },
})
.catch((err) =>
this.logger.warn(`prefetch failed ${account.puuid}: ${err}`),
),
);
processed += 1;
}
if (processed >= this.USER_CAP_PER_SLOT) break;
}
this.logger.log(`Slot ${slotIndex} processed ${processed} accounts.`);
}
private slotOfUser(userId: string): number {
// FNV-1a 32bit — 외부 의존성 없이 안정적 분산
let h = 2166136261;
for (let i = 0; i < userId.length; i += 1) {
h ^= userId.charCodeAt(i);
h = Math.imul(h, 16777619);
}
return Math.abs(h) % this.SLOTS;
}
}
```
#### 동작 요약
- **leader election**: 슬롯별 Garnet NX 락. 다중 인스턴스 중 첫 도달자만 처리.
- **사용자 분산**: FNV-1a 해시로 결정적 분산 (같은 사용자는 항상 같은 슬롯). region 분포가 편향되어도 슬롯별 부하는 균일.
- **throttle 합류**: enrichment 호출이 `RiotRateLimiterService` 통과 → 별도 sleep 불필요.
- **community-aware**: cursor 안에서 community 조회로 platform/region/seasonStartedAt 적용.
- **시즌 force fetch**: `seasonStartedAt > recentStatsFetchedAt` 면 TTL 무시.
- **안전 상한**: 슬롯당 1000 사용자 cap.
- **TZ 주의**: `@Cron` 의 `timeZone` 옵션은 cron 발화에만 영향. `new Date().getHours()` 는 process TZ 따라가므로 운영 환경의 `TZ=Asia/Seoul` 보장 또는 명시 변환 필요. 안전한 대안은 슬롯별 cron 5개 정의 (각 cron 안에서 slotIndex 상수 박기).
#### 더 안전한 변형 (권장)
```ts
@Cron('0 0 3 * * *', { timeZone: 'Asia/Seoul' }) async slot0() { return this.processSlot(0); }
@Cron('0 0 4 * * *', { timeZone: 'Asia/Seoul' }) async slot1() { return this.processSlot(1); }
@Cron('0 0 5 * * *', { timeZone: 'Asia/Seoul' }) async slot2() { return this.processSlot(2); }
@Cron('0 0 6 * * *', { timeZone: 'Asia/Seoul' }) async slot3() { return this.processSlot(3); }
@Cron('0 0 7 * * *', { timeZone: 'Asia/Seoul' }) async slot4() { return this.processSlot(4); }
```
→ TZ 의존성 제거, 슬롯 매핑 명확.
테스트:
- 락 미획득 시 즉시 return 검증
- stale cutoff 기준 정확히 필터링되는지 fixture 기반 검증
- (실제 cron 발화는 e2e 범위 외 — 메서드 직접 호출 테스트로 충분)
---
## 4. 단위 테스트
- `apps/api/src/modules/riot/riot-recent-matches.service.spec.ts`
- `computeSummary`: 0경기 / 단일경기(승) / 5경기 mix / 같은 챔피언 빈도 상위 3개 정렬 검증
- **라인별 집계**: 미드 3경기 + 정글 2경기 fixture → `byLane.MIDDLE.games === 3`, `byLane.JUNGLE.games === 2`
- **빈 teamPosition**: fallback to `individualPosition`, 둘 다 비면 `byLane` 에는 안 들어가도 `overall` 에는 포함
- **avgCsPerMin**: gameDuration 1500s + cs 200 → 분당 8.0
- 같은 puuid 가 detail.participants 에 없는 경우 → 해당 매치 skip
- `apps/api/src/modules/riot/riot-account-enrichment.service.spec.ts` 확장
- `recentMatches` outcome 분기 커버 (stale/fresh/failed)
- `apps/api/src/modules/riot/riot-rate-limiter.service.spec.ts`
- 1초 윈도우 한도 도달 시 다음 호출이 대기하는지 (Garnet은 ioredis-mock 또는 실제 컨테이너)
- 120초 윈도우만 막히는 경우 — 더 큰 wait 반환 검증
- 다중 region (asia/kr) 키가 분리되어 서로 영향 없는지
- `apps/api/src/modules/riot/riot-prefetch.scheduler.spec.ts`
- 락 미획득 시 enrichment 호출 0회
- cutoff 보다 fresh 한 account 는 skip
- 1000 사용자 cap 동작
- **슬롯 분산**: 동일 userId 의 `slotOfUser` 가 항상 동일 값 반환, 1000 사용자 분포 편차 < 30%
- **시즌 force**: `community.seasonStartedAt > recentStatsFetchedAt` 시 force=true 로 enrichment 호출
- community 의 `riotPlatform`/`riotRegion` 이 옵션에 정확히 전달되는지
---
## 5. Rollout
1. (PR-1) `RiotRateLimiterService` + Lua sliding-window + 테스트, `RiotClientService` 통합. **이게 먼저 깔려야 다른 PR 의 enrichment 가 안전.**
2. (PR-2) `RiotRecentMatchesService` + `computeSummary` 라인별 집계 + 테스트, schema 신규 타입 정의
3. (PR-3) `RiotAccountEnrichmentService` 에 통합 + `p-limit` 의존성 추가 + auction.service 트리거
4. (PR-4) 클라 types/mapper/AuctionPage 카드 재설계 (`RecentSoloStats` 컴포넌트)
5. (PR-5) `RiotPrefetchScheduler` + `@nestjs/schedule` 의존성 + Garnet leader election
6. (PR-6) 운영 모니터링 로그 (throttle wait, X-App-Rate-Limit-Count drift, prefetch 처리 건수)
7. (Phase 2 합류) 수동 갱신 엔드포인트
---
## 6. 추가로 고려해야 할 점 (확정 / 미결)
### 확정 (사용자 결정 2026-04-26)
- **API 키 등급**: 개인키 → §2.7 throttle 구현 필수.
- **윈도우 크기**: 20경기 고정 (환경변수화 안 함).
- **RiotMatch 보관**: 무한 저장. TTL/prune 없음.
- **자유랭크/노말 미포함**: queue=420 솔로랭크 only.
- **라인별 데이터 구분**: §2.5 의 `byLane` 구조 + AuctionPage 카드 재설계 (§3.7).
- **lane 보정 = 분당 CS (avgCsPerMin)**.
- **0-state UX**: §2.5.2 표 적용.
- **야간 prefetch 스케줄러**: §3.8 — 03/04/05/06/07 시 KST 5슬롯 분산, 사용자 hash 로 결정적 분산, 슬롯별 Garnet 락.
- **championId 타입 통일**: §2.5.3 — Riot DTO 와 동일 `number` 로 통일. `mostPlayedChampionIds: number[]`.
- **시즌 경계 자동 리셋**: §2.5.4 — `Community.seasonStartedAt` 추가. 운영자 수동 등록 + enrichment 자동 force fetch + 매치 필터링.
- **다국가 region 지원 구조**: §2.5.5 — `Community.riotPlatform/riotRegion` 활용, 호출자가 옵션에 주입. 기본값 kr/asia.
- **외부 공유 OK** — ACL 별도 처리 없음.
### 미결
(없음)
---
## 7. Done 정의
- AuctionPage 의 "최근 솔로랭크" 카드가 0 이 아닌 실제 값을 표시 (테스트 사용자 1명 이상)
- 카드에 라인별 미니 row 5줄(TOP/JGL/MID/ADC/SUP) 표시, 주 라인 강조
- 0게임 사용자에게 placeholder ("최근 솔로랭크 기록이 없습니다") 표시 확인
- 같은 사용자 재진입 시 6h 이내에는 Match-V5 호출 0 회 (서버 로그로 확인)
- `riot_match` 컬렉션에 raw 저장 + `participantPuuids` 인덱스 hit 확인
- Throttle 동작: 21+ calls 동시 발생 시 `RiotRateLimiterService.acquire()` wait 로그 발생, Riot 429 0건
- 야간 03~07시 KST cron 5회 슬롯 발화, 슬롯별로 다른 사용자 집합 처리되는지 로그 확인
- `championId` 가 schema/types/응답 전부에서 `number` 로 통일됨 (grep 으로 string 잔존 0건)
- `Community.seasonStartedAt` 갱신 시 다음 enrichment 가 force fetch 되고, 시즌 이전 매치가 통계에서 제외됨
- enrichment 호출이 community.riotPlatform/riotRegion 을 받아 동작 (`'kr'` 외 region 도 옵션 분기 가능)
- 단위 테스트 통과 (라인별 집계 / throttle 윈도우 / scheduler 슬롯 분산 / 시즌 force / region 전달)
- Phase 2 의 `*FetchedAt` 노출 패턴과 정합 (응답에 `recentStatsFetchedAt` 추가)
-586
View File
@@ -1,586 +0,0 @@
# Riot 캐싱 Phase 2 플랜
> **대상**: codex가 이어서 진행 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-25
> **선행 작업**: dakao NATS 통합, RiotAccountEnrichmentService(force=true 동기 호출, summoner/league/mastery v4) 1차 구현 완료
---
## 1. Context
dakao 카카오톡 명령(`!내전 신청 ...`) 이 들어오면 라이엇 ID를 검증·등록하고, 동시에 summoner v4 / league v4 / champion-mastery v4 데이터를 가져와 `User.riotAccounts[*]` 임베딩에 캐싱하는 1차 구현이 끝난 상태입니다.
이 플랜은 그 위에 다음을 더합니다.
1. **community별 default platform 지정** + region/by-puuid 기반 자동 보정
2. **champion-mastery top 10** 으로 좁히고 스키마를 Riot DTO 그대로
3. **league 변동 시 tierHistory 자동 누적**
4. **사용자 수동 갱신 엔드포인트 + 한가한 시간대 스케줄러**
5. **신선도 표시(API 응답에 `*FetchedAt` 노출)**
6. **무거운 필드(`championRecords`, `tiers`)는 list/find 쿼리에서 projection 으로 잘라내기**
7. **동일 puuid 동시 enrichment dedup**
8. **v4 서비스 응답 파서 단위 테스트**
비목표:
- Rate limit 글로벌 throttle (token bucket / Redis) — Phase 3
- OpenSearch / Slack 운영 알림 — Phase 3
- 백오피스 UI — 별도 트랙
---
## 2. 결정된 설계 사항
### 2.1 Riot Schema 우선 (Data Dragon 호환)
기존 `ChampionMasteryEntry`, `TierInfo`, `TierHistoryEntry` 를 Riot v4 응답 그대로 매칭하도록 재정의합니다.
**현재 (수정 전)**
```ts
export interface ChampionMasteryEntry {
championId: string; // ← Riot 은 number
championName?: string; // ← Riot 응답에 없음
level: number; // ← championLevel
points: number; // ← championPoints
}
export interface TierInfo {
queueType: string;
tier: string;
rank: string;
leaguePoints: number;
wins: number;
losses: number;
fetchedAt: Date;
}
```
**목표 (수정 후)**
```ts
// Riot Champion-Mastery-V4 DTO 그대로
export interface ChampionMasteryEntry {
puuid: string;
championId: number;
championLevel: number;
championPoints: number;
lastPlayTime?: number;
championPointsSinceLastLevel?: number;
championPointsUntilNextLevel?: number;
markRequiredForNextLevel?: number;
tokensEarned?: number;
championSeasonMilestone?: number;
milestoneGrades?: string[];
nextSeasonMilestone?: Record<string, unknown>;
}
// Riot League-V4 entries DTO + 우리 측 fetchedAt
export interface TierInfo {
leagueId: string;
queueType: string;
tier: string;
rank: string;
puuid: string;
leaguePoints: number;
wins: number;
losses: number;
veteran?: boolean;
inactive?: boolean;
freshBlood?: boolean;
hotStreak?: boolean;
miniSeries?: Record<string, unknown>;
fetchedAt: Date;
}
// 시점별 tier 스냅샷
export interface TierHistoryEntry {
queueType: string;
tier: string;
rank?: string;
leaguePoints?: number;
wins?: number;
losses?: number;
recordedAt: Date;
// 시즌 단위 통계 / peak (옵션)
season?: string;
peakTier?: string;
peakRank?: string;
}
```
`championRecords` 는 챔피언별 *집계 데이터(향후 매치 분석)* 용으로 유지하되, **mastery 원본은 더 이상 `championRecords` 에 중복 저장하지 않습니다.** mastery 자체가 이제 Riot DTO 형태이기 때문입니다.
기존 schema 의 `RiotAccount.championRecords` 와 `RiotAccount.championRecordsFetchedAt` 는 그대로 둡니다 (다른 용도).
### 2.2 community 별 default platform
```ts
export interface Community extends MongooseTimestamps {
// ...
riotPlatform?: RiotPlatformRoute; // default 'kr'
riotRegion?: RiotRegionalRoute; // default 'asia'
}
```
- platform 기본 `kr`, region 기본 `asia` 는 코드 상 fallback. 명시 지정 시 community 설정값 우선.
- enrichment / lookup 시 community 의 platform 을 사용.
- 추가로 puuid 만 있는 상황(예: 다른 community 매치 import)에서는 region/by-puuid 로 platform 보정.
### 2.3 region/by-puuid 자동 보정
> `GET https://{regional}.api.riotgames.com/riot/account/v1/region/by-game/lol/by-puuid/{puuid}` → `{ puuid, game, region }`
- 응답의 `region` 이 platform 코드 (`kr`, `na1`, …)
- 사용 시점: community 의 platform 과 puuid 의 실제 platform 이 다른지 의심될 때 (예: 처음 등록 시, summoner v4 404 발생 시)
- 새 서비스: `RiotAccountService.getRegionByPuuid(puuid, options)`
- enrichment fallback 정책: summoner v4 가 404 면 region/by-puuid 호출해서 platform 보정 후 한 번 더 시도, 그래도 실패면 failed 처리
### 2.4 mastery top 10
- 엔드포인트 변경: `/lol/champion-mastery/v4/champion-masteries/by-puuid/{puuid}/top?count=10`
- 저장 상한 10. `MASTERY_LIMIT = 10`.
- `RiotChampionMasteryService.getTopByPuuid(puuid, { platform, count })` 신규 메서드. 기존 `getByPuuid` 는 leftover/내부용으로 유지하거나 삭제 (사용처 확인 후 결정).
### 2.5 tierHistory 누적 규칙
- enrichment 가 league entries 를 갱신할 때, **queueType 별로 가장 최근 history entry 와 비교**하여 다음 중 하나라도 다르면 history 에 push:
- `tier`, `rank`
- `leaguePoints` 변화 (옵션 — 너무 잦으면 noise. 1차에선 tier/rank 변화만 추적)
- 1차 결정: **tier 또는 rank 가 변하면 push**. lp 변화는 history 에 안 남김.
- 신규 등록 시(history 비어있음)는 첫 league fetch 결과를 그대로 history 에 1건 push.
- `recordedAt = new Date()`.
- queueType 외 다른 분류는 도입하지 않음. season 추적은 별도 작업.
### 2.6 신선도 노출 (`*FetchedAt`)
API 응답(`GET /users/:id`, `/me`, `/communities/:id/matches/:id` 등)에 RiotAccount 가 포함될 때 다음 필드를 함께 노출:
- `tiers[*].fetchedAt`
- `championMasteriesFetchedAt`
- `revisionDate` (summoner)
- `championRecordsFetchedAt`
스키마 상 이미 존재하므로 변경 불필요. 단, **list 쿼리에서는 무거운 raw 필드(`championRecords`, `championMasteries[*].milestoneGrades` 등) 는 projection 으로 제외**. (2.8 참조)
### 2.7 수동 갱신 + 스케줄러
**HTTP 엔드포인트**
```
POST /users/me/riot-accounts/:puuid/refresh
Body: { force?: boolean, platform?: RiotPlatformRoute }
Auth: 본인 또는 admin
Response: EnrichResult
```
- 본인 또는 community admin 이상만 허용.
- `force = true` 면 TTL 무시.
- platform 지정 시 community default 무시.
**스케줄러**
- NestJS `@nestjs/schedule` (cron) 도입.
- 작업명: `RiotAccountRefreshScheduler`
- 실행 주기: 매일 KST 04:00 ~ 06:00 사이에 chunked 실행
- 대상 선정:
- `tiers[*].fetchedAt` 가 24h 초과 또는 비어있는 RiotAccount
- 한 batch 당 최대 200건, batch 간 5초 간격
- enrichment 호출 시 `force = false` (TTL 기반)
- per-batch try/catch + 실패 카운터 로그
- `@Cron('0 4 * * *')` 단일 트리거로 시작 → 추후 batch 분산은 Phase 3 에서 보강
### 2.8 list/find projection 정책
`apps/api/src/modules/global/database/projection.ts` 신설하여 공통 projection 상수를 모음.
```ts
// 매치 리스트, /me 등에서 RiotAccount 의 무거운 필드를 잘라낸다
export const RIOT_ACCOUNT_LIGHT_PROJECTION = {
'riotAccounts.championRecords': 0,
'riotAccounts.championRecordsFetchedAt': 0,
// championMasteries 자체는 살리되 milestoneGrades 등 무거운 nested 는 protected list 에서만 fetch
} as const;
```
- 적용 대상: `MatchService.list`, `UserController.list`, `MatchController.listMatches` 등
- 단건 조회(`getById`, `/me`) 는 풀 데이터 포함
### 2.9 동일 puuid 동시 enrichment dedup
**채택 방식**: in-memory `Map<puuid, Promise<EnrichResult>>` (단일 인스턴스 dedup)
```ts
private inFlight = new Map<string, Promise<EnrichResult>>();
public enrichRiotAccount(params): Promise<EnrichResult> {
const key = params.puuid;
const existing = this.inFlight.get(key);
if (existing) return existing;
const promise = this.doEnrich(params).finally(() => {
this.inFlight.delete(key);
});
this.inFlight.set(key, promise);
return promise;
}
```
이유:
- 카카오 신청 빈도가 낮아 분산 락까지 필요 없음.
- 동일 인스턴스 내 race(동시 신청)만 막아도 90%의 중복 호출 절감.
- 멀티 인스턴스 환경 dedup 은 Phase 3 (Redis SET NX) 에서.
**대안 비교 (참고)**
| 방식 | 장점 | 단점 |
| --- | --- | --- |
| in-memory Map | 의존성 없음, 빠름 | 멀티 인스턴스 미지원 |
| Mongo `findOneAndUpdate` 락 | 의존성 없음, 분산 가능 | 실패 시 락 만료 처리 복잡, 추가 필드 필요 |
| Redis SET NX EX | 분산 / TTL 자연스러움 | Redis 인프라 필요 |
### 2.10 v4 파서 단위 테스트
- `riot-summoner.service.spec.ts`
- `riot-league.service.spec.ts`
- `riot-champion-mastery.service.spec.ts`
각각 정상 응답 / 누락 필드 거부 / 빈 배열 / 타입 불일치 거부 케이스.
---
## 3. 실행 단계 (codex 진행 순서)
작업 단위는 PR 단위로 쪼갤 수 있도록 분리되어 있습니다. 단계 간 의존성이 있는 부분은 명시.
### Step 1. 스키마 재정의 (TierInfo / ChampionMasteryEntry / TierHistoryEntry)
**파일**: `apps/api/src/modules/global/database/schema.ts`
1. `TierInfo`, `TierHistoryEntry`, `ChampionMasteryEntry` 인터페이스 위 2.1 정의로 교체.
2. `TierInfoSubSchema`, `TierHistoryEntrySubSchema`, `ChampionMasteryEntrySubSchema` 도 동일하게 갱신.
- `championId`: `Number` 로 변경
- `championLevel`, `championPoints`: 새 필드명
- `milestoneGrades`: `[String]` (default `undefined`)
- `nextSeasonMilestone`: `Schema.Types.Mixed`
- `TierInfo` 에 `leagueId`, `puuid`, `veteran`, `inactive`, `freshBlood`, `hotStreak`, `miniSeries(Mixed)` 추가
- `TierHistoryEntry` 에 `recordedAt: { type: Date, required: true }`, `leaguePoints/wins/losses` optional
3. `Community` 에 `riotPlatform`, `riotRegion` 추가:
```ts
riotPlatform: { type: String },
riotRegion: { type: String },
```
4. `MatchParticipantSubSchema.tier` 는 새 `TierInfo` 모양을 자동으로 따라감 — 추가 변경 없음.
**Risk**: 기존 데이터가 있다면 마이그레이션 필요. 현재 dev 환경 seed 만 사용한다면 seed 재실행으로 충분. `apps/api/src/seed.ts` 도 새 필드명에 맞춰 갱신.
**테스트**: 타입체크 통과 확인.
### Step 2. RiotChampionMasteryService → top 엔드포인트로 변경
**파일**: `apps/api/src/modules/riot/riot-champion-mastery.service.ts`
1. 메서드 시그니처 변경 또는 신규:
```ts
public async getTopByPuuid(
puuid: string,
options: { platform?: RiotPlatformRoute; count?: number; signal?: AbortSignal } = {},
): Promise<RiotChampionMasteryDto[]>
```
엔드포인트: `/lol/champion-mastery/v4/champion-masteries/by-puuid/{puuid}/top`
query: `count` (default 10, max 10)
2. 기존 `getByPuuid` 사용처 grep 후 모두 `getTopByPuuid` 로 교체.
3. `riot-account-enrichment.service.ts` 에서 `MASTERY_LIMIT = 10` 으로 변경.
### Step 3. region/by-puuid 서비스 + 자동 보정
**파일**: `apps/api/src/modules/riot/riot-account.service.ts`
```ts
public async getRegionByPuuid(
puuid: string,
options: RiotAccountLookupOptions = {},
): Promise<{ puuid: string; game: string; region: RiotPlatformRoute }> {
return this.riotClientService.get(
`/riot/account/v1/region/by-game/lol/by-puuid/${encodeURIComponent(puuid)}`,
{ region: options.region ?? 'asia', signal: options.signal },
parseRegionByPuuid,
);
}
```
`riot.types.ts` 에 응답 타입 추가:
```ts
export interface RiotAccountRegionDto {
puuid: string;
game: 'lol' | string;
region: RiotPlatformRoute;
}
```
**enrichment 보정 로직**:
`RiotAccountEnrichmentService.fetchSummonerSafe` 에서 `RiotApiError && status === 404` 발생 시:
1. `getRegionByPuuid` 호출
2. 받은 platform 으로 다시 summoner 호출
3. 그래도 실패면 `failed` 처리
4. 새 platform 이 community default 와 다르면 로그(`logger.warn`) — 향후 schema 에 puuid 별 platform 저장 여부는 별도 결정
### Step 4. enrichment dedup + force/TTL 흐름 정리
**파일**: `apps/api/src/modules/riot/riot-account-enrichment.service.ts`
1. 클래스에 `private inFlight = new Map<string, Promise<EnrichResult>>()` 추가.
2. `enrichRiotAccount` 진입부에서 dedup 체크. key 는 `${userId}:${puuid}` (user 다른데 puuid 같은 케이스도 있으니 user 포함이 안전).
3. `applyMasteries` 에서 `championRecords` 채우는 코드 제거 (2.1 결정).
4. `applyLeagueEntries` 호출 직전 `tierHistory` 갱신 헬퍼 호출:
```ts
private appendTierHistoryIfChanged(
account: RiotAccount,
entries: RiotLeagueEntryDto[],
): void {
const now = new Date();
for (const e of entries) {
const last = [...account.tierHistory]
.reverse()
.find((h) => h.queueType === e.queueType);
const changed =
!last ||
last.tier !== e.tier ||
(last.rank ?? '') !== (e.rank ?? '');
if (changed) {
account.tierHistory.push({
queueType: e.queueType,
tier: e.tier,
rank: e.rank,
leaguePoints: e.leaguePoints,
wins: e.wins,
losses: e.losses,
recordedAt: now,
});
}
}
}
```
5. 위 헬퍼는 `applyLeagueEntries` 가 처음 호출되더라도 빈 history → 첫 entry push 가 자연스럽게 일어남.
### Step 5. community.platform 사용 + DakaoUserService 연결
**파일**:
- `apps/api/src/modules/dakao/dakao-user.service.ts`
- `apps/api/src/modules/dakao/handlers/match-join.handler.ts` (필요 시)
1. `resolveRiotAccount` 가 community 를 한 번 조회해서 `riotPlatform`, `riotRegion` 을 옵션으로 enrichment / Riot lookup 에 전달.
2. `RiotAccountService.getByRiotId` 에 `region` 옵션 전달 (community.riotRegion 우선, fallback `asia`).
3. enrichment 호출에도 `platform: community.riotPlatform ?? 'kr'`.
```ts
const community = await CommunityModel.findById(context.communityId)
.select({ riotPlatform: 1, riotRegion: 1 })
.lean()
.exec();
const platform = (community?.riotPlatform as RiotPlatformRoute) ?? 'kr';
const region = (community?.riotRegion as RiotRegionalRoute) ?? 'asia';
```
### Step 6. 수동 갱신 엔드포인트
**신규 파일**: `apps/api/src/modules/user/user.controller.ts` (이미 존재) 에 라우트 추가, 또는 `riot-account.controller.ts` 신설.
- 기존 `user.module.ts` / `user.controller.ts` 구조 확인 (현재 `user/user.controller.ts`, `user/user.module.ts` 존재).
- 라우트:
```ts
@Post('me/riot-accounts/:puuid/refresh')
async refreshMyRiotAccount(
@CurrentUser() me: UserDocument,
@Param('puuid') puuid: string,
@Body() body: { force?: boolean; platform?: RiotPlatformRoute },
): Promise<EnrichResult> {
if (!me) throw new UnauthorizedException();
const owns = me.riotAccounts.some((a) => a.puuid === puuid);
if (!owns) throw new ForbiddenException();
return this.enrichmentService.enrichRiotAccount({
userId: me._id,
puuid,
options: { force: body.force === true, platform: body.platform },
});
}
```
- `UserModule.imports` 에 `RiotModule` 추가 (이미 RiotModule 이 `RiotAccountEnrichmentService` export 함).
- DTO: `class-validator` 기반 `RefreshRiotAccountDto`.
### Step 7. 스케줄러
**의존성**: `pnpm --filter api add @nestjs/schedule`
**신규 파일**: `apps/api/src/modules/riot/riot-account-refresh.scheduler.ts`
```ts
@Injectable()
export class RiotAccountRefreshScheduler {
private readonly logger = new Logger(RiotAccountRefreshScheduler.name);
constructor(
private readonly connectionService: ConnectionService,
private readonly enrichment: RiotAccountEnrichmentService,
) {}
@Cron('0 4 * * *', { timeZone: 'Asia/Seoul' })
async refreshStaleAccounts() {
const UserModel = await this.connectionService.getModel('user');
const cursor = UserModel.find({
'riotAccounts.0': { $exists: true },
})
.select({ _id: 1, riotAccounts: 1, communityId: 1 })
.cursor();
let processed = 0;
for await (const user of cursor) {
for (const acc of user.riotAccounts) {
try {
await this.enrichment.enrichRiotAccount({
userId: user._id,
puuid: acc.puuid,
options: { force: false },
});
processed += 1;
if (processed % 50 === 0) {
await sleep(5000);
}
} catch (err) {
this.logger.warn(`refresh failed: ${(err as Error)?.message ?? err}`);
}
}
}
this.logger.log(`Scheduler done: processed=${processed}`);
}
}
function sleep(ms: number) {
return new Promise((resolve) => setTimeout(resolve, ms));
}
```
`RiotModule.providers` 에 추가, `app.module.ts` 에 `ScheduleModule.forRoot()` 추가.
### Step 8. projection 적용
**신규 파일**: `apps/api/src/modules/global/database/projections.ts`
```ts
export const USER_LIGHT_PROJECTION = {
'riotAccounts.championRecords': 0,
'riotAccounts.championRecordsFetchedAt': 0,
} as const;
```
**적용 지점**:
- `MatchService.list` — 매치 자체에는 RiotAccount 가 없지만 향후 populate 시 사용
- 신규 `UserService.list` 또는 `findByCommunity` 류 — projection 적용
- `/me` 핸들러 — full 데이터 유지
- `/users/:id` 단건 조회 — full 데이터 유지
대부분의 `riotAccounts.*` 가 무거워지는 시점이 mastery top 10 + tierHistory 누적이므로, 우선 list 쿼리에만 적용.
### Step 9. v4 파서 단위 테스트
**신규 파일**:
- `apps/api/src/modules/riot/riot-summoner.service.spec.ts`
- `apps/api/src/modules/riot/riot-league.service.spec.ts`
- `apps/api/src/modules/riot/riot-champion-mastery.service.spec.ts`
각 서비스에 RiotClientService mock 주입, 정상/누락 필드/배열 비정상 케이스 검증. enrichment 의 적용 단계는 기존 `riot-account-enrichment.service.spec.ts` 에서 이미 커버 중이므로, **Step 1 변경에 따라 기존 spec 의 응답 fixture 도 새 필드명으로 갱신** 필요.
### Step 10. 회귀 테스트 / 정리
1. `npx tsc --noEmit` 통과
2. `npx jest` 전체 PASS
3. seed 재실행으로 새 스키마 정상 작동 확인
4. dakao 시나리오 수동 검증:
- 신규 카카오 사용자가 `!내전 신청 ...` 으로 등록될 때 summoner v4 가 한 번 호출되고, 응답 후 user 문서에 `tiers`, `championMasteries`(10건), `tierHistory`(1건) 가 채워지는지 확인
- 같은 사용자가 즉시 재신청하면 enrichment 가 dedup 으로 단일 호출에 합쳐지는지 로그로 확인
- 한 시즌 후 tier 가 변경된 상태에서 enrichment 가 호출되면 `tierHistory` 에 새 entry 가 push 되는지 단위 테스트
---
## 4. 변경/추가 파일 목록
### 신규
- `apps/api/src/modules/global/database/projections.ts`
- `apps/api/src/modules/riot/riot-account-refresh.scheduler.ts`
- `apps/api/src/modules/riot/riot-summoner.service.spec.ts`
- `apps/api/src/modules/riot/riot-league.service.spec.ts`
- `apps/api/src/modules/riot/riot-champion-mastery.service.spec.ts`
- (옵션) `apps/api/src/modules/user/dto/refresh-riot-account.dto.ts`
### 수정
- `apps/api/src/modules/global/database/schema.ts` — TierInfo / TierHistoryEntry / ChampionMasteryEntry / Community 재정의
- `apps/api/src/modules/riot/riot.types.ts` — DTO 타입, RiotAccountRegionDto 추가
- `apps/api/src/modules/riot/riot-account.service.ts` — `getRegionByPuuid` 추가
- `apps/api/src/modules/riot/riot-champion-mastery.service.ts` — `getTopByPuuid` 로 교체
- `apps/api/src/modules/riot/riot-account-enrichment.service.ts` — 새 스키마 적용, dedup, tierHistory 누적, 404 보정
- `apps/api/src/modules/riot/riot.module.ts` — Scheduler / region service provider 등록
- `apps/api/src/modules/dakao/dakao-user.service.ts` — community platform/region 사용
- `apps/api/src/modules/user/user.controller.ts` (또는 신설) — `/me/riot-accounts/:puuid/refresh`
- `apps/api/src/modules/user/user.module.ts` — RiotModule import
- `apps/api/src/modules/match/match.service.ts` — list 쿼리 projection
- `apps/api/src/app.module.ts` — `ScheduleModule.forRoot()`
- `apps/api/src/seed.ts` — 새 mastery / tier 필드명에 맞춰 seed 데이터 수정
- `apps/api/src/modules/riot/riot-account-enrichment.service.spec.ts` — fixture 갱신
### 의존성
- `pnpm --filter api add @nestjs/schedule`
---
## 5. 검증 체크리스트
- [ ] `pnpm --filter api exec tsc --noEmit` 통과
- [ ] `pnpm --filter api exec jest` 전체 PASS
- [ ] seed 재실행 후 user 문서 정상 (`db.user.findOne()` 으로 새 필드 확인)
- [ ] dakao `!내전 신청 <id> <기존_등록_riot_id> 미드,탑` → enrichment 캐시 hit, Riot API 호출 0회
- [ ] dakao `!내전 신청 <id> <신규_riot_id> 미드,탑` → summoner v4 1회, league v4 1회, mastery top v4 1회 호출, user 문서에 tiers/masteries/tierHistory 채워짐
- [ ] `POST /users/me/riot-accounts/:puuid/refresh { force: true }` → enrichment 수동 강제 갱신 동작
- [ ] cron 시뮬레이션 (`@Cron` 수동 트리거 또는 `node -e` 로 메서드 직접 호출) → 200건 이상 처리되어도 OOM/timeout 없이 완료
- [ ] match list API 응답 사이즈 → projection 적용으로 기존 대비 30%+ 감소 (실측)
- [ ] 동시 동일 puuid enrichment 두 번 호출 → in-flight Map 으로 1회로 합쳐짐 (단위 테스트)
---
## 6. Phase 3 으로 미루는 것 (참고)
- **분산 dedup** (Redis SET NX EX 또는 mongo 락)
- **Token bucket / Riot API rate limit** 글로벌 throttle
- **OpenSearch 인덱싱** (RiotAccount, Match 변화 로그)
- **Slack 알림** (enrichment 실패 임계 초과, scheduler 실패)
- **puuid 별 last-known platform 캐싱** (Step 3 의 보정 결과를 RiotAccount 에 영구 저장)
- **시즌 종료 시 tierHistory 의 `season` 필드 자동 채움** + peakTier 계산
- **백오피스 UI** — community.riotPlatform 설정 / 수동 갱신 트리거 / 신선도 리포트
- **NATS 기반 enrichment 분산** (현재 dakao 외 트리거가 없으므로 보류)
---
## 7. 운영 노트
- Riot personal API key 는 **개당 100req / 2분 / IP** 한도. mastery + summoner + league 가 1 user attach 당 3회. dakao 첫 신청이 폭주해도 분당 ~30명 미만이면 무탈.
- 스케줄러는 5초 간격 batch 50건 → 10분에 6000건. 대부분의 community 규모에서 충분.
- region/by-puuid 보정은 community 의 platform 이 잘못 설정된 케이스에서 운영자가 즉시 알 수 있도록 `logger.warn` 만 남김. Phase 3 에서 알림 채널로 승격.
- `championRecords` 와 `championRecordsFetchedAt` 은 비워두는 채로 schema 만 유지. mastery 와는 다른 용도(향후 매치 분석 집계)이므로 충돌 없음.
-572
View File
@@ -1,572 +0,0 @@
# 토너먼트 코드 풀 / 표시 플랜
> **대상**: codex 가 이어서 작업 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-27
---
## 1. Context
내전이 `team-built` 상태가 되면 5명씩 게임에 입장할 수 있도록 **토너먼트 코드** 1개를 매치에 발급해 표시해야 합니다.
**제약** — Riot Tournament-Stub-V5 사용 권한 없음. 우회:
1. 외부 서비스(별도 운영) 가 토너먼트 코드를 미리 수십~수백 개 생성.
2. 운영자가 그 코드를 우리 Admin UI 에 **수동 업로드** → 풀에 적재.
3. 매치가 `team-built` 으로 전환되는 순간 풀에서 atomic pop → 매치에 attach.
4. (Phase 후속) 게임 끝난 후 `match-v5` detail 의 `info.tournamentCode` 필드로 우리 코드와 매칭해 매치 결과 수집.
본 plan 은 1~3 까지. 4 는 §5.E 에 자리만.
---
## 2. 결정사항 (사용자 결정 2026-04-27)
- **적재**: 운영자 수동 업로드 → Admin UI 필수
- **카테고리**: 5v5 소환사 협곡 단일 (`mapType=SUMMONERS_RIFT`, `teamSize=5`)
- **화이트리스트**: 사용 안 함 (`allowedSummonerIds` 미지정)
- **만료**: `expiresAt` 보관 + pop 쿼리에 검사 (24h 안전 마진)
- **Tournament API**: 사용 불가. 단순 표시만.
- **결과 수집**: Phase 후속 — 일반 match-v5 응답의 `info.tournamentCode` 매칭으로 우회
- **잔여 알림**: 미구현. 운영자 수동 확인.
- **권한**: 코드 자체는 누구나 볼 수 있음. **풀 잔여 통계는 admin 만**.
- **풀 비었을 때**: placeholder 표시 + 운영자가 채우면 자동 attach
- **데이터 모델**: 별도 `TournamentCode` 컬렉션 + **`Match.tournamentCodeIds[]` 1:N join**
- **다게임 구조**: 한 내전 = N 경기 (1경기/2경기/3경기 …). `team-built` 진입 시 N개 코드 atomic 발급
- **표시 범위**: `team-built` + `in-progress` 모두 표시. `finished` 에서만 SideCard 숨김
- **코드 형식 검증**: 정규식 통과한 코드만 적재 (`/^[A-Z0-9-]{8,}$/i` 1차)
- **bulk 업로드 2모드**: 간단(textarea CSV) + 확장(JSON 붙여넣기)
---
## 3. 데이터 모델
### 3.1 TournamentCode (신규 컬렉션)
```ts
// apps/api/src/modules/global/database/schema.ts
export type TournamentCodeState =
| 'available' // 풀에 대기 중
| 'reserved' // 매치에 할당됨, 아직 게임 시작 전
| 'used' // 게임 시작/종료 — 회수 불가
| 'expired' // expiresAt 경과 (cron 으로 마킹)
| 'released'; // 매치 취소로 풀 복귀 (재할당 가능)
export interface TournamentCode extends MongooseTimestamps {
code: string; // unique, Riot 형식 (정규식 검증)
region: RiotPlatformRoute; // 기본 'kr'
mapType: 'SUMMONERS_RIFT';
teamSize: number; // 5 고정
spectatorType: 'NONE' | 'LOBBYONLY' | 'ALL';
metadata?: Record<string, unknown>; // 외부 서비스에서 받은 부가 정보
expiresAt: Date; // 운영자 입력 필수
state: TournamentCodeState;
// 할당 추적
matchId?: mongoose.Types.ObjectId; // reserved/used 시 채워짐
gameNumber?: number; // 1-based, 한 매치 안에서 몇 번째 경기인지
reservedAt?: Date;
usedAt?: Date; // 게임 시작 webhook 또는 결과 수집 시
releasedAt?: Date;
riotMatchId?: string; // 결과 수집 시 매칭된 match-v5 id (Phase 후속)
// 운영 추적
uploadedBy: mongoose.Types.ObjectId; // userId
uploadedAt: Date;
source?: string; // 외부 서비스 식별자 (옵션)
notes?: string;
}
export const TournamentCodeSchema = new Schema<TournamentCode>(
{ /* ... */ },
{ timestamps: true, collection: 'tournament_code' },
);
TournamentCodeSchema.index({ code: 1 }, { unique: true });
TournamentCodeSchema.index({ state: 1, expiresAt: 1 }); // pop 쿼리
TournamentCodeSchema.index({ matchId: 1, gameNumber: 1 }); // join lookup + 정렬
TournamentCodeSchema.index({ state: 1, uploadedAt: -1 }); // admin 목록
TournamentCodeSchema.index({ riotMatchId: 1 }, { sparse: true }); // 결과 수집 reverse lookup
```
> 모델 등록: `connection.service.ts` 의 `getModel<'tournamentCode'>` 추가.
#### 3.1.1 코드 형식 정규식 검증
`/^[A-Z0-9-]{8,}$/i` (영숫자 + 하이픈, 최소 8자). bulk 업로드/수동 추가 시 통과 못 한 코드는 응답의 `invalid` 배열에 포함, DB 적재 X. 정규식은 `tournament-code.constants.ts` 에 상수로 분리.
### 3.2 Match 확장
```ts
// schema.ts Match 추가
gameCount: number; // 한 내전의 경기 수 (default 3, community 설정에서 snapshot)
tournamentCodeIds: mongoose.Types.ObjectId[]; // gameNumber 순서 보장 (length ≤ gameCount)
// MatchSchema
gameCount: { type: Number, required: true, default: 3 },
tournamentCodeIds: {
type: [{ type: Schema.Types.ObjectId, ref: 'tournamentCode' }],
default: [],
}
```
#### 3.2.1 Community 확장 (게임 수 기본값)
```ts
// Community
matchGameCount?: number; // default 3, 매치 생성 시 snapshot
```
매치 생성 시 `match.gameCount = community.matchGameCount ?? 3`. 매치별 override 도 매치 생성 폼에서 가능.
#### 3.2.2 API 응답 구조
```ts
// /matches/:id 응답
{
...match,
tournamentCodes: [
{ gameNumber: 1, code: 'KR-...', expiresAt: '...', state: 'reserved', riotMatchId: null },
{ gameNumber: 2, code: 'KR-...', expiresAt: '...', state: 'reserved', riotMatchId: null },
{ gameNumber: 3, code: null, expiresAt: null, state: 'pending', riotMatchId: null }, // 풀 부족분
],
}
```
`gameCount` 만큼 슬롯이 항상 차 있음. 풀 부족 시 코드 자리는 `code: null, state: 'pending'` placeholder. 추후 풀 보충 시 자동 attach.
---
## 4. Lifecycle / 트리거 지점
```
upload (admin) atomic pop game start (Phase 후속)
│ │ │
[available] ─────→ [reserved] ───────────────→ [used]
│
│ match cancel / re-recruit
└──────────→ [released] ──→ [available] (재할당 가능)
[any state] ──── expiresAt < now ────→ [expired] (cron daily)
```
### 4.1 reserve (`team-built` 전환) — N개 atomic 발급
- `auction.service.ts:175` (마지막 멤버 배정), `:395` (admin 강제 전환) 두 곳에서 `match.status = 'team-built'` 직후 호출.
```ts
// TournamentCodeService.reserveForMatch(match): 부족분만 보충하는 idempotent 함수
const need = match.gameCount - match.tournamentCodeIds.length;
if (need <= 0) return;
const startGameNumber = match.tournamentCodeIds.length + 1;
const reservedIds: mongoose.Types.ObjectId[] = [];
for (let i = 0; i < need; i++) {
const code = await TournamentCodeModel.findOneAndUpdate(
{
state: 'available',
region: 'kr',
mapType: 'SUMMONERS_RIFT',
teamSize: 5,
expiresAt: { $gt: new Date(Date.now() + 24 * 60 * 60 * 1000) }, // 24h 안전 마진
},
{
$set: {
state: 'reserved',
matchId: match._id,
gameNumber: startGameNumber + i,
reservedAt: new Date(),
},
},
{ sort: { expiresAt: 1 }, new: true }, // 만료 임박순 소비
);
if (!code) break; // 풀 고갈 — 부분 발급으로 종료
reservedIds.push(code._id);
}
if (reservedIds.length > 0) {
match.tournamentCodeIds.push(...reservedIds);
await match.save();
}
```
- 각 호출이 atomic findOneAndUpdate → 두 매치가 같은 코드 받지 않음.
- 부족분만 채우는 idempotent 라 `pendingMatches` cron 에서 재호출해도 안전.
### 4.2 release (`team-built` → `recruiting` 회귀)
- `auction.service.ts:314-315` 의 회귀 흐름에서 호출.
- match cancel/삭제 시에도 호출.
```ts
// TournamentCodeService.releaseFromMatch(match)
await TournamentCodeModel.updateMany(
{ _id: { $in: match.tournamentCodeIds }, state: 'reserved' },
{ $set: { state: 'released', releasedAt: new Date() }, $unset: { matchId: 1, gameNumber: 1 } },
);
match.tournamentCodeIds = [];
await match.save();
```
`used` 상태(이미 게임 시작) 코드는 release 대상에서 제외. `released` 는 admin UI 환원 버튼에서만 `available` 로 돌아옴 (audit 보존).
### 4.3 expired 마킹 (cron)
```ts
@Cron('0 0 * * * *', { timeZone: 'Asia/Seoul' }) // 매시 정각
async markExpired() {
await TournamentCodeModel.updateMany(
{ state: { $in: ['available', 'reserved', 'released'] }, expiresAt: { $lte: new Date() } },
{ $set: { state: 'expired' } },
);
}
```
`reserved` 였는데 만료되면 → `expired`. 매치 표시는 "코드 만료됨" placeholder. (희박한 케이스 — 운영자가 매치 시작 직전 코드 안 채웠을 때만)
### 4.4 placeholder 자동 채우기 (풀 부족분 보충)
- `team-built` / `in-progress` 인 매치 중 `tournamentCodeIds.length < gameCount` 인 매치 검색 → `reserveForMatch` 재호출 (부족분만 채움).
- **트리거 두 곳**:
1. **admin 업로드 controller 안에서 직접 실행** — 즉시성 보장
2. **cron `@Cron('*/30 * * * * *')`** — 안전망 (30초 간격)
```ts
// TournamentCodeScheduler.attachPending
const pendingMatches = await MatchModel.find({
status: { $in: ['team-built', 'in-progress'] },
$expr: { $lt: [{ $size: '$tournamentCodeIds' }, '$gameCount'] },
});
for (const match of pendingMatches) await codeService.reserveForMatch(match);
```
---
## 5. 변경 사항
### 5.1 백엔드
#### 신규 모듈 `apps/api/src/modules/tournament-code/`
```
tournament-code.module.ts
tournament-code.service.ts # reserveForMatch / releaseFromMatch / markExpired / bulkUpload / list / delete
tournament-code.controller.ts # admin endpoints
tournament-code.scheduler.ts # 만료 cron + 자동 attach cron
tournament-code.types.ts
```
#### 엔드포인트
| Method | Path | 권한 | 용도 |
|---|---|---|---|
| POST | `/communities/:cid/tournament-codes` | `@Roles('owner','admin')` | bulk 업로드 |
| GET | `/communities/:cid/tournament-codes` | `@Roles('owner','admin')` | 목록 (state/expiresAt 필터) |
| GET | `/communities/:cid/tournament-codes/stats` | `@Roles('owner','admin')` | 풀 잔여 통계 (state 별 카운트 + 만료 임박 카운트) |
| DELETE | `/communities/:cid/tournament-codes/:id` | `@Roles('owner','admin')` | 폐기 (state=available 만) |
| POST | `/communities/:cid/tournament-codes/:id/release` | `@Roles('owner','admin')` | reserved/released → available 수동 환원 |
bulk 업로드 body:
```ts
interface BulkUploadRequest {
codes: Array<{
code: string; // 공백 trim
expiresAt: string; // ISO
spectatorType?: 'NONE' | 'LOBBYONLY' | 'ALL'; // 기본 'ALL'
metadata?: Record<string, unknown>;
source?: string;
notes?: string;
}>;
}
```
응답:
```ts
interface BulkUploadResponse {
inserted: number;
duplicates: string[]; // 이미 존재하는 code (skipped)
invalid: Array<{ code: string; reason: string }>;
}
```
#### 매치 응답에 join
`match.service.ts` 의 `serializeMatch` (또는 mapper) 에서 `tournamentCodeIds` 를 `populate` 또는 `$lookup` 으로 풀어 `gameNumber` 정렬 + 부족분은 placeholder 슬롯으로 채워서 응답:
```ts
function buildTournamentCodeSlots(
match: Match,
codes: TournamentCode[],
): TournamentCodeSlotView[] {
const byNumber = new Map(codes.map((c) => [c.gameNumber!, c]));
return Array.from({ length: match.gameCount }, (_, i) => {
const gameNumber = i + 1;
const code = byNumber.get(gameNumber);
return code
? {
gameNumber,
code: code.code,
expiresAt: code.expiresAt.toISOString(),
state: code.state, // 'reserved' | 'used' | 'expired'
riotMatchId: code.riotMatchId ?? null,
}
: { gameNumber, code: null, expiresAt: null, state: 'pending', riotMatchId: null };
});
}
```
#### auction.service 통합
- `:175`, `:395` 직후 `tournamentCodeService.reserveForMatch(match)` 호출.
- `:314-315` 직전 `tournamentCodeService.releaseFromMatch(match)` 호출.
### 5.2 프런트
#### 매치 상세 우측 SideCard 추가
`apps/web/src/pages/MatchDetailPage.tsx` `611~654` 일정/상품/안내사항 SideCard 들 아래에:
```tsx
{match.status !== 'finished' &&
(match.status === 'team-built' || match.status === 'in-progress') && (
<SideCard title="토너먼트 코드">
<TournamentCodeList slots={match.tournamentCodes} />
{isAdmin && <PoolStatsHint />} {/* §8.5 운영자에게만 잔여 표시 */}
</SideCard>
)}
```
`TournamentCodeList` 컴포넌트 — 1경기 / 2경기 / 3경기 식 row:
```tsx
function TournamentCodeList({ slots }: { slots: TournamentCodeSlotView[] }) {
return (
<div className="space-y-2">
{slots.map((slot) => (
<TournamentCodeRow key={slot.gameNumber} slot={slot} />
))}
</div>
);
}
function TournamentCodeRow({ slot }: { slot: TournamentCodeSlotView }) {
return (
<div className="flex items-center gap-2">
<span className="text-[11px] font-bold text-base-content/40 w-12 shrink-0">
{slot.gameNumber}경기
</span>
{slot.code ? (
<TournamentCodeDisplay slot={slot} />
) : (
<span className="text-[11px] text-base-content/30">발급 대기 중…</span>
)}
</div>
);
}
```
`TournamentCodeDisplay`:
- 모노스페이스 코드 + 카피 버튼 (clipboard) + 카피 토스트 ("복사했어요. 게임 클라이언트의 토너먼트 코드 입력란에 붙여 넣으세요")
- 만료 시각 ("만료: 4월 30일 18:00")
- 만료 24h 이내면 amber 경고
- `state === 'expired'` → "코드 만료. 운영자에게 문의해 주세요."
- `state === 'used'` → 회색 + "사용됨" 라벨 (다음 경기 코드만 강조)
- `riotMatchId` 있으면 hover 시 매치 ID 툴팁 (Phase 후속 결과 수집 후)
#### types.ts
```ts
export type TournamentCodeSlotState = 'reserved' | 'used' | 'expired' | 'pending';
export interface TournamentCodeSlotView {
gameNumber: number;
code: string | null;
expiresAt: string | null;
state: TournamentCodeSlotState;
riotMatchId: string | null;
}
export interface ApiMatch {
// ...
gameCount: number;
tournamentCodes: TournamentCodeSlotView[]; // 항상 length === gameCount
}
```
#### Admin 페이지 신규
`apps/web/src/pages/admin/TournamentCodesPage.tsx`:
- 라우트: `/admin/communities/:cid/tournament-codes`
- 권한 가드: `useMe` 의 `currentUser.role === 'owner' | 'admin'` 아니면 redirect
- 섹션:
1. **잔여 현황 카드**: state 별 카운트 (available / reserved / used / expired) + 만료 임박 7일 이내 카운트
2. **bulk 업로드 — 2모드 탭**:
- **간단**: textarea, 줄당 `code,expiresAt(ISO)` (CSV 1줄). 예: `KR-ABCD-1234,2026-05-30T18:00:00Z`
- **확장**: JSON 붙여넣기 (`{spectatorType, metadata, source, notes}` 추가 가능)
- 정규식 통과한 코드만 적재, invalid/duplicate 결과 응답 표시
3. **목록 테이블**: state 필터 / expiresAt 정렬 / 매치 ID 링크 (`gameNumber` 함께) / 폐기·환원 버튼
- 폴링: React Query `refetchInterval: 30s`
#### SideCard 안의 운영자 잔여 안내 (§8.5)
`PoolStatsHint` 컴포넌트:
- `useMe` 로 admin/owner 판별
- 별도 호출 `GET /communities/:cid/tournament-codes/stats` (다음 §)
- 표시: "풀 잔여 12개 (만료 임박 3개)" — 5개 미만이면 빨강
- admin 페이지로 가는 inline link
#### 매치 상세 클릭 트리거 — 변경 없음
기본 `MatchDetailPage` 안에서 자동 표시. 외부 공유 OK 정책 그대로.
### 5.3 매치 cancel/삭제 시 release
- `match.service.ts` 의 매치 삭제/취소 흐름에 `releaseFromMatch` 호출.
- match status 가 `team-built` → `in-progress` 로 전환되면 **코드 자체는 그대로 reserved 유지**. 게임이 끝나는 시점(Phase 후속 결과 수집)에 `reserved → used` 전환.
- `in-progress` 상태에서도 SideCard 표시 유지 (다음 경기 코드 보여주기 위함).
---
## 6. 결과 수집 우회 (Phase 후속 — 본 plan 자리만)
토너먼트 API 못 쓰니까 게임이 끝났는지 알 방법이 없습니다. **`match-v5 by-puuid` 의 `type=tourney` 필터** 를 활용해 호출량/정확도를 끌어올리는 우회 흐름:
### 6.1 호출 패턴 — `type=tourney` + `startTime` window
```
GET /lol/match/v5/matches/by-puuid/{puuid}/ids
?type=tourney
&startTime={teamBuiltAtEpochSeconds - 60} // 안전 마진 60초
&endTime={now}
&start=0
&count=100
```
- `type=tourney` 로 **토너먼트 코드로 만들어진 매치만** 필터 → 일반/랭크 매치 제외, payload·detail call 모두 절감.
- `startTime` = 매치가 `team-built` 으로 전환된 epoch seconds (안전 마진 60초). `Match.teamBuiltAt: Date` 신규 필드 필요.
- `endTime` = 폴링 시점.
- `start/count` 페이지네이션은 1차 100 으로 충분 (BO3/BO5 라도 한 매치는 최대 5게임).
- `RiotMatchService.getMatchIdsByPuuid` 가 이미 `type: 'tourney'` 를 지원함 (`riot.types.ts:29`, `riot-match.service.ts:21~26`) — 신규 클라이언트 코드 불필요.
### 6.2 매핑 흐름
1. 매치가 `team-built` 으로 전환되는 시점에 `Match.teamBuiltAt = now` snapshot.
2. **결과 수집 작업 큐** (선행 plan 의 Riot 작업 큐 high stream 재사용) 에 `riot.tournament-result.poll.match` job enqueue. payload: `{matchId, puuids: [캡틴 2명], teamBuiltAtEpoch}`.
3. worker:
```ts
for (const puuid of puuids) {
const ids = await matchService.getMatchIdsByPuuid(puuid, {
type: 'tourney',
startTime: teamBuiltAtEpoch - 60,
count: 100,
region: 'asia',
});
for (const matchV5Id of ids) {
const detail = await matchService.getMatch(matchV5Id);
const tCode = detail.info.tournamentCode;
if (!tCode) continue;
const code = await TournamentCodeModel.findOneAndUpdate(
{ code: tCode, matchId: match._id, state: 'reserved' },
{ $set: { state: 'used', usedAt: new Date(detail.info.gameCreation), riotMatchId: matchV5Id } },
{ new: true },
);
if (code) await maybeAdvanceMatch(match); // 모든 슬롯 used 면 finished 전환
}
}
```
4. **재폴링 정책**: 결과를 모두 못 찾았으면 5분 후 재 enqueue (예: 첫 polling 후 1시간 동안 5분 간격 재시도, 그 후 1시간 간격으로 24시간까지). 24h 내 못 찾으면 `state = 'expired'` 마킹 + 운영자 알림 자리.
5. **dedup**: 매치당 jobId 단일 (`riot:tourney-poll:dedup:<matchId>` Garnet NX). 한 매치는 한 polling 체인.
### 6.3 finished 전환
```ts
async function maybeAdvanceMatch(match: Match) {
const codes = await TournamentCodeModel.find({ matchId: match._id }).sort({ gameNumber: 1 });
if (codes.length < match.gameCount) return;
if (!codes.every((c) => c.state === 'used' && c.riotMatchId)) return;
match.status = 'finished';
match.result = match.result ?? defaultResult();
match.result.riotMatchIds = codes.map((c) => c.riotMatchId!);
// 승패/스코어는 별도 결과 집계 단계 (이번 PR 범위 외)
await match.save();
}
```
### 6.4 본 plan 에서 미리 준비할 것
- `Match.teamBuiltAt: Date` 필드 추가 (PR-1 에서 같이) — 결과 수집 시 `startTime` 으로 사용.
- `TournamentCode.riotMatchId` 필드 + sparse 인덱스 (이미 §3.1).
- `gameNumber` 로 어느 경기 결과인지 매핑 가능 (운영자가 코드를 1경기/2경기 순서대로 발급한 가정).
- `RiotMatchService.getMatchIdsByPuuid` 의 `type: 'tourney'` 지원 확인 완료.
### 6.5 폴링 대상 puuid 선택
- 기본: **양 팀 캡틴 puuid 2명만** 폴링 → 최소 호출.
- 캡틴이 게임에 입장 안 한 케이스 (드물지만 가능) 대비: 24h 안에 결과 못 찾으면 **모든 참가자 puuid** (10명) 로 확장 retry.
- 한 매치당 최악 호출량: 2 puuid × 100ids list + 매치당 detail call 5게임 = ~12 calls. 매치 1개 finished 까지 ≤ 24h.
### 6.6 결과 수집 모듈 자체는 별도 PR (`Tournament-Result-수집-플랜.md` 후속).
---
## 7. Rollout
1. (PR-1) `TournamentCode` 컬렉션 + Match `gameCount`/`tournamentCodeIds[]`/`teamBuiltAt` + Community `matchGameCount` + 모델 등록 + 인덱스 (riotMatchId sparse 포함)
2. (PR-2) `TournamentCodeService.reserveForMatch (idempotent N개 발급) / releaseFromMatch / bulkUpload (정규식 검증) / list / stats` + 단위 테스트 (atomic pop concurrency, 부분 발급, 정규식 reject)
3. (PR-3) auction.service 통합 (reserve/release 두 트리거) + 매치 생성 시 `gameCount` snapshot + `team-built` 전환 시 `teamBuiltAt` snapshot
4. (PR-4) 매치 응답에 `tournamentCodes[]` slot 빌더 + types 확장 (gameCount + slot view)
5. (PR-5) `TournamentCodeScheduler` (만료 cron 매시 + 부족분 자동 attach cron 30초)
6. (PR-6) 매치 상세 SideCard — `TournamentCodeList` (1경기/2경기/3경기 row) + 카피 토스트 + 만료 경고. status guard: `team-built` ∪ `in-progress`
7. (PR-7) Admin 페이지 `TournamentCodesPage` — 잔여 현황 + 2모드 bulk 업로드 + 목록 + 환원/폐기
8. (PR-8) SideCard `PoolStatsHint` (admin/owner 만 표시, /stats 엔드포인트 호출)
9. (PR-9) 매치 cancel/삭제 흐름에 release 통합
10. (Phase 후속) 결과 수집 폴링 모듈 (`info.tournamentCode` 매칭)
---
## 8. 추가 고려사항
### 확정 (사용자 결정 2026-04-27)
본 plan §2 의 모든 결정사항. 추가 항목:
1. **정규식 검증** (`/^[A-Z0-9-]{8,}$/i`) — bulk 업로드 시 invalid 응답에 포함, DB 적재 X.
2. **만료 안전 마진 24h** — pop 쿼리에 `expiresAt > now + 24h`. admin 페이지에서 임박 코드 amber 표시.
3. **bulk 업로드 2모드** — 간단(textarea CSV) + 확장(JSON 붙여넣기).
4. **표시 범위**: `team-built` + `in-progress` 모두 표시 (1경기/2경기/3경기 식). `finished` 에서만 사라짐.
5. **풀 잔여 통계**: admin/owner 에게만 SideCard 안에 inline 표시 + admin 페이지 카드.
6. **자동 attach 트리거**: admin 업로드 controller 안 + cron 30초 둘 다.
7. **재할당 audit**: `released → available` 은 admin 환원 버튼만. 자동 환원 cron 두지 않음.
8. **카피 토스트**: 코드 카피 시 "복사했어요. 게임 클라이언트의 토너먼트 코드 입력란에 붙여 넣으세요".
### 추후 (Phase 후속)
- 결과 수집 폴링 모듈 (§6) — `info.tournamentCode` 매칭으로 `riotMatchId` 채움 + `state=used`
- 잔여 알림 (dakao bot 또는 discord webhook)
- 풀 자동 보충 (외부 서비스 webhook / API key 인증)
- 토너먼트 API 권한 받으면 본 plan 의 풀 메커니즘은 그대로 두고 코드 생성 자동화만 추가
---
## 9. Done 정의
- `TournamentCode` 컬렉션 생성 + 인덱스 5개 등록 (riotMatchId sparse 포함)
- `Match.gameCount` + `Match.tournamentCodeIds[]` 추가, `Community.matchGameCount` 자리
- 운영자가 admin 페이지에서 2모드 (CSV/JSON) bulk 업로드, 정규식 통과한 코드만 적재
- 매치가 `team-built` 으로 전환 → 매치에 `gameCount` 만큼 코드 atomic N개 발급 (만료 임박순, gameNumber 1..N), 동시 두 매치 같은 코드 받지 않음
- 풀 부족 시 부분 발급 → 부족 슬롯은 `state: 'pending'` placeholder 로 응답
- `team-built` → `recruiting` 회귀 시 reserved 코드 모두 release → admin 환원 버튼으로 available 로 복귀
- MatchDetailPage 우측 SideCard 에 `team-built` ∪ `in-progress` 일 때 1경기/2경기/3경기 row 표시. `finished` 에서 사라짐
- admin/owner 에게는 SideCard 안에 풀 잔여 inline 표시 ("풀 잔여 12개 (만료 임박 3개)")
- 풀이 비었던 슬롯은 admin 이 새 코드 업로드하면 30초 안에 자동 attach
- 만료 임박 24h 이내 코드는 pop 쿼리에서 제외, admin 페이지 amber
- 만료된 코드는 매시 cron 으로 state=expired 마킹
- 매치 응답 (`/matches/:id`) 에 `tournamentCodes: TournamentCodeSlotView[]` (length === gameCount) 포함
- `match-v5` 응답의 `info.tournamentCode` 파싱이 이미 가능함을 확인 + `TournamentCode.riotMatchId` 필드/인덱스 자리 마련 + `Match.teamBuiltAt` 자리 마련 (Phase 후속 결과 수집의 `startTime` 으로 사용)
- `RiotMatchService.getMatchIdsByPuuid` 가 `type: 'tourney'` 지원 확인됨 (Phase 후속에서 그대로 호출)
- 단위 테스트 통과 (atomic N개 pop / 부분 발급 / 정규식 reject / 만료 필터 / release / bulk 중복 skip)
-470
View File
@@ -1,470 +0,0 @@
# 토너먼트 결과 수집 (우회) 플랜
> **대상**: codex 가 이어서 작업 가능한 수준의 실행 플랜
> **레포**: `/Users/dahyeon/source/lolympus-tournament-support` (pnpm workspace)
> **작성 기준**: 2026-04-27
> **선행 작업**:
> - `Tournament-Code-플랜.md` (코드 풀, `Match.tournamentCodeIds[]`, `Match.teamBuiltAt`, `TournamentCode.riotMatchId` 자리)
> - `Riot-소환사전적-플랜.md` (Redis Stream 작업 큐 + leader election + throttle + ETA)
> - `Riot-최근경기-플랜.md` (RiotRateLimiterService, RiotMatch 영구 저장)
---
## 1. Context
토너먼트 API 사용 권한이 없어 게임 종료 webhook 을 받을 수 없습니다. 우회로 다음을 구현합니다.
1. 매치가 `team-built` 으로 전환되면 결과 수집 작업이 큐에 enqueue.
2. **`match-v5 by-puuid?type=tourney&startTime=teamBuiltAt`** 폴링.
3. 응답 `info.tournamentCode` 를 우리 `TournamentCode.code` 와 매칭.
4. 매칭된 match-v5 의 **승팀/스코어/MVP 후보 / riotMatchIds** 를 우리 `Match.result` 로 변환.
5. 모든 게임 슬롯이 `used` 가 되면 `Match.status = 'finished'` 자동 전환.
본 plan 은 "선행 plan 의 §6 자리만 마련" 부분을 실제 모듈로 구현합니다.
---
## 2. 결정사항 (사용자 결정 2026-04-27)
- **호출 방식**: `match-v5 by-puuid` + **`type=tourney`** 필터 + `startTime=teamBuiltAt - 60s` window
- **폴링 puuid**: 캡틴 2명 우선, 24h 안에 못 찾으면 전체 참가자 puuid 로 확장
- **재폴링 정책**: 처음 1h 동안 **5분 간격**, 다음 23h 동안 **1h 간격**, 24h 후 `expired` 마킹 + 운영자 알림 자리
- **인프라 재사용**: Redis Stream 작업 큐 (`Riot-소환사전적-플랜.md` 의 `riot:queue:high/low`) + RiotRateLimiterService (글로벌 throttle)
- **저장**: 매칭된 match-v5 raw 는 이미 영구 저장되는 `RiotMatch` 컬렉션 그대로 활용 (선행 인프라)
- **결과 매핑**: 우리 `Match.teams[].members[].userId` ↔ match-v5 `info.participants[].puuid` ↔ `User.riotAccounts[].puuid` 로 양 팀 결정
---
## 3. 데이터 모델 보강
### 3.1 Match.result 확장
```ts
// schema.ts MatchResult 확장
export interface MatchGameResult {
gameNumber: number; // 1-based, TournamentCode.gameNumber 와 동일
riotMatchId: string;
winnerSide: TeamSide; // 'blue' | 'red' (우리 팀 매핑 후)
gameCreation: number;
gameDuration: number;
// 본인 멤버별 KDA snapshot — Match 결과 카드 표시용
participants: Array<{
userId: mongoose.Types.ObjectId;
side: TeamSide;
championId: number;
kills: number; deaths: number; assists: number;
win: boolean;
}>;
}
export interface MatchResult {
winnerSide?: TeamSide; // 시리즈 최종 승팀 (BO3: 2승 한 팀). 진행 중이면 undefined
blueScore: number; // 시리즈 누적 승수
redScore: number;
mvpUserId?: mongoose.Types.ObjectId;
riotMatchIds: string[]; // 기존 필드 (호환 유지)
games: MatchGameResult[]; // 신규: 게임별 상세
}
```
### 3.2 TournamentCode.riotMatchId — 결과 수집 시 채워짐
기존 sparse 인덱스 (`{ riotMatchId: 1 }`) 그대로 활용 — 같은 match-v5 가 두 번 매칭되는 일 방지.
### 3.3 신규: TournamentResultPollState (선택)
폴링 진척 상태 추적용 별도 컬렉션 또는 `Match.resultPollState` 임베드:
```ts
export interface MatchResultPollState {
startedAt: Date; // 첫 enqueue 시점
lastPolledAt?: Date;
lastPollOutcome?: 'matched' | 'not-found' | 'failed';
matchedCount: number; // 지금까지 매칭된 game 수
expandedToAllPuuids: boolean; // 24h 후 확장됐는지
state: 'polling' | 'complete' | 'expired' | 'failed';
}
// Match 에 추가
resultPollState?: MatchResultPollState;
```
→ 별도 컬렉션 보다 임베드가 join 0회로 단순. `Match` 안에 둬도 1개 도큐먼트당 작은 크기.
---
## 4. 작업 큐 통합
### 4.1 신규 stream/job 타입
선행 plan 의 작업 큐 (`riot:queue:high`, `riot:queue:low`) 그대로 사용. 새 job 타입만 추가:
```ts
interface PollTournamentResultJob {
jobId: string;
matchId: string; // ObjectId.toString()
attempt: number; // 1부터 증가
expandedToAllPuuids: boolean;
enqueuedAt: number;
priority: 'high' | 'low';
}
```
작업 종류는 기존 `RefreshAccountJob` 과 분리하기 위해 message field 에 `kind: 'poll-tournament-result'` 추가. worker 가 kind 별 dispatch.
### 4.2 enqueue 트리거
| 시점 | 호출 위치 | priority |
|---|---|---|
| `team-built` 전환 직후 | `auction.service.ts:175`, `:395` (코드 reserve 와 같이) | high (10분 내 첫 폴링) |
| 5분 / 1h / 24h 재폴링 | worker 가 작업 끝낼 때 다음 attempt enqueue | low |
| 운영자 수동 트리거 | admin 엔드포인트 `POST /matches/:id/poll-tournament-result` | high |
### 4.3 worker 처리 흐름
```ts
async function processPollJob(job: PollTournamentResultJob) {
const match = await MatchModel.findById(job.matchId);
if (!match || match.status === 'finished') return; // 이미 끝남
const codes = await TournamentCodeModel.find({ matchId: match._id }).sort({ gameNumber: 1 });
const unmatched = codes.filter((c) => c.state === 'reserved' && !c.riotMatchId);
if (unmatched.length === 0) {
await advanceMatchIfReady(match, codes);
return;
}
const puuids = job.expandedToAllPuuids
? await collectAllParticipantPuuids(match)
: await collectCaptainPuuids(match);
const matchedThisRound: number[] = [];
for (const puuid of puuids) {
const ids = await matchService.getMatchIdsByPuuid(puuid, {
type: 'tourney',
startTime: Math.floor((match.teamBuiltAt!.getTime() - 60_000) / 1000),
endTime: Math.floor(Date.now() / 1000),
count: 100,
region: 'asia',
});
for (const matchV5Id of ids) {
// 이미 매칭된 game 은 skip (riotMatchId 인덱스로 빠른 lookup)
const already = await TournamentCodeModel.findOne({ riotMatchId: matchV5Id });
if (already) continue;
const detail = await ensureRiotMatchPersisted(matchV5Id); // RiotMatch 테이블에 upsert
const tCode = detail.info.tournamentCode;
if (!tCode) continue;
const code = unmatched.find((c) => c.code === tCode);
if (!code) continue;
await applyMatchToGameSlot(match, code, detail);
matchedThisRound.push(code.gameNumber!);
}
}
await updatePollState(match, matchedThisRound, job);
await advanceMatchIfReady(match, await reloadCodes(match));
await scheduleNextPoll(match, job);
}
```
### 4.4 `applyMatchToGameSlot` — 우리 팀 매핑
```ts
async function applyMatchToGameSlot(match, code: TournamentCode, detail: RiotMatchDto) {
const { teamMapping, gameResult } = computeGameResult(match, detail);
code.state = 'used';
code.usedAt = new Date(detail.info.gameCreation);
code.riotMatchId = detail.metadata.matchId;
await code.save();
match.result = match.result ?? { blueScore: 0, redScore: 0, riotMatchIds: [], games: [] };
match.result.games.push(gameResult);
match.result.riotMatchIds = [
...new Set([...match.result.riotMatchIds, detail.metadata.matchId]),
];
if (gameResult.winnerSide === 'blue') match.result.blueScore += 1;
else match.result.redScore += 1;
await match.save();
}
function computeGameResult(match: Match, detail: RiotMatchDto): {
teamMapping: Record<100 | 200, TeamSide>;
gameResult: MatchGameResult;
} {
const blueUserPuuids = collectTeamPuuids(match, 'blue'); // userId → primary riotAccount.puuid
const redUserPuuids = collectTeamPuuids(match, 'red');
const team100Puuids = detail.info.participants.filter((p) => p.teamId === 100).map((p) => p.puuid);
const team200Puuids = detail.info.participants.filter((p) => p.teamId === 200).map((p) => p.puuid);
// 가장 많이 겹치는 쪽이 그 팀
const team100MatchesBlue = countOverlap(team100Puuids, blueUserPuuids) >= countOverlap(team100Puuids, redUserPuuids);
const teamMapping = team100MatchesBlue
? { 100: 'blue' as TeamSide, 200: 'red' as TeamSide }
: { 100: 'red' as TeamSide, 200: 'blue' as TeamSide };
const winningTeamId = detail.info.teams.find((t) => t.win)!.teamId as 100 | 200;
const winnerSide = teamMapping[winningTeamId];
return {
teamMapping,
gameResult: {
gameNumber: code.gameNumber!,
riotMatchId: detail.metadata.matchId,
winnerSide,
gameCreation: detail.info.gameCreation,
gameDuration: detail.info.gameDuration,
participants: detail.info.participants
.map((p) => {
const userId = lookupUserIdByPuuid(match, p.puuid);
if (!userId) return null; // 외부 puuid (다른 매치 참가자) 제외
return {
userId,
side: teamMapping[p.teamId as 100 | 200],
championId: p.championId,
kills: p.kills, deaths: p.deaths, assists: p.assists,
win: p.win,
};
})
.filter((p): p is NonNullable<typeof p> => p !== null),
},
};
}
```
> 팀 매핑 시 우리 멤버가 1명도 안 겹치면 (잘못된 매칭) → game slot 적용 skip + 운영자 알림 자리. 정상 케이스에선 5명 모두 일치.
### 4.5 `advanceMatchIfReady` — finished 자동 전환
```ts
async function advanceMatchIfReady(match: Match, codes: TournamentCode[]) {
if (codes.length < match.gameCount) return;
if (!codes.every((c) => c.state === 'used' && c.riotMatchId)) return;
match.status = 'finished';
// 시리즈 최종 승팀 = 우세 점수
if (match.result) {
match.result.winnerSide =
match.result.blueScore > match.result.redScore ? 'blue' :
match.result.redScore > match.result.blueScore ? 'red' : undefined;
}
match.resultPollState = { ...match.resultPollState, state: 'complete' } as any;
await match.save();
}
```
`mvpUserId` 자동 산정은 본 plan 범위 외 (Phase 후속). 현재는 운영자 수동 입력 가능 자리만 둠.
### 4.6 `scheduleNextPoll` — 재시도 cadence
```ts
function nextPollDelayMs(attempt: number, startedAt: Date): number | null {
const elapsedMs = Date.now() - startedAt.getTime();
if (elapsedMs > 24 * 3600_000) return null; // 24h 후 종료
if (elapsedMs <= 1 * 3600_000) return 5 * 60_000; // 1h 동안 5분 간격
return 60 * 60_000; // 그 후 1h 간격
}
async function scheduleNextPoll(match: Match, job: PollTournamentResultJob) {
const delay = nextPollDelayMs(job.attempt, match.resultPollState!.startedAt);
if (delay === null) {
await markExpired(match);
return;
}
await jobQueue.enqueue({
kind: 'poll-tournament-result',
matchId: match._id.toString(),
attempt: job.attempt + 1,
expandedToAllPuuids: shouldExpand(job, match),
priority: 'low',
deferUntil: Date.now() + delay, // §4.7 참고
});
}
```
`shouldExpand`: `elapsedMs > 1h && matchedCount === 0` 또는 `elapsedMs > 24h - 1h` 시점부터 모든 puuid 사용.
### 4.7 deferUntil — 지연 enqueue
Redis Stream 자체는 schedule 미지원. 대안:
- (a) **Garnet ZSET** `riot:queue:scheduled` — score=실행시각ms. 별도 cron `@Interval(5_000)` 가 `ZRANGEBYSCORE 0 now` 항목을 꺼내 stream 으로 옮김.
- (b) NATS JetStream `expires`/`headers.Nats-Delay` — JetStream 활성화 부담.
→ (a) 채택. 작은 헬퍼 `RiotJobScheduler.scheduleAt(deferUntilMs, payload)` 한 곳에서 관리.
### 4.8 만료 마킹 + 운영자 알림 자리
```ts
async function markExpired(match: Match) {
match.resultPollState = { ...match.resultPollState, state: 'expired' } as any;
await match.save();
// 알림 자리 — Phase 후속에서 dakao bot publish
this.logger.warn(`Tournament result polling expired for match ${match._id}`);
}
```
---
## 5. 변경 사항 (파일 단위)
### 5.1 백엔드
```
apps/api/src/modules/tournament-result/
tournament-result.module.ts
tournament-result.service.ts # processPollJob / applyMatchToGameSlot / advanceMatchIfReady
tournament-result.worker.ts # 작업 큐 dispatch (kind=poll-tournament-result)
tournament-result.controller.ts # POST /matches/:id/poll-tournament-result (admin 수동)
tournament-result.types.ts
team-mapping.util.ts # collectTeamPuuids / countOverlap / lookupUserIdByPuuid
game-result.util.ts # computeGameResult
```
`riot-job-queue.service.ts` (선행 plan):
- `enqueue(payload, deferUntil?)` 시그니처에 `deferUntil` 옵션 추가
- worker 의 dispatch 에 `kind === 'poll-tournament-result'` 분기 추가
`auction.service.ts`:
- `team-built` 전환 + `reserveForMatch` 직후 → `tournamentResultService.scheduleInitialPoll(match)` 호출
`match.service.ts` 의 `serializeMatch`:
- `result.games[]` 응답에 포함 (gameNumber 정렬)
### 5.2 인덱스 보강
`RiotMatch` 컬렉션 인덱스 추가 (선행 plan 에 없으면):
- `{ 'raw.info.tournamentCode': 1 }` sparse — match-v5 의 tournamentCode 로 reverse lookup 가능 (디버깅/admin)
### 5.3 프런트
#### MatchDetailPage 결과 표시
`apps/web/src/pages/MatchDetailPage.tsx`:
- 기존 `match.result` 단일 score 표시 → `result.games[]` 게임별 표시:
```
1경기 블루 ⓦ KR_xxxxx 28:14
2경기 레드 ⓦ KR_xxxxx 31:02
3경기 대기 중
최종 블루 2 - 1 레드
```
- `match.status === 'in-progress'` 인 동안 부분 결과 점진 표시.
- `result.games[].participants[]` 로 멤버별 KDA 표시 가능.
#### types.ts
```ts
export interface ApiMatchGameResult {
gameNumber: number;
riotMatchId: string;
winnerSide: TeamSide;
gameCreation: number;
gameDuration: number;
participants: Array<{
userId: string;
side: TeamSide;
championId: number;
kills: number; deaths: number; assists: number;
win: boolean;
}>;
}
export interface ApiMatchResult {
winnerSide?: TeamSide;
blueScore: number;
redScore: number;
mvpUserId?: string;
riotMatchIds: string[];
games: ApiMatchGameResult[];
}
```
#### admin 수동 트리거 버튼
매치 상세에 admin 만 보이는 "결과 다시 수집" 버튼 — `POST /matches/:id/poll-tournament-result` 호출 → 토스트 "수집 작업이 큐에 등록되었어요".
---
## 6. 단위 테스트
- `team-mapping.util.spec.ts`
- 5명 모두 일치 → 정확한 매핑
- 4 vs 1 일치 → 다수쪽 매핑
- 0 일치 → null 반환 (skip)
- `game-result.util.spec.ts`
- winnerSide 정확
- participants 외부 puuid 제외
- `tournament-result.service.spec.ts`
- 첫 폴링: 캡틴 puuid 만 사용
- 1h 경과 + 매치 0건 → expandedToAllPuuids=true
- 24h 후 → markExpired
- 모든 game slot used → match.status=finished, winnerSide 우세 계산
- 부분 매칭 (3경기 중 1경기만) → match.status 그대로 유지, result.games 1개
- `riot-job-scheduler.spec.ts` (deferUntil ZSET)
- scheduleAt 후 cron 이 정확한 시점에 stream 으로 옮김
---
## 7. Rollout
1. (PR-1) `Match.result.games[]` schema 확장 + `Match.resultPollState` 임베드 + 마이그레이션 (옛 result 호환 유지)
2. (PR-2) `RiotJobScheduler` (deferUntil ZSET + cron) — 다른 모듈도 재사용 가능
3. (PR-3) `tournament-result.service` (processPollJob / applyMatchToGameSlot / scheduleNextPoll) + 단위 테스트
4. (PR-4) worker dispatch 에 `kind=poll-tournament-result` 추가
5. (PR-5) auction.service `team-built` 전환 직후 `scheduleInitialPoll` 호출
6. (PR-6) admin 수동 트리거 엔드포인트 + 권한 가드
7. (PR-7) 매치 상세 결과 표시 (게임별 row + 시리즈 점수)
8. (PR-8) 운영 모니터링 (폴링 attempt / 매칭 성공률 / expired 카운트)
9. (Phase 후속) MVP 자동 산정 / dakao 알림 / mvpUserId 운영자 수동 입력 UI
---
## 8. 추가 고려사항
### 확정 (사용자 결정 2026-04-27)
- **`type=tourney` 필터** 사용 (`Tournament-Code-플랜.md` §6 결정)
- **재폴링**: 5분(1h) → 1h(23h) → 24h 후 expired
- **puuid 확장**: 24h 안 못 찾으면 캡틴 → 전체 참가자
- **finished 전환**: 모든 슬롯 used + riotMatchId 채워짐
- **결과 표시**: in-progress 부터 부분 게임 결과 점진 표시
### 권장 (운영 후 확인)
1. **잘못된 코드 매칭 방어** — `applyMatchToGameSlot` 직전에 `team100/200` 우리 멤버 합집합 ≥ 6명 이면 정상, 미만이면 skip + 운영자 알림. (예: 운영자가 코드를 외부에 유출 → 다른 사람들이 사용한 게임이 우리 매치로 잘못 들어오는 케이스)
2. **`teamBuiltAt` 누락 가드** — 옛 매치 마이그레이션 시 `teamBuiltAt` 없을 수 있음. `null` 이면 폴링 skip + admin 페이지 경고.
3. **재폴링 cadence 초기 burst** — 5분 간격은 12회/h × Match-V5 list 1 + detail N = 매치당 최악 60+ calls/h. 글로벌 throttle 통과는 되지만 큰 매치 동시 진행 시 high stream 점유. low priority 로 enqueue 가 안전.
4. **gameNumber 순서 보존** — 운영자가 1경기/2경기/3경기 코드를 순서대로 발급한 가정. 만약 사용자가 2경기 코드를 먼저 게임에 입력하면 `gameNumber` 와 실제 플레이 순서가 어긋남. `gameCreation` 기준으로 후처리 정렬 필요할 수도. 일단 운영 흐름 가정 유지.
5. **시리즈 동점 판정** — gameCount=3 인데 1-1-pending 상황에서 마지막 매치가 expired 되면 winnerSide 미정. 운영자 수동 종료 자리 필요.
6. **부분 finished UI 처리** — `result.games.length < gameCount` 인 동안 "남은 경기 N개" 표시. 모두 done 되면 시리즈 결과 카드.
7. **외부 사용자에게 노출되는 raw match-v5 id** — `result.riotMatchIds` 가 외부에 노출되는데 puuid 같은 민감 정보는 응답 매핑 단에서 자동 제외 (이미 우리 userId 만 남기는 구조).
8. **Phase 후속 MVP 산정** — 라인별 KDA z-score / damage share / vision score 가중 — 평점 산식과 같은 로직 재사용 가능 (`Riot-소환사전적-플랜.md` §2.7.B.1).
9. **Replays / 랭크/AI 매치 false positive** — `type=tourney` 가 토너먼트 코드 매치만 반환하므로 false positive 거의 없음. 추가로 `info.tournamentCode` 정확 매칭이라 2중 가드.
### 추후 (Phase 후속)
- MVP 자동 산정
- dakao bot / discord 알림 (시리즈 종료 시)
- 운영자 수동 결과 입력 UI (폴링 expired / 잘못된 매칭 정정용)
- 결과 통계 대시보드 (우리 커뮤니티의 시즌 W-L, 멤버 KDA 누적)
---
## 9. Done 정의
- `Match.result.games[]` + `Match.resultPollState` schema 추가
- `team-built` 전환 시 `scheduleInitialPoll` 호출 → 작업 큐 high 에 첫 enqueue
- worker 가 `match-v5 by-puuid?type=tourney&startTime=teamBuiltAt-60` 호출
- `info.tournamentCode` 와 우리 코드 매칭 → 해당 `TournamentCode.state='used'`, `riotMatchId` 저장
- 우리 팀(blue/red) 매핑 정확 (5명 일치 케이스 테스트)
- 부분 결과 표시: `in-progress` 동안 매칭된 game 만큼 result.games[] 채워지고 UI 점진 표시
- 모든 슬롯 used → `Match.status='finished'`, `result.winnerSide` 자동 산정
- 24h 안 못 찾으면 `resultPollState.state='expired'` + 로그 경고
- admin 수동 재시도 엔드포인트 동작
- `RiotJobScheduler` (deferUntil ZSET) 동작 — 5분/1h 후 정확히 enqueue
- 단위 테스트 통과 (team-mapping / game-result / cadence / 부분 매칭)
- Riot 429 0건 (글로벌 throttle 통과)
+120
View File
@@ -0,0 +1,120 @@
# Agent Personas
Specialist personas that play a single role with a single perspective. Each persona is a Markdown file consumed as a system prompt by your harness (Claude Code, Cursor, Copilot, etc.).
| Persona | Role | Best for |
|---------|------|----------|
| [code-reviewer](code-reviewer.md) | Senior Staff Engineer | Five-axis review before merge |
| [security-auditor](security-auditor.md) | Security Engineer | Vulnerability detection, OWASP-style audit |
| [test-engineer](test-engineer.md) | QA Engineer | Test strategy, coverage analysis, Prove-It pattern |
## How personas relate to skills and commands
Three layers, each with a distinct job:
| Layer | What it is | Example | Composition role |
|-------|-----------|---------|------------------|
| **Skill** | A workflow with steps and exit criteria | `code-review-and-quality` | The *how* — invoked from inside a persona or command |
| **Persona** | A role with a perspective and an output format | `code-reviewer` | The *who* — adopts a viewpoint, produces a report |
| **Command** | A user-facing entry point | `/review`, `/ship` | The *when* — composes personas and skills |
The user (or a slash command) is the orchestrator. **Personas do not call other personas.** Skills are mandatory hops inside a persona's workflow.
## When to use each
### Direct persona invocation
Pick this when you want one perspective on the current change and the user is in the loop.
- "Review this PR" → invoke `code-reviewer` directly
- "Are there security issues in `auth.ts`?" → invoke `security-auditor` directly
- "What tests are missing for the checkout flow?" → invoke `test-engineer` directly
### Slash command (single persona behind it)
Pick this when there's a repeatable workflow you'd otherwise re-explain every time.
- `/review` → wraps `code-reviewer` with the project's review skill
- `/test` → wraps `test-engineer` with TDD skill
### Slash command (orchestrator — fan-out)
Pick this only when **independent** investigations can run in parallel and produce reports that a single agent then merges.
- `/ship` → fans out to `code-reviewer` + `security-auditor` + `test-engineer` in parallel, then synthesizes their reports into a go/no-go decision
This is the only orchestration pattern this repo endorses. See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full pattern catalog and anti-patterns.
## Decision matrix
```
Is the work a single perspective on a single artifact?
├── Yes → Direct persona invocation
└── No → Are the sub-tasks independent (no shared mutable state, no ordering)?
├── Yes → Slash command with parallel fan-out (e.g. /ship)
└── No → Sequential slash commands run by the user (/spec → /plan → /build → /test → /review)
```
## Worked example: valid orchestration
`/ship` is the canonical fan-out orchestrator in this repo:
```
/ship
├── (parallel) code-reviewer → review report
├── (parallel) security-auditor → audit report
└── (parallel) test-engineer → coverage report
↓
merge phase (main agent)
↓
go/no-go decision + rollback plan
```
Why this works:
- Each sub-agent operates on the same diff but produces a **different perspective**
- They have no dependencies on each other → genuine parallelism, real wall-clock savings
- Each runs in a fresh context window → main session stays uncluttered
- The merge step is small and benefits from full context, so it stays in the main agent
## Worked example: invalid orchestration (do not build this)
A `meta-orchestrator` persona whose job is "decide which other persona to call":
```
/work-on-pr → meta-orchestrator
↓ (decides "this needs a review")
code-reviewer
↓ (returns)
meta-orchestrator (paraphrases result)
↓
user
```
Why this fails:
- Pure routing layer with no domain value
- Adds two paraphrasing hops → information loss + 2× token cost
- The user already knows they want a review; let them call `/review` directly
- Replicates work that slash commands and `AGENTS.md` intent-mapping already do
## Rules for personas
1. A persona is a single role with a single output format. If you find yourself adding a second role, create a second persona.
2. **Personas do not invoke other personas.** Composition is the job of slash commands or the user. On Claude Code this is also a hard platform constraint — *"subagents cannot spawn other subagents"* — so the rule is enforced for you.
3. A persona may invoke skills (the *how*).
4. Every persona file ends with a "Composition" block stating where it fits.
## Claude Code interop
The personas in this repo are designed to work as Claude Code subagents and as Agent Teams teammates without modification:
- **As subagents:** auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with `subagent_type: code-reviewer` (or `security-auditor`, `test-engineer`). `/ship` is the canonical example.
- **As Agent Teams teammates** (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): reference the same persona name when spawning a teammate. The persona's body is **appended to** the teammate's system prompt as additional instructions (not a replacement), so your persona text sits on top of the team-coordination instructions the lead installs (SendMessage, task-list tools, etc.).
Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging). See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full mapping.
Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode` frontmatter — those fields are silently ignored. Avoid relying on them when authoring new personas here.
## Adding a new persona
1. Create `agents/<role>.md` with the same frontmatter format used by existing personas.
2. Define the role, scope, output format, and rules.
3. Add a **Composition** block at the bottom (Invoke directly when / Invoke via / Do not invoke from another persona).
4. Add the persona to the table at the top of this file.
5. If the persona enables a new orchestration pattern, document it in `references/orchestration-patterns.md` rather than inventing the pattern in the persona file itself.
+97
View File
@@ -0,0 +1,97 @@
---
name: code-reviewer
description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
---
# Senior Code Reviewer
You are an experienced Staff Engineer conducting a thorough code review. Your role is to evaluate the proposed changes and provide actionable, categorized feedback.
## Review Framework
Evaluate every change across these five dimensions:
### 1. Correctness
- Does the code do what the spec/task says it should?
- Are edge cases handled (null, empty, boundary values, error paths)?
- Do the tests actually verify the behavior? Are they testing the right things?
- Are there race conditions, off-by-one errors, or state inconsistencies?
### 2. Readability
- Can another engineer understand this without explanation?
- Are names descriptive and consistent with project conventions?
- Is the control flow straightforward (no deeply nested logic)?
- Is the code well-organized (related code grouped, clear boundaries)?
### 3. Architecture
- Does the change follow existing patterns or introduce a new one?
- If a new pattern, is it justified and documented?
- Are module boundaries maintained? Any circular dependencies?
- Is the abstraction level appropriate (not over-engineered, not too coupled)?
- Are dependencies flowing in the right direction?
### 4. Security
- Is user input validated and sanitized at system boundaries?
- Are secrets kept out of code, logs, and version control?
- Is authentication/authorization checked where needed?
- Are queries parameterized? Is output encoded?
- Any new dependencies with known vulnerabilities?
### 5. Performance
- Any N+1 query patterns?
- Any unbounded loops or unconstrained data fetching?
- Any synchronous operations that should be async?
- Any unnecessary re-renders (in UI components)?
- Any missing pagination on list endpoints?
## Output Format
Categorize every finding:
**Critical** — Must fix before merge (security vulnerability, data loss risk, broken functionality)
**Important** — Should fix before merge (missing test, wrong abstraction, poor error handling)
**Suggestion** — Consider for improvement (naming, code style, optional optimization)
## Review Output Template
```markdown
## Review Summary
**Verdict:** APPROVE | REQUEST CHANGES
**Overview:** [1-2 sentences summarizing the change and overall assessment]
### Critical Issues
- [File:line] [Description and recommended fix]
### Important Issues
- [File:line] [Description and recommended fix]
### Suggestions
- [File:line] [Description]
### What's Done Well
- [Positive observation — always include at least one]
### Verification Story
- Tests reviewed: [yes/no, observations]
- Build verified: [yes/no]
- Security checked: [yes/no, observations]
```
## Rules
1. Review the tests first — they reveal intent and coverage
2. Read the spec or task description before reviewing code
3. Every Critical and Important finding should include a specific fix recommendation
4. Don't approve code with Critical issues
5. Acknowledge what's done well — specific praise motivates good practices
6. If you're uncertain about something, say so and suggest investigation rather than guessing
## Composition
- **Invoke directly when:** the user asks for a review of a specific change, file, or PR.
- **Invoke via:** `/review` (single-perspective review) or `/ship` (parallel fan-out alongside `security-auditor` and `test-engineer`).
- **Do not invoke from another persona.** If you find yourself wanting to delegate to `security-auditor` or `test-engineer`, surface that as a recommendation in your report instead — orchestration belongs to slash commands, not personas. See [agents/README.md](README.md).
+101
View File
@@ -0,0 +1,101 @@
---
name: security-auditor
description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations.
---
# Security Auditor
You are an experienced Security Engineer conducting a security review. Your role is to identify vulnerabilities, assess risk, and recommend mitigations. You focus on practical, exploitable issues rather than theoretical risks.
## Review Scope
### 1. Input Handling
- Is all user input validated at system boundaries?
- Are there injection vectors (SQL, NoSQL, OS command, LDAP)?
- Is HTML output encoded to prevent XSS?
- Are file uploads restricted by type, size, and content?
- Are URL redirects validated against an allowlist?
### 2. Authentication & Authorization
- Are passwords hashed with a strong algorithm (bcrypt, scrypt, argon2)?
- Are sessions managed securely (httpOnly, secure, sameSite cookies)?
- Is authorization checked on every protected endpoint?
- Can users access resources belonging to other users (IDOR)?
- Are password reset tokens time-limited and single-use?
- Is rate limiting applied to authentication endpoints?
### 3. Data Protection
- Are secrets in environment variables (not code)?
- Are sensitive fields excluded from API responses and logs?
- Is data encrypted in transit (HTTPS) and at rest (if required)?
- Is PII handled according to applicable regulations?
- Are database backups encrypted?
### 4. Infrastructure
- Are security headers configured (CSP, HSTS, X-Frame-Options)?
- Is CORS restricted to specific origins?
- Are dependencies audited for known vulnerabilities?
- Are error messages generic (no stack traces or internal details to users)?
- Is the principle of least privilege applied to service accounts?
### 5. Third-Party Integrations
- Are API keys and tokens stored securely?
- Are webhook payloads verified (signature validation)?
- Are third-party scripts loaded from trusted CDNs with integrity hashes?
- Are OAuth flows using PKCE and state parameters?
## Severity Classification
| Severity | Criteria | Action |
|----------|----------|--------|
| **Critical** | Exploitable remotely, leads to data breach or full compromise | Fix immediately, block release |
| **High** | Exploitable with some conditions, significant data exposure | Fix before release |
| **Medium** | Limited impact or requires authenticated access to exploit | Fix in current sprint |
| **Low** | Theoretical risk or defense-in-depth improvement | Schedule for next sprint |
| **Info** | Best practice recommendation, no current risk | Consider adopting |
## Output Format
```markdown
## Security Audit Report
### Summary
- Critical: [count]
- High: [count]
- Medium: [count]
- Low: [count]
### Findings
#### [CRITICAL] [Finding title]
- **Location:** [file:line]
- **Description:** [What the vulnerability is]
- **Impact:** [What an attacker could do]
- **Proof of concept:** [How to exploit it]
- **Recommendation:** [Specific fix with code example]
#### [HIGH] [Finding title]
...
### Positive Observations
- [Security practices done well]
### Recommendations
- [Proactive improvements to consider]
```
## Rules
1. Focus on exploitable vulnerabilities, not theoretical risks
2. Every finding must include a specific, actionable recommendation
3. Provide proof of concept or exploitation scenario for Critical/High findings
4. Acknowledge good security practices — positive reinforcement matters
5. Check the OWASP Top 10 as a minimum baseline
6. Review dependencies for known CVEs
7. Never suggest disabling security controls as a "fix"
## Composition
- **Invoke directly when:** the user wants a security-focused pass on a specific change, file, or system component.
- **Invoke via:** `/ship` (parallel fan-out alongside `code-reviewer` and `test-engineer`), or any future `/audit` command.
- **Do not invoke from another persona.** If `code-reviewer` flags something that warrants a deeper security pass, the user or a slash command initiates that pass — not the reviewer. See [agents/README.md](README.md).
+95
View File
@@ -0,0 +1,95 @@
---
name: test-engineer
description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality.
---
# Test Engineer
You are an experienced QA Engineer focused on test strategy and quality assurance. Your role is to design test suites, write tests, analyze coverage gaps, and ensure that code changes are properly verified.
## Approach
### 1. Analyze Before Writing
Before writing any test:
- Read the code being tested to understand its behavior
- Identify the public API / interface (what to test)
- Identify edge cases and error paths
- Check existing tests for patterns and conventions
### 2. Test at the Right Level
```
Pure logic, no I/O → Unit test
Crosses a boundary → Integration test
Critical user flow → E2E test
```
Test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover.
### 3. Follow the Prove-It Pattern for Bugs
When asked to write a test for a bug:
1. Write a test that demonstrates the bug (must FAIL with current code)
2. Confirm the test fails
3. Report the test is ready for the fix implementation
### 4. Write Descriptive Tests
```
describe('[Module/Function name]', () => {
it('[expected behavior in plain English]', () => {
// Arrange → Act → Assert
});
});
```
### 5. Cover These Scenarios
For every function or component:
| Scenario | Example |
|----------|---------|
| Happy path | Valid input produces expected output |
| Empty input | Empty string, empty array, null, undefined |
| Boundary values | Min, max, zero, negative |
| Error paths | Invalid input, network failure, timeout |
| Concurrency | Rapid repeated calls, out-of-order responses |
## Output Format
When analyzing test coverage:
```markdown
## Test Coverage Analysis
### Current Coverage
- [X] tests covering [Y] functions/components
- Coverage gaps identified: [list]
### Recommended Tests
1. **[Test name]** — [What it verifies, why it matters]
2. **[Test name]** — [What it verifies, why it matters]
### Priority
- Critical: [Tests that catch potential data loss or security issues]
- High: [Tests for core business logic]
- Medium: [Tests for edge cases and error handling]
- Low: [Tests for utility functions and formatting]
```
## Rules
1. Test behavior, not implementation details
2. Each test should verify one concept
3. Tests should be independent — no shared mutable state between tests
4. Avoid snapshot tests unless reviewing every change to the snapshot
5. Mock at system boundaries (database, network), not between internal functions
6. Every test name should read like a specification
7. A test that never fails is as useless as a test that always fails
## Composition
- **Invoke directly when:** the user asks for test design, coverage analysis, or a Prove-It test for a specific bug.
- **Invoke via:** `/test` (TDD workflow) or `/ship` (parallel fan-out for coverage gap analysis alongside `code-reviewer` and `security-auditor`).
- **Do not invoke from another persona.** Recommendations to add tests belong in your report; the user or a slash command decides when to act on them. See [agents/README.md](README.md).
+7
View File
@@ -25,6 +25,13 @@
[Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
## Riot Background Refresh
Stale Riot accounts refresh automatically between KST 03:00 and 10:00.
The scheduler picks active users whose
`lastRefreshRequestedAt` is older than 6 hours, oldest first, and uses a
background-only Riot token bucket capped at roughly 40% of the app rate limit.
## Project setup
```bash
+2 -2
View File
@@ -11,10 +11,10 @@
"seed:dev": "ts-node src/seed.ts",
"seed:dakao-participant": "ts-node src/seed-dakao-participant.ts",
"start:dev": "node -e \"process.env.NODE_ENV='dev'; require('./dist/main.js')\"",
"start:test": "node -e \"process.env.NODE_ENV='test'; require('./dist/main.js')\"",
"start:staging": "node -e \"process.env.NODE_ENV='staging'; require('./dist/main.js')\"",
"start:prod": "node -e \"process.env.NODE_ENV='prod'; require('./dist/main.js')\"",
"pm2:dev": "pm2 start npm --name lolympus-tournament-support --update-env -- run start:dev",
"pm2:test": "pm2 start npm --name lolympus-tournament-support --update-env -- run start:test",
"pm2:staging": "pm2 start npm --name lolympus-tournament-support --update-env -- run start:staging",
"pm2:prod": "pm2 start npm --name lolympus-tournament-support --update-env -- run start:prod",
"start:debug": "nest start --debug --watch",
"lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+2
View File
@@ -11,6 +11,7 @@ import { GlobalModule } from './modules/global/global.module';
import { LegacyImportModule } from './modules/legacy-import/legacy-import.module';
import { MatchHistoryModule } from './modules/match-history/match-history.module';
import { MatchModule } from './modules/match/match.module';
import { BackgroundRefreshModule } from './modules/riot-background-refresh/background-refresh.module';
import { RiotModule } from './modules/riot/riot.module';
import { TournamentCodeModule } from './modules/tournament-code/tournament-code.module';
import { TournamentResultModule } from './modules/tournament-result/tournament-result.module';
@@ -25,6 +26,7 @@ import { UserModule } from './modules/user/user.module';
GlobalModule,
AuthModule,
RiotModule,
BackgroundRefreshModule,
CommunityModule,
CommunityStatsModule,
MatchModule,
+67
View File
@@ -0,0 +1,67 @@
import {
createCorsOrigin,
isAllowedCorsOrigin,
resolveWebOrigins,
} from './cors-origin';
describe('CORS origin resolution', () => {
it('allows Cloudflare Pages preview origins in dev and staging', () => {
const origin = 'https://807e0ea6.lolympus.pages.dev';
expect(isAllowedCorsOrigin(origin, 'dev')).toBe(true);
expect(isAllowedCorsOrigin(origin, 'staging')).toBe(true);
});
it('does not allow Cloudflare Pages preview origins in prod', () => {
expect(
isAllowedCorsOrigin('https://807e0ea6.lolympus.pages.dev', 'prod'),
).toBe(false);
});
it('rejects similar but unsafe Pages origins', () => {
expect(
isAllowedCorsOrigin('http://807e0ea6.lolympus.pages.dev', 'staging'),
).toBe(false);
expect(isAllowedCorsOrigin('https://lolympus.pages.dev', 'staging')).toBe(
false,
);
expect(
isAllowedCorsOrigin('https://a.b.lolympus.pages.dev', 'staging'),
).toBe(false);
expect(
isAllowedCorsOrigin(
'https://807e0ea6.lolympus.pages.dev.evil.com',
'staging',
),
).toBe(false);
});
it('keeps configured web origins allowed', () => {
expect(
isAllowedCorsOrigin('https://example.com', 'prod', [
'https://example.com',
]),
).toBe(true);
});
it('falls back to default web origins when WEB_ORIGIN is empty', () => {
expect(resolveWebOrigins('')).toContain('http://localhost:5173');
});
it('creates a Nest CORS callback from the same rules', (done) => {
const corsOrigin = createCorsOrigin('staging');
expect(corsOrigin).not.toBe(true);
if (corsOrigin === true) return;
corsOrigin('https://807e0ea6.lolympus.pages.dev', (error, allow) => {
expect(error).toBeNull();
expect(allow).toBe(true);
done();
});
});
it('keeps dev CORS permissive for local development', () => {
expect(createCorsOrigin('dev')).toBe(true);
});
});
+101
View File
@@ -0,0 +1,101 @@
import type { CustomOrigin } from '@nestjs/common/interfaces/external/cors-options.interface';
const DEFAULT_WEB_ORIGINS = [
'http://localhost:5173',
'http://126.dahyeon.us:5173',
'https://lolympus.dahyeon.us',
];
const PAGES_DEV_ORIGIN_HOST_PATTERN =
/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.lolympus\.pages\.dev$/i;
const PAGES_DEV_CORS_ENVIRONMENTS = new Set(['dev', 'staging']);
function parseOrigin(origin: string, allowPath: boolean): URL | null {
const trimmedOrigin = origin.trim();
if (trimmedOrigin.length === 0) return null;
try {
const url = new URL(trimmedOrigin);
if (
!allowPath &&
(url.pathname !== '/' || url.search !== '' || url.hash !== '')
) {
return null;
}
return url;
} catch {
return null;
}
}
function normalizeOrigin(origin: string, allowPath = false): string | null {
const url = parseOrigin(origin, allowPath);
if (!url) return null;
return `${url.protocol}//${url.host}`;
}
export function resolveWebOrigins(
webOrigin = process.env.WEB_ORIGIN,
): string[] {
const configuredOrigins = webOrigin
?.split(',')
.map((origin) => normalizeOrigin(origin, true))
.filter((origin): origin is string => origin !== null);
if (configuredOrigins && configuredOrigins.length > 0) {
return configuredOrigins;
}
return [...DEFAULT_WEB_ORIGINS];
}
export function isLolympusPagesDevOrigin(origin: string): boolean {
const url = parseOrigin(origin, false);
if (!url) return false;
return (
url.protocol === 'https:' &&
url.port === '' &&
PAGES_DEV_ORIGIN_HOST_PATTERN.test(url.hostname)
);
}
export function isAllowedCorsOrigin(
requestOrigin: string | undefined,
nodeEnv = process.env.NODE_ENV,
webOrigins = resolveWebOrigins(),
): boolean {
if (!requestOrigin) return false;
const normalizedRequestOrigin = normalizeOrigin(requestOrigin);
if (!normalizedRequestOrigin) return false;
const normalizedWebOrigins = webOrigins
.map((origin) => normalizeOrigin(origin, true))
.filter((origin): origin is string => origin !== null);
if (normalizedWebOrigins.includes(normalizedRequestOrigin)) {
return true;
}
return (
PAGES_DEV_CORS_ENVIRONMENTS.has(nodeEnv ?? '') &&
isLolympusPagesDevOrigin(requestOrigin)
);
}
export function createCorsOrigin(
nodeEnv = process.env.NODE_ENV,
webOrigin = process.env.WEB_ORIGIN,
): true | CustomOrigin {
if (nodeEnv === 'dev') return true;
const webOrigins = resolveWebOrigins(webOrigin);
return (requestOrigin, callback) => {
callback(null, isAllowedCorsOrigin(requestOrigin, nodeEnv, webOrigins));
};
}
+5 -10
View File
@@ -1,23 +1,18 @@
import { ValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { createCorsOrigin } from './cors-origin';
async function bootstrap() {
const app = await NestFactory.create(AppModule, {
rawBody: true,
});
const isDev = process.env.NODE_ENV === 'dev';
const webOrigins = process.env.WEB_ORIGIN?.split(',').map((origin) =>
origin.trim(),
) ?? [
'http://localhost:5173',
'http://126.dahyeon.us:5173',
'https://lolympus.dahyeon.us',
];
const nodeEnv = process.env.NODE_ENV;
const isDev = nodeEnv === 'dev';
app.enableCors({
origin: isDev ? true : webOrigins,
origin: createCorsOrigin(nodeEnv),
credentials: true,
allowedHeaders: ['Authorization', 'Content-Type', 'X-Auth-User-Id'],
});
@@ -31,4 +26,4 @@ async function bootstrap() {
);
await app.listen(isDev ? 3000 : 10712);
}
bootstrap();
void bootstrap();
@@ -18,11 +18,20 @@ import { RolesGuard } from '../auth/roles.guard';
import { ParseObjectIdPipe } from '../common/parse-object-id.pipe';
import type { UserDocument } from '../global/database/schema';
import { AuctionService } from './auction.service';
import { PlaceBidDto, SoldDto, StartAuctionDto } from './dto/auction.dto';
import { AuctionGateway } from './auction.gateway';
import {
PlaceBidDto,
SoldDto,
StartAuctionDto,
UndoAuctionDto,
} from './dto/auction.dto';
@Controller('communities/:communityId/matches/:matchId/auction')
export class AuctionController {
constructor(private readonly auctionService: AuctionService) {}
constructor(
private readonly auctionService: AuctionService,
private readonly auctionGateway: AuctionGateway,
) {}
@Post()
@Roles('admin', 'owner')
@@ -39,12 +48,17 @@ export class AuctionController {
matchId,
communityId,
captains: body.captains.map((c) => ({
side: c.side,
groupIndex: c.groupIndex ?? 1,
teamIndex: c.teamIndex,
userId: new mongoose.Types.ObjectId(c.userId),
initialPoints: c.initialPoints,
})),
initialPoints: body.initialPoints ?? 1000,
maxTimerSeconds: body.maxTimerSeconds ?? 30,
bidExtensionSeconds: body.bidExtensionSeconds ?? 5,
topTierThreshold: body.topTierThreshold ?? 'NONE',
manualTopTierUserIds: (body.manualTopTierUserIds ?? []).map(
(userId) => new mongoose.Types.ObjectId(userId),
),
});
}
@@ -76,8 +90,7 @@ export class AuctionController {
) {
return this.auctionService.placeBid({
matchId,
side: body.side,
groupIndex: body.groupIndex ?? 1,
teamIndex: body.teamIndex,
amount: body.amount,
bidderUserId: this.resolveBidder(currentUser, body.bidderUserId),
});
@@ -105,6 +118,40 @@ export class AuctionController {
return this.auctionService.next(matchId);
}
@Get('history')
@Roles('admin', 'owner')
@UseGuards(RolesGuard)
public async listHistory(
@CurrentUser() currentUser: UserDocument,
@Param('communityId', ParseObjectIdPipe)
communityId: mongoose.Types.ObjectId,
@Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId,
) {
this.assertSameCommunity(currentUser, communityId);
return this.auctionService.listHistory({ matchId, communityId });
}
@Post('undo')
@Roles('admin', 'owner')
@UseGuards(RolesGuard)
@HttpCode(HttpStatus.OK)
public async undo(
@CurrentUser() currentUser: UserDocument,
@Param('communityId', ParseObjectIdPipe)
communityId: mongoose.Types.ObjectId,
@Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId,
@Body() body: UndoAuctionDto,
) {
this.assertSameCommunity(currentUser, communityId);
const auction = await this.auctionService.undoTo({
matchId,
communityId,
sequence: body.sequence,
});
this.auctionGateway.broadcastState(matchId.toString(), auction);
return auction;
}
@Delete()
@Roles('admin', 'owner')
@UseGuards(RolesGuard)
@@ -117,6 +164,7 @@ export class AuctionController {
) {
this.assertSameCommunity(currentUser, communityId);
await this.auctionService.reset({ matchId, communityId });
this.auctionGateway.broadcastReset(matchId.toString());
}
private resolveBidder(
+117 -6
View File
@@ -16,10 +16,10 @@ import { IdentityService } from '../auth/identity.service';
import { JwtService } from '../auth/jwt.service';
import { ConnectionService } from '../global/database/connection.service';
import type {
AuctionChatMessage,
AuctionDocument,
IdentityDocument,
Position,
TeamSide,
UserDocument,
} from '../global/database/schema';
import { AuctionService } from './auction.service';
@@ -29,8 +29,7 @@ interface JoinAuctionPayload {
}
interface BidPayload {
side: TeamSide;
groupIndex?: number;
teamIndex: number;
amount: number;
bidderUserId?: string;
}
@@ -39,6 +38,11 @@ interface SoldPayload {
assignedPosition?: Position;
}
interface ChatMessagePayload {
message?: string;
displayName?: string;
}
@WebSocketGateway({
namespace: '/auction',
cors: {
@@ -102,6 +106,7 @@ export class AuctionGateway
const auction = await this.auctionService.getByMatchId(
new mongoose.Types.ObjectId(payload.matchId),
);
this.emitChatHistory(socket, auction);
this.broadcastState(payload.matchId, auction);
} catch (error) {
this.emitKnownError(socket, error);
@@ -125,8 +130,7 @@ export class AuctionGateway
try {
const auction = await this.auctionService.placeBid({
matchId: new mongoose.Types.ObjectId(matchId),
side: payload.side,
groupIndex: payload.groupIndex ?? 1,
teamIndex: payload.teamIndex,
amount: payload.amount,
bidderUserId,
});
@@ -185,6 +189,34 @@ export class AuctionGateway
}
}
@SubscribeMessage('chat-message')
public async handleChatMessage(
@ConnectedSocket() socket: Socket,
@MessageBody() payload: ChatMessagePayload,
) {
const matchId = this.requireJoinedMatchId(socket);
if (!matchId) return;
if (typeof payload?.message !== 'string') {
this.emitError(socket, 'Chat message is required.');
return;
}
try {
const { message } = await this.auctionService.appendChatMessage({
matchId: new mongoose.Types.ObjectId(matchId),
userId: this.resolveSocketUserId(socket),
displayName: this.resolveChatDisplayName(socket, payload.displayName),
message: payload.message,
});
this.server
.to(matchId)
.emit('chat-message', this.serializeChatMessage(message));
} catch (error) {
this.emitKnownError(socket, error);
}
}
private requireJoinedMatchId(socket: Socket): string | null {
const matchId = this.getSocketMatchId(socket);
if (!matchId) {
@@ -222,6 +254,36 @@ export class AuctionGateway
return Array.isArray(header) ? header[0] : header;
}
private resolveSocketUserId(
socket: Socket,
): mongoose.Types.ObjectId | undefined {
return (socket.data.user as UserDocument | undefined)?._id;
}
private resolveChatDisplayName(
socket: Socket,
fallbackDisplayName?: string,
): string {
const user = socket.data.user as UserDocument | undefined;
const primaryRiotAccount =
user?.riotAccounts.find((entry) => entry.isPrimary) ??
user?.riotAccounts[0];
if (primaryRiotAccount?.gameName) {
return primaryRiotAccount.tagLine
? `${primaryRiotAccount.gameName}#${primaryRiotAccount.tagLine}`
: primaryRiotAccount.gameName;
}
if (user?.kakaoTalkNickname) return user.kakaoTalkNickname;
if (user?.discordNickname) return user.discordNickname;
const identity = socket.data.identity as IdentityDocument | undefined;
if (identity?.displayName) return identity.displayName;
if (identity?.email) return identity.email;
return fallbackDisplayName ?? '관전자';
}
private async authenticateSocket(socket: Socket): Promise<void> {
const fallback = await this.authService.resolveDevUserById(
this.readHandshakeUserId(socket),
@@ -297,17 +359,34 @@ export class AuctionGateway
return typeof value === 'string' && value.length > 0 ? value : undefined;
}
private broadcastState(matchId: string, auction: AuctionDocument) {
public broadcastState(matchId: string, auction: AuctionDocument) {
this.server.to(matchId).emit('state', this.serializeAuction(auction));
this.syncRoomTimer(matchId, auction);
}
public broadcastReset(matchId: string) {
this.clearRoomTimer(matchId);
this.server.to(matchId).emit('reset', { matchId });
}
private emitChatHistory(socket: Socket, auction: AuctionDocument) {
socket.emit('chat-history', {
messages: (auction.chatMessages ?? []).map((message) =>
this.serializeChatMessage(message),
),
});
}
private syncRoomTimer(matchId: string, auction: AuctionDocument) {
this.clearRoomTimer(matchId);
if (!auction.currentDeadline) return;
const deadline = auction.currentDeadline;
const deadlineIso = deadline.toISOString();
if (Date.now() >= deadline.getTime()) {
void this.handleDeadlineExpiry(matchId);
return;
}
this.server.to(matchId).emit('tick', {
deadline: deadlineIso,
serverTime: new Date().toISOString(),
@@ -321,12 +400,34 @@ export class AuctionGateway
if (Date.now() >= deadline.getTime()) {
this.clearRoomTimer(matchId);
void this.handleDeadlineExpiry(matchId);
}
}, 1000);
this.roomTimers.set(matchId, timer);
}
private async handleDeadlineExpiry(matchIdStr: string) {
const matchId = new mongoose.Types.ObjectId(matchIdStr);
const auction = await this.auctionService
.getByMatchId(matchId)
.catch(() => null);
if (!auction || auction.phase !== 'bidding') return;
if (!auction.currentDeadline || auction.currentDeadline.getTime() > Date.now()) {
return;
}
try {
const nextAuction =
auction.currentBid > 0
? await this.auctionService.markSold({ matchId })
: await this.auctionService.markPassed(matchId);
this.broadcastState(matchIdStr, nextAuction);
} catch (error) {
this.emitKnownErrorToRoom(matchIdStr, error);
}
}
private maybeClearRoomTimer(matchId: string) {
const room = this.server.adapter.rooms.get(matchId);
if (room && room.size > 0) return;
@@ -346,6 +447,12 @@ export class AuctionGateway
this.emitError(socket, message);
}
private emitKnownErrorToRoom(matchId: string, error: unknown) {
const message =
error instanceof Error ? error.message : 'Unexpected auction gateway error.';
this.server.to(matchId).emit('error', { message });
}
private emitError(socket: Socket, message: string) {
socket.emit('error', { message });
}
@@ -353,4 +460,8 @@ export class AuctionGateway
private serializeAuction(auction: AuctionDocument) {
return JSON.parse(JSON.stringify(auction));
}
private serializeChatMessage(message: AuctionChatMessage) {
return JSON.parse(JSON.stringify(message));
}
}
@@ -3,8 +3,27 @@ import { AuctionService } from './auction.service';
describe('AuctionService', () => {
function createService(models: Record<string, unknown>) {
const auctionHistoryModel = {
findOne: jest.fn().mockReturnValue({
sort: jest.fn().mockReturnValue({
select: jest.fn().mockReturnValue({
lean: jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue(null),
}),
}),
}),
}),
create: jest.fn().mockResolvedValue(undefined),
deleteMany: jest.fn().mockReturnValue({
session: jest.fn().mockResolvedValue(undefined),
}),
};
const allModels = {
auctionHistory: auctionHistoryModel,
...models,
};
const connectionService = {
getModel: jest.fn((name: string) => models[name]),
getModel: jest.fn((name: string) => allModels[name]),
createSession: jest.fn(),
};
const enrichmentService = {
@@ -16,6 +35,7 @@ describe('AuctionService', () => {
};
const tournamentResultService = {
scheduleInitialPoll: jest.fn().mockResolvedValue(null),
cancelPolling: jest.fn().mockResolvedValue(undefined),
};
return {
@@ -28,12 +48,13 @@ describe('AuctionService', () => {
connectionService,
tournamentCodeService,
tournamentResultService,
auctionHistoryModel,
};
}
function createFullTeam(side: 'blue' | 'red') {
function createFullTeam(teamIndex: number) {
return {
side,
teamIndex,
captainUserId: new mongoose.Types.ObjectId(),
points: 100,
members: Array.from({ length: 4 }, () => ({
@@ -44,11 +65,381 @@ describe('AuctionService', () => {
};
}
afterEach(() => {
jest.restoreAllMocks();
jest.useRealTimers();
});
it('starts an auction without reserving tournament codes before teams are complete', async () => {
const matchId = new mongoose.Types.ObjectId();
const communityId = new mongoose.Types.ObjectId();
const userIds = Array.from(
{ length: 10 },
() => new mongoose.Types.ObjectId(),
);
const participants = userIds.map((userId, index) => ({
userId,
preferredPositions: [{ position: 'MID', priority: 1 }],
joinedAt: new Date(index),
excluded: false,
}));
const match = {
_id: matchId,
communityId,
participants,
status: 'recruiting',
teamBuiltAt: undefined,
save: jest.fn().mockResolvedValue(undefined),
};
const users = userIds.slice(2).map((userId, index) => ({
_id: userId,
riotAccounts: [
{
puuid: `puuid-${index}`,
gameName: `Player${index}`,
tagLine: 'KR1',
profileIconId: index,
tiers: [],
championMasteries: [],
recentStatsSummary: undefined,
lastRefreshRequestedAt: new Date(),
isPrimary: true,
},
],
}));
const auction = {
_id: new mongoose.Types.ObjectId(),
matchId,
toObject: jest.fn().mockReturnValue({ matchId }),
};
const { service, tournamentCodeService, tournamentResultService } =
createService({
match: {
findById: jest.fn().mockResolvedValue(match),
},
user: {
find: jest.fn().mockResolvedValue(users),
},
auction: {
findOne: jest.fn().mockResolvedValue(null),
create: jest.fn().mockResolvedValue(auction),
},
community: {
findById: jest.fn().mockReturnValue({
select: jest.fn().mockReturnValue({
lean: jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue({
riotPlatform: 'kr',
riotRegion: 'asia',
}),
}),
}),
}),
},
});
await service.start({
matchId,
communityId,
captains: [
{ teamIndex: 1, userId: userIds[0] },
{ teamIndex: 2, userId: userIds[1] },
],
initialPoints: 1000,
maxTimerSeconds: 30,
bidExtensionSeconds: 5,
topTierThreshold: 'NONE',
manualTopTierUserIds: [],
});
expect(match.status).toBe('team-built');
expect(match.teamBuiltAt).toBeInstanceOf(Date);
expect(match.save).toHaveBeenCalledTimes(1);
expect(tournamentCodeService.reserveForMatch).not.toHaveBeenCalled();
expect(tournamentResultService.scheduleInitialPoll).not.toHaveBeenCalled();
});
it('appends a chat message and keeps only the latest 200 messages', async () => {
const matchId = new mongoose.Types.ObjectId();
const userId = new mongoose.Types.ObjectId();
const oldMessages = Array.from({ length: 200 }, (_, index) => ({
id: `old-${index}`,
displayName: 'Old',
message: `old message ${index}`,
sentAt: new Date(index),
}));
const auction = {
matchId,
chatMessages: oldMessages,
save: jest.fn().mockResolvedValue(undefined),
};
const { service } = createService({
auction: {
findOne: jest.fn().mockResolvedValue(auction),
},
});
const appended = await service.appendChatMessage({
matchId,
userId,
displayName: ' Captain One ',
message: ' 좋은 픽입니다 ',
});
expect(appended.message).toMatchObject({
userId,
displayName: 'Captain One',
message: '좋은 픽입니다',
});
expect(appended.message.id).toHaveLength(36);
expect(appended.message.sentAt).toBeInstanceOf(Date);
expect(auction.chatMessages).toHaveLength(200);
expect(auction.chatMessages[0].id).toBe('old-1');
expect(auction.chatMessages.at(-1)).toBe(appended.message);
expect(auction.save).toHaveBeenCalledTimes(1);
});
it('rejects blank and overly long chat messages', async () => {
const matchId = new mongoose.Types.ObjectId();
const auction = {
matchId,
chatMessages: [],
save: jest.fn().mockResolvedValue(undefined),
};
const { service } = createService({
auction: {
findOne: jest.fn().mockResolvedValue(auction),
},
});
await expect(
service.appendChatMessage({
matchId,
displayName: 'Spectator',
message: ' ',
}),
).rejects.toThrow('Chat message is required.');
await expect(
service.appendChatMessage({
matchId,
displayName: 'Spectator',
message: 'a'.repeat(301),
}),
).rejects.toThrow('Chat message must be 300 characters or less.');
expect(auction.save).not.toHaveBeenCalled();
});
it('randomizes the non-captain player order when starting an auction', async () => {
const randomSpy = jest.spyOn(Math, 'random').mockReturnValue(0);
const matchId = new mongoose.Types.ObjectId();
const communityId = new mongoose.Types.ObjectId();
const userIds = Array.from(
{ length: 10 },
() => new mongoose.Types.ObjectId(),
);
const participants = userIds.map((userId, index) => ({
userId,
preferredPositions: [{ position: 'MID', priority: 1 }],
joinedAt: new Date(index),
excluded: false,
}));
const match = {
_id: matchId,
communityId,
participants,
status: 'recruiting',
teamBuiltAt: undefined,
save: jest.fn().mockResolvedValue(undefined),
};
const users = userIds.slice(2).map((userId, index) => ({
_id: userId,
riotAccounts: [
{
puuid: `puuid-${index}`,
gameName: `Player${index}`,
tagLine: 'KR1',
profileIconId: index,
tiers: [],
championMasteries: [],
recentStatsSummary: undefined,
lastRefreshRequestedAt: new Date(),
isPrimary: true,
},
],
}));
const auctionCreate = jest.fn().mockImplementation(async (payload) => ({
_id: new mongoose.Types.ObjectId(),
matchId,
toObject: jest.fn().mockReturnValue({ matchId, ...payload }),
}));
const { service } = createService({
match: {
findById: jest.fn().mockResolvedValue(match),
},
user: {
find: jest.fn().mockResolvedValue(users),
},
auction: {
findOne: jest.fn().mockResolvedValue(null),
create: auctionCreate,
},
community: {
findById: jest.fn().mockReturnValue({
select: jest.fn().mockReturnValue({
lean: jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue({
riotPlatform: 'kr',
riotRegion: 'asia',
}),
}),
}),
}),
},
});
await service.start({
matchId,
communityId,
captains: [
{ teamIndex: 1, userId: userIds[0] },
{ teamIndex: 2, userId: userIds[1] },
],
initialPoints: 1000,
maxTimerSeconds: 30,
bidExtensionSeconds: 5,
topTierThreshold: 'NONE',
manualTopTierUserIds: [],
});
const signupOrder = userIds.slice(2).map((userId) => userId.toString());
const auctionOrder = auctionCreate.mock.calls[0][0].order.map(
(player: { userId: mongoose.Types.ObjectId }) =>
player.userId.toString(),
);
expect(auctionOrder).not.toEqual(signupOrder);
expect([...auctionOrder].sort()).toEqual([...signupOrder].sort());
expect(randomSpy).toHaveBeenCalled();
});
it('includes tier history in auction player snapshots when starting an auction', async () => {
const matchId = new mongoose.Types.ObjectId();
const communityId = new mongoose.Types.ObjectId();
const userIds = Array.from(
{ length: 10 },
() => new mongoose.Types.ObjectId(),
);
const participants = userIds.map((userId, index) => ({
userId,
preferredPositions: [{ position: 'MID', priority: 1 }],
joinedAt: new Date(index),
excluded: false,
}));
const match = {
_id: matchId,
communityId,
participants,
status: 'recruiting',
teamBuiltAt: undefined,
save: jest.fn().mockResolvedValue(undefined),
};
const tierHistory = [
{
queueType: 'RANKED_SOLO_5x5',
tier: 'GOLD',
rank: 'II',
leaguePoints: 42,
wins: 30,
losses: 24,
recordedAt: new Date('2026-05-01T00:00:00.000Z'),
},
{
queueType: 'RANKED_SOLO_5x5',
tier: 'PLATINUM',
rank: 'IV',
leaguePoints: 15,
wins: 34,
losses: 27,
recordedAt: new Date('2026-05-08T00:00:00.000Z'),
},
];
const users = userIds.slice(2).map((userId, index) => ({
_id: userId,
riotAccounts: [
{
puuid: `puuid-${index}`,
gameName: `Player${index}`,
tagLine: 'KR1',
profileIconId: index,
tiers: [],
tierHistory: index === 0 ? tierHistory : [],
championMasteries: [],
recentStatsSummary: undefined,
lastRefreshRequestedAt: new Date(),
isPrimary: true,
},
],
}));
const auctionCreate = jest.fn().mockImplementation(async (payload) => ({
_id: new mongoose.Types.ObjectId(),
matchId,
toObject: jest.fn().mockReturnValue({ matchId, ...payload }),
}));
const { service } = createService({
match: {
findById: jest.fn().mockResolvedValue(match),
},
user: {
find: jest.fn().mockResolvedValue(users),
},
auction: {
findOne: jest.fn().mockResolvedValue(null),
create: auctionCreate,
},
community: {
findById: jest.fn().mockReturnValue({
select: jest.fn().mockReturnValue({
lean: jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue({
riotPlatform: 'kr',
riotRegion: 'asia',
}),
}),
}),
}),
},
});
await service.start({
matchId,
communityId,
captains: [
{ teamIndex: 1, userId: userIds[0] },
{ teamIndex: 2, userId: userIds[1] },
],
initialPoints: 1000,
maxTimerSeconds: 30,
bidExtensionSeconds: 5,
topTierThreshold: 'NONE',
manualTopTierUserIds: [],
});
const firstPlayerSnapshot = auctionCreate.mock.calls[0][0].order.find(
(player: { userId: mongoose.Types.ObjectId }) =>
player.userId.equals(userIds[2]),
);
expect(firstPlayerSnapshot).toMatchObject({
userId: userIds[2],
tierHistory,
});
});
it('rejects bids when the team already has 5 members including captain', async () => {
const matchId = new mongoose.Types.ObjectId();
const auction = {
phase: 'bidding',
teams: [createFullTeam('blue'), createFullTeam('red')],
teams: [createFullTeam(1), createFullTeam(2)],
currentBid: 10,
save: jest.fn().mockResolvedValue(undefined),
};
@@ -61,18 +452,62 @@ describe('AuctionService', () => {
await expect(
service.placeBid({
matchId,
side: 'blue',
teamIndex: 1,
amount: 20,
}),
).rejects.toThrow('Team already has maximum members.');
expect(auction.save).not.toHaveBeenCalled();
});
it('extends a short bid deadline using the configured bid extension seconds', async () => {
const now = new Date('2026-05-02T00:00:00.000Z');
jest.useFakeTimers().setSystemTime(now);
const matchId = new mongoose.Types.ObjectId();
const captainUserId = new mongoose.Types.ObjectId();
const auction = {
_id: new mongoose.Types.ObjectId(),
matchId,
phase: 'bidding',
teams: [
{
teamIndex: 1,
captainUserId,
points: 1000,
members: [],
},
],
currentBid: 10,
currentDeadline: new Date(now.getTime() + 2000),
maxTimerSeconds: 30,
bidExtensionSeconds: 12,
bids: [],
save: jest.fn().mockResolvedValue(undefined),
toObject: jest.fn().mockReturnValue({ _id: 'auction', matchId }),
};
const { service } = createService({
auction: {
findOne: jest.fn().mockResolvedValue(auction),
},
});
await service.placeBid({
matchId,
teamIndex: 1,
amount: 20,
});
expect(auction.currentDeadline).toEqual(
new Date(now.getTime() + 12000),
);
expect(auction.save).toHaveBeenCalledTimes(1);
});
it('rejects sold confirmation when the winning team is already full', async () => {
const matchId = new mongoose.Types.ObjectId();
const auction = {
phase: 'bidding',
currentBidder: 'blue',
currentBidderTeamIndex: 1,
currentBid: 20,
currentIndex: 0,
order: [
@@ -81,7 +516,7 @@ describe('AuctionService', () => {
preferredPositions: [{ position: 'ADC', priority: 1 }],
},
],
teams: [createFullTeam('blue'), createFullTeam('red')],
teams: [createFullTeam(1), createFullTeam(2)],
save: jest.fn().mockResolvedValue(undefined),
};
const { service } = createService({
@@ -96,6 +531,139 @@ describe('AuctionService', () => {
expect(auction.save).not.toHaveBeenCalled();
});
it('marks a zero-bid player as passed and queues them for another round', async () => {
const matchId = new mongoose.Types.ObjectId();
const playerId = new mongoose.Types.ObjectId();
const auction = {
_id: new mongoose.Types.ObjectId(),
matchId,
phase: 'bidding',
currentBid: 0,
currentIndex: 0,
auctionRound: 1,
order: [
{
userId: playerId,
preferredPositions: [{ position: 'MID', priority: 1 }],
passCount: 0,
},
],
passedQueue: [],
save: jest.fn().mockResolvedValue(undefined),
toObject: jest.fn().mockReturnValue({ _id: 'auction', matchId }),
};
const { service } = createService({
auction: {
findOne: jest.fn().mockResolvedValue(auction),
},
});
await service.markPassed(matchId);
expect(auction.phase).toBe('passed');
expect(auction.order[0].passCount).toBe(1);
expect(auction.passedQueue).toHaveLength(1);
expect(auction.save).toHaveBeenCalledTimes(1);
});
it('queues zero-bid passes after the first auction round', async () => {
const matchId = new mongoose.Types.ObjectId();
const playerId = new mongoose.Types.ObjectId();
const auction = {
_id: new mongoose.Types.ObjectId(),
matchId,
phase: 'bidding',
currentBid: 0,
currentIndex: 0,
auctionRound: 2,
order: [
{
userId: playerId,
preferredPositions: [{ position: 'MID', priority: 1 }],
passCount: 1,
},
],
passedQueue: [],
save: jest.fn().mockResolvedValue(undefined),
toObject: jest.fn().mockReturnValue({ _id: 'auction', matchId }),
};
const { service } = createService({
auction: {
findOne: jest.fn().mockResolvedValue(auction),
},
});
await service.markPassed(matchId);
expect(auction.phase).toBe('passed');
expect(auction.order[0].passCount).toBe(2);
expect(auction.passedQueue).toHaveLength(1);
expect(auction.passedQueue[0]).toMatchObject({
userId: playerId.toString(),
preferredPositions: [{ position: 'MID', priority: 1 }],
passCount: 2,
});
});
it('requeues second-pass players instead of force-assigning them', async () => {
const matchId = new mongoose.Types.ObjectId();
const captainOneId = new mongoose.Types.ObjectId();
const captainTwoId = new mongoose.Types.ObjectId();
const passedPlayerId = new mongoose.Types.ObjectId();
const passedPlayer = {
userId: passedPlayerId,
preferredPositions: [{ position: 'SUP', priority: 1 }],
passCount: 2,
};
const auction = {
_id: new mongoose.Types.ObjectId(),
matchId,
phase: 'passed',
currentIndex: 0,
auctionRound: 2,
order: [passedPlayer],
passedQueue: [passedPlayer],
teams: [
{
teamIndex: 1,
captainUserId: captainOneId,
points: 10,
members: [],
},
{
teamIndex: 2,
captainUserId: captainTwoId,
points: 50,
members: [],
},
],
save: jest.fn().mockResolvedValue(undefined),
toObject: jest.fn().mockReturnValue({ _id: 'auction', matchId }),
};
const { service } = createService({
auction: {
findOne: jest.fn().mockResolvedValue(auction),
},
});
await service.next(matchId);
expect(auction.phase).toBe('presenting');
expect(auction.auctionRound).toBe(3);
expect(auction.currentIndex).toBe(1);
expect(auction.order).toHaveLength(2);
expect(auction.order[1]).toMatchObject({
userId: passedPlayerId.toString(),
preferredPositions: [{ position: 'SUP', priority: 1 }],
passCount: 2,
});
expect(auction.passedQueue).toEqual([]);
expect(auction.teams[0].members).toEqual([]);
expect(auction.teams[1].members).toEqual([]);
expect(auction.teams[0].points).toBe(10);
expect(auction.teams[1].points).toBe(50);
});
it('syncs completed auction teams into the match document', async () => {
const matchId = new mongoose.Types.ObjectId();
const blueCaptainId = new mongoose.Types.ObjectId();
@@ -110,7 +678,7 @@ describe('AuctionService', () => {
order: [{ userId: blueMemberId }, { userId: redMemberId }],
teams: [
{
side: 'blue',
teamIndex: 1,
captainUserId: blueCaptainId,
points: 970,
members: [
@@ -122,7 +690,7 @@ describe('AuctionService', () => {
],
},
{
side: 'red',
teamIndex: 2,
captainUserId: redCaptainId,
points: 940,
members: [
@@ -159,14 +727,15 @@ describe('AuctionService', () => {
teams: [],
save: jest.fn().mockResolvedValue(undefined),
};
const { service } = createService({
auction: {
findOne: jest.fn().mockResolvedValue(auction),
},
match: {
findById: jest.fn().mockResolvedValue(match),
},
});
const { service, tournamentCodeService, tournamentResultService } =
createService({
auction: {
findOne: jest.fn().mockResolvedValue(auction),
},
match: {
findById: jest.fn().mockResolvedValue(match),
},
});
await service.next(matchId);
@@ -176,8 +745,8 @@ describe('AuctionService', () => {
expect(match.save).toHaveBeenCalledTimes(1);
expect(match.teams).toEqual([
{
side: 'blue',
name: '블루팀',
teamIndex: 1,
name: '1팀',
captainUserId: blueCaptainId,
members: [
{
@@ -193,8 +762,8 @@ describe('AuctionService', () => {
],
},
{
side: 'red',
name: '레드팀',
teamIndex: 2,
name: '2팀',
captainUserId: redCaptainId,
members: [
{
@@ -210,6 +779,10 @@ describe('AuctionService', () => {
],
},
]);
expect(tournamentCodeService.reserveForMatch).toHaveBeenCalledWith(match);
expect(tournamentResultService.scheduleInitialPoll).toHaveBeenCalledWith(
match,
);
});
it('clears match teams when resetting an auction', async () => {
@@ -229,11 +802,14 @@ describe('AuctionService', () => {
status: 'team-built',
teams: [
{
side: 'blue',
name: '블루팀',
teamIndex: 1,
name: '1팀',
members: [],
},
],
tournamentCodeIds: [new mongoose.Types.ObjectId()],
gameSchedule: [{ gameNumber: 1, teamAIndex: 1, teamBIndex: 2 }],
participants: [],
save: jest.fn().mockResolvedValue(undefined),
};
const auctionFindOneQuery = {
@@ -256,7 +832,97 @@ describe('AuctionService', () => {
expect(match.status).toBe('recruiting');
expect(match.teams).toEqual([]);
expect(match.tournamentCodeIds).toEqual([]);
expect(match.gameSchedule).toEqual([]);
expect(match.save).toHaveBeenCalledWith({ session });
expect(session.commitTransaction).toHaveBeenCalledTimes(1);
});
it('undoes to a history snapshot and releases resources when leaving complete', async () => {
const matchId = new mongoose.Types.ObjectId();
const communityId = new mongoose.Types.ObjectId();
const auctionId = new mongoose.Types.ObjectId();
const session = {
startTransaction: jest.fn(),
commitTransaction: jest.fn().mockResolvedValue(undefined),
abortTransaction: jest.fn().mockResolvedValue(undefined),
endSession: jest.fn().mockResolvedValue(undefined),
};
const auction = {
_id: auctionId,
matchId,
completedAt: new Date(),
};
const snapshot = {
_id: auctionId.toString(),
matchId: matchId.toString(),
phase: 'bidding',
order: [],
teams: [],
};
const restored = { _id: auctionId, phase: 'bidding' };
const match = {
communityId,
status: 'finished',
result: { games: [] },
save: jest.fn().mockResolvedValue(undefined),
};
const auctionFindOneQuery = {
session: jest.fn().mockResolvedValue(auction),
};
const matchFindByIdQuery = {
session: jest.fn().mockResolvedValue(match),
};
const historyFindOneQuery = {
session: jest.fn().mockReturnValue({
lean: jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue({
auctionId,
matchId,
sequence: 3,
snapshotBefore: snapshot,
}),
}),
}),
};
const historyDeleteManyQuery = {
session: jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue(undefined),
}),
};
const auctionReplaceOne = jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue(undefined),
});
const { service, connectionService, tournamentCodeService, tournamentResultService } =
createService({
auction: {
findOne: jest.fn().mockReturnValue(auctionFindOneQuery),
replaceOne: auctionReplaceOne,
findById: jest.fn().mockResolvedValue(restored),
},
auctionHistory: {
findOne: jest.fn().mockReturnValue(historyFindOneQuery),
deleteMany: jest.fn().mockReturnValue(historyDeleteManyQuery),
},
match: {
findById: jest.fn().mockReturnValue(matchFindByIdQuery),
},
});
connectionService.createSession.mockResolvedValue(session);
await expect(
service.undoTo({ matchId, communityId, sequence: 3 }),
).resolves.toBe(restored);
expect(tournamentCodeService.releaseFromMatch).toHaveBeenCalledWith(match);
expect(tournamentResultService.cancelPolling).toHaveBeenCalledWith(match);
expect(match.status).toBe('team-built');
expect(match.result).toBeUndefined();
expect(auctionReplaceOne).toHaveBeenCalledWith(
{ _id: auctionId },
snapshot,
{ session },
);
expect(session.commitTransaction).toHaveBeenCalledTimes(1);
});
});
+541 -87
View File
@@ -2,41 +2,54 @@ import {
BadRequestException,
Injectable,
InternalServerErrorException,
Logger,
NotFoundException,
} from '@nestjs/common';
import { randomUUID } from 'crypto';
import mongoose from 'mongoose';
import { ConnectionService } from '../global/database/connection.service';
import {
AuctionActionType,
AuctionChatMessage,
AuctionDocument,
AuctionPlayerSnapshot,
AuctionTeam,
AuctionTopTierThreshold,
MatchParticipant,
MatchTeamMember,
Position,
TeamSide,
RiotAccount,
} from '../global/database/schema';
import { RiotAccountEnrichmentService } from '../riot/riot-account-enrichment.service';
import type { RiotPlatformRoute, RiotRegionalRoute } from '../riot/riot.types';
import { TournamentCodeService } from '../tournament-code/tournament-code.service';
import { TournamentResultService } from '../tournament-result/tournament-result.service';
const AUCTION_MAX_TEAM_SIZE = 5;
const AUCTION_BACKGROUND_ENRICHMENT_CONCURRENCY = 1;
const AUCTION_ENRICHMENT_COOLDOWN_MS = 3 * 60 * 60 * 1000;
const AUCTION_CHAT_MAX_MESSAGES = 200;
const AUCTION_CHAT_MAX_MESSAGE_LENGTH = 300;
const AUCTION_CHAT_MAX_DISPLAY_NAME_LENGTH = 24;
interface StartAuctionParams {
matchId: mongoose.Types.ObjectId;
communityId: mongoose.Types.ObjectId;
captains: {
side: TeamSide;
groupIndex: number;
teamIndex: number;
userId: mongoose.Types.ObjectId;
initialPoints?: number;
}[];
initialPoints: number;
maxTimerSeconds: number;
bidExtensionSeconds: number;
topTierThreshold: AuctionTopTierThreshold;
manualTopTierUserIds: mongoose.Types.ObjectId[];
}
interface PlaceBidParams {
matchId: mongoose.Types.ObjectId;
side: TeamSide;
groupIndex: number;
teamIndex: number;
amount: number;
bidderUserId?: mongoose.Types.ObjectId;
}
@@ -46,8 +59,29 @@ interface MarkSoldParams {
assignedPosition?: Position;
}
interface AppendChatMessageParams {
matchId: mongoose.Types.ObjectId;
userId?: mongoose.Types.ObjectId;
displayName?: string;
message: string;
}
export interface AuctionHistoryView {
sequence: number;
action: AuctionActionType;
actionLabel: string;
takenAt: Date;
}
interface AuctionEnrichmentTarget {
userId: mongoose.Types.ObjectId;
puuid: string;
}
@Injectable()
export class AuctionService {
private readonly logger = new Logger(AuctionService.name);
constructor(
private readonly connectionService: ConnectionService,
private readonly enrichmentService: RiotAccountEnrichmentService,
@@ -78,13 +112,16 @@ export class AuctionService {
throw new BadRequestException('Not enough participants (need at least 10).');
}
const expectedCaptainCount = desiredAuctionCount / AUCTION_MAX_TEAM_SIZE;
const groupCount = expectedCaptainCount / 2;
if (params.captains.length !== expectedCaptainCount) {
throw new BadRequestException(
`Expected ${expectedCaptainCount} captains for ${desiredAuctionCount} participants.`,
);
}
this.assertCaptainAssignments(params.captains, activeParticipants, groupCount);
this.assertCaptainAssignments(
params.captains,
activeParticipants,
expectedCaptainCount,
);
const captainUserIds = params.captains.map((c) => c.userId);
const basePlayerUsers = await UserModel.find({
@@ -101,32 +138,16 @@ export class AuctionService {
const platform = community?.riotPlatform ?? 'kr';
const region = community?.riotRegion ?? 'asia';
const enrichTargets = basePlayerUsers
.map((user) => ({
userId: user._id,
puuid: (user.riotAccounts.find((account) => account.isPrimary) ?? user.riotAccounts[0])
?.puuid,
}))
.filter((target): target is { userId: mongoose.Types.ObjectId; puuid: string } =>
typeof target.puuid === 'string' && target.puuid.length > 0,
);
await runWithConcurrency(enrichTargets, 3, async (target) => {
await this.enrichmentService.enrichRiotAccount({
userId: target.userId,
puuid: target.puuid,
options: {
force: false,
platform,
region,
},
});
const enrichCooldownCutoff = Date.now() - AUCTION_ENRICHMENT_COOLDOWN_MS;
const enrichTargets = basePlayerUsers.flatMap((user) => {
const account =
user.riotAccounts.find((entry) => entry.isPrimary) ?? user.riotAccounts[0];
if (!account?.puuid) return [];
if (this.wasRecentlyRefreshed(account, enrichCooldownCutoff)) return [];
return [{ userId: user._id, puuid: account.puuid }];
});
const playerUsers = await UserModel.find({
_id: { $in: basePlayerUsers.map((user) => user._id) },
});
const userById = new Map(playerUsers.map((u) => [u._id.toString(), u]));
const userById = new Map(basePlayerUsers.map((u) => [u._id.toString(), u]));
const nonCaptainPuuids = new Set<string>();
const order: AuctionPlayerSnapshot[] = [];
@@ -153,35 +174,53 @@ export class AuctionService {
profileIconId: primary.profileIconId,
preferredPositions: participant.preferredPositions,
tiers: primary.tiers,
tierHistory: primary.tierHistory ?? [],
masteries: primary.championMasteries,
recentStatsSummary: primary.recentStatsSummary,
passCount: 0,
});
}
const shuffledOrder = this.shuffleAuctionPlayerOrder(order);
const prioritizedOrder = this.applyTopTierPriority(
shuffledOrder,
params.topTierThreshold,
params.manualTopTierUserIds,
);
const auction = await AuctionModel.create({
matchId: params.matchId,
phase: 'presenting',
teams: params.captains.map((c) => ({
side: c.side,
groupIndex: c.groupIndex,
teamIndex: c.teamIndex,
captainUserId: c.userId,
points: params.initialPoints,
points: c.initialPoints ?? params.initialPoints,
members: [],
})),
order,
order: prioritizedOrder,
passedQueue: [],
auctionRound: 1,
currentIndex: 0,
bids: [],
currentBid: 0,
maxTimerSeconds: params.maxTimerSeconds,
bidExtensionSeconds: params.bidExtensionSeconds,
initialPoints: params.initialPoints,
topTierThreshold: params.topTierThreshold,
manualTopTierUserIds:
params.topTierThreshold === 'MANUAL' ? params.manualTopTierUserIds : [],
startedAt: new Date(),
});
await this.recordSnapshot(auction, 'start');
match.status = 'team-built';
match.teamBuiltAt = match.teamBuiltAt ?? new Date();
await match.save();
await this.tournamentCodeService.reserveForMatch(match);
await this.tournamentResultService.scheduleInitialPoll(match);
this.enqueueBackgroundOrderEnrichment({
auctionId: auction._id,
targets: enrichTargets,
platform,
region,
});
return auction;
}
@@ -195,6 +234,60 @@ export class AuctionService {
return auction;
}
public async appendChatMessage(params: AppendChatMessageParams): Promise<{
auction: AuctionDocument;
message: AuctionChatMessage;
}> {
const auction = await this.getByMatchId(params.matchId);
const messageText = this.normalizeChatMessage(params.message);
const message: AuctionChatMessage = {
id: randomUUID(),
userId: params.userId,
displayName: this.normalizeChatDisplayName(params.displayName),
message: messageText,
sentAt: new Date(),
};
auction.chatMessages ??= [];
auction.chatMessages.push(message);
const overflow = auction.chatMessages.length - AUCTION_CHAT_MAX_MESSAGES;
if (overflow > 0) {
auction.chatMessages.splice(0, overflow);
}
await auction.save();
return { auction, message };
}
public async listHistory(params: {
matchId: mongoose.Types.ObjectId;
communityId: mongoose.Types.ObjectId;
}): Promise<AuctionHistoryView[]> {
const MatchModel = await this.connectionService.getModel('match');
const AuctionHistoryModel =
await this.connectionService.getModel('auctionHistory');
const match = await MatchModel.findById(params.matchId).select({
communityId: 1,
});
if (!match) throw new NotFoundException('Match not found.');
if (!match.communityId.equals(params.communityId)) {
throw new BadRequestException('Match does not belong to this community.');
}
const entries = await AuctionHistoryModel.find({ matchId: params.matchId })
.sort({ sequence: -1 })
.limit(100)
.lean()
.exec();
return entries.map((entry) => ({
sequence: entry.sequence,
action: entry.action,
actionLabel: this.formatHistoryActionLabel(entry.action),
takenAt: entry.takenAt,
}));
}
public async openBidding(
matchId: mongoose.Types.ObjectId,
): Promise<AuctionDocument> {
@@ -202,10 +295,10 @@ export class AuctionService {
if (auction.phase !== 'presenting') {
throw new BadRequestException('Auction is not in presenting phase.');
}
await this.recordSnapshot(auction, 'open-bidding');
auction.phase = 'bidding';
auction.currentBid = 0;
auction.currentBidder = undefined;
auction.currentBidderGroupIndex = undefined;
auction.currentBidderTeamIndex = undefined;
auction.currentDeadline = this.createDeadline(auction.maxTimerSeconds);
await auction.save();
return auction;
@@ -216,7 +309,7 @@ export class AuctionService {
if (auction.phase !== 'bidding') {
throw new BadRequestException('Auction is not in bidding phase.');
}
const team = this.findAuctionTeam(auction, params.side, params.groupIndex);
const team = this.findAuctionTeamByIndex(auction, params.teamIndex);
if (!team) throw new BadRequestException('Unknown team.');
if (params.amount <= auction.currentBid) {
throw new BadRequestException('Bid must exceed current bid.');
@@ -227,15 +320,14 @@ export class AuctionService {
this.assertTeamHasSlot(team);
// 임시 운영용: 클라이언트에서 선택한 팀장 모드를 신뢰하고 실제 로그인 사용자 검증은 건너뛴다.
await this.recordSnapshot(auction, 'bid', params.bidderUserId);
auction.currentBid = params.amount;
auction.currentBidder = params.side;
auction.currentBidderGroupIndex = params.groupIndex;
auction.currentBidderTeamIndex = params.teamIndex;
auction.currentDeadline = this.createDeadline(
this.resolveBidExtensionSeconds(auction),
);
auction.bids.push({
side: params.side,
groupIndex: params.groupIndex,
teamIndex: params.teamIndex,
amount: params.amount,
bidderUserId: team.captainUserId,
timestamp: new Date(),
@@ -249,13 +341,12 @@ export class AuctionService {
if (auction.phase !== 'bidding') {
throw new BadRequestException('Auction is not in bidding phase.');
}
if (!auction.currentBidder || auction.currentBid <= 0) {
if (!auction.currentBidderTeamIndex || auction.currentBid <= 0) {
throw new BadRequestException('No bid to mark sold.');
}
const team = this.findAuctionTeam(
const team = this.findAuctionTeamByIndex(
auction,
auction.currentBidder,
auction.currentBidderGroupIndex ?? 1,
auction.currentBidderTeamIndex,
);
if (!team) throw new BadRequestException('Winning team not found.');
this.assertTeamHasSlot(team);
@@ -263,6 +354,7 @@ export class AuctionService {
const current = auction.order[auction.currentIndex];
if (!current) throw new BadRequestException('No current player.');
await this.recordSnapshot(auction, 'sold');
const preferredPrimary = current.preferredPositions[0]?.position;
team.members.push({
userId: current.userId,
@@ -276,23 +368,67 @@ export class AuctionService {
return auction;
}
public async markPassed(
matchId: mongoose.Types.ObjectId,
): Promise<AuctionDocument> {
const auction = await this.getByMatchId(matchId);
if (auction.phase !== 'bidding') {
throw new BadRequestException('Auction is not in bidding phase.');
}
if (auction.currentBid > 0) {
throw new BadRequestException('Cannot pass a player with an active bid.');
}
const current = auction.order[auction.currentIndex];
if (!current) throw new BadRequestException('No current player.');
await this.recordSnapshot(auction, 'passed');
current.passCount = (current.passCount ?? 0) + 1;
auction.passedQueue ??= [];
auction.passedQueue.push(this.cloneAuctionPlayerSnapshot(current));
auction.phase = 'passed';
auction.currentDeadline = undefined;
await auction.save();
return auction;
}
public async next(
matchId: mongoose.Types.ObjectId,
): Promise<AuctionDocument> {
const auction = await this.getByMatchId(matchId);
if (auction.phase !== 'sold' && auction.phase !== 'presenting') {
if (
auction.phase !== 'sold' &&
auction.phase !== 'presenting' &&
auction.phase !== 'passed'
) {
throw new BadRequestException('Cannot advance from current phase.');
}
const nextIndex = auction.currentIndex + 1;
const completesAuction =
nextIndex >= auction.order.length &&
(auction.passedQueue?.length ?? 0) === 0;
await this.recordSnapshot(auction, completesAuction ? 'complete' : 'next');
if (nextIndex >= auction.order.length) {
auction.phase = 'complete';
auction.completedAt = new Date();
if ((auction.passedQueue?.length ?? 0) > 0) {
auction.order.push(
...auction.passedQueue.map((player) =>
this.cloneAuctionPlayerSnapshot(player),
),
);
auction.passedQueue = [];
auction.auctionRound = (auction.auctionRound ?? 1) + 1;
auction.currentIndex = nextIndex;
auction.phase = 'presenting';
auction.currentBid = 0;
auction.currentBidderTeamIndex = undefined;
} else {
auction.phase = 'complete';
auction.completedAt = new Date();
}
} else {
auction.currentIndex = nextIndex;
auction.phase = 'presenting';
auction.currentBid = 0;
auction.currentBidder = undefined;
auction.currentBidderGroupIndex = undefined;
auction.currentBidderTeamIndex = undefined;
}
auction.currentDeadline = undefined;
await auction.save();
@@ -307,6 +443,8 @@ export class AuctionService {
communityId: mongoose.Types.ObjectId;
}): Promise<void> {
const AuctionModel = await this.connectionService.getModel('auction');
const AuctionHistoryModel =
await this.connectionService.getModel('auctionHistory');
const MatchModel = await this.connectionService.getModel('match');
const session = await this.connectionService.createSession();
@@ -327,11 +465,15 @@ export class AuctionService {
}
await auction.deleteOne({ session });
await AuctionHistoryModel.deleteMany({ auctionId: auction._id }).session(
session,
);
if (match.status === 'team-built') {
await this.tournamentCodeService.releaseFromMatch(match);
match.status = 'recruiting';
match.teams = [];
match.tournamentCodeIds = [];
match.gameSchedule = [];
match.participants.forEach((participant) => {
participant.excluded = false;
});
@@ -349,6 +491,225 @@ export class AuctionService {
}
}
public async undoTo(params: {
matchId: mongoose.Types.ObjectId;
communityId: mongoose.Types.ObjectId;
sequence: number;
}): Promise<AuctionDocument> {
const AuctionModel = await this.connectionService.getModel('auction');
const AuctionHistoryModel =
await this.connectionService.getModel('auctionHistory');
const MatchModel = await this.connectionService.getModel('match');
const session = await this.connectionService.createSession();
if (!session) {
throw new InternalServerErrorException('Failed to start DB session.');
}
try {
session.startTransaction();
const auction = await AuctionModel.findOne({
matchId: params.matchId,
}).session(session);
if (!auction) throw new NotFoundException('Auction not found.');
const match = await MatchModel.findById(params.matchId).session(session);
if (!match) throw new NotFoundException('Match not found.');
if (!match.communityId.equals(params.communityId)) {
throw new BadRequestException('Community mismatch.');
}
const history = await AuctionHistoryModel.findOne({
auctionId: auction._id,
sequence: params.sequence,
})
.session(session)
.lean()
.exec();
if (!history) throw new NotFoundException('Auction history not found.');
const snapshot = history.snapshotBefore;
if (!snapshot || typeof snapshot !== 'object') {
throw new BadRequestException('Auction history snapshot is invalid.');
}
const undoingCompletedAuction =
Boolean(auction.completedAt) && !('completedAt' in snapshot);
if (undoingCompletedAuction) {
await this.tournamentCodeService.releaseFromMatch(match);
await this.tournamentResultService.cancelPolling(match);
match.status = 'team-built';
match.result = undefined;
await match.save({ session });
}
await AuctionModel.replaceOne({ _id: auction._id }, snapshot, {
session,
}).exec();
await AuctionHistoryModel.deleteMany({
auctionId: auction._id,
sequence: { $gt: params.sequence },
})
.session(session)
.exec();
await session.commitTransaction();
const restored = await AuctionModel.findById(auction._id);
if (!restored) throw new NotFoundException('Auction not found.');
return restored;
} catch (err) {
await session.abortTransaction();
throw err;
} finally {
await session.endSession();
}
}
private applyTopTierPriority(
order: AuctionPlayerSnapshot[],
threshold: AuctionTopTierThreshold,
manualTopTierUserIds: mongoose.Types.ObjectId[],
): AuctionPlayerSnapshot[] {
if (threshold === 'NONE') return order;
if (threshold === 'MANUAL') {
const manualIds = new Set(
manualTopTierUserIds.map((userId) => userId.toString()),
);
if (manualIds.size === 0) return order;
const selected = order.filter((snap) =>
manualIds.has(snap.userId.toString()),
);
const rest = order.filter(
(snap) => !manualIds.has(snap.userId.toString()),
);
return [...selected, ...rest];
}
const ranks = [
'IRON',
'BRONZE',
'SILVER',
'GOLD',
'PLATINUM',
'EMERALD',
'DIAMOND',
'MASTER',
'GRANDMASTER',
'CHALLENGER',
];
const cutoff = ranks.indexOf(threshold);
const score = (snap: AuctionPlayerSnapshot) => {
const solo = snap.tiers.find(
(tier) => tier.queueType === 'RANKED_SOLO_5x5',
);
if (!solo) return -1;
const tierIdx = ranks.indexOf(solo.tier);
if (tierIdx < cutoff) return -1;
const rankBonus =
({ I: 4, II: 3, III: 2, IV: 1, '': 0 } as Record<string, number>)[
solo.rank
] ?? 0;
return tierIdx * 1000 + rankBonus * 100 + (solo.leaguePoints ?? 0) * 0.001;
};
const top = order
.filter((snap) => score(snap) >= 0)
.sort((left, right) => score(right) - score(left));
const rest = order.filter((snap) => score(snap) < 0);
return [...top, ...rest];
}
private shuffleAuctionPlayerOrder(
order: AuctionPlayerSnapshot[],
): AuctionPlayerSnapshot[] {
const shuffled = [...order];
for (let index = shuffled.length - 1; index > 0; index -= 1) {
const swapIndex = Math.floor(Math.random() * (index + 1));
[shuffled[index], shuffled[swapIndex]] = [
shuffled[swapIndex],
shuffled[index],
];
}
return shuffled;
}
private cloneAuctionPlayerSnapshot(
player: AuctionPlayerSnapshot,
): AuctionPlayerSnapshot {
return JSON.parse(JSON.stringify(player)) as AuctionPlayerSnapshot;
}
private normalizeChatMessage(message: string): string {
const normalized = message.trim();
if (!normalized) {
throw new BadRequestException('Chat message is required.');
}
if (Array.from(normalized).length > AUCTION_CHAT_MAX_MESSAGE_LENGTH) {
throw new BadRequestException(
`Chat message must be ${AUCTION_CHAT_MAX_MESSAGE_LENGTH} characters or less.`,
);
}
return normalized;
}
private normalizeChatDisplayName(displayName: string | undefined): string {
const normalized = displayName?.trim() || '관전자';
const chars = Array.from(normalized);
if (chars.length <= AUCTION_CHAT_MAX_DISPLAY_NAME_LENGTH) {
return normalized;
}
return chars.slice(0, AUCTION_CHAT_MAX_DISPLAY_NAME_LENGTH).join('');
}
private async recordSnapshot(
auction: AuctionDocument,
action: AuctionActionType,
actorUserId?: mongoose.Types.ObjectId,
): Promise<void> {
const AuctionHistoryModel =
await this.connectionService.getModel('auctionHistory');
const latest = await AuctionHistoryModel.findOne({ auctionId: auction._id })
.sort({ sequence: -1 })
.select({ sequence: 1 })
.lean()
.exec();
const snapshotBefore =
typeof auction.toObject === 'function'
? auction.toObject({ depopulate: true })
: auction;
await AuctionHistoryModel.create({
auctionId: auction._id,
matchId: auction.matchId,
sequence: (latest?.sequence ?? 0) + 1,
action,
actorUserId,
snapshotBefore: JSON.parse(JSON.stringify(snapshotBefore)),
takenAt: new Date(),
});
}
private formatHistoryActionLabel(action: AuctionActionType): string {
switch (action) {
case 'start':
return '경매 시작';
case 'open-bidding':
return '입찰 열기';
case 'bid':
return '입찰';
case 'sold':
return '낙찰 처리';
case 'passed':
return '유찰';
case 'next':
return '다음 선수';
case 'complete':
return '경매 완료';
default:
return action;
}
}
private applyAuctionCut(match: {
participants: MatchParticipant[];
}): MatchParticipant[] {
@@ -370,18 +731,13 @@ export class AuctionService {
private assertCaptainAssignments(
captains: StartAuctionParams['captains'],
activeParticipants: Array<{ userId: mongoose.Types.ObjectId }>,
groupCount: number,
expectedCaptainCount: number,
): void {
const activeUserIds = new Set(
activeParticipants.map((participant) => participant.userId.toString()),
);
const captainUserIds = new Set<string>();
const teamKeys = new Set<string>();
const requiredKeys = new Set<string>();
for (let groupIndex = 1; groupIndex <= groupCount; groupIndex += 1) {
requiredKeys.add(`blue:${groupIndex}`);
requiredKeys.add(`red:${groupIndex}`);
}
const teamIndexes = new Set<number>();
for (const captain of captains) {
const userId = captain.userId.toString();
@@ -395,31 +751,31 @@ export class AuctionService {
}
captainUserIds.add(userId);
if (captain.groupIndex < 1 || captain.groupIndex > groupCount) {
throw new BadRequestException('Captain groupIndex is out of range.');
if (
!Number.isInteger(captain.teamIndex) ||
captain.teamIndex < 1 ||
captain.teamIndex > expectedCaptainCount
) {
throw new BadRequestException('Captain teamIndex is out of range.');
}
const key = `${captain.side}:${captain.groupIndex}`;
if (teamKeys.has(key)) {
if (teamIndexes.has(captain.teamIndex)) {
throw new BadRequestException('Duplicate captain team assignment.');
}
teamKeys.add(key);
teamIndexes.add(captain.teamIndex);
}
for (const key of requiredKeys) {
if (!teamKeys.has(key)) {
throw new BadRequestException('Each group needs one blue and one red captain.');
for (let teamIndex = 1; teamIndex <= expectedCaptainCount; teamIndex += 1) {
if (!teamIndexes.has(teamIndex)) {
throw new BadRequestException('Each teamIndex needs one captain.');
}
}
}
private findAuctionTeam(
private findAuctionTeamByIndex(
auction: AuctionDocument,
side: TeamSide,
groupIndex: number,
teamIndex: number,
): AuctionTeam | undefined {
return auction.teams.find(
(team) => team.side === side && (team.groupIndex ?? 1) === groupIndex,
);
return auction.teams.find((team) => team.teamIndex === teamIndex);
}
private createDeadline(secondsFromNow: number): Date {
@@ -427,14 +783,24 @@ export class AuctionService {
}
private resolveBidExtensionSeconds(auction: AuctionDocument): number {
const maxTimerSeconds = Math.max(5, auction.maxTimerSeconds ?? 30);
const bidExtensionSeconds = Math.max(0, auction.bidExtensionSeconds ?? 5);
const minimumRemainingSeconds = Math.min(
maxTimerSeconds,
bidExtensionSeconds,
);
if (!auction.currentDeadline) {
return auction.maxTimerSeconds;
return maxTimerSeconds;
}
const remainingSeconds = Math.ceil(
(auction.currentDeadline.getTime() - Date.now()) / 1000,
);
return Math.max(5, remainingSeconds);
return Math.min(
maxTimerSeconds,
Math.max(minimumRemainingSeconds, remainingSeconds),
);
}
private assertTeamHasSlot(team: AuctionTeam): void {
@@ -483,9 +849,8 @@ export class AuctionService {
];
return {
side: team.side,
groupIndex: team.groupIndex ?? 1,
name: this.resolveTeamName(team.side, team.groupIndex ?? 1, auction.teams),
teamIndex: team.teamIndex,
name: this.resolveTeamName(team.teamIndex),
captainUserId: team.captainUserId,
members,
};
@@ -497,14 +862,103 @@ export class AuctionService {
await this.tournamentResultService.scheduleInitialPoll(match);
}
private resolveTeamName(
side: TeamSide,
groupIndex: number,
teams: AuctionTeam[],
): string {
const groupCount = new Set(teams.map((team) => team.groupIndex ?? 1)).size;
const sideLabel = side === 'blue' ? '블루팀' : '레드팀';
return groupCount <= 1 ? sideLabel : `${groupIndex}조 ${sideLabel}`;
private enqueueBackgroundOrderEnrichment(params: {
auctionId: mongoose.Types.ObjectId;
targets: AuctionEnrichmentTarget[];
platform: RiotPlatformRoute;
region: RiotRegionalRoute;
}): void {
if (params.targets.length === 0) return;
// 경매 시작 UX를 막지 않도록 Riot 최신화는 뒤에서 1명씩 천천히 수행한다.
void this.refreshOrderSnapshotsFromRiot(params).catch((error: unknown) => {
this.logger.warn(
`Auction background Riot refresh failed for ${params.auctionId.toString()}: ${
error instanceof Error ? error.message : error
}`,
);
});
}
private async refreshOrderSnapshotsFromRiot(params: {
auctionId: mongoose.Types.ObjectId;
targets: AuctionEnrichmentTarget[];
platform: RiotPlatformRoute;
region: RiotRegionalRoute;
}): Promise<void> {
const AuctionModel = await this.connectionService.getModel('auction');
this.logger.debug(
`Refreshing Riot snapshots for ${params.targets.length} auction players in background.`,
);
await runWithConcurrency(
params.targets,
AUCTION_BACKGROUND_ENRICHMENT_CONCURRENCY,
async (target) => {
try {
const result = await this.enrichmentService.enrichRiotAccount({
userId: target.userId,
puuid: target.puuid,
options: {
force: false,
platform: params.platform,
region: params.region,
},
});
const account = result.account;
if (!account) return;
await AuctionModel.updateOne(
{
_id: params.auctionId,
'order.userId': target.userId,
},
{
$set: {
'order.$.gameName': account.gameName,
'order.$.tagLine': account.tagLine,
'order.$.profileIconId': account.profileIconId,
'order.$.tiers': account.tiers,
'order.$.tierHistory': account.tierHistory ?? [],
'order.$.masteries': account.championMasteries,
'order.$.recentStatsSummary': account.recentStatsSummary,
updatedAt: new Date(),
},
},
).exec();
} catch (error: unknown) {
this.logger.warn(
`Failed to refresh auction Riot snapshot for ${target.puuid}: ${
error instanceof Error ? error.message : error
}`,
);
}
},
);
}
private wasRecentlyRefreshed(account: RiotAccount, cutoff: number): boolean {
return this.getLatestRefreshAt(account) >= cutoff;
}
private getLatestRefreshAt(account: RiotAccount): number {
const timestamps = [
account.lastRefreshRequestedAt,
account.recentStatsFetchedAt,
account.championMasteriesFetchedAt,
account.matchIdsFetchedAt,
...account.tiers.map((tier) => tier.fetchedAt),
];
return timestamps.reduce((latest, value) => {
const timestamp = value instanceof Date ? value.getTime() : 0;
return Math.max(latest, timestamp);
}, 0);
}
private resolveTeamName(teamIndex: number): string {
return `${teamIndex}팀`;
}
}
+37 -14
View File
@@ -7,23 +7,28 @@ import {
IsInt,
IsMongoId,
IsOptional,
Max,
Min,
ValidateNested,
} from 'class-validator';
import { TEAM_SIDES } from '../../global/database/schema';
import type { TeamSide } from '../../global/database/schema';
import { AUCTION_TOP_TIER_THRESHOLDS } from '../../global/database/schema';
export type AuctionTopTierThreshold =
(typeof AUCTION_TOP_TIER_THRESHOLDS)[number];
class CaptainAssignmentDto {
@IsEnum(TEAM_SIDES)
side!: TeamSide;
@IsOptional()
@IsInt()
@Min(1)
groupIndex?: number;
teamIndex!: number;
@IsMongoId()
userId!: string;
@IsOptional()
@IsInt()
@Min(100)
@Max(100000)
initialPoints?: number;
}
export class StartAuctionDto {
@@ -36,23 +41,35 @@ export class StartAuctionDto {
@IsOptional()
@IsInt()
@Min(1)
@Min(100)
@Max(100000)
initialPoints?: number;
@IsOptional()
@IsEnum(AUCTION_TOP_TIER_THRESHOLDS)
topTierThreshold?: AuctionTopTierThreshold;
@IsOptional()
@IsArray()
@ArrayMaxSize(100)
@IsMongoId({ each: true })
manualTopTierUserIds?: string[];
@IsOptional()
@IsInt()
@Min(5)
maxTimerSeconds?: number;
}
export class PlaceBidDto {
@IsEnum(TEAM_SIDES)
side!: TeamSide;
@IsOptional()
@IsInt()
@Min(0)
bidExtensionSeconds?: number;
}
export class PlaceBidDto {
@IsInt()
@Min(1)
groupIndex?: number;
teamIndex!: number;
@IsInt()
@Min(1)
@@ -68,3 +85,9 @@ export class SoldDto {
@IsEnum(['TOP', 'JGL', 'MID', 'ADC', 'SUP'])
assignedPosition?: 'TOP' | 'JGL' | 'MID' | 'ADC' | 'SUP';
}
export class UndoAuctionDto {
@IsInt()
@Min(1)
sequence!: number;
}
@@ -1,7 +1,7 @@
import { Injectable, Logger } from '@nestjs/common';
import { GarnetService } from '../global/garnet/garnet.service';
const COMMUNITY_STATS_TTL_SECONDS = 60 * 60;
const COMMUNITY_STATS_TTL_SECONDS = 5 * 60;
const COMMUNITY_STATS_DETAIL_TTL_SECONDS = 24 * 60 * 60;
@Injectable()
@@ -2,10 +2,19 @@ import { Module } from '@nestjs/common';
import { CommunityStatsCacheService } from './community-stats-cache.service';
import { CommunityStatsController } from './community-stats.controller';
import { CommunityStatsService } from './community-stats.service';
import { MatchStatsFragmentBuilder } from './match-stats-fragment.builder';
import { MatchStatsRepository } from './match-stats.repository';
import { MatchStatsService } from './match-stats.service';
@Module({
controllers: [CommunityStatsController],
providers: [CommunityStatsService, CommunityStatsCacheService],
exports: [CommunityStatsService],
providers: [
CommunityStatsService,
CommunityStatsCacheService,
MatchStatsFragmentBuilder,
MatchStatsRepository,
MatchStatsService,
],
exports: [CommunityStatsService, MatchStatsService],
})
export class CommunityStatsModule {}
File diff suppressed because it is too large. Load diff
@@ -22,17 +22,25 @@ export interface InternalMatchCardView {
scheduledAt: string;
status: 'finished' | 'in-progress';
gameCount: number;
blueScore: number;
redScore: number;
winnerSide?: TeamSide;
winnerTeamIndex?: number;
seriesResults: Array<{
teamAIndex: number;
teamBIndex: number;
teamAWins: number;
teamBWins: number;
winnerTeamIndex?: number;
}>;
games: Array<{
gameNumber: number;
riotMatchId: string | null;
blueTeamIndex: number;
redTeamIndex: number;
winnerTeamIndex: number | null;
winnerSide: TeamSide | null;
gameDuration: number;
}>;
teams: Array<{
side: TeamSide;
teamIndex: number;
name: string;
members: Array<{
userId: string;
@@ -101,12 +109,14 @@ export interface InternalMatchDetailResponse {
gameCreation: number;
gameDuration: number;
teams: Array<{
teamIndex: number;
side: TeamSide;
win: boolean;
objectives: { baron: number; dragon: number; tower: number };
participants: Array<{
userId: string | null;
summonerName: string;
teamIndex: number;
side: TeamSide;
teamPosition: string;
championId: number;
@@ -0,0 +1,98 @@
import mongoose from 'mongoose';
import type { MatchDocument } from '../global/database/schema';
import { MatchStatsFragmentBuilder } from './match-stats-fragment.builder';
function makeMatch(): MatchDocument {
const userId = new mongoose.Types.ObjectId();
return {
_id: new mongoose.Types.ObjectId(),
communityId: new mongoose.Types.ObjectId(),
title: '내전',
scheduledAt: new Date('2026-05-03T00:00:00.000Z'),
status: 'finished',
gameCount: 1,
participants: [
{
userId,
puuid: 'puuid-1',
gameName: 'Player',
profileIconId: 7,
},
],
teams: [
{
teamIndex: 1,
name: 'A',
members: [{ userId, assignedPosition: 'TOP' }],
},
{ teamIndex: 2, name: 'B', members: [] },
],
result: {
winnerTeamIndex: 1,
riotMatchIds: ['KR_1'],
games: [
{
gameNumber: 1,
riotMatchId: 'KR_1',
blueTeamIndex: 1,
redTeamIndex: 2,
winnerTeamIndex: 1,
winnerSide: 'blue',
gameCreation: 1_000,
gameDuration: 1_800,
participants: [
{
userId,
teamIndex: 1,
side: 'blue',
championId: 266,
kills: 5,
deaths: 1,
assists: 7,
win: true,
},
],
},
],
seriesResults: [
{
teamAIndex: 1,
teamBIndex: 2,
teamAWins: 1,
teamBWins: 0,
winnerTeamIndex: 1,
},
],
},
} as unknown as MatchDocument;
}
describe('MatchStatsFragmentBuilder', () => {
it('builds a fallback fragment without raw Riot match data', () => {
const builder = new MatchStatsFragmentBuilder();
const match = makeMatch();
const fragment = builder.buildFragment({
match,
rawByRiotMatchId: new Map(),
});
expect(fragment.matchCard.matchId).toBe(match._id.toString());
expect(fragment.gameCreationMin).toBe(1_000);
expect(fragment.gameCreationMax).toBe(1_000);
expect(fragment.userIds.map((id) => id.toString())).toEqual([
match.participants[0].userId.toString(),
]);
expect(fragment.championIds).toEqual([266]);
expect(fragment.records).toHaveLength(1);
expect(fragment.records[0]).toMatchObject({
summonerName: 'Player',
championId: 266,
kills: 5,
deaths: 1,
assists: 7,
win: true,
});
expect(fragment.gameDetails[0].teams[0].participants).toHaveLength(1);
});
});
@@ -0,0 +1,367 @@
import { Injectable } from '@nestjs/common';
import mongoose from 'mongoose';
import type {
MatchDocument,
MatchGameResultParticipant,
TeamSide,
} from '../global/database/schema';
import type { RiotMatchDto, RiotMatchParticipantDto } from '../riot/riot.types';
import type { InternalMatchCardView } from './community-stats.types';
import type {
InternalGameDetail,
InternalRecord,
MatchStatsFragment,
} from './match-stats.types';
@Injectable()
export class MatchStatsFragmentBuilder {
public buildFragment(params: {
match: MatchDocument;
rawByRiotMatchId: Map<string, RiotMatchDto>;
}): MatchStatsFragment {
const games = [...(params.match.result?.games ?? [])].sort(
(left, right) => left.gameNumber - right.gameNumber,
);
const matchCard = this.toMatchCard(params.match, games);
const gameDetails = games.map((game) => {
const raw = params.rawByRiotMatchId.get(game.riotMatchId);
return raw
? this.toGameDetail(params.match, game, raw)
: this.toFallbackGameDetail(params.match, game);
});
const records = gameDetails.flatMap((detail) =>
detail.teams.flatMap((team) => team.participants),
);
const gameCreations = gameDetails.map((detail) => detail.gameCreation);
return {
matchCard,
records,
gameDetails,
userIds: [
...new Map(
records
.filter((record) => mongoose.isValidObjectId(record.userId))
.map((record) => [
record.userId,
new mongoose.Types.ObjectId(record.userId),
]),
).values(),
],
championIds: [...new Set(records.map((record) => record.championId))],
gameCreationMin:
gameCreations.length > 0
? Math.min(...gameCreations)
: params.match.scheduledAt.getTime(),
gameCreationMax:
gameCreations.length > 0
? Math.max(...gameCreations)
: params.match.scheduledAt.getTime(),
};
}
private toMatchCard(
match: MatchDocument,
games: NonNullable<MatchDocument['result']>['games'],
): InternalMatchCardView {
const participantById = new Map(
match.participants.map((participant) => [
participant.userId.toString(),
participant,
]),
);
return {
matchId: match._id.toString(),
title: match.title,
scheduledAt: match.scheduledAt.toISOString(),
status: match.status === 'finished' ? 'finished' : 'in-progress',
gameCount: match.gameCount,
winnerTeamIndex: match.result?.winnerTeamIndex,
seriesResults: match.result?.seriesResults ?? [],
games: games.map((game) => ({
gameNumber: game.gameNumber,
riotMatchId: game.riotMatchId ?? null,
blueTeamIndex: game.blueTeamIndex,
redTeamIndex: game.redTeamIndex,
winnerTeamIndex: game.winnerTeamIndex ?? null,
winnerSide: game.winnerSide ?? null,
gameDuration: game.gameDuration,
})),
teams: match.teams.map((team) => ({
teamIndex: team.teamIndex,
name: team.name,
members: team.members.map((member) => {
const participant = participantById.get(member.userId.toString());
return {
userId: member.userId.toString(),
summonerName: participant?.gameName ?? 'Unknown',
profileIconId: participant?.profileIconId ?? 0,
};
}),
})),
};
}
private toGameDetail(
match: MatchDocument,
game: NonNullable<MatchDocument['result']>['games'][number],
raw: RiotMatchDto,
): InternalGameDetail {
const puuidByUserId = new Map(
match.participants
.filter((participant) => participant.puuid)
.map((participant) => [
participant.userId.toString(),
participant.puuid as string,
]),
);
const rawByPuuid = new Map(
raw.info.participants.map((participant) => [
participant.puuid,
participant,
]),
);
const rawTeamIdBySide = new Map<TeamSide, number>();
for (const participant of game.participants) {
const puuid = puuidByUserId.get(participant.userId.toString());
const rawParticipant = puuid ? rawByPuuid.get(puuid) : undefined;
if (rawParticipant) {
rawTeamIdBySide.set(participant.side, rawParticipant.teamId);
}
}
return {
gameNumber: game.gameNumber,
riotMatchId: game.riotMatchId,
gameCreation: game.gameCreation,
gameDuration: game.gameDuration,
winnerSide: game.winnerSide,
teams: (['blue', 'red'] as TeamSide[]).map((side) => {
const teamIndex =
side === 'blue' ? game.blueTeamIndex : game.redTeamIndex;
const rawTeamId = rawTeamIdBySide.get(side);
const rawTeam = raw.info.teams.find(
(team) => team.teamId === rawTeamId,
);
const teamRawParticipants = raw.info.participants.filter(
(participant) => participant.teamId === rawTeamId,
);
const teamKills = teamRawParticipants.reduce(
(sum, participant) => sum + participant.kills,
0,
);
const teamDamage = teamRawParticipants.reduce(
(sum, participant) => sum + participant.totalDamageDealtToChampions,
0,
);
return {
teamIndex,
side,
win: game.winnerSide === side,
objectives: {
baron: rawTeam?.objectives?.baron?.kills ?? 0,
dragon: rawTeam?.objectives?.dragon?.kills ?? 0,
tower: rawTeam?.objectives?.tower?.kills ?? 0,
},
participants: game.participants
.filter((participant) => participant.side === side)
.map((participant) =>
this.toRecord({
match,
game,
participant,
rawParticipant: rawByPuuid.get(
puuidByUserId.get(participant.userId.toString()) ?? '',
),
teamKills,
teamDamage,
}),
),
};
}),
};
}
private toFallbackGameDetail(
match: MatchDocument,
game: NonNullable<MatchDocument['result']>['games'][number],
): InternalGameDetail {
return {
gameNumber: game.gameNumber,
riotMatchId: game.riotMatchId,
gameCreation: game.gameCreation,
gameDuration: game.gameDuration,
winnerSide: game.winnerSide,
teams: (['blue', 'red'] as TeamSide[]).map((side) => ({
teamIndex: side === 'blue' ? game.blueTeamIndex : game.redTeamIndex,
side,
win: game.winnerSide === side,
objectives: { baron: 0, dragon: 0, tower: 0 },
participants: game.participants
.filter((participant) => participant.side === side)
.map((participant) =>
this.toRecord({
match,
game,
participant,
teamKills: 0,
teamDamage: 0,
}),
),
})),
};
}
private toRecord(params: {
match: MatchDocument;
game: NonNullable<MatchDocument['result']>['games'][number];
participant: MatchGameResultParticipant;
rawParticipant?: RiotMatchParticipantDto;
teamKills: number;
teamDamage: number;
}): InternalRecord {
const { match, game, participant, rawParticipant, teamKills, teamDamage } =
params;
const snapshot = match.participants.find((item) =>
item.userId.equals(participant.userId),
);
const minutes = Math.max(
(rawParticipant?.timePlayed ?? game.gameDuration) / 60,
1,
);
const cs = rawParticipant
? rawParticipant.totalMinionsKilled + rawParticipant.neutralMinionsKilled
: 0;
const damage = rawParticipant?.totalDamageDealtToChampions ?? 0;
const killParticipation = percent(
participant.kills + participant.assists,
teamKills,
);
const damageShare = percent(damage, teamDamage);
const rating = this.resolveRating({
kills: participant.kills,
deaths: participant.deaths,
assists: participant.assists,
killParticipation,
csPerMin: average(cs, minutes),
damageShare,
visionPerMin: average(rawParticipant?.visionScore ?? 0, minutes),
});
return {
matchId: match._id.toString(),
title: match.title,
scheduledAt: match.scheduledAt,
gameNumber: game.gameNumber,
riotMatchId: game.riotMatchId,
gameCreation: game.gameCreation,
gameDuration: game.gameDuration,
userId: participant.userId.toString(),
summonerName:
snapshot?.gameName ??
rawParticipant?.riotIdGameName ??
rawParticipant?.summonerName ??
'Unknown',
profileIconId: snapshot?.profileIconId ?? 0,
teamIndex: participant.teamIndex,
side: participant.side,
championId: participant.championId,
championLevel: rawParticipant?.champLevel ?? 0,
teamPosition:
rawParticipant?.teamPosition ||
rawParticipant?.individualPosition ||
'',
kills: participant.kills,
deaths: participant.deaths,
assists: participant.assists,
win: participant.win,
cs,
csPerMin: average(cs, minutes),
gold: rawParticipant?.goldEarned ?? 0,
gpm: average(rawParticipant?.goldEarned ?? 0, minutes),
damageDealtToChampions: damage,
damageTaken: rawParticipant?.totalDamageTaken ?? 0,
damageShare,
killParticipation,
visionScore: rawParticipant?.visionScore ?? 0,
controlWardsBought: numberField(
rawParticipant,
'visionWardsBoughtInGame',
),
wardsPlaced: rawParticipant?.wardsPlaced ?? 0,
wardsKilled: rawParticipant?.wardsKilled ?? 0,
items: [
rawParticipant?.item0 ?? 0,
rawParticipant?.item1 ?? 0,
rawParticipant?.item2 ?? 0,
rawParticipant?.item3 ?? 0,
rawParticipant?.item4 ?? 0,
rawParticipant?.item5 ?? 0,
],
trinket: rawParticipant?.item6 ?? 0,
summonerSpells: [
rawParticipant?.summoner1Id ?? 0,
rawParticipant?.summoner2Id ?? 0,
],
perks: rawParticipant ? this.resolvePerks(rawParticipant) : {},
rating,
};
}
private resolvePerks(participant: RiotMatchParticipantDto) {
const primary = participant.perks.styles.find(
(style) => style.description === 'primaryStyle',
);
const sub = participant.perks.styles.find(
(style) => style.description === 'subStyle',
);
return {
primaryStyle: primary?.style,
subStyle: sub?.style,
keystone: primary?.selections[0]?.perk,
};
}
private resolveRating(params: {
kills: number;
deaths: number;
assists: number;
killParticipation: number;
csPerMin: number;
damageShare: number;
visionPerMin: number;
}): number {
const kdaScore = kda(params.kills, params.deaths, params.assists);
const score =
Math.min(kdaScore / 6, 1) * 4 +
Math.min(params.killParticipation / 100, 1) * 2 +
Math.min(params.csPerMin / 9, 1) * 2 +
Math.min(params.damageShare / 35, 1) +
Math.min(params.visionPerMin / 2, 1);
return round(score);
}
}
function kda(kills: number, deaths: number, assists: number): number {
return deaths === 0 ? kills + assists : round((kills + assists) / deaths);
}
function percent(value: number, total: number): number {
return total > 0 ? Math.round((value / total) * 100) : 0;
}
function average(value: number, total: number): number {
return total > 0 ? round(value / total) : 0;
}
function round(value: number): number {
return Math.round(value * 10) / 10;
}
function numberField(
participant: RiotMatchParticipantDto | undefined,
key: string,
): number {
const value = participant?.[key];
return typeof value === 'number' && Number.isFinite(value) ? value : 0;
}
@@ -0,0 +1,84 @@
import { Injectable } from '@nestjs/common';
import mongoose from 'mongoose';
import { ConnectionService } from '../global/database/connection.service';
import type { MatchStats, MatchStatsDocument } from '../global/database/schema';
@Injectable()
export class MatchStatsRepository {
constructor(private readonly connectionService: ConnectionService) {}
public async upsert(
fragment: Omit<MatchStats, 'createdAt' | 'updatedAt'>,
): Promise<void> {
const MatchStatsModel = await this.connectionService.getModel('matchStats');
await MatchStatsModel.updateOne(
{ matchId: fragment.matchId },
{ $set: fragment },
{ upsert: true },
).exec();
}
public async deleteByMatch(matchId: mongoose.Types.ObjectId): Promise<void> {
const MatchStatsModel = await this.connectionService.getModel('matchStats');
await MatchStatsModel.deleteOne({ matchId }).exec();
}
public async deleteByMatches(
matchIds: mongoose.Types.ObjectId[],
): Promise<void> {
if (matchIds.length === 0) return;
const MatchStatsModel = await this.connectionService.getModel('matchStats');
await MatchStatsModel.deleteMany({ matchId: { $in: matchIds } }).exec();
}
public async findByMatch(
matchId: mongoose.Types.ObjectId,
): Promise<MatchStatsDocument | null> {
const MatchStatsModel = await this.connectionService.getModel('matchStats');
return MatchStatsModel.findOne({ matchId }).exec();
}
public async findByCommunity(params: {
communityId: mongoose.Types.ObjectId;
fromGameCreation?: number;
toGameCreation?: number;
limit?: number;
}): Promise<MatchStatsDocument[]> {
const MatchStatsModel = await this.connectionService.getModel('matchStats');
const filter: Record<string, unknown> = {
communityId: params.communityId,
};
if (params.fromGameCreation !== undefined) {
filter.gameCreationMax = { $gte: params.fromGameCreation };
}
if (params.toGameCreation !== undefined) {
filter.gameCreationMin = { $lte: params.toGameCreation };
}
return MatchStatsModel.find(filter)
.sort({ scheduledAt: -1 })
.limit(params.limit ?? 300)
.exec();
}
public async findByUser(params: {
communityId: mongoose.Types.ObjectId;
userId: mongoose.Types.ObjectId;
fromGameCreation?: number;
toGameCreation?: number;
}): Promise<MatchStatsDocument[]> {
const MatchStatsModel = await this.connectionService.getModel('matchStats');
const filter: Record<string, unknown> = {
communityId: params.communityId,
userIds: params.userId,
};
if (params.fromGameCreation !== undefined) {
filter.gameCreationMax = { $gte: params.fromGameCreation };
}
if (params.toGameCreation !== undefined) {
filter.gameCreationMin = { $lte: params.toGameCreation };
}
return MatchStatsModel.find(filter).sort({ scheduledAt: -1 }).exec();
}
}
@@ -0,0 +1,104 @@
import mongoose from 'mongoose';
import { ConnectionService } from '../global/database/connection.service';
import { MatchStatsFragmentBuilder } from './match-stats-fragment.builder';
import { MatchStatsRepository } from './match-stats.repository';
import { MatchStatsService } from './match-stats.service';
describe('MatchStatsService', () => {
it('deletes an existing fragment when the match is no longer eligible', async () => {
const matchId = new mongoose.Types.ObjectId();
const findById = jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue({
_id: matchId,
status: 'recruiting',
result: undefined,
}),
});
const connectionService = {
getModel: jest.fn().mockImplementation(async (name: string) => {
if (name === 'match') return { findById };
if (name === 'riotMatch') return {};
throw new Error(`Unexpected model: ${name}`);
}),
} as unknown as ConnectionService;
const repository = {
deleteByMatch: jest.fn().mockResolvedValue(undefined),
upsert: jest.fn(),
} as unknown as jest.Mocked<MatchStatsRepository>;
const service = new MatchStatsService(
connectionService,
repository,
{} as MatchStatsFragmentBuilder,
);
await service.buildAndUpsert(matchId);
expect(repository.deleteByMatch).toHaveBeenCalledWith(matchId);
expect(repository.upsert).not.toHaveBeenCalled();
});
it('upserts a fragment for eligible matches', async () => {
const matchId = new mongoose.Types.ObjectId();
const communityId = new mongoose.Types.ObjectId();
const scheduledAt = new Date('2026-05-03T00:00:00.000Z');
const match = {
_id: matchId,
communityId,
scheduledAt,
status: 'finished',
result: { games: [{ riotMatchId: 'KR_1' }] },
};
const findById = jest.fn().mockReturnValue({
exec: jest.fn().mockResolvedValue(match),
});
const riotFind = jest.fn().mockReturnValue({
lean: () => ({
exec: jest.fn().mockResolvedValue([{ matchId: 'KR_1', raw: {} }]),
}),
});
const connectionService = {
getModel: jest.fn().mockImplementation(async (name: string) => {
if (name === 'match') return { findById };
if (name === 'riotMatch') return { find: riotFind };
throw new Error(`Unexpected model: ${name}`);
}),
} as unknown as ConnectionService;
const repository = {
upsert: jest.fn().mockResolvedValue(undefined),
deleteByMatch: jest.fn(),
} as unknown as jest.Mocked<MatchStatsRepository>;
const builder = {
buildFragment: jest.fn().mockReturnValue({
matchCard: { matchId: matchId.toString() },
records: [],
gameDetails: [],
userIds: [],
championIds: [],
gameCreationMin: 1_000,
gameCreationMax: 2_000,
}),
} as unknown as jest.Mocked<MatchStatsFragmentBuilder>;
const service = new MatchStatsService(
connectionService,
repository,
builder,
);
await service.buildAndUpsert(matchId);
expect(builder.buildFragment).toHaveBeenCalledWith({
match,
rawByRiotMatchId: expect.any(Map),
});
expect(repository.upsert).toHaveBeenCalledWith(
expect.objectContaining({
matchId,
communityId,
scheduledAt,
gameCreationMin: 1_000,
gameCreationMax: 2_000,
builderVersion: 1,
}),
);
});
});
@@ -0,0 +1,104 @@
import { Injectable } from '@nestjs/common';
import mongoose from 'mongoose';
import { ConnectionService } from '../global/database/connection.service';
import type { MatchDocument } from '../global/database/schema';
import type { RiotMatchDto } from '../riot/riot.types';
import { MatchStatsFragmentBuilder } from './match-stats-fragment.builder';
import { MatchStatsRepository } from './match-stats.repository';
import { MATCH_STATS_BUILDER_VERSION } from './match-stats.types';
@Injectable()
export class MatchStatsService {
constructor(
private readonly connectionService: ConnectionService,
private readonly repository: MatchStatsRepository,
private readonly builder: MatchStatsFragmentBuilder,
) {}
public async buildAndUpsert(matchId: mongoose.Types.ObjectId): Promise<void> {
const MatchModel = await this.connectionService.getModel('match');
const RiotMatchModel = await this.connectionService.getModel('riotMatch');
const match = await MatchModel.findById(matchId).exec();
if (!match) return;
if (!this.isEligible(match)) {
await this.repository.deleteByMatch(matchId);
return;
}
const riotIds = [
...new Set(
(match.result?.games ?? [])
.map((game) => game.riotMatchId)
.filter((riotMatchId): riotMatchId is string => Boolean(riotMatchId)),
),
];
const riotDocs =
riotIds.length > 0
? await RiotMatchModel.find({ matchId: { $in: riotIds } })
.lean()
.exec()
: [];
const rawByRiotMatchId = new Map(
riotDocs.map((doc) => [doc.matchId, doc.raw as unknown as RiotMatchDto]),
);
const fragment = this.builder.buildFragment({ match, rawByRiotMatchId });
await this.repository.upsert({
matchId: match._id,
communityId: match.communityId,
scheduledAt: match.scheduledAt,
gameCreationMin: fragment.gameCreationMin,
gameCreationMax: fragment.gameCreationMax,
userIds: fragment.userIds,
championIds: fragment.championIds,
matchCard: fragment.matchCard as unknown as Record<string, unknown>,
records: fragment.records,
gameDetails: fragment.gameDetails,
builtAt: new Date(),
builderVersion: MATCH_STATS_BUILDER_VERSION,
});
}
public async removeByMatch(matchId: mongoose.Types.ObjectId): Promise<void> {
await this.repository.deleteByMatch(matchId);
}
public async removeByMatches(
matchIds: mongoose.Types.ObjectId[],
): Promise<void> {
await this.repository.deleteByMatches(matchIds);
}
public async backfillCommunity(
communityId: mongoose.Types.ObjectId,
): Promise<{ processed: number; failed: number }> {
const MatchModel = await this.connectionService.getModel('match');
const matches = await MatchModel.find({
communityId,
status: { $in: ['finished', 'in-progress'] },
'result.games.0': { $exists: true },
})
.sort({ scheduledAt: -1 })
.select({ _id: 1 })
.exec();
let processed = 0;
let failed = 0;
for (const match of matches) {
try {
await this.buildAndUpsert(match._id);
processed += 1;
} catch {
failed += 1;
}
}
return { processed, failed };
}
private isEligible(match: MatchDocument): boolean {
return (
(match.status === 'finished' || match.status === 'in-progress') &&
Boolean(match.result?.games?.length)
);
}
}
@@ -0,0 +1,20 @@
import type {
MatchStatsGameDetail,
MatchStatsRecord,
} from '../global/database/schema';
import type { InternalMatchCardView } from './community-stats.types';
export const MATCH_STATS_BUILDER_VERSION = 1;
export type InternalRecord = MatchStatsRecord;
export type InternalGameDetail = MatchStatsGameDetail;
export interface MatchStatsFragment {
matchCard: InternalMatchCardView;
records: InternalRecord[];
gameDetails: InternalGameDetail[];
userIds: import('mongoose').Types.ObjectId[];
championIds: number[];
gameCreationMin: number;
gameCreationMax: number;
}
@@ -0,0 +1,123 @@
import { Injectable } from '@nestjs/common';
import { ConnectionService } from '../global/database/connection.service';
const DEFAULT_LEASE_MS = 5 * 60 * 1000;
export type DakaoInboxClaimResult =
| { status: 'claimed' }
| { status: 'duplicate' }
| { status: 'inflight' };
@Injectable()
export class DakaoInboxService {
constructor(private readonly connectionService: ConnectionService) {}
public async claim(params: {
consumer: string;
projectId: string;
chatLogLogId: string;
leaseMs?: number;
}): Promise<DakaoInboxClaimResult> {
const Model = await this.connectionService.getModel('dakaoInboundMessage');
const now = new Date();
const processingExpiresAt = new Date(
now.getTime() + (params.leaseMs ?? DEFAULT_LEASE_MS),
);
try {
await Model.create({
consumer: params.consumer,
projectId: params.projectId,
chatLogLogId: params.chatLogLogId,
state: 'processing',
attempts: 1,
processingExpiresAt,
});
return { status: 'claimed' };
} catch (err) {
if ((err as { code?: number })?.code !== 11000) throw err;
}
const existing = await Model.findOne({
consumer: params.consumer,
projectId: params.projectId,
chatLogLogId: params.chatLogLogId,
})
.lean()
.exec();
if (!existing) return { status: 'inflight' };
if (existing.state === 'processed') return { status: 'duplicate' };
if (
existing.state === 'processing' &&
existing.processingExpiresAt &&
existing.processingExpiresAt > now
) {
return { status: 'inflight' };
}
const updated = await Model.updateOne(
{
_id: existing._id,
$or: [
{ state: 'failed' },
{ state: 'processing', processingExpiresAt: { $lte: now } },
],
},
{
$set: {
state: 'processing',
processingExpiresAt,
},
$inc: { attempts: 1 },
},
).exec();
return updated.modifiedCount > 0
? { status: 'claimed' }
: { status: 'inflight' };
}
public async markProcessed(params: {
consumer: string;
projectId: string;
chatLogLogId: string;
}): Promise<void> {
const Model = await this.connectionService.getModel('dakaoInboundMessage');
await Model.updateOne(
{
consumer: params.consumer,
projectId: params.projectId,
chatLogLogId: params.chatLogLogId,
},
{
$set: {
state: 'processed',
processedAt: new Date(),
},
$unset: { processingExpiresAt: '', lastError: '' },
},
).exec();
}
public async markFailed(params: {
consumer: string;
projectId: string;
chatLogLogId: string;
error: unknown;
}): Promise<void> {
const Model = await this.connectionService.getModel('dakaoInboundMessage');
await Model.updateOne(
{
consumer: params.consumer,
projectId: params.projectId,
chatLogLogId: params.chatLogLogId,
},
{
$set: {
state: 'failed',
lastError: (params.error as Error)?.message ?? String(params.error),
},
$unset: { processingExpiresAt: '' },
},
).exec();
}
}
@@ -0,0 +1,64 @@
import { Injectable } from '@nestjs/common';
import { NatsService } from '../global/nats/nats.service';
import { resolveDakaoNatsNames } from './dakao.nats-names';
@Injectable()
export class DakaoJetStreamResourceService {
private ensurePromise: Promise<void> | null = null;
constructor(private readonly natsService: NatsService) {}
public async ensure(): Promise<void> {
this.ensurePromise ??= this.ensureInternal();
await this.ensurePromise;
}
private async ensureInternal(): Promise<void> {
const names = resolveDakaoNatsNames();
await this.natsService.ensureJetStreamStream({
name: names.streams.botCommand,
subjects: [names.subjects.botCommandSubmitted],
retention: 'workqueue',
replicas: 1,
});
await this.natsService.ensureJetStreamConsumer({
stream: names.streams.botCommand,
durable: names.consumers.botCommand,
filterSubject: names.subjects.botCommandSubmitted,
description: 'LolyMpus Dakao bot command handler',
replicas: 1,
});
await this.natsService.ensureJetStreamStream({
name: names.streams.sendRequest,
subjects: [names.subjects.chatSendMessage],
retention: 'workqueue',
replicas: 1,
});
await this.natsService.ensureJetStreamConsumer({
stream: names.streams.sendRequest,
durable: names.consumers.sendRequest,
filterSubject: names.subjects.chatSendMessage,
description: 'Dakao send-message worker',
replicas: 1,
});
await this.natsService.ensureJetStreamStream({
name: names.streams.sendResult,
subjects: [
names.subjects.chatSendMessageSucceeded,
names.subjects.chatSendMessageFailed,
],
retention: 'limits',
maxAgeDays: 30,
replicas: 1,
});
await this.natsService.ensureJetStreamConsumer({
stream: names.streams.sendResult,
durable: names.consumers.sendResult,
filterSubject: `${names.env}.lolympus.dakao.chat.send-message.*.v1`,
description: 'LolyMpus Dakao send-message result handler',
replicas: 1,
});
}
}
@@ -0,0 +1,47 @@
import {
Injectable,
Logger,
OnModuleDestroy,
OnModuleInit,
} from '@nestjs/common';
import { DakaoOutboxService } from './dakao-outbox.service';
const SWEEP_INTERVAL_MS = 60 * 1000;
const STALE_OUTBOX_MS = 5 * 60 * 1000;
@Injectable()
export class DakaoOutboxSweeperService
implements OnModuleInit, OnModuleDestroy
{
private readonly logger = new Logger(DakaoOutboxSweeperService.name);
private timer: NodeJS.Timeout | undefined;
constructor(private readonly outboxService: DakaoOutboxService) {}
onModuleInit() {
this.timer = setInterval(() => {
void this.sweep();
}, SWEEP_INTERVAL_MS);
this.timer.unref();
}
onModuleDestroy() {
if (this.timer) clearInterval(this.timer);
}
private async sweep(): Promise<void> {
try {
const swept = await this.outboxService.sweepStale({
staleMs: STALE_OUTBOX_MS,
limit: 20,
});
if (swept > 0) {
this.logger.warn(`Re-published ${swept} stale Dakao outbox messages.`);
}
} catch (err) {
this.logger.error(
`Dakao outbox sweep failed: ${(err as Error)?.stack ?? err}`,
);
}
}
}
@@ -0,0 +1,116 @@
import { ConnectionService } from '../global/database/connection.service';
import { NatsService } from '../global/nats/nats.service';
import { DakaoOutboxService } from './dakao-outbox.service';
import { DakaoResultSubjects } from './dakao.types';
function execResult<T>(value: T) {
return { exec: jest.fn().mockResolvedValue(value) };
}
function makeService(outboxModel: Record<string, unknown>) {
const connectionService = {
getModel: jest.fn().mockResolvedValue(outboxModel),
} as unknown as ConnectionService;
const natsService = {
publishJetStream: jest.fn().mockResolvedValue(undefined),
} as unknown as NatsService;
return {
service: new DakaoOutboxService(connectionService, natsService),
connectionService,
natsService,
};
}
describe('DakaoOutboxService', () => {
it('persists result subjects when enqueuing send-message commands', async () => {
const outboxModel = {
findOneAndUpdate: jest.fn().mockReturnValue(execResult({})),
updateOne: jest.fn().mockReturnValue(execResult({})),
};
const { service, natsService } = makeService(outboxModel);
const resultSubjects: DakaoResultSubjects = {
succeeded: 'staging.lolympus.dakao.chat.send-message.succeeded.v1',
failed: 'staging.lolympus.dakao.chat.send-message.failed.v1',
};
await service.enqueueAndPublish({
subject: 'staging.dakao.chat.send-message.v1',
eventId: 'lolympus:chat.send-message:chat-log-1',
envelope: {
schema: 'dakao.command.v1',
eventId: 'lolympus:chat.send-message:chat-log-1',
type: 'chat.send-message',
eventSource: 'lolympus',
correlationId: 'chat-log-1',
resultSubjects,
payload: {
chatroomId: '18474390111480678',
segments: [{ kind: 'text', text: 'done' }],
},
},
});
expect(outboxModel.findOneAndUpdate).toHaveBeenCalledWith(
{ eventId: 'lolympus:chat.send-message:chat-log-1' },
expect.objectContaining({
$setOnInsert: expect.objectContaining({ resultSubjects }),
}),
expect.any(Object),
);
expect(natsService.publishJetStream).toHaveBeenCalledWith(
'staging.dakao.chat.send-message.v1',
expect.objectContaining({ resultSubjects }),
{ messageId: 'lolympus:chat.send-message:chat-log-1' },
);
});
it('restores send-message result subjects when sweeping legacy stale rows', async () => {
const previousNodeEnv = process.env.NODE_ENV;
process.env.NODE_ENV = 'staging';
try {
const exec = jest.fn().mockResolvedValue([
{
eventId: 'lolympus:chat.send-message:chat-log-1',
type: 'chat.send-message',
eventSource: 'lolympus',
subject: 'staging.dakao.chat.send-message.v1',
correlationId: 'chat-log-1',
payload: {
chatroomId: '18474390111480678',
segments: [{ kind: 'text', text: 'done' }],
},
},
]);
const lean = jest.fn().mockReturnValue({ exec });
const limit = jest.fn().mockReturnValue({ lean });
const sort = jest.fn().mockReturnValue({ limit });
const outboxModel = {
find: jest.fn().mockReturnValue({ sort }),
};
const { service } = makeService(outboxModel);
const enqueue = jest
.spyOn(service, 'enqueueAndPublish')
.mockResolvedValue(undefined);
await expect(service.sweepStale({ staleMs: 1, limit: 1 })).resolves.toBe(
1,
);
expect(enqueue).toHaveBeenCalledWith(
expect.objectContaining({
envelope: expect.objectContaining({
resultSubjects: {
succeeded:
'staging.lolympus.dakao.chat.send-message.succeeded.v1',
failed: 'staging.lolympus.dakao.chat.send-message.failed.v1',
},
}),
}),
);
} finally {
process.env.NODE_ENV = previousNodeEnv;
}
});
});
@@ -0,0 +1,191 @@
import { Injectable, Logger } from '@nestjs/common';
import { ConnectionService } from '../global/database/connection.service';
import { NatsService } from '../global/nats/nats.service';
import { resolveDakaoNatsNames } from './dakao.nats-names';
import {
DakaoCommandEnvelope,
DakaoResultEnvelope,
DakaoResultSubjects,
} from './dakao.types';
const CHAT_SEND_MESSAGE_TYPE = 'chat.send-message';
const TERMINAL_STATES = ['sent', 'failed'] as const;
@Injectable()
export class DakaoOutboxService {
private readonly logger = new Logger(DakaoOutboxService.name);
private readonly chatSendMessageResultSubjects = {
succeeded: resolveDakaoNatsNames().subjects.chatSendMessageSucceeded,
failed: resolveDakaoNatsNames().subjects.chatSendMessageFailed,
};
constructor(
private readonly connectionService: ConnectionService,
private readonly natsService: NatsService,
) {}
public async enqueueAndPublish<TPayload>(params: {
subject: string;
eventId: string;
envelope: DakaoCommandEnvelope<TPayload>;
}): Promise<void> {
const OutboxModel =
await this.connectionService.getModel('dakaoOutboxMessage');
await OutboxModel.findOneAndUpdate(
{ eventId: params.eventId },
{
$setOnInsert: {
eventId: params.eventId,
eventSource: params.envelope.eventSource,
type: params.envelope.type,
subject: params.subject,
correlationId: params.envelope.correlationId,
resultSubjects: params.envelope.resultSubjects,
payload: params.envelope.payload as Record<string, unknown>,
state: 'pending',
publishAttempts: 0,
compensationState: 'none',
},
},
{ upsert: true, returnDocument: 'after', setDefaultsOnInsert: true },
).exec();
try {
await this.natsService.publishJetStream(params.subject, params.envelope, {
messageId: params.eventId,
});
await OutboxModel.updateOne(
{
eventId: params.eventId,
state: { $nin: TERMINAL_STATES },
},
{
$set: {
state: 'published',
publishedAt: new Date(),
},
$inc: { publishAttempts: 1 },
$unset: { lastPublishError: '' },
},
).exec();
} catch (err) {
await OutboxModel.updateOne(
{
eventId: params.eventId,
state: { $nin: TERMINAL_STATES },
},
{
$inc: { publishAttempts: 1 },
$set: {
lastPublishError: (err as Error)?.message ?? String(err),
},
},
).exec();
this.logger.error(
`Failed to publish Dakao outbox eventId=${params.eventId}: ${
(err as Error)?.stack ?? err
}`,
);
}
}
public async applySendResult(params: {
subject: string;
envelope: DakaoResultEnvelope;
}): Promise<{ duplicate: boolean; terminalState?: 'sent' | 'failed' }> {
const ResultModel = await this.connectionService.getModel(
'dakaoSendResultEvent',
);
const OutboxModel =
await this.connectionService.getModel('dakaoOutboxMessage');
try {
await ResultModel.create({
eventId: params.envelope.eventId,
requestEventId: params.envelope.requestEventId,
eventSource: params.envelope.eventSource,
requestEventSource: params.envelope.requestEventSource,
type: params.envelope.type,
subject: params.subject,
status: params.envelope.status,
correlationId: params.envelope.correlationId,
handledAt: new Date(params.envelope.handledAt),
providerMessageId: params.envelope.providerMessageId,
error: params.envelope.error,
raw: params.envelope as unknown as Record<string, unknown>,
});
} catch (err) {
if ((err as { code?: number })?.code === 11000) {
return { duplicate: true };
}
throw err;
}
const terminalState =
params.envelope.status === 'succeeded' ? 'sent' : 'failed';
await OutboxModel.updateOne(
{
eventId: params.envelope.requestEventId,
state: { $nin: TERMINAL_STATES },
},
{
$set: {
state: terminalState,
terminalAt: new Date(),
resultEventId: params.envelope.eventId,
terminalError: params.envelope.error,
compensationState:
params.envelope.status === 'failed' ? 'pending' : 'none',
compensationReason: params.envelope.error?.code,
},
},
).exec();
return { duplicate: false, terminalState };
}
public async sweepStale(params?: {
staleMs?: number;
limit?: number;
}): Promise<number> {
const OutboxModel =
await this.connectionService.getModel('dakaoOutboxMessage');
const staleBefore = new Date(
Date.now() - (params?.staleMs ?? 5 * 60 * 1000),
);
const rows = await OutboxModel.find({
state: { $in: ['pending', 'published'] },
updatedAt: { $lte: staleBefore },
})
.sort({ updatedAt: 1 })
.limit(params?.limit ?? 20)
.lean()
.exec();
for (const row of rows) {
await this.enqueueAndPublish({
subject: row.subject,
eventId: row.eventId,
envelope: {
schema: 'dakao.command.v1',
eventId: row.eventId,
type: row.type,
eventSource: row.eventSource,
correlationId: row.correlationId,
resultSubjects:
row.resultSubjects ?? this.resolveDefaultResultSubjects(row.type),
payload: row.payload,
},
});
}
return rows.length;
}
private resolveDefaultResultSubjects(
type: string,
): DakaoResultSubjects | undefined {
if (type !== CHAT_SEND_MESSAGE_TYPE) return undefined;
return this.chatSendMessageResultSubjects;
}
}
@@ -0,0 +1,81 @@
import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { NatsService } from '../global/nats/nats.service';
import { DakaoJetStreamResourceService } from './dakao-jetstream-resource.service';
import { resolveDakaoNatsNames } from './dakao.nats-names';
import { DakaoOutboxService } from './dakao-outbox.service';
import { DakaoResultEnvelope } from './dakao.types';
@Injectable()
export class DakaoSendResultSubscriber implements OnModuleInit {
private readonly logger = new Logger(DakaoSendResultSubscriber.name);
constructor(
private readonly natsService: NatsService,
private readonly resources: DakaoJetStreamResourceService,
private readonly outboxService: DakaoOutboxService,
) {}
async onModuleInit() {
await this.resources.ensure();
const names = resolveDakaoNatsNames();
void this.natsService.consumeJetStream<DakaoResultEnvelope>(
{
stream: names.streams.sendResult,
durable: names.consumers.sendResult,
},
(event, msg) => this.handleResult(event, msg.subject),
);
this.logger.log(
`Dakao send-result subscriber ready on stream="${names.streams.sendResult}" durable="${names.consumers.sendResult}"`,
);
}
private async handleResult(
event: DakaoResultEnvelope,
subject: string,
): Promise<void> {
if (!this.validate(event)) {
this.logger.warn(`Ignoring invalid Dakao send-result on ${subject}`);
return;
}
const result = await this.outboxService.applySendResult({
subject,
envelope: event,
});
if (result.duplicate) {
this.logger.log(
`Duplicate Dakao result ignored eventId=${event.eventId}`,
);
return;
}
this.logger.log(
`Dakao result applied eventId=${event.eventId} requestEventId=${event.requestEventId} state=${result.terminalState ?? '-'}`,
);
}
private validate(event: unknown): event is DakaoResultEnvelope {
if (!event || typeof event !== 'object') return false;
const e = event as Partial<DakaoResultEnvelope>;
if (e.schema !== 'dakao.result.v1') return false;
if (typeof e.eventId !== 'string' || e.eventId.length === 0) return false;
if (typeof e.requestEventId !== 'string' || e.requestEventId.length === 0) {
return false;
}
if (typeof e.eventSource !== 'string' || e.eventSource.length === 0)
return false;
if (
typeof e.requestEventSource !== 'string' ||
e.requestEventSource.length === 0
) {
return false;
}
if (e.status !== 'succeeded' && e.status !== 'failed') return false;
if (
typeof e.handledAt !== 'string' ||
Number.isNaN(Date.parse(e.handledAt))
)
return false;
return true;
}
}
@@ -0,0 +1,148 @@
import { SecretService } from '../global/secret/secret.service';
import { DakaoUrlShortenerService } from './dakao-url-shortener.service';
describe('DakaoUrlShortenerService', () => {
const originalEnv = process.env;
const originalFetch = global.fetch;
beforeEach(() => {
process.env = { ...originalEnv };
});
afterEach(() => {
process.env = originalEnv;
global.fetch = originalFetch;
jest.restoreAllMocks();
});
function makeService(token = 'shortener-token') {
const secretService = {
get: jest.fn().mockResolvedValue(token),
} as unknown as jest.Mocked<SecretService>;
return {
service: new DakaoUrlShortenerService(secretService),
secretService,
};
}
it('posts a production match detail URL with a deterministic slug', async () => {
process.env.NODE_ENV = 'prod';
global.fetch = jest.fn().mockResolvedValue({
ok: true,
status: 201,
json: jest
.fn()
.mockResolvedValue({ shortUrl: 'https://go.dahyeon.us/lmtpAB12' }),
} as unknown as Response);
const { service } = makeService();
const shortUrl = await service.shortenMatchLink({
matchId: '333333333333333333333333',
shortCode: 'ab12',
});
expect(shortUrl).toBe('https://go.dahyeon.us/lmtpAB12');
expect(global.fetch).toHaveBeenCalledWith(
'https://go.dahyeon.us/api/shorten',
expect.objectContaining({
method: 'POST',
headers: expect.objectContaining({
Accept: 'application/json',
Authorization: 'Bearer shortener-token',
'Content-Type': 'application/json',
}),
}),
);
const init = (global.fetch as jest.Mock).mock.calls[0][1] as RequestInit;
expect(JSON.parse(init.body as string)).toEqual({
slug: 'lmtpAB12',
url: 'https://lolympus.dahyeon.us/match/333333333333333333333333',
redirectStatus: 302,
expiresAt: null,
});
});
it('uses staging slug prefix and configured target base URL outside production', async () => {
process.env.NODE_ENV = 'staging';
process.env.URL_SHORTENER_TARGET_BASE_URL =
'https://staging.lolympus.pages.dev/';
global.fetch = jest.fn().mockResolvedValue({
ok: true,
status: 201,
json: jest
.fn()
.mockResolvedValue({ shortUrl: 'https://go.dahyeon.us/lmtsCD34' }),
} as unknown as Response);
const { service } = makeService();
await service.shortenMatchLink({
matchId: '444444444444444444444444',
shortCode: 'cd34',
});
const init = (global.fetch as jest.Mock).mock.calls[0][1] as RequestInit;
expect(JSON.parse(init.body as string)).toEqual(
expect.objectContaining({
slug: 'lmtsCD34',
url: 'https://staging.lolympus.pages.dev/match/444444444444444444444444',
}),
);
});
it('builds the direct match detail URL for fallback output', () => {
process.env.URL_SHORTENER_TARGET_BASE_URL =
'https://staging.lolympus.pages.dev/';
const { service } = makeService();
expect(service.buildMatchDetailUrl('444444444444444444444444')).toBe(
'https://staging.lolympus.pages.dev/match/444444444444444444444444',
);
});
it('skips shortener calls when the bearer token is missing', async () => {
global.fetch = jest.fn();
const { service } = makeService('');
await expect(
service.shortenMatchLink({
matchId: '333333333333333333333333',
shortCode: 'AB12',
}),
).resolves.toBeUndefined();
expect(global.fetch).not.toHaveBeenCalled();
});
it('returns the deterministic short URL when the slug already exists', async () => {
process.env.NODE_ENV = 'prod';
global.fetch = jest.fn().mockResolvedValue({
ok: false,
status: 409,
text: jest.fn().mockResolvedValue('Conflict'),
} as unknown as Response);
const { service } = makeService();
await expect(
service.shortenMatchLink({
matchId: '333333333333333333333333',
shortCode: 'AB12',
}),
).resolves.toBe('https://go.dahyeon.us/lmtpAB12');
});
it('returns undefined when the shortener rejects the request', async () => {
global.fetch = jest.fn().mockResolvedValue({
ok: false,
status: 500,
text: jest.fn().mockResolvedValue('server error'),
} as unknown as Response);
const { service } = makeService();
await expect(
service.shortenMatchLink({
matchId: '333333333333333333333333',
shortCode: 'AB12',
}),
).resolves.toBeUndefined();
});
});
@@ -0,0 +1,180 @@
import { Injectable, Logger } from '@nestjs/common';
import { SecretService } from '../global/secret/secret.service';
const DEFAULT_SHORTENER_API_URL = 'https://go.dahyeon.us/api/shorten';
const DEFAULT_SHORTENER_BASE_URL = 'https://go.dahyeon.us';
const DEFAULT_TARGET_BASE_URL = 'https://lolympus.dahyeon.us';
const DEFAULT_TIMEOUT_MS = 1500;
interface ShortenMatchLinkParams {
matchId: string;
shortCode: string | undefined;
}
interface ShortenerResponseBody {
shortUrl?: unknown;
}
@Injectable()
export class DakaoUrlShortenerService {
private readonly logger = new Logger(DakaoUrlShortenerService.name);
constructor(private readonly secretService: SecretService) {}
public async shortenMatchLink(
params: ShortenMatchLinkParams,
): Promise<string | undefined> {
const shortCode = params.shortCode?.trim().toUpperCase();
if (!shortCode) return undefined;
const token = await this.resolveToken();
if (!token) return undefined;
const slug = `${this.resolveSlugPrefix()}${shortCode}`;
const requestBody = {
slug,
url: this.buildMatchDetailUrl(params.matchId),
redirectStatus: 302,
expiresAt: null,
};
const controller = new AbortController();
const timeout = setTimeout(
() => controller.abort(),
this.resolveTimeoutMs(),
);
try {
const response = await fetch(this.resolveApiUrl(), {
method: 'POST',
headers: {
Accept: 'application/json',
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(requestBody),
signal: controller.signal,
});
if (response.status === 409) {
return this.buildShortUrl(slug);
}
if (!response.ok) {
await this.logFailedResponse(response, slug);
return undefined;
}
const payload = await this.parseResponseBody(response);
const shortUrl = payload?.shortUrl;
return typeof shortUrl === 'string' && shortUrl.trim()
? shortUrl.trim()
: this.buildShortUrl(slug);
} catch (error) {
this.logger.warn(
`URL shortener request failed for slug="${slug}": ${error instanceof Error ? error.message : String(error)}`,
);
return undefined;
} finally {
clearTimeout(timeout);
}
}
private async resolveToken(): Promise<string | undefined> {
try {
const token = await this.secretService.get<string>(
'URL_SHORTENER_TOKEN',
'',
);
return token.trim() || undefined;
} catch (error) {
this.logger.warn(
`URL shortener token unavailable: ${error instanceof Error ? error.message : String(error)}`,
);
return undefined;
}
}
private resolveSlugPrefix(): 'lmtp' | 'lmts' {
const nodeEnv = process.env.NODE_ENV?.trim().toLowerCase();
return nodeEnv === 'prod' || nodeEnv === 'production' ? 'lmtp' : 'lmts';
}
public buildMatchDetailUrl(matchId: string): string {
return `${this.resolveTargetBaseUrl()}/match/${encodeURIComponent(matchId)}`;
}
private buildShortUrl(slug: string): string {
return `${this.resolveShortenerBaseUrl()}/${encodeURIComponent(slug)}`;
}
private resolveApiUrl(): string {
return (
process.env.URL_SHORTENER_API_URL?.trim() || DEFAULT_SHORTENER_API_URL
);
}
private resolveShortenerBaseUrl(): string {
return (
this.normalizeBaseUrl(process.env.URL_SHORTENER_BASE_URL) ??
this.normalizeOrigin(this.resolveApiUrl()) ??
DEFAULT_SHORTENER_BASE_URL
);
}
private resolveTargetBaseUrl(): string {
return (
this.normalizeBaseUrl(process.env.URL_SHORTENER_TARGET_BASE_URL) ??
this.normalizeBaseUrl(process.env.WEB_ORIGIN) ??
DEFAULT_TARGET_BASE_URL
);
}
private resolveTimeoutMs(): number {
const configured = Number(process.env.URL_SHORTENER_TIMEOUT_MS);
return Number.isFinite(configured) && configured > 0
? configured
: DEFAULT_TIMEOUT_MS;
}
private normalizeBaseUrl(value: string | undefined): string | undefined {
const raw = value?.split(',')[0]?.trim();
if (!raw) return undefined;
try {
const url = new URL(raw);
const pathname = url.pathname.replace(/\/+$/u, '');
return `${url.origin}${pathname}`;
} catch {
return undefined;
}
}
private normalizeOrigin(value: string): string | undefined {
try {
return new URL(value).origin;
} catch {
return undefined;
}
}
private async parseResponseBody(
response: Response,
): Promise<ShortenerResponseBody | undefined> {
try {
return (await response.json()) as ShortenerResponseBody;
} catch {
return undefined;
}
}
private async logFailedResponse(
response: Response,
slug: string,
): Promise<void> {
const body = await response.text().catch(() => '');
this.logger.warn(
`URL shortener returned ${response.status} for slug="${slug}"${body ? `: ${body.slice(0, 200)}` : ''}`,
);
}
}
@@ -3,7 +3,7 @@ import { ConnectionService } from '../global/database/connection.service';
import { RiotAccount, UserDocument } from '../global/database/schema';
import { RiotAccountEnrichmentService } from '../riot/riot-account-enrichment.service';
import { RiotAccountService } from '../riot/riot-account.service';
import { DakaoUserError, DakaoUserService } from './dakao-user.service';
import { DakaoUserService } from './dakao-user.service';
const objectId = (hex: string) => new mongoose.Types.ObjectId(hex);
@@ -14,15 +14,26 @@ function makeQuery<T>(value: T) {
}
function makeService(params: {
user: Partial<UserDocument>;
user: Partial<UserDocument> | null;
community?: Record<string, unknown> | null;
riotAccountService?: Partial<RiotAccountService>;
enrichmentService?: Partial<RiotAccountEnrichmentService>;
}) {
const findOneAndUpdate = jest
.fn()
.mockReturnValue(makeQuery(params.user as UserDocument));
const findOne = jest.fn().mockReturnValue(makeQuery(params.user));
const findById = jest.fn().mockReturnValue({
select: jest.fn().mockReturnValue({
lean: jest.fn().mockReturnValue(makeQuery(params.community ?? {})),
}),
});
const connectionService = {
getModel: jest.fn().mockResolvedValue({ findOneAndUpdate }),
getModel: jest.fn().mockImplementation(async (name: string) => {
if (name === 'user') return { findOneAndUpdate, findOne };
if (name === 'community') return { findById };
throw new Error(`Unexpected model: ${name}`);
}),
} as unknown as ConnectionService;
const riotAccountService = {
getByRiotId: jest.fn(),
@@ -41,13 +52,15 @@ function makeService(params: {
),
connectionService,
findOneAndUpdate,
findOne,
findById,
riotAccountService,
enrichmentService,
};
}
describe('DakaoUserService', () => {
it('rejects account registration when the user already has a Riot account', async () => {
it('registers an additional Riot account when the user already has one', async () => {
const save = jest.fn().mockResolvedValue(undefined);
const existingAccount = {
puuid: 'puuid-1',
@@ -66,25 +79,169 @@ describe('DakaoUserService', () => {
riotAccounts: [existingAccount],
save,
} as Partial<UserDocument>,
riotAccountService: {
getByRiotId: jest.fn().mockResolvedValue({
puuid: 'puuid-2',
gameName: '새소환사',
tagLine: 'KR2',
}),
},
enrichmentService: {
enrichRiotAccount: jest.fn().mockResolvedValue({ account: null }),
},
});
const result = await service.registerRiotAccount({
communityId: objectId('111111111111111111111111'),
kakaoTalkId: 'kakao-user-1',
kakaoTalkNickname: '프리리',
gameName: '새소환사',
tagLine: 'KR2',
});
expect(result.riotAccount).toMatchObject({
puuid: 'puuid-2',
gameName: '새소환사',
tagLine: 'KR2',
isPrimary: false,
});
expect((result.user.riotAccounts as RiotAccount[])[0]).toMatchObject({
puuid: 'puuid-1',
isPrimary: true,
});
expect(result.user.riotAccounts).toHaveLength(2);
expect(connectionService.getModel).toHaveBeenCalledWith('user');
expect(connectionService.getModel).toHaveBeenCalledWith('community');
expect(riotAccountService.getByRiotId).toHaveBeenCalledWith(
'새소환사',
'KR2',
{
region: 'asia',
},
);
expect(enrichmentService.enrichRiotAccount).toHaveBeenCalledWith(
expect.objectContaining({
userId: expect.any(mongoose.Types.ObjectId),
puuid: 'puuid-2',
options: { force: true, platform: 'kr', region: 'asia' },
}),
);
expect(save).toHaveBeenCalled();
});
it('reuses an already attached Riot account by puuid', async () => {
const save = jest.fn().mockResolvedValue(undefined);
const existingAccount = {
puuid: 'puuid-1',
gameName: '기존소환사',
tagLine: 'KR1',
isPrimary: true,
} as RiotAccount;
const { service, enrichmentService } = makeService({
user: {
_id: objectId('222222222222222222222222'),
riotAccounts: [existingAccount],
save,
} as Partial<UserDocument>,
riotAccountService: {
getByRiotId: jest.fn().mockResolvedValue({
puuid: 'puuid-1',
gameName: '바뀐소환사',
tagLine: 'KR1',
}),
},
});
const result = await service.registerRiotAccount({
communityId: objectId('111111111111111111111111'),
kakaoTalkId: 'kakao-user-1',
kakaoTalkNickname: '프리리',
gameName: '바뀐소환사',
tagLine: 'KR1',
});
expect(result.user.riotAccounts).toHaveLength(1);
expect(result.riotAccount).toMatchObject({
puuid: 'puuid-1',
gameName: '바뀐소환사',
tagLine: 'KR1',
isPrimary: true,
});
expect(enrichmentService.enrichRiotAccount).not.toHaveBeenCalled();
expect(save).toHaveBeenCalled();
});
it('changes the primary Riot account for the Dakao user', async () => {
const save = jest.fn().mockResolvedValue(undefined);
const oldPrimary = {
puuid: 'puuid-1',
gameName: '기존소환사',
tagLine: 'KR1',
isPrimary: true,
} as RiotAccount;
const nextPrimary = {
puuid: 'puuid-2',
gameName: '프리리',
tagLine: 'KR1',
isPrimary: false,
} as RiotAccount;
const { service, findOne } = makeService({
user: {
_id: objectId('222222222222222222222222'),
kakaoTalkNickname: '이전닉',
riotAccounts: [oldPrimary, nextPrimary],
save,
} as Partial<UserDocument>,
});
const result = await service.changePrimaryRiotAccount({
communityId: objectId('111111111111111111111111'),
kakaoTalkId: 'kakao-user-1',
kakaoTalkNickname: '프리리',
gameName: '프리리',
tagLine: 'KR1',
});
expect(findOne).toHaveBeenCalledWith({
communityId: objectId('111111111111111111111111'),
kakaoTalkId: 'kakao-user-1',
});
expect(oldPrimary.isPrimary).toBe(false);
expect(nextPrimary.isPrimary).toBe(true);
expect(result.riotAccount).toBe(nextPrimary);
expect(result.user.kakaoTalkNickname).toBe('프리리');
expect(save).toHaveBeenCalled();
});
it('rejects primary account changes for unregistered Riot accounts', async () => {
const save = jest.fn().mockResolvedValue(undefined);
const { service } = makeService({
user: {
_id: objectId('222222222222222222222222'),
riotAccounts: [
{
puuid: 'puuid-1',
gameName: '기존소환사',
tagLine: 'KR1',
isPrimary: true,
},
],
save,
} as Partial<UserDocument>,
});
await expect(
service.registerPrimaryRiotAccount({
service.changePrimaryRiotAccount({
communityId: objectId('111111111111111111111111'),
kakaoTalkId: 'kakao-user-1',
kakaoTalkNickname: '프리리',
gameName: '새소환사',
tagLine: 'KR2',
gameName: '프리리',
tagLine: 'KR1',
}),
).rejects.toMatchObject({
code: 'riot_account_already_registered',
detail: '기존소환사#KR1',
} satisfies Partial<DakaoUserError>);
expect(connectionService.getModel).toHaveBeenCalledTimes(1);
expect(connectionService.getModel).toHaveBeenCalledWith('user');
expect(riotAccountService.getByRiotId).not.toHaveBeenCalled();
expect(enrichmentService.enrichRiotAccount).not.toHaveBeenCalled();
code: 'riot_account_not_found',
detail: '프리리#KR1',
});
expect(save).not.toHaveBeenCalled();
});
});
+103 -31
View File
@@ -1,7 +1,12 @@
import { Injectable, Logger } from '@nestjs/common';
import mongoose, { isValidObjectId } from 'mongoose';
import { ConnectionService } from '../global/database/connection.service';
import { RiotAccount, UserDocument } from '../global/database/schema';
import {
Position,
PositionPreference,
RiotAccount,
UserDocument,
} from '../global/database/schema';
import { RiotApiError } from '../riot/riot.client.service';
import { RiotAccountEnrichmentService } from '../riot/riot-account-enrichment.service';
import { RiotAccountService } from '../riot/riot-account.service';
@@ -111,6 +116,17 @@ export class DakaoUserService {
return user;
}
public async findUserByKakaoTalkId(params: {
communityId: mongoose.Types.ObjectId;
kakaoTalkId: string;
}): Promise<UserDocument | null> {
const UserModel = await this.connectionService.getModel('user');
return UserModel.findOne({
communityId: params.communityId,
kakaoTalkId: params.kakaoTalkId,
}).exec();
}
public async resolveRiotAccount(
context: ResolveContext,
): Promise<ResolveResult> {
@@ -118,6 +134,8 @@ export class DakaoUserService {
const routing = await this.resolveRiotRouting(context.communityId);
const { requestedGameName, requestedTagLine, dto } =
await this.lookupRiotIdentity(context, routing);
const nextGameName = dto.gameName ?? requestedGameName;
const nextTagLine = dto.tagLine ?? requestedTagLine;
const existing = user.riotAccounts.find(
(a) =>
@@ -131,8 +149,6 @@ export class DakaoUserService {
}
if (existing) {
const nextGameName = dto.gameName ?? requestedGameName;
const nextTagLine = dto.tagLine ?? requestedTagLine;
if (existing.puuid !== dto.puuid) {
this.logger.warn(
`Riot account puuid mismatch for ${requestedGameName}#${requestedTagLine}: stored=${existing.puuid} resolved=${dto.puuid}. Updating stored account.`,
@@ -161,37 +177,21 @@ export class DakaoUserService {
return { user, riotAccount: existing };
}
return this.attachRiotAccount({
user,
puuid: dto.puuid,
gameName: dto.gameName ?? requestedGameName,
tagLine: dto.tagLine ?? requestedTagLine,
platform: routing.platform,
region: routing.region,
});
}
public async registerPrimaryRiotAccount(
context: ResolveContext,
): Promise<ResolveResult> {
const user = await this.upsertUser(context);
const existingPrimary = user.riotAccounts.find(
(account) => account.isPrimary,
const existingByPuuid = user.riotAccounts.find(
(account) => account.puuid === dto.puuid,
);
const existingAccount = existingPrimary ?? user.riotAccounts[0];
if (existingAccount) {
throw new DakaoUserError(
'riot_account_already_registered',
`${existingAccount.gameName}#${existingAccount.tagLine}`,
);
if (existingByPuuid) {
if (
existingByPuuid.gameName !== nextGameName ||
existingByPuuid.tagLine !== nextTagLine
) {
existingByPuuid.gameName = nextGameName;
existingByPuuid.tagLine = nextTagLine;
await user.save();
}
return { user, riotAccount: existingByPuuid };
}
const routing = await this.resolveRiotRouting(context.communityId);
const { requestedGameName, requestedTagLine, dto } =
await this.lookupRiotIdentity(context, routing);
const nextGameName = dto.gameName ?? requestedGameName;
const nextTagLine = dto.tagLine ?? requestedTagLine;
return this.attachRiotAccount({
user,
puuid: dto.puuid,
@@ -202,6 +202,78 @@ export class DakaoUserService {
});
}
public async registerRiotAccount(
context: ResolveContext,
): Promise<ResolveResult> {
return this.resolveRiotAccount(context);
}
public async registerPrimaryRiotAccount(
context: ResolveContext,
): Promise<ResolveResult> {
return this.registerRiotAccount(context);
}
public async registerPreferredPositions(params: {
communityId: mongoose.Types.ObjectId;
kakaoTalkId: string;
kakaoTalkNickname: string;
positions: Position[];
}): Promise<UserDocument> {
const user = await this.upsertUser({
communityId: params.communityId,
kakaoTalkId: params.kakaoTalkId,
kakaoTalkNickname: params.kakaoTalkNickname,
});
user.preferredPositions = this.toPositionPreferences(params.positions);
await user.save();
return user;
}
public async changePrimaryRiotAccount(
context: ResolveContext,
): Promise<ResolveResult> {
const requestedGameName = normalizeRiotIdPart(context.gameName);
const requestedTagLine = normalizeRiotIdPart(context.tagLine);
const detail = `${requestedGameName}#${requestedTagLine}`;
const user = await this.findUserByKakaoTalkId({
communityId: context.communityId,
kakaoTalkId: context.kakaoTalkId,
});
if (!user) {
throw new DakaoUserError('riot_account_not_found', detail);
}
const target = user.riotAccounts.find(
(account) =>
normalizeRiotIdPart(account.gameName).toLowerCase() ===
requestedGameName.toLowerCase() &&
normalizeRiotIdPart(account.tagLine).toLowerCase() ===
requestedTagLine.toLowerCase(),
);
if (!target) {
throw new DakaoUserError('riot_account_not_found', detail);
}
if (context.kakaoTalkNickname.trim()) {
user.kakaoTalkNickname = context.kakaoTalkNickname;
}
for (const account of user.riotAccounts) {
account.isPrimary = account.puuid === target.puuid;
}
await user.save();
return { user, riotAccount: target };
}
private toPositionPreferences(positions: Position[]): PositionPreference[] {
return positions.map((position, index) => ({
position,
priority: index + 1,
}));
}
private async lookupRiotIdentity(
context: ResolveContext,
routing: RiotRouting,
+19 -6
View File
@@ -1,17 +1,22 @@
import { Module } from '@nestjs/common';
import { MatchModule } from '../match/match.module';
import { RiotModule } from '../riot/riot.module';
import {
DAKAO_OPTIONS,
createDefaultDakaoOptions,
} from './dakao.options';
import { DAKAO_OPTIONS, createDefaultDakaoOptions } from './dakao.options';
import { DakaoPublisher } from './dakao.publisher';
import { DakaoSubscriber } from './dakao.subscriber';
import { DakaoInboxService } from './dakao-inbox.service';
import { DakaoJetStreamResourceService } from './dakao-jetstream-resource.service';
import { DakaoOutboxSweeperService } from './dakao-outbox-sweeper.service';
import { DakaoOutboxService } from './dakao-outbox.service';
import { DakaoUserService } from './dakao-user.service';
import { IdempotencyCache } from './idempotency.cache';
import { DakaoSendResultSubscriber } from './dakao-send-result.subscriber';
import { DakaoUrlShortenerService } from './dakao-url-shortener.service';
import { AccountRegisterHandler } from './handlers/account-register.handler';
import { MatchCancelHandler } from './handlers/match-cancel.handler';
import { MatchJoinHandler } from './handlers/match-join.handler';
import { MatchListHandler } from './handlers/match-list.handler';
import { PreferredPositionRegisterHandler } from './handlers/preferred-position-register.handler';
import { PrimaryAccountChangeHandler } from './handlers/primary-account-change.handler';
@Module({
imports: [RiotModule, MatchModule],
@@ -20,13 +25,21 @@ import { MatchListHandler } from './handlers/match-list.handler';
provide: DAKAO_OPTIONS,
useFactory: createDefaultDakaoOptions,
},
DakaoOutboxService,
DakaoOutboxSweeperService,
DakaoInboxService,
DakaoJetStreamResourceService,
DakaoPublisher,
DakaoSubscriber,
DakaoSendResultSubscriber,
DakaoUserService,
IdempotencyCache,
DakaoUrlShortenerService,
AccountRegisterHandler,
MatchListHandler,
MatchJoinHandler,
MatchCancelHandler,
PreferredPositionRegisterHandler,
PrimaryAccountChangeHandler,
],
exports: [DakaoPublisher],
})
@@ -0,0 +1,38 @@
import { resolveDakaoNatsNames } from './dakao.nats-names';
describe('resolveDakaoNatsNames', () => {
it('resolves staging subjects and JetStream resources from NODE_ENV=staging', () => {
expect(resolveDakaoNatsNames('staging')).toEqual({
env: 'staging',
shortEnv: 'STG',
subjects: {
botCommandSubmitted: 'staging.lolympus.dakao.bot-command.submitted.v1',
chatSendMessage: 'staging.dakao.chat.send-message.v1',
chatSendMessageSucceeded:
'staging.lolympus.dakao.chat.send-message.succeeded.v1',
chatSendMessageFailed:
'staging.lolympus.dakao.chat.send-message.failed.v1',
},
streams: {
botCommand: 'STG_DAKAO_TO_LOLYMPUS_BOTCMD',
sendRequest: 'STG_DAKAO_SENDREQ',
sendResult: 'STG_DAKAO_TO_LOLYMPUS_SENDRES',
},
consumers: {
botCommand: 'STG_LOLYMPUS_BOTCMD',
sendRequest: 'STG_DAKAO_SENDREQ_WORKER',
sendResult: 'STG_LOLYMPUS_SENDRES',
},
});
});
it('keeps JetStream resource names within the 32 character safety target', () => {
const names = resolveDakaoNatsNames('prod');
const resources = [
...Object.values(names.streams),
...Object.values(names.consumers),
];
expect(resources.every((name) => name.length <= 32)).toBe(true);
});
});
@@ -0,0 +1,68 @@
export type DakaoRuntimeEnv = 'dev' | 'staging' | 'prod';
export type DakaoShortEnv = 'DEV' | 'STG' | 'PROD';
export interface DakaoNatsNames {
env: DakaoRuntimeEnv;
shortEnv: DakaoShortEnv;
subjects: {
botCommandSubmitted: string;
chatSendMessage: string;
chatSendMessageSucceeded: string;
chatSendMessageFailed: string;
};
streams: {
botCommand: string;
sendRequest: string;
sendResult: string;
};
consumers: {
botCommand: string;
sendRequest: string;
sendResult: string;
};
}
export function resolveDakaoNatsNames(
nodeEnv = process.env.NODE_ENV,
): DakaoNatsNames {
const env = resolveRuntimeEnv(nodeEnv);
const shortEnv = toShortEnv(env);
return {
env,
shortEnv,
subjects: {
botCommandSubmitted: `${env}.lolympus.dakao.bot-command.submitted.v1`,
chatSendMessage: `${env}.dakao.chat.send-message.v1`,
chatSendMessageSucceeded: `${env}.lolympus.dakao.chat.send-message.succeeded.v1`,
chatSendMessageFailed: `${env}.lolympus.dakao.chat.send-message.failed.v1`,
},
streams: {
botCommand: `${shortEnv}_DAKAO_TO_LOLYMPUS_BOTCMD`,
sendRequest: `${shortEnv}_DAKAO_SENDREQ`,
sendResult: `${shortEnv}_DAKAO_TO_LOLYMPUS_SENDRES`,
},
consumers: {
botCommand: `${shortEnv}_LOLYMPUS_BOTCMD`,
sendRequest: `${shortEnv}_DAKAO_SENDREQ_WORKER`,
sendResult: `${shortEnv}_LOLYMPUS_SENDRES`,
},
};
}
function resolveRuntimeEnv(nodeEnv?: string): DakaoRuntimeEnv {
if (nodeEnv === 'prod' || nodeEnv === 'production') return 'prod';
if (nodeEnv === 'staging') return 'staging';
return 'dev';
}
function toShortEnv(env: DakaoRuntimeEnv): DakaoShortEnv {
switch (env) {
case 'prod':
return 'PROD';
case 'staging':
return 'STG';
case 'dev':
return 'DEV';
}
}
@@ -1,32 +1,38 @@
import { SecretService } from '../global/secret/secret.service';
import { NatsService } from '../global/nats/nats.service';
import { DakaoCommandEnvelope, DakaoSendMessagePayload } from './dakao.types';
import { DakaoPublisher } from './dakao.publisher';
import { DakaoOutboxService } from './dakao-outbox.service';
function makePublisher() {
const natsService = {
publish: jest.fn().mockResolvedValue(undefined),
subscribe: jest.fn(),
} as unknown as NatsService;
const outboxService = {
enqueueAndPublish: jest.fn().mockResolvedValue(undefined),
} as unknown as DakaoOutboxService;
const secretService = {} as SecretService;
const publisher = new DakaoPublisher(natsService, secretService, {
instanceId: 'test',
});
const previousNodeEnv = process.env.NODE_ENV;
process.env.NODE_ENV = 'staging';
return { publisher, natsService };
try {
const publisher = new DakaoPublisher(secretService, outboxService, {
instanceId: 'staging-instance',
});
return { publisher, outboxService };
} finally {
process.env.NODE_ENV = previousNodeEnv;
}
}
function getPublishedPayload(natsService: NatsService): DakaoSendMessagePayload {
const publish = natsService.publish as jest.Mock;
const envelope = publish.mock.calls[0][1] as DakaoCommandEnvelope<
DakaoSendMessagePayload
>;
return envelope.payload;
function getPublishedEnvelope(
outboxService: DakaoOutboxService,
): DakaoCommandEnvelope<DakaoSendMessagePayload> {
const enqueue = outboxService.enqueueAndPublish as jest.Mock;
return enqueue.mock.calls[0][0]
.envelope as DakaoCommandEnvelope<DakaoSendMessagePayload>;
}
describe('DakaoPublisher', () => {
it('keeps valid mention segments intact', async () => {
const { publisher, natsService } = makePublisher();
const { publisher, outboxService } = makePublisher();
await publisher.sendMessage({
chatroomId: '18474390111480678',
@@ -40,7 +46,7 @@ describe('DakaoPublisher', () => {
],
});
expect(getPublishedPayload(natsService).segments).toEqual([
expect(getPublishedEnvelope(outboxService).payload.segments).toEqual([
{
kind: 'mention',
userId: '6215844374579825921',
@@ -51,7 +57,7 @@ describe('DakaoPublisher', () => {
});
it('downgrades invalid mention segments to text before publishing', async () => {
const { publisher, natsService } = makePublisher();
const { publisher, outboxService } = makePublisher();
await publisher.sendMessage({
chatroomId: '18474390111480678',
@@ -65,9 +71,39 @@ describe('DakaoPublisher', () => {
],
});
expect(getPublishedPayload(natsService).segments).toEqual([
expect(getPublishedEnvelope(outboxService).payload.segments).toEqual([
{ kind: 'text', text: '@소쿠리' },
{ kind: 'text', text: ' 신청 완료' },
]);
});
it('uses deterministic event ids and the shared Dakao send subject', async () => {
const { publisher, outboxService } = makePublisher();
await publisher.sendMessage({
chatroomId: '18474390111480678',
segments: [{ kind: 'text', text: '신청 완료' }],
correlationId: 'chat-log-1',
});
const enqueue = outboxService.enqueueAndPublish as jest.Mock;
expect(enqueue.mock.calls[0][0]).toMatchObject({
subject: 'staging.dakao.chat.send-message.v1',
eventId: 'lolympus:chat.send-message:chat-log-1',
});
expect(getPublishedEnvelope(outboxService)).toMatchObject({
schema: 'dakao.command.v1',
eventId: 'lolympus:chat.send-message:chat-log-1',
eventSource: 'lolympus',
type: 'chat.send-message',
correlationId: 'chat-log-1',
resultSubjects: {
succeeded: 'staging.lolympus.dakao.chat.send-message.succeeded.v1',
failed: 'staging.lolympus.dakao.chat.send-message.failed.v1',
},
});
expect(getPublishedEnvelope(outboxService)).not.toHaveProperty(
'replySubject',
);
});
});
+39 -55
View File
@@ -1,86 +1,86 @@
import {
Inject,
Injectable,
Logger,
OnModuleDestroy,
OnModuleInit,
} from '@nestjs/common';
import { Inject, Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { randomUUID } from 'crypto';
import { SecretService } from '../global/secret/secret.service';
import { NatsService } from '../global/nats/nats.service';
import {
DakaoCommandEnvelope,
DakaoResultEnvelope,
DakaoResultSubjects,
DakaoSegment,
DakaoSendMessagePayload,
} from './dakao.types';
import type { DakaoOptions } from './dakao.options';
import { DAKAO_OPTIONS } from './dakao.options';
import { resolveDakaoNatsNames } from './dakao.nats-names';
import { DakaoOutboxService } from './dakao-outbox.service';
const SEND_MESSAGE_SUBJECT_DEFAULT = 'dakao.command.chat.send-message.v1';
const COMMAND_SOURCE_DEFAULT = 'lolympus-tournament-support';
const EVENT_SOURCE_DEFAULT = 'lolympus';
@Injectable()
export class DakaoPublisher implements OnModuleInit, OnModuleDestroy {
export class DakaoPublisher implements OnModuleInit {
private readonly logger = new Logger(DakaoPublisher.name);
private replySubject = '';
private sendMessageSubject = SEND_MESSAGE_SUBJECT_DEFAULT;
private source = COMMAND_SOURCE_DEFAULT;
private readonly names = resolveDakaoNatsNames();
private sendMessageSubject = this.names.subjects.chatSendMessage;
private resultSubjects: DakaoResultSubjects = {
succeeded: this.names.subjects.chatSendMessageSucceeded,
failed: this.names.subjects.chatSendMessageFailed,
};
private eventSource = EVENT_SOURCE_DEFAULT;
constructor(
private readonly natsService: NatsService,
private readonly secretService: SecretService,
private readonly outboxService: DakaoOutboxService,
@Inject(DAKAO_OPTIONS) private readonly options: DakaoOptions,
) {}
async onModuleInit() {
const replyOverride = await this.secretService
.get<string>('DAKAO_REPLY_SUBJECT_PREFIX')
.catch(() => undefined);
const sendOverride = await this.secretService
.get<string>('DAKAO_NATS_COMMAND_CHAT_SEND_MESSAGE_SUBJECT')
.get<string>('DAKAO_CHAT_SEND_MESSAGE_SUBJECT')
.catch(() => undefined);
const sourceOverride = await this.secretService
.get<string>('DAKAO_COMMAND_SOURCE')
.get<string>('DAKAO_EVENT_SOURCE')
.catch(() => undefined);
const replyPrefix = replyOverride || `dakao.result.${COMMAND_SOURCE_DEFAULT}`;
this.replySubject = `${replyPrefix}.${this.options.instanceId}`;
this.sendMessageSubject = sendOverride || SEND_MESSAGE_SUBJECT_DEFAULT;
this.source = sourceOverride || COMMAND_SOURCE_DEFAULT;
this.sendMessageSubject =
sendOverride || resolveDakaoNatsNames().subjects.chatSendMessage;
this.resultSubjects = {
succeeded: this.names.subjects.chatSendMessageSucceeded,
failed: this.names.subjects.chatSendMessageFailed,
};
this.eventSource = sourceOverride || EVENT_SOURCE_DEFAULT;
this.natsService.subscribe<DakaoResultEnvelope>(
this.replySubject,
(data) => this.handleReply(data),
);
this.logger.log(
`Dakao reply subscriber ready on subject="${this.replySubject}"`,
`Dakao send-message publisher ready on subject="${this.sendMessageSubject}" source="${this.eventSource}" instanceId="${this.options.instanceId}"`,
);
}
async onModuleDestroy() {
// NatsService 가 subscription 정리한다.
}
public async sendMessage(params: {
chatroomId: string;
segments: DakaoSegment[];
correlationId?: string;
eventId?: string;
}): Promise<void> {
const eventId =
params.eventId ??
(params.correlationId
? `${this.eventSource}:chat.send-message:${params.correlationId}`
: `${this.eventSource}:chat.send-message:${randomUUID()}`);
const payload: DakaoSendMessagePayload = {
chatroomId: params.chatroomId,
segments: this.normalizeSegments(params.segments),
};
const envelope: DakaoCommandEnvelope<DakaoSendMessagePayload> = {
schema: 'dakao.command.v1',
id: randomUUID(),
eventId,
type: 'chat.send-message',
source: this.source,
eventSource: this.eventSource,
correlationId: params.correlationId,
replySubject: this.replySubject,
resultSubjects: this.resultSubjects,
payload,
};
await this.natsService.publish(this.sendMessageSubject, envelope);
await this.outboxService.enqueueAndPublish({
subject: this.sendMessageSubject,
eventId,
envelope,
});
}
private normalizeSegments(segments: DakaoSegment[]): DakaoSegment[] {
@@ -111,11 +111,7 @@ export class DakaoPublisher implements OnModuleInit, OnModuleDestroy {
const id = segment.id.trim();
const altText = segment.altText.trim();
if (
id.length > 0 &&
altText.length > 0 &&
!/[()@]/.test(altText)
) {
if (id.length > 0 && altText.length > 0 && !/[()@]/.test(altText)) {
normalized.push({ kind: 'emoticon', id, altText });
continue;
}
@@ -139,16 +135,4 @@ export class DakaoPublisher implements OnModuleInit, OnModuleDestroy {
const label = displayText || userId || '사용자';
return label.startsWith('@') ? label : `@${label}`;
}
private handleReply(reply: DakaoResultEnvelope): void {
if (reply.status === 'succeeded') {
this.logger.log(
`Dakao reply succeeded id=${reply.id} type=${reply.type} correlationId=${reply.correlationId ?? '-'}`,
);
return;
}
this.logger.warn(
`Dakao reply failed id=${reply.id} type=${reply.type} code=${reply.error?.code ?? '-'} retryable=${reply.error?.retryable ?? false} message=${reply.error?.message ?? '-'}`,
);
}
}
@@ -0,0 +1,107 @@
import { DakaoSubscriber } from './dakao.subscriber';
import { DakaoInboundEvent, DakaoSegment } from './dakao.types';
import { CommandParseError } from './parsers/command.parser';
function makeSubscriber(): DakaoSubscriber {
return new DakaoSubscriber(
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
);
}
const event = {
projectId: '111111111111111111111111',
chatroomId: 'chatroom-1',
nickname: '프리리',
userId: '12345',
origin: {
chatId: 'chat-1',
logId: 'log-1',
chatLog: {
logId: 'log-1',
chatId: 'chat-1',
authorId: '12345',
type: 1,
sendAt: 0,
message: '!내전',
},
},
} satisfies DakaoInboundEvent;
describe('DakaoSubscriber', () => {
it('renders usage help with star emoticon command lines', () => {
const subscriber = makeSubscriber() as unknown as {
parseErrorReply: (
event: DakaoInboundEvent,
senderNickname: string,
err: CommandParseError,
) => DakaoSegment[];
};
const segments = subscriber.parseErrorReply(
event,
'프리리',
new CommandParseError('usage'),
);
expect(segments).toEqual([
{ kind: 'mention', userId: '12345', displayText: '프리리' },
{ kind: 'text', text: ' 사용법\n' },
{ kind: 'emoticon', id: '1200281_035', altText: '스타' },
{ kind: 'text', text: ' !내전 일정\n' },
{ kind: 'emoticon', id: '1200281_035', altText: '스타' },
{
kind: 'text',
text: ' !내전 신청 코드 소환사이름#태그 포지션1,포지션2\n',
},
{ kind: 'emoticon', id: '1200281_035', altText: '스타' },
{ kind: 'text', text: ' !내전 계정등록 소환사이름#태그\n' },
{ kind: 'emoticon', id: '1200281_035', altText: '스타' },
{
kind: 'text',
text: ' !내전 선호포지션등록 포지션1,포지션2\n',
},
{ kind: 'emoticon', id: '1200281_035', altText: '스타' },
{
kind: 'text',
text: ' !내전 대표계정변경 소환사이름#태그',
},
]);
});
it('keeps the unknown command header before star emoticon usage lines', () => {
const subscriber = makeSubscriber() as unknown as {
parseErrorReply: (
event: DakaoInboundEvent,
senderNickname: string,
err: CommandParseError,
) => DakaoSegment[];
};
const segments = subscriber.parseErrorReply(
event,
'프리리',
new CommandParseError('unknown_command', '폭파'),
);
expect(segments.slice(0, 2)).toEqual([
{ kind: 'mention', userId: '12345', displayText: '프리리' },
{ kind: 'text', text: ' 알 수 없는 명령어입니다.\n' },
]);
expect(segments).toContainEqual({
kind: 'emoticon',
id: '1200281_035',
altText: '스타',
});
});
});
+131 -35
View File
@@ -6,46 +6,59 @@ import { CommandParseError, parseCommand } from './parsers/command.parser';
import { DakaoInboundEvent, DakaoLong, DakaoSegment } from './dakao.types';
import { DakaoPublisher } from './dakao.publisher';
import { DakaoUserError, DakaoUserService } from './dakao-user.service';
import { IdempotencyCache } from './idempotency.cache';
import { AccountRegisterHandler } from './handlers/account-register.handler';
import { MatchCancelHandler } from './handlers/match-cancel.handler';
import { MatchJoinHandler } from './handlers/match-join.handler';
import { MatchListHandler } from './handlers/match-list.handler';
const INBOUND_SUBJECT_DEFAULT = 'lolympus-tournament-support.kakaotalk.command';
import { PreferredPositionRegisterHandler } from './handlers/preferred-position-register.handler';
import { PrimaryAccountChangeHandler } from './handlers/primary-account-change.handler';
import { resolveDakaoNatsNames } from './dakao.nats-names';
import { DakaoInboxService } from './dakao-inbox.service';
import { DakaoJetStreamResourceService } from './dakao-jetstream-resource.service';
@Injectable()
export class DakaoSubscriber implements OnModuleInit {
private readonly logger = new Logger(DakaoSubscriber.name);
private inboundSubject = INBOUND_SUBJECT_DEFAULT;
private readonly natsNames = resolveDakaoNatsNames();
private botUserId: string | undefined;
private readonly usageCommands = [
'!내전 일정',
'!내전 신청 코드 소환사이름#태그 포지션1,포지션2',
'!내전 계정등록 소환사이름#태그',
'!내전 선호포지션등록 포지션1,포지션2',
'!내전 대표계정변경 소환사이름#태그',
];
constructor(
private readonly natsService: NatsService,
private readonly secretService: SecretService,
private readonly dakaoUserService: DakaoUserService,
private readonly publisher: DakaoPublisher,
private readonly idempotency: IdempotencyCache,
private readonly inbox: DakaoInboxService,
private readonly resources: DakaoJetStreamResourceService,
private readonly accountRegisterHandler: AccountRegisterHandler,
private readonly matchListHandler: MatchListHandler,
private readonly matchJoinHandler: MatchJoinHandler,
private readonly matchCancelHandler: MatchCancelHandler,
private readonly preferredPositionRegisterHandler: PreferredPositionRegisterHandler,
private readonly primaryAccountChangeHandler: PrimaryAccountChangeHandler,
) {}
async onModuleInit() {
const subjectOverride = await this.secretService
.get<string>('DAKAO_INBOUND_SUBJECT')
.catch(() => undefined);
this.inboundSubject = subjectOverride || INBOUND_SUBJECT_DEFAULT;
this.botUserId = await this.secretService
.get<string>('DAKAO_BOT_USER_ID')
.catch(() => undefined);
this.natsService.subscribe<DakaoInboundEvent>(
this.inboundSubject,
await this.resources.ensure();
void this.natsService.consumeJetStream<DakaoInboundEvent>(
{
stream: this.natsNames.streams.botCommand,
durable: this.natsNames.consumers.botCommand,
},
(event) => this.handleEvent(event),
);
this.logger.log(
`Dakao inbound subscriber ready on subject="${this.inboundSubject}"`,
`Dakao inbound subscriber ready on stream="${this.natsNames.streams.botCommand}" durable="${this.natsNames.consumers.botCommand}"`,
);
}
@@ -56,35 +69,52 @@ export class DakaoSubscriber implements OnModuleInit {
return;
}
const logIdKey = this.deriveLogIdKey(event);
if (logIdKey && this.idempotency.has(logIdKey)) {
return;
const chatLogLogId = this.serializeDakaoLong(event.origin.chatLog.logId);
let claimed = false;
if (chatLogLogId) {
const claim = await this.inbox.claim({
consumer: this.natsNames.consumers.botCommand,
projectId: event.projectId,
chatLogLogId,
});
if (claim.status === 'duplicate') return;
if (claim.status === 'inflight') {
throw new Error(
`Dakao event is already being processed projectId=${event.projectId} logId=${chatLogLogId}`,
);
}
claimed = true;
}
if (logIdKey) this.idempotency.remember(logIdKey);
let communityId: mongoose.Types.ObjectId;
try {
communityId = await this.dakaoUserService.resolveCommunityIdByDakaoProjectId(
event.projectId,
);
communityId =
await this.dakaoUserService.resolveCommunityIdByDakaoProjectId(
event.projectId,
);
} catch (err) {
if (err instanceof DakaoUserError) {
if (err.code === 'invalid_project_id') {
this.logger.warn(`Invalid dakao projectId format: ${event.projectId}`);
this.logger.warn(
`Invalid dakao projectId format: ${event.projectId}`,
);
if (claimed) await this.markProcessed(event, chatLogLogId);
return;
}
if (err.code === 'community_not_found') {
// 우리 쪽이 모르는 projectId. 메시지를 보내봤자 컨텍스트가 없으므로 로그만.
this.logger.warn(`Unknown dakao projectId: ${event.projectId}`);
if (claimed) await this.markProcessed(event, chatLogLogId);
return;
}
}
if (claimed) await this.markFailed(event, chatLogLogId, err);
throw err;
}
let segments: DakaoSegment[];
const senderNickname = this.resolveSenderNickname(event);
const correlationId = this.serializeDakaoLong(event.origin.chatLog.logId);
const correlationId = chatLogLogId;
try {
const command = parseCommand(event.origin.chatLog.message);
@@ -105,17 +135,40 @@ export class DakaoSubscriber implements OnModuleInit {
tagLine: command.tagLine,
});
break;
case 'match-join':
segments = await this.matchJoinHandler.handle({
case 'primary-account-change':
segments = await this.primaryAccountChangeHandler.handle({
communityId,
matchId: command.matchId,
senderUserId: event.userId,
senderNickname,
gameName: command.gameName,
tagLine: command.tagLine,
});
break;
case 'match-join':
segments = await this.matchJoinHandler.handle({
communityId,
matchAndRiotId: command.matchAndRiotId,
senderUserId: event.userId,
senderNickname,
positions: command.positions?.positions,
});
break;
case 'preferred-position-register':
segments = await this.preferredPositionRegisterHandler.handle({
communityId,
senderUserId: event.userId,
senderNickname,
positions: command.positions.positions,
});
break;
case 'match-cancel':
segments = await this.matchCancelHandler.handle({
communityId,
matchId: command.matchId,
senderUserId: event.userId,
senderNickname,
});
break;
}
await this.publisher.sendMessage({
@@ -123,27 +176,35 @@ export class DakaoSubscriber implements OnModuleInit {
segments,
correlationId,
});
if (claimed) await this.markProcessed(event, chatLogLogId);
} catch (err) {
if (err instanceof CommandParseError) {
// not_a_command 는 명령이 아닌 일반 메시지 → 무시.
if (err.code === 'not_a_command') return;
if (err.code === 'not_a_command') {
if (claimed) await this.markProcessed(event, chatLogLogId);
return;
}
await this.publisher.sendMessage({
chatroomId: event.chatroomId,
segments: this.parseErrorReply(event, senderNickname, err),
correlationId,
});
if (claimed) await this.markProcessed(event, chatLogLogId);
return;
}
this.logger.error(
`Unhandled dakao event error: ${(err as Error)?.stack ?? err}`,
);
if (claimed) await this.markFailed(event, chatLogLogId, err);
throw err;
}
}
private validate(event: unknown): event is DakaoInboundEvent {
if (!event || typeof event !== 'object') return false;
const e = event as Partial<DakaoInboundEvent>;
if (typeof e.projectId !== 'string' || e.projectId.length === 0) return false;
if (typeof e.projectId !== 'string' || e.projectId.length === 0)
return false;
if (typeof e.chatroomId !== 'string' || e.chatroomId.length === 0)
return false;
if (typeof e.nickname !== 'string') return false;
@@ -156,11 +217,6 @@ export class DakaoSubscriber implements OnModuleInit {
return true;
}
private deriveLogIdKey(event: DakaoInboundEvent): string | null {
const serialized = this.serializeDakaoLong(event.origin.chatLog.logId);
return serialized ? `${event.projectId}:${serialized}` : null;
}
private serializeDakaoLong(value: DakaoLong | string | undefined): string {
if (typeof value === 'string') return value;
if (!value || typeof value !== 'object') return '';
@@ -179,6 +235,30 @@ export class DakaoSubscriber implements OnModuleInit {
return fallback ?? '';
}
private async markProcessed(
event: DakaoInboundEvent,
chatLogLogId: string,
): Promise<void> {
await this.inbox.markProcessed({
consumer: this.natsNames.consumers.botCommand,
projectId: event.projectId,
chatLogLogId,
});
}
private async markFailed(
event: DakaoInboundEvent,
chatLogLogId: string,
error: unknown,
): Promise<void> {
await this.inbox.markFailed({
consumer: this.natsNames.consumers.botCommand,
projectId: event.projectId,
chatLogLogId,
error,
});
}
private parseErrorReply(
event: DakaoInboundEvent,
senderNickname: string,
@@ -194,19 +274,35 @@ export class DakaoSubscriber implements OnModuleInit {
const text = ((): string => {
switch (err.code) {
case 'unknown_command':
return ` 알 수 없는 명령어입니다. 사용법: !내전 목록, !내전 계정등록 <게임명>#<태그>, !내전 신청 <ID> <게임명>#<태그> <포지션1>,<포지션2>`;
return ` 알 수 없는 명령어입니다.\n`;
case 'usage':
return ` 사용법: !내전 목록, !내전 계정등록 <게임명>#<태그>, !내전 신청 <ID> <게임명>#<태그> <포지션1>,<포지션2>`;
return ` 내전 명령어 사용법\n`;
case 'invalid_match_id':
return ` 매치 ID 형식이 올바르지 않습니다 (${err.detail ?? ''}).`;
case 'invalid_riot_id':
return ` 라이엇 ID 형식이 올바르지 않습니다 (예: 프리리#KR1).`;
case 'invalid_position':
return ` 포지션 입력이 올바르지 않습니다. 최소 2개, 중복 없이, 인식되는 별칭(탑/정글/미드/원딜/서폿) 사용.`;
return ` 포지션 입력이 올바르지 않습니다. 쉼표로 구분해서 최소 2개를 중복 없이 입력해주세요. 사용 가능: 탑, 정글, 미드, 원딜, 서폿`;
default:
return ` 명령을 처리할 수 없습니다.`;
}
})();
if (err.code === 'unknown_command' || err.code === 'usage') {
return [...head, { kind: 'text', text }, ...this.usageCommandSegments()];
}
return [...head, { kind: 'text', text }];
}
private usageCommandSegments(): DakaoSegment[] {
return this.usageCommands.flatMap((command, index) => [
{ kind: 'emoticon', id: '1200281_035', altText: '스타' } as const,
{
kind: 'text',
text:
index === this.usageCommands.length - 1
? ` ${command}`
: ` ${command} \n`,
} as const,
]);
}
}
+17 -8
View File
@@ -1,7 +1,7 @@
// dakao NATS contracts
// inbound: dakao 가 lolympus-tournament-support.kakaotalk.command 로 발행하는 이벤트
// outbound: 우리가 dakao.command.chat.send-message.v1 로 발행하는 명령
// reply: dakao 가 우리 envelope 의 replySubject 로 publish 하는 결과
// inbound: dakao 가 {env}.lolympus.dakao.bot-command.submitted.v1 로 발행하는 이벤트
// outbound: 우리가 {env}.dakao.chat.send-message.v1 로 발행하는 명령
// result: dakao 가 {env}.lolympus.dakao.chat.send-message.{succeeded|failed}.v1 로 발행하는 결과 이벤트
// ===== Inbound =====
export interface DakaoLong {
@@ -75,24 +75,33 @@ export interface DakaoSendMessagePayload {
silence?: boolean;
}
export interface DakaoResultSubjects {
succeeded: string;
failed: string;
}
export interface DakaoCommandEnvelope<TPayload> {
schema: 'dakao.command.v1';
id: string;
eventId: string;
type: string;
source: string;
eventSource: string;
correlationId?: string;
replySubject?: string;
resultSubjects?: DakaoResultSubjects;
payload: TPayload;
}
// ===== Reply =====
// ===== Result =====
export interface DakaoResultEnvelope {
schema: 'dakao.result.v1';
id: string;
eventId: string;
requestEventId: string;
type: string;
eventSource: string;
requestEventSource: string;
status: 'succeeded' | 'failed';
handledAt: string;
correlationId?: string;
providerMessageId?: string;
result?: Record<string, unknown>;
error?: {
code: string;
@@ -6,7 +6,7 @@ const objectId = (hex: string) => new mongoose.Types.ObjectId(hex);
function makeHandler(dakaoUserService?: Partial<DakaoUserService>) {
return new AccountRegisterHandler({
registerPrimaryRiotAccount: jest.fn(),
registerRiotAccount: jest.fn(),
...dakaoUserService,
} as unknown as DakaoUserService);
}
@@ -20,15 +20,39 @@ const baseParams = {
};
describe('AccountRegisterHandler', () => {
it('translates already-registered Riot account errors', async () => {
it('registers a Riot account through DakaoUserService', async () => {
const registerRiotAccount = jest.fn().mockResolvedValue({
user: { _id: objectId('222222222222222222222222') },
riotAccount: { gameName: '프리리', tagLine: 'KR1' },
});
const handler = makeHandler({
registerPrimaryRiotAccount: jest
registerRiotAccount,
});
const segments = await handler.handle(baseParams);
expect(registerRiotAccount).toHaveBeenCalledWith({
communityId: baseParams.communityId,
kakaoTalkId: 'kakao-user-1',
kakaoTalkNickname: '프리리',
gameName: '프리리',
tagLine: 'KR1',
});
expect(segments).toEqual([
expect.objectContaining({ kind: 'mention', userId: 'kakao-user-1' }),
expect.objectContaining({
kind: 'text',
text: expect.stringContaining('등록 계정: 프리리#KR1'),
}),
]);
});
it('translates Riot account conflict errors', async () => {
const handler = makeHandler({
registerRiotAccount: jest
.fn()
.mockRejectedValue(
new DakaoUserError(
'riot_account_already_registered',
'기존소환사#KR1',
),
new DakaoUserError('riot_account_conflict', '기존소환사#KR1'),
),
});
@@ -38,7 +62,7 @@ describe('AccountRegisterHandler', () => {
expect.objectContaining({ kind: 'mention', userId: 'kakao-user-1' }),
expect.objectContaining({
kind: 'text',
text: expect.stringContaining('이미 등록된 라이엇 계정'),
text: expect.stringContaining('이미 다른 사용자가 등록한 라이엇 계정'),
}),
]);
expect(segments[1]).toMatchObject({
@@ -19,7 +19,7 @@ export class AccountRegisterHandler {
params: AccountRegisterHandlerParams,
): Promise<DakaoSegment[]> {
try {
const resolved = await this.dakaoUserService.registerPrimaryRiotAccount({
const resolved = await this.dakaoUserService.registerRiotAccount({
communityId: params.communityId,
kakaoTalkId: params.senderUserId,
kakaoTalkNickname: params.senderNickname,
@@ -37,7 +37,7 @@ export class AccountRegisterHandler {
kind: 'text',
text:
` 계정 등록 완료` +
`\n대표 계정: ${resolved.riotAccount.gameName}#${resolved.riotAccount.tagLine}`,
`\n등록 계정: ${resolved.riotAccount.gameName}#${resolved.riotAccount.tagLine}`,
},
];
} catch (err) {
@@ -0,0 +1,168 @@
import { BadRequestException } from '@nestjs/common';
import mongoose from 'mongoose';
import { MatchService } from '../../match/match.service';
import { DakaoUserService } from '../dakao-user.service';
import { MatchCancelHandler } from './match-cancel.handler';
const objectId = (hex: string) => new mongoose.Types.ObjectId(hex);
function makeHandler(overrides?: {
matchService?: Partial<MatchService>;
dakaoUserService?: Partial<DakaoUserService>;
}): MatchCancelHandler {
const matchService = {
cancelJoin: jest.fn(),
list: jest.fn(),
...overrides?.matchService,
} as unknown as MatchService;
const dakaoUserService = {
findUserByKakaoTalkId: jest.fn(),
...overrides?.dakaoUserService,
} as unknown as DakaoUserService;
return new MatchCancelHandler(matchService, dakaoUserService);
}
const baseParams = {
communityId: objectId('111111111111111111111111'),
matchId: '69b63bc96da18dfdb218ee8c',
senderUserId: 'kakao-user-1',
senderNickname: '프리리',
};
describe('MatchCancelHandler', () => {
it('rejects unknown match reference without cancelling', async () => {
const cancelJoin = jest.fn();
const handler = makeHandler({
matchService: {
cancelJoin,
list: jest.fn().mockResolvedValue([]),
} as Partial<MatchService>,
dakaoUserService: {
findUserByKakaoTalkId: jest.fn().mockResolvedValue({
_id: objectId('222222222222222222222222'),
}),
} as Partial<DakaoUserService>,
});
const segments = await handler.handle({
...baseParams,
matchId: 'not-an-id',
});
expect(cancelJoin).not.toHaveBeenCalled();
expect(segments).toEqual([
expect.objectContaining({ kind: 'mention', userId: 'kakao-user-1' }),
expect.objectContaining({
kind: 'text',
text: expect.stringContaining('모집 중인 내전이 없습니다'),
}),
]);
});
it('replies with success for registered user cancellation', async () => {
const cancelJoin = jest.fn().mockResolvedValue({
title: '저녁 내전',
participants: [{}, {}],
maxParticipants: 10,
});
const findUserByKakaoTalkId = jest.fn().mockResolvedValue({
_id: objectId('222222222222222222222222'),
});
const handler = makeHandler({
matchService: { cancelJoin } as Partial<MatchService>,
dakaoUserService: {
findUserByKakaoTalkId,
} as Partial<DakaoUserService>,
});
const segments = await handler.handle(baseParams);
expect(findUserByKakaoTalkId).toHaveBeenCalledWith({
communityId: baseParams.communityId,
kakaoTalkId: 'kakao-user-1',
});
expect(cancelJoin).toHaveBeenCalledWith({
matchId: expect.any(mongoose.Types.ObjectId),
userId: expect.any(mongoose.Types.ObjectId),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('참가 취소 완료 (2/10)'),
});
});
it('resolves cancellation by short code', async () => {
const matchId = objectId('333333333333333333333333');
const cancelJoin = jest.fn().mockResolvedValue({
title: '저녁 내전',
participants: [{}, {}],
maxParticipants: 10,
});
const findUserByKakaoTalkId = jest.fn().mockResolvedValue({
_id: objectId('222222222222222222222222'),
});
const handler = makeHandler({
matchService: {
cancelJoin,
list: jest.fn().mockResolvedValue([
{ _id: matchId, title: '저녁 내전', shortCode: 'AB12' },
]),
} as Partial<MatchService>,
dakaoUserService: {
findUserByKakaoTalkId,
} as Partial<DakaoUserService>,
});
await handler.handle({
...baseParams,
matchId: 'AB12',
});
expect(cancelJoin).toHaveBeenCalledWith({
matchId,
userId: expect.any(mongoose.Types.ObjectId),
});
});
it('asks unregistered user to register first', async () => {
const cancelJoin = jest.fn();
const handler = makeHandler({
matchService: { cancelJoin } as Partial<MatchService>,
dakaoUserService: {
findUserByKakaoTalkId: jest.fn().mockResolvedValue(null),
} as Partial<DakaoUserService>,
});
const segments = await handler.handle(baseParams);
expect(cancelJoin).not.toHaveBeenCalled();
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('계정을 등록'),
});
});
it('translates not-joined cancellation errors', async () => {
const handler = makeHandler({
matchService: {
cancelJoin: jest
.fn()
.mockRejectedValue(
new BadRequestException('User has not joined this match.'),
),
} as Partial<MatchService>,
dakaoUserService: {
findUserByKakaoTalkId: jest.fn().mockResolvedValue({
_id: objectId('222222222222222222222222'),
}),
} as Partial<DakaoUserService>,
});
const segments = await handler.handle(baseParams);
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('신청한 내전이 아닙니다'),
});
});
});
@@ -0,0 +1,126 @@
import {
BadRequestException,
Injectable,
NotFoundException,
} from '@nestjs/common';
import mongoose from 'mongoose';
import { MatchService } from '../../match/match.service';
import { DakaoSegment } from '../dakao.types';
import { DakaoUserService } from '../dakao-user.service';
import { resolveRecruitingMatchReference } from './match-reference.util';
interface CancelHandlerParams {
communityId: mongoose.Types.ObjectId;
matchId: string;
senderUserId: string; // kakaoTalkId
senderNickname: string; // kakaoTalkNickname
}
@Injectable()
export class MatchCancelHandler {
constructor(
private readonly matchService: MatchService,
private readonly dakaoUserService: DakaoUserService,
) {}
public async handle(params: CancelHandlerParams): Promise<DakaoSegment[]> {
const user = await this.dakaoUserService.findUserByKakaoTalkId({
communityId: params.communityId,
kakaoTalkId: params.senderUserId,
});
if (!user) {
return this.errorReply(
params,
'먼저 !내전 계정등록 <닉네임>#<태그> 로 계정을 등록해주세요.',
);
}
const matchTarget = await this.resolveCancelTarget(params);
if (typeof matchTarget === 'string') {
return this.errorReply(params, matchTarget);
}
try {
const match = await this.matchService.cancelJoin({
matchId: matchTarget,
userId: user._id,
});
return [
{
kind: 'mention',
userId: params.senderUserId,
displayText: params.senderNickname,
},
{
kind: 'text',
text:
` 참가 취소 완료 (${match.participants.length}/${match.maxParticipants})` +
`\n내전: ${match.title}`,
},
];
} catch (err) {
if (err instanceof NotFoundException) {
return this.errorReply(params, '내전을 찾을 수 없습니다.');
}
if (err instanceof BadRequestException) {
return this.errorReply(params, this.translateBadRequest(err.message));
}
throw err;
}
}
private async resolveCancelTarget(
params: CancelHandlerParams,
): Promise<mongoose.Types.ObjectId | string> {
if (mongoose.isValidObjectId(params.matchId)) {
return new mongoose.Types.ObjectId(params.matchId);
}
const recruitingMatches = await this.matchService.list({
communityId: params.communityId,
status: 'recruiting',
limit: 50,
});
if (recruitingMatches.length === 0) {
return '모집 중인 내전이 없습니다.';
}
const result = resolveRecruitingMatchReference(
params.matchId,
recruitingMatches,
);
if (result.kind === 'matched') {
return result.match._id;
}
if (result.kind === 'ambiguous') {
return `내전 코드 또는 제목이 여러 개와 겹칩니다 (${result.titles.join(', ')}). 더 길게 입력하거나 ID를 사용해주세요.`;
}
return '모집 중인 내전을 찾을 수 없습니다. !내전 리스트에서 코드 또는 제목을 확인해주세요.';
}
private errorReply(
params: CancelHandlerParams,
message: string,
): DakaoSegment[] {
return [
{
kind: 'mention',
userId: params.senderUserId,
displayText: params.senderNickname,
},
{ kind: 'text', text: ` ${message}` },
];
}
private translateBadRequest(raw: string): string {
if (raw.includes('different communities')) {
return '이 내전은 현재 채팅방의 커뮤니티 소속이 아닙니다.';
}
if (raw.includes('not recruiting')) {
return '모집 중인 내전만 참가 취소할 수 있습니다.';
}
if (raw.includes('has not joined')) return '신청한 내전이 아닙니다.';
return raw;
}
}
@@ -12,10 +12,12 @@ function makeHandler(overrides?: {
}): MatchJoinHandler {
const matchService = {
join: jest.fn(),
list: jest.fn(),
...overrides?.matchService,
} as unknown as MatchService;
const dakaoUserService = {
resolveRiotAccount: jest.fn(),
findUserByKakaoTalkId: jest.fn(),
...overrides?.dakaoUserService,
} as unknown as DakaoUserService;
return new MatchJoinHandler(matchService, dakaoUserService);
@@ -23,27 +25,37 @@ function makeHandler(overrides?: {
const baseParams = {
communityId: objectId('111111111111111111111111'),
matchId: '69b63bc96da18dfdb218ee8c',
matchAndRiotId: '69b63bc96da18dfdb218ee8c 프리리#KR1',
senderUserId: 'kakao-user-1',
senderNickname: '프리리',
gameName: '프리리',
tagLine: 'KR1',
positions: ['MID', 'TOP'] as const,
};
describe('MatchJoinHandler', () => {
it('rejects invalid match id without touching services', async () => {
const handler = makeHandler();
it('rejects missing match reference when multiple matches are recruiting', async () => {
const resolveRiotAccount = jest.fn();
const handler = makeHandler({
matchService: {
list: jest.fn().mockResolvedValue([
{ _id: objectId('333333333333333333333333'), title: '저녁 내전' },
{ _id: objectId('444444444444444444444444'), title: '심야 내전' },
]),
} as Partial<MatchService>,
dakaoUserService: {
resolveRiotAccount,
} as Partial<DakaoUserService>,
});
const segments = await handler.handle({
...baseParams,
matchId: 'not-an-id',
matchAndRiotId: '프리리#KR1',
positions: [...baseParams.positions],
});
expect(resolveRiotAccount).not.toHaveBeenCalled();
expect(segments).toEqual([
expect.objectContaining({ kind: 'mention', userId: 'kakao-user-1' }),
expect.objectContaining({
kind: 'text',
text: expect.stringContaining('유효하지 않은 내전 ID'),
text: expect.stringContaining('코드 또는 제목'),
}),
]);
});
@@ -92,6 +104,245 @@ describe('MatchJoinHandler', () => {
});
});
it('uses the only recruiting match when match reference is omitted', async () => {
const matchId = objectId('333333333333333333333333');
const join = jest.fn().mockResolvedValue({
title: '저녁 내전',
participants: [{}],
maxParticipants: 10,
});
const handler = makeHandler({
matchService: {
list: jest
.fn()
.mockResolvedValue([{ _id: matchId, title: '저녁 내전' }]),
join,
} as Partial<MatchService>,
dakaoUserService: {
resolveRiotAccount: jest.fn().mockResolvedValue({
user: { _id: objectId('222222222222222222222222') },
riotAccount: { puuid: 'puuid-1', gameName: '프리리', tagLine: 'KR1' },
}),
} as Partial<DakaoUserService>,
});
const segments = await handler.handle({
...baseParams,
matchAndRiotId: '프리리#KR1',
positions: [...baseParams.positions],
});
expect(join).toHaveBeenCalledWith(
expect.objectContaining({
matchId,
}),
);
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('신청 완료 (1/10)'),
});
});
it('resolves a unique recruiting match by title prefix', async () => {
const matchId = objectId('333333333333333333333333');
const join = jest.fn().mockResolvedValue({
title: '저녁 내전',
participants: [{}],
maxParticipants: 10,
});
const handler = makeHandler({
matchService: {
list: jest.fn().mockResolvedValue([
{ _id: matchId, title: '저녁 내전' },
{ _id: objectId('444444444444444444444444'), title: '심야 내전' },
]),
join,
} as Partial<MatchService>,
dakaoUserService: {
resolveRiotAccount: jest.fn().mockResolvedValue({
user: { _id: objectId('222222222222222222222222') },
riotAccount: { puuid: 'puuid-1', gameName: '프리리', tagLine: 'KR1' },
}),
} as Partial<DakaoUserService>,
});
await handler.handle({
...baseParams,
matchAndRiotId: '저녁 프리리#KR1',
positions: [...baseParams.positions],
});
expect(join).toHaveBeenCalledWith(
expect.objectContaining({
matchId,
}),
);
});
it('resolves a recruiting match by short code', async () => {
const matchId = objectId('333333333333333333333333');
const join = jest.fn().mockResolvedValue({
title: '저녁 내전',
participants: [{}],
maxParticipants: 10,
});
const handler = makeHandler({
matchService: {
list: jest.fn().mockResolvedValue([
{ _id: matchId, title: '저녁 내전', shortCode: 'AB12' },
{
_id: objectId('444444444444444444444444'),
title: '심야 내전',
shortCode: 'CD34',
},
]),
join,
} as Partial<MatchService>,
dakaoUserService: {
resolveRiotAccount: jest.fn().mockResolvedValue({
user: { _id: objectId('222222222222222222222222') },
riotAccount: { puuid: 'puuid-1', gameName: '프리리', tagLine: 'KR1' },
}),
} as Partial<DakaoUserService>,
});
await handler.handle({
...baseParams,
matchAndRiotId: 'AB12 프리리#KR1',
positions: [...baseParams.positions],
});
expect(join).toHaveBeenCalledWith(
expect.objectContaining({
matchId,
}),
);
});
it('uses registered account and preferred positions for abbreviated join', async () => {
const matchId = objectId('333333333333333333333333');
const userId = objectId('222222222222222222222222');
const join = jest.fn().mockResolvedValue({
title: '저녁 내전',
participants: [{}],
maxParticipants: 10,
});
const resolveRiotAccount = jest.fn();
const handler = makeHandler({
matchService: {
list: jest.fn().mockResolvedValue([
{ _id: matchId, title: '저녁 내전', shortCode: 'AB12' },
]),
join,
} as Partial<MatchService>,
dakaoUserService: {
resolveRiotAccount,
findUserByKakaoTalkId: jest.fn().mockResolvedValue({
_id: userId,
riotAccounts: [
{
puuid: 'puuid-1',
gameName: '프리리',
tagLine: 'KR1',
isPrimary: true,
},
],
preferredPositions: [
{ position: 'MID', priority: 1 },
{ position: 'JGL', priority: 2 },
],
}),
} as Partial<DakaoUserService>,
});
const segments = await handler.handle({
...baseParams,
matchAndRiotId: 'AB12',
positions: undefined,
});
expect(resolveRiotAccount).not.toHaveBeenCalled();
expect(join).toHaveBeenCalledWith({
matchId,
userId,
preferredPositions: [
{ position: 'MID', priority: 1 },
{ position: 'JGL', priority: 2 },
],
riotPuuid: 'puuid-1',
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('계정: 프리리#KR1'),
});
});
it('asks abbreviated join users to register missing preferred positions', async () => {
const matchId = objectId('333333333333333333333333');
const join = jest.fn();
const handler = makeHandler({
matchService: {
list: jest.fn().mockResolvedValue([
{ _id: matchId, title: '저녁 내전', shortCode: 'AB12' },
]),
join,
} as Partial<MatchService>,
dakaoUserService: {
findUserByKakaoTalkId: jest.fn().mockResolvedValue({
_id: objectId('222222222222222222222222'),
riotAccounts: [
{
puuid: 'puuid-1',
gameName: '프리리',
tagLine: 'KR1',
isPrimary: true,
},
],
preferredPositions: [],
}),
} as Partial<DakaoUserService>,
});
const segments = await handler.handle({
...baseParams,
matchAndRiotId: 'AB12',
positions: undefined,
});
expect(join).not.toHaveBeenCalled();
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('선호포지션등록'),
});
});
it('rejects ambiguous title prefixes', async () => {
const resolveRiotAccount = jest.fn();
const handler = makeHandler({
matchService: {
list: jest.fn().mockResolvedValue([
{ _id: objectId('333333333333333333333333'), title: '저녁 내전 A' },
{ _id: objectId('444444444444444444444444'), title: '저녁 내전 B' },
]),
} as Partial<MatchService>,
dakaoUserService: {
resolveRiotAccount,
} as Partial<DakaoUserService>,
});
const segments = await handler.handle({
...baseParams,
matchAndRiotId: '저녁 프리리#KR1',
positions: [...baseParams.positions],
});
expect(resolveRiotAccount).not.toHaveBeenCalled();
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('여러 개와 겹칩니다'),
});
});
it('translates riot_account_not_found errors', async () => {
const handler = makeHandler({
dakaoUserService: {
@@ -5,18 +5,30 @@ import {
} from '@nestjs/common';
import mongoose from 'mongoose';
import { MatchService } from '../../match/match.service';
import { Position, PositionPreference } from '../../global/database/schema';
import {
MatchDocument,
Position,
PositionPreference,
RiotAccount,
UserDocument,
} from '../../global/database/schema';
import { DakaoSegment } from '../dakao.types';
import { DakaoUserError, DakaoUserService } from '../dakao-user.service';
import { normalizeRiotIdPart } from '../riot-id.util';
import { resolveRecruitingMatchReference } from './match-reference.util';
interface JoinHandlerParams {
communityId: mongoose.Types.ObjectId;
matchId: string;
matchAndRiotId: string;
senderUserId: string; // kakaoTalkId
senderNickname: string; // kakaoTalkNickname
gameName: string;
tagLine: string;
positions: Position[];
positions?: Position[];
}
interface ResolvedJoinTarget {
matchId: mongoose.Types.ObjectId;
gameName?: string;
tagLine?: string;
}
@Injectable()
@@ -27,34 +39,46 @@ export class MatchJoinHandler {
) {}
public async handle(params: JoinHandlerParams): Promise<DakaoSegment[]> {
if (!mongoose.isValidObjectId(params.matchId)) {
return this.errorReply(params, '유효하지 않은 내전 ID 입니다.');
const joinTarget = await this.resolveJoinTarget(params);
if (typeof joinTarget === 'string') {
return this.errorReply(params, joinTarget);
}
const matchObjectId = new mongoose.Types.ObjectId(params.matchId);
let resolved;
let resolved:
| { user: UserDocument; riotAccount: RiotAccount }
| string;
try {
resolved = await this.dakaoUserService.resolveRiotAccount({
communityId: params.communityId,
kakaoTalkId: params.senderUserId,
kakaoTalkNickname: params.senderNickname,
gameName: params.gameName,
tagLine: params.tagLine,
});
resolved =
joinTarget.gameName && joinTarget.tagLine
? await this.dakaoUserService.resolveRiotAccount({
communityId: params.communityId,
kakaoTalkId: params.senderUserId,
kakaoTalkNickname: params.senderNickname,
gameName: joinTarget.gameName,
tagLine: joinTarget.tagLine,
})
: await this.resolveRegisteredRiotAccount(params);
} catch (err) {
if (err instanceof DakaoUserError) {
return this.errorReply(params, this.translateUserError(err));
}
throw err;
}
if (typeof resolved === 'string') {
return this.errorReply(params, resolved);
}
const preferredPositions: PositionPreference[] = params.positions.map(
(position, index) => ({ position, priority: index + 1 }),
const preferredPositions = this.resolvePreferredPositions(
params.positions,
resolved.user.preferredPositions,
);
if (typeof preferredPositions === 'string') {
return this.errorReply(params, preferredPositions);
}
try {
const match = await this.matchService.join({
matchId: matchObjectId,
matchId: joinTarget.matchId,
userId: resolved.user._id,
preferredPositions,
riotPuuid: resolved.riotAccount.puuid,
@@ -72,7 +96,9 @@ export class MatchJoinHandler {
` 신청 완료 (${match.participants.length}/${match.maxParticipants})` +
`\n내전: ${match.title}` +
`\n계정: ${resolved.riotAccount.gameName}#${resolved.riotAccount.tagLine}` +
`\n포지션: ${params.positions.join(', ')}`,
`\n포지션: ${preferredPositions
.map((entry) => entry.position)
.join(', ')}`,
},
];
} catch (err) {
@@ -86,6 +112,196 @@ export class MatchJoinHandler {
}
}
private async resolveJoinTarget(
params: JoinHandlerParams,
): Promise<ResolvedJoinTarget | string> {
if (!params.matchAndRiotId.includes('#')) {
return this.resolveJoinTargetWithoutRiotId(params);
}
const riotId = this.parseRiotId(params.matchAndRiotId);
if (typeof riotId === 'string') return riotId;
const objectIdMatch = riotId.gameNameWithOptionalMatchRef.match(
/^([a-f0-9]{24})(?:\s+(.+))?$/i,
);
if (objectIdMatch) {
const gameName = normalizeRiotIdPart(objectIdMatch[2] ?? '');
if (!gameName) {
return '라이엇 ID 형식이 올바르지 않습니다 (예: 프리리#KR1).';
}
return {
matchId: new mongoose.Types.ObjectId(objectIdMatch[1]),
gameName,
tagLine: riotId.tagLine,
};
}
const recruitingMatches = await this.matchService.list({
communityId: params.communityId,
status: 'recruiting',
limit: 50,
});
if (recruitingMatches.length === 0) {
return '모집 중인 내전이 없습니다.';
}
const titleTarget = this.resolveTitleTarget(
riotId.gameNameWithOptionalMatchRef,
recruitingMatches,
);
if (titleTarget.kind === 'matched') {
return {
matchId: titleTarget.match._id,
gameName: titleTarget.gameName,
tagLine: riotId.tagLine,
};
}
if (titleTarget.kind === 'ambiguous') {
return `내전 코드 또는 제목이 여러 개와 겹칩니다 (${titleTarget.titles.join(', ')}). 더 길게 입력하거나 ID를 사용해주세요.`;
}
if (recruitingMatches.length === 1) {
return {
matchId: recruitingMatches[0]._id,
gameName: riotId.gameNameWithOptionalMatchRef,
tagLine: riotId.tagLine,
};
}
return '모집 중인 내전을 찾을 수 없습니다. !내전 리스트에서 코드 또는 제목을 확인해주세요.';
}
private async resolveJoinTargetWithoutRiotId(
params: JoinHandlerParams,
): Promise<ResolvedJoinTarget | string> {
const reference = params.matchAndRiotId.trim();
if (/^[a-f0-9]{24}$/i.test(reference)) {
return {
matchId: new mongoose.Types.ObjectId(reference),
};
}
const recruitingMatches = await this.matchService.list({
communityId: params.communityId,
status: 'recruiting',
limit: 50,
});
if (recruitingMatches.length === 0) {
return '모집 중인 내전이 없습니다.';
}
if (!reference) {
if (recruitingMatches.length === 1) {
return { matchId: recruitingMatches[0]._id };
}
return '모집 중인 내전이 여러 개입니다. !내전 일정에서 코드 또는 제목을 확인해주세요.';
}
const result = resolveRecruitingMatchReference(
reference,
recruitingMatches,
);
if (result.kind === 'matched') {
return { matchId: result.match._id };
}
if (result.kind === 'ambiguous') {
return `내전 코드 또는 제목이 여러 개와 겹칩니다 (${result.titles.join(', ')}). 더 길게 입력하거나 ID를 사용해주세요.`;
}
return '모집 중인 내전을 찾을 수 없습니다. !내전 일정에서 코드 또는 제목을 확인해주세요.';
}
private parseRiotId(
value: string,
): { gameNameWithOptionalMatchRef: string; tagLine: string } | string {
const hashIndex = value.lastIndexOf('#');
if (hashIndex <= 0 || hashIndex === value.length - 1) {
return '라이엇 ID 형식이 올바르지 않습니다 (예: 프리리#KR1).';
}
const gameNameWithOptionalMatchRef = normalizeRiotIdPart(
value.slice(0, hashIndex),
);
const tagLine = normalizeRiotIdPart(value.slice(hashIndex + 1));
if (!gameNameWithOptionalMatchRef || !tagLine) {
return '라이엇 ID 형식이 올바르지 않습니다 (예: 프리리#KR1).';
}
return { gameNameWithOptionalMatchRef, tagLine };
}
private resolveTitleTarget(
value: string,
matches: MatchDocument[],
):
| { kind: 'matched'; match: MatchDocument; gameName: string }
| { kind: 'ambiguous'; titles: string[] }
| { kind: 'not-found' } {
let ambiguousTitles: string[] | null = null;
for (const splitAt of splitPositionsFromRight(value)) {
const matchTitlePrefix = value.slice(0, splitAt).trim();
const gameName = normalizeRiotIdPart(value.slice(splitAt + 1));
if (!matchTitlePrefix || !gameName) continue;
const result = resolveRecruitingMatchReference(
matchTitlePrefix,
matches,
);
if (result.kind === 'matched') {
return { kind: 'matched', match: result.match, gameName };
}
if (result.kind === 'ambiguous') {
ambiguousTitles = result.titles;
}
}
return ambiguousTitles
? { kind: 'ambiguous', titles: ambiguousTitles }
: { kind: 'not-found' };
}
private async resolveRegisteredRiotAccount(
params: JoinHandlerParams,
): Promise<{ user: UserDocument; riotAccount: RiotAccount } | string> {
const user = await this.dakaoUserService.findUserByKakaoTalkId({
communityId: params.communityId,
kakaoTalkId: params.senderUserId,
});
if (!user) {
return '먼저 !내전 계정등록 <닉네임>#<태그> 로 계정을 등록해주세요.';
}
const riotAccount =
user.riotAccounts.find((account) => account.isPrimary) ??
user.riotAccounts[0];
if (!riotAccount) {
return '먼저 !내전 계정등록 <닉네임>#<태그> 로 계정을 등록해주세요.';
}
return { user, riotAccount };
}
private resolvePreferredPositions(
inputPositions: Position[] | undefined,
registeredPositions: PositionPreference[],
): PositionPreference[] | string {
if (inputPositions?.length) {
return inputPositions.map((position, index) => ({
position,
priority: index + 1,
}));
}
const preferredPositions = [...(registeredPositions ?? [])]
.sort((left, right) => left.priority - right.priority)
.filter((entry) => entry.position);
if (preferredPositions.length < 2) {
return '선호포지션을 입력하거나 !내전 선호포지션등록 미드,정글 로 먼저 등록해주세요.';
}
return preferredPositions;
}
private errorReply(
params: JoinHandlerParams,
message: string,
@@ -126,3 +342,11 @@ export class MatchJoinHandler {
return raw;
}
}
function splitPositionsFromRight(value: string): number[] {
const positions: number[] = [];
for (let index = value.length - 1; index >= 0; index -= 1) {
if (/\s/.test(value[index])) positions.push(index);
}
return positions;
}
@@ -0,0 +1,122 @@
import mongoose from 'mongoose';
import { MatchService } from '../../match/match.service';
import { DakaoUrlShortenerService } from '../dakao-url-shortener.service';
import { MatchListHandler } from './match-list.handler';
const objectId = (hex: string) => new mongoose.Types.ObjectId(hex);
function makeHandler(params: {
matchService: Partial<MatchService>;
urlShortener?: Partial<DakaoUrlShortenerService>;
}): MatchListHandler {
return new MatchListHandler(
params.matchService as MatchService,
{
shortenMatchLink: jest.fn().mockResolvedValue(undefined),
buildMatchDetailUrl: jest.fn(
(matchId: string) => `https://lolympus.dahyeon.us/match/${matchId}`,
),
...params.urlShortener,
} as unknown as DakaoUrlShortenerService,
);
}
describe('MatchListHandler', () => {
it('prints short codes, compact KST dates, and short links', async () => {
const match = {
_id: objectId('333333333333333333333333'),
title: '토요 내전',
shortCode: 'AB12',
participants: [{}, {}],
maxParticipants: 10,
scheduledAt: new Date('2026-05-02T10:30:00.000Z'),
};
const matchService = {
list: jest.fn().mockResolvedValue([match]),
ensureShortCode: jest.fn().mockResolvedValue(match),
};
const urlShortener = {
shortenMatchLink: jest
.fn()
.mockResolvedValue('https://go.dahyeon.us/lmtpAB12'),
};
const handler = makeHandler({ matchService, urlShortener });
const segments = await handler.handle({
communityId: objectId('111111111111111111111111'),
senderUserId: 'kakao-user-1',
senderNickname: '프리리',
});
expect(matchService.ensureShortCode).toHaveBeenCalledWith(match);
expect(urlShortener.shortenMatchLink).toHaveBeenCalledWith({
matchId: '333333333333333333333333',
shortCode: 'AB12',
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('토요 내전 (2/10) 5/2 19:30'),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('코드: AB12'),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('링크: https://go.dahyeon.us/lmtpAB12'),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.not.stringContaining('2026-05-02'),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.not.stringContaining('ID:'),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.not.stringContaining('계정등록:'),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.not.stringContaining('신청:'),
});
});
it('falls back to a direct match detail link when short link creation is skipped', async () => {
const match = {
_id: objectId('333333333333333333333333'),
title: '토요 내전',
shortCode: 'AB12',
participants: [],
maxParticipants: 10,
scheduledAt: new Date('2026-05-02T10:30:00.000Z'),
};
const handler = makeHandler({
matchService: {
list: jest.fn().mockResolvedValue([match]),
ensureShortCode: jest.fn().mockResolvedValue(match),
},
urlShortener: {
shortenMatchLink: jest.fn().mockResolvedValue(undefined),
},
});
const segments = await handler.handle({
communityId: objectId('111111111111111111111111'),
senderUserId: 'kakao-user-1',
senderNickname: '프리리',
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('코드: AB12'),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining(
'링크: https://lolympus.dahyeon.us/match/333333333333333333333333',
),
});
});
});
@@ -1,11 +1,18 @@
import { Injectable } from '@nestjs/common';
import { Injectable, Logger } from '@nestjs/common';
import mongoose from 'mongoose';
import { MatchDocument } from '../../global/database/schema';
import { MatchService } from '../../match/match.service';
import { DakaoSegment } from '../dakao.types';
import { DakaoUrlShortenerService } from '../dakao-url-shortener.service';
@Injectable()
export class MatchListHandler {
constructor(private readonly matchService: MatchService) {}
private readonly logger = new Logger(MatchListHandler.name);
constructor(
private readonly matchService: MatchService,
private readonly urlShortener: DakaoUrlShortenerService,
) {}
public async handle(params: {
communityId: mongoose.Types.ObjectId;
@@ -29,13 +36,20 @@ export class MatchListHandler {
];
}
const lines = matches.map((m, i) => {
const id = (m._id as mongoose.Types.ObjectId).toString();
const filled = m.participants.length;
const cap = m.maxParticipants;
const time = formatScheduledAt(m.scheduledAt);
return `\n${i + 1}. ${m.title} (${filled}/${cap}) ${time}\n ID: ${id}`;
});
const matchesWithCodes = await Promise.all(
matches.map((match) => this.matchService.ensureShortCode(match)),
);
const lines = await Promise.all(
matchesWithCodes.map(async (m, i) => {
const filled = m.participants.length;
const cap = m.maxParticipants;
const time = formatScheduledAt(m.scheduledAt);
const shortUrl = await this.createShortUrl(m);
const linkLine = shortUrl ? `\n 링크: ${shortUrl}` : '';
return `\n${i + 1}. ${m.title} (${filled}/${cap}) ${time}\n 코드: ${m.shortCode}${linkLine}`;
}),
);
return [
{
@@ -45,19 +59,37 @@ export class MatchListHandler {
},
{
kind: 'text',
text: ` 모집 중인 내전 ${matches.length}건${lines.join('')}\n계정등록: !내전 계정등록 <닉네임>#<태그>\n신청: !내전 신청 <ID> <닉네임>#<태그> <포지션1>,<포지션2>`,
text: ` 모집 중인 내전 ${matches.length}건${lines.join('')}`,
},
];
}
private async createShortUrl(
match: MatchDocument,
): Promise<string | undefined> {
try {
const shortUrl = await this.urlShortener.shortenMatchLink({
matchId: String(match._id),
shortCode: match.shortCode,
});
return (
shortUrl ?? this.urlShortener.buildMatchDetailUrl(String(match._id))
);
} catch (error) {
this.logger.warn(
`Failed to create dakao match short URL for match="${String(match._id)}": ${error instanceof Error ? error.message : String(error)}`,
);
return this.urlShortener.buildMatchDetailUrl(String(match._id));
}
}
}
function formatScheduledAt(date: Date): string {
// YYYY-MM-DD HH:mm (KST 표기)
// M/D HH:mm (KST 표기)
const kst = new Date(date.getTime() + 9 * 60 * 60 * 1000);
const yyyy = kst.getUTCFullYear();
const mm = String(kst.getUTCMonth() + 1).padStart(2, '0');
const dd = String(kst.getUTCDate()).padStart(2, '0');
const month = kst.getUTCMonth() + 1;
const day = kst.getUTCDate();
const hh = String(kst.getUTCHours()).padStart(2, '0');
const mi = String(kst.getUTCMinutes()).padStart(2, '0');
return `${yyyy}-${mm}-${dd} ${hh}:${mi}`;
return `${month}/${day} ${hh}:${mi}`;
}
@@ -0,0 +1,63 @@
import type { MatchDocument } from '../../global/database/schema';
export type MatchReferenceResult =
| { kind: 'matched'; match: MatchDocument }
| { kind: 'ambiguous'; titles: string[] }
| { kind: 'not-found' };
export function resolveRecruitingMatchReference(
reference: string,
matches: MatchDocument[],
): MatchReferenceResult {
const normalizedCode = normalizeShortCode(reference);
const codeMatches = matches.filter(
(match) =>
match.shortCode && normalizeShortCode(match.shortCode) === normalizedCode,
);
if (codeMatches.length === 1) {
return { kind: 'matched', match: codeMatches[0] };
}
if (codeMatches.length > 1) {
return {
kind: 'ambiguous',
titles: codeMatches.map((match) => match.title),
};
}
const normalizedReference = normalizeLookup(reference);
const exactMatches = matches.filter(
(match) => normalizeLookup(match.title) === normalizedReference,
);
if (exactMatches.length === 1) {
return { kind: 'matched', match: exactMatches[0] };
}
if (exactMatches.length > 1) {
return {
kind: 'ambiguous',
titles: exactMatches.map((match) => match.title),
};
}
const prefixMatches = matches.filter((match) =>
normalizeLookup(match.title).startsWith(normalizedReference),
);
if (prefixMatches.length === 1) {
return { kind: 'matched', match: prefixMatches[0] };
}
if (prefixMatches.length > 1) {
return {
kind: 'ambiguous',
titles: prefixMatches.map((match) => match.title),
};
}
return { kind: 'not-found' };
}
function normalizeLookup(value: string): string {
return value.normalize('NFC').trim().replace(/\s+/g, ' ').toLowerCase();
}
function normalizeShortCode(value: string): string {
return value.normalize('NFC').trim().replace(/\s+/g, '').toUpperCase();
}
@@ -0,0 +1,41 @@
import mongoose from 'mongoose';
import { DakaoUserService } from '../dakao-user.service';
import { PreferredPositionRegisterHandler } from './preferred-position-register.handler';
const objectId = (hex: string) => new mongoose.Types.ObjectId(hex);
describe('PreferredPositionRegisterHandler', () => {
it('registers preferred positions for abbreviated joins', async () => {
const registerPreferredPositions = jest.fn().mockResolvedValue({
preferredPositions: [
{ position: 'MID', priority: 1 },
{ position: 'JGL', priority: 2 },
],
});
const handler = new PreferredPositionRegisterHandler({
registerPreferredPositions,
} as unknown as DakaoUserService);
const segments = await handler.handle({
communityId: objectId('111111111111111111111111'),
senderUserId: 'kakao-user-1',
senderNickname: '프리리',
positions: ['MID', 'JGL'],
});
expect(registerPreferredPositions).toHaveBeenCalledWith({
communityId: objectId('111111111111111111111111'),
kakaoTalkId: 'kakao-user-1',
kakaoTalkNickname: '프리리',
positions: ['MID', 'JGL'],
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('선호 포지션 등록 완료'),
});
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('!내전 신청 <내전코드>'),
});
});
});
@@ -0,0 +1,54 @@
import { Injectable } from '@nestjs/common';
import mongoose from 'mongoose';
import { Position } from '../../global/database/schema';
import { DakaoSegment } from '../dakao.types';
import { DakaoUserService } from '../dakao-user.service';
const POSITION_LABELS: Record<Position, string> = {
TOP: '탑',
JGL: '정글',
MID: '미드',
ADC: '원딜',
SUP: '서포터',
};
interface PreferredPositionRegisterHandlerParams {
communityId: mongoose.Types.ObjectId;
senderUserId: string;
senderNickname: string;
positions: Position[];
}
@Injectable()
export class PreferredPositionRegisterHandler {
constructor(private readonly dakaoUserService: DakaoUserService) {}
public async handle(
params: PreferredPositionRegisterHandlerParams,
): Promise<DakaoSegment[]> {
const user = await this.dakaoUserService.registerPreferredPositions({
communityId: params.communityId,
kakaoTalkId: params.senderUserId,
kakaoTalkNickname: params.senderNickname,
positions: params.positions,
});
return [
{
kind: 'mention',
userId: params.senderUserId,
displayText: params.senderNickname,
},
{
kind: 'text',
text:
` 선호 포지션 등록 완료` +
`\n포지션: ${user.preferredPositions
.sort((left, right) => left.priority - right.priority)
.map((entry) => POSITION_LABELS[entry.position])
.join(', ')}` +
`\n이제 !내전 신청 <내전코드> 로 간단히 신청할 수 있습니다.`,
},
];
}
}
@@ -0,0 +1,73 @@
import mongoose from 'mongoose';
import { DakaoUserError, DakaoUserService } from '../dakao-user.service';
import { PrimaryAccountChangeHandler } from './primary-account-change.handler';
const objectId = (hex: string) => new mongoose.Types.ObjectId(hex);
function makeHandler(dakaoUserService?: Partial<DakaoUserService>) {
return new PrimaryAccountChangeHandler({
changePrimaryRiotAccount: jest.fn(),
...dakaoUserService,
} as unknown as DakaoUserService);
}
const baseParams = {
communityId: objectId('111111111111111111111111'),
senderUserId: 'kakao-user-1',
senderNickname: '프리리',
gameName: '프리리',
tagLine: 'KR1',
};
describe('PrimaryAccountChangeHandler', () => {
it('changes the primary Riot account through DakaoUserService', async () => {
const changePrimaryRiotAccount = jest.fn().mockResolvedValue({
user: { _id: objectId('222222222222222222222222') },
riotAccount: { gameName: '프리리', tagLine: 'KR1' },
});
const handler = makeHandler({
changePrimaryRiotAccount,
});
const segments = await handler.handle(baseParams);
expect(changePrimaryRiotAccount).toHaveBeenCalledWith({
communityId: baseParams.communityId,
kakaoTalkId: 'kakao-user-1',
kakaoTalkNickname: '프리리',
gameName: '프리리',
tagLine: 'KR1',
});
expect(segments).toEqual([
expect.objectContaining({ kind: 'mention', userId: 'kakao-user-1' }),
expect.objectContaining({
kind: 'text',
text: expect.stringContaining('대표 계정 변경 완료'),
}),
]);
expect(segments[1]).toMatchObject({
kind: 'text',
text: expect.stringContaining('대표 계정: 프리리#KR1'),
});
});
it('asks users to register the Riot account first when not found', async () => {
const handler = makeHandler({
changePrimaryRiotAccount: jest
.fn()
.mockRejectedValue(
new DakaoUserError('riot_account_not_found', '프리리#KR1'),
),
});
const segments = await handler.handle(baseParams);
expect(segments).toEqual([
expect.objectContaining({ kind: 'mention', userId: 'kakao-user-1' }),
expect.objectContaining({
kind: 'text',
text: expect.stringContaining('먼저 !내전 계정등록'),
}),
]);
});
});
@@ -0,0 +1,81 @@
import { Injectable } from '@nestjs/common';
import mongoose from 'mongoose';
import { DakaoSegment } from '../dakao.types';
import { DakaoUserError, DakaoUserService } from '../dakao-user.service';
interface PrimaryAccountChangeHandlerParams {
communityId: mongoose.Types.ObjectId;
senderUserId: string;
senderNickname: string;
gameName: string;
tagLine: string;
}
@Injectable()
export class PrimaryAccountChangeHandler {
constructor(private readonly dakaoUserService: DakaoUserService) {}
public async handle(
params: PrimaryAccountChangeHandlerParams,
): Promise<DakaoSegment[]> {
try {
const resolved = await this.dakaoUserService.changePrimaryRiotAccount({
communityId: params.communityId,
kakaoTalkId: params.senderUserId,
kakaoTalkNickname: params.senderNickname,
gameName: params.gameName,
tagLine: params.tagLine,
});
return [
{
kind: 'mention',
userId: params.senderUserId,
displayText: params.senderNickname,
},
{
kind: 'text',
text:
` 대표 계정 변경 완료` +
`\n대표 계정: ${resolved.riotAccount.gameName}#${resolved.riotAccount.tagLine}`,
},
];
} catch (err) {
if (err instanceof DakaoUserError) {
return this.errorReply(params, this.translateUserError(err));
}
throw err;
}
}
private errorReply(
params: PrimaryAccountChangeHandlerParams,
message: string,
): DakaoSegment[] {
return [
{
kind: 'mention',
userId: params.senderUserId,
displayText: params.senderNickname,
},
{ kind: 'text', text: ` ${message}` },
];
}
private translateUserError(err: DakaoUserError): string {
switch (err.code) {
case 'invalid_project_id':
return '커뮤니티 식별자가 올바르지 않습니다.';
case 'community_not_found':
return '연결된 커뮤니티를 찾을 수 없습니다.';
case 'riot_account_not_found':
return `등록된 라이엇 계정을 찾을 수 없습니다 (${err.detail ?? ''}). 먼저 !내전 계정등록 <닉네임>#<태그> 로 계정을 등록해주세요.`;
case 'riot_account_already_registered':
return `이미 등록된 라이엇 계정이 있습니다 (${err.detail ?? ''}).`;
case 'riot_account_conflict':
return `이미 다른 사용자가 등록한 라이엇 계정입니다 (${err.detail ?? ''}).`;
case 'riot_account_lookup_failed':
return '라이엇 계정 조회 중 오류가 발생했습니다. 잠시 후 다시 시도해주세요.';
}
}
}
@@ -9,15 +9,17 @@ describe('parseCommand', () => {
expect(parseCommand('!내전 리스트')).toEqual({ kind: 'match-list' });
});
it('parses match-list command (일정)', () => {
expect(parseCommand('!내전 일정')).toEqual({ kind: 'match-list' });
});
it('parses match-join command with simple riot id', () => {
const result = parseCommand(
'!내전 신청 69b63bc96da18dfdb218ee8c 프리리#KR1 미드,탑',
);
expect(result).toMatchObject({
kind: 'match-join',
matchId: '69b63bc96da18dfdb218ee8c',
gameName: '프리리',
tagLine: 'KR1',
matchAndRiotId: '69b63bc96da18dfdb218ee8c 프리리#KR1',
});
if (result.kind === 'match-join') {
expect(result.positions.positions).toEqual(['MID', 'TOP']);
@@ -30,12 +32,11 @@ describe('parseCommand', () => {
);
expect(result).toMatchObject({
kind: 'match-join',
gameName: 'hello world',
tagLine: 'KR1',
matchAndRiotId: '69b63bc96da18dfdb218ee8c hello world#KR1',
});
});
it('normalizes hidden unicode differences in riot id', () => {
it('parses hidden unicode differences in riot id input', () => {
const decomposedGameName = '프리리'.normalize('NFD');
const result = parseCommand(
`!내전 신청 69b63bc96da18dfdb218ee8c ${decomposedGameName}\u200B#KR1\uFEFF 미드,탑`,
@@ -43,8 +44,72 @@ describe('parseCommand', () => {
expect(result).toMatchObject({
kind: 'match-join',
gameName: '프리리',
tagLine: 'KR1',
matchAndRiotId: `69b63bc96da18dfdb218ee8c ${decomposedGameName}\u200B#KR1`,
});
});
it('parses match-join command without explicit match id', () => {
const result = parseCommand('!내전 신청 프리리#KR1 미드,탑');
expect(result).toMatchObject({
kind: 'match-join',
matchAndRiotId: '프리리#KR1',
});
});
it('parses match-join command with title prefix', () => {
const result = parseCommand('!내전 신청 저녁 프리리#KR1 미드,탑');
expect(result).toMatchObject({
kind: 'match-join',
matchAndRiotId: '저녁 프리리#KR1',
});
});
it('parses abbreviated match-join command with only match code', () => {
expect(parseCommand('!내전 신청 cab1')).toEqual({
kind: 'match-join',
matchAndRiotId: 'cab1',
});
});
it('parses match-join command with registered account and explicit positions', () => {
const result = parseCommand('!내전 신청 cab1 미드,서포터');
expect(result).toMatchObject({
kind: 'match-join',
matchAndRiotId: 'cab1',
});
if (result.kind === 'match-join') {
expect(result.positions?.positions).toEqual(['MID', 'SUP']);
}
});
it('parses preferred position registration command', () => {
const result = parseCommand('!내전 선호포지션등록 미드,SPT');
expect(result).toMatchObject({
kind: 'preferred-position-register',
});
if (result.kind === 'preferred-position-register') {
expect(result.positions.positions).toEqual(['MID', 'SUP']);
}
});
it('parses match-cancel command (취소)', () => {
expect(parseCommand('!내전 취소 69b63bc96da18dfdb218ee8c')).toEqual({
kind: 'match-cancel',
matchId: '69b63bc96da18dfdb218ee8c',
});
});
it('parses match-cancel command (참가취소)', () => {
expect(parseCommand('!내전 참가취소 69b63bc96da18dfdb218ee8c')).toEqual({
kind: 'match-cancel',
matchId: '69b63bc96da18dfdb218ee8c',
});
});
it('parses match-cancel command with short code', () => {
expect(parseCommand('!내전 취소 AB12')).toEqual({
kind: 'match-cancel',
matchId: 'AB12',
});
});
@@ -56,6 +121,25 @@ describe('parseCommand', () => {
});
});
it('parses primary account change command', () => {
expect(parseCommand('!내전 대표계정변경 프리리#KR1')).toEqual({
kind: 'primary-account-change',
gameName: '프리리',
tagLine: 'KR1',
});
});
it('normalizes primary account change riot id', () => {
const decomposedGameName = '프리리'.normalize('NFD');
expect(
parseCommand(`!내전 대표계정변경 ${decomposedGameName}\u200B#KR1\uFEFF`),
).toEqual({
kind: 'primary-account-change',
gameName: '프리리',
tagLine: 'KR1',
});
});
it('normalizes account register riot id', () => {
const decomposedGameName = '프리리'.normalize('NFD');
expect(
@@ -71,20 +155,30 @@ describe('parseCommand', () => {
expect(() => parseCommand('안녕하세요')).toThrow(/not_a_command/);
});
it('throws usage for bare command prefix', () => {
expect(() => parseCommand('!내전')).toThrow(/usage/);
});
it('throws unknown_command for unrecognized subcommands', () => {
expect(() => parseCommand('!내전 폭파')).toThrow(/unknown_command/);
});
it('throws invalid_match_id for non-objectid match', () => {
expect(() =>
it('allows non-objectid join match reference for title matching', () => {
expect(
parseCommand('!내전 신청 not-an-id 프리리#KR1 미드,탑'),
).toThrow(/invalid_match_id/);
).toMatchObject({
kind: 'match-join',
matchAndRiotId: 'not-an-id 프리리#KR1',
});
});
it('throws invalid_riot_id when # missing', () => {
expect(() =>
parseCommand('!내전 신청 69b63bc96da18dfdb218ee8c 프리리 미드,탑'),
).toThrow(/invalid_riot_id/);
it('allows match-join without riot id for registered-account flow', () => {
expect(
parseCommand('!내전 신청 69b63bc96da18dfdb218ee8c 미드,탑'),
).toMatchObject({
kind: 'match-join',
matchAndRiotId: '69b63bc96da18dfdb218ee8c',
});
});
it('throws invalid_position for too few positions', () => {
@@ -1,4 +1,8 @@
import { ParsedPositions, parsePositionList } from './position.parser';
import {
ParsedPositions,
isPositionAlias,
parsePositionList,
} from './position.parser';
import { normalizeRiotIdPart } from '../riot-id.util';
export type DakaoCommand =
@@ -9,10 +13,21 @@ export type DakaoCommand =
tagLine: string;
}
| {
kind: 'match-join';
matchId: string;
kind: 'primary-account-change';
gameName: string;
tagLine: string;
}
| {
kind: 'match-join';
matchAndRiotId: string;
positions?: ParsedPositions;
}
| {
kind: 'match-cancel';
matchId: string;
}
| {
kind: 'preferred-position-register';
positions: ParsedPositions;
};
@@ -51,17 +66,44 @@ export function parseCommand(rawMessage: string): DakaoCommand {
switch (subCommand) {
case '목록':
case '리스트':
case '일정':
return { kind: 'match-list' };
case '신청':
return parseJoinArgs(args);
case '취소':
case '참가취소':
return parseCancelArgs(args);
case '계정등록':
return parseAccountRegisterArgs(args);
case '대표계정변경':
return parsePrimaryAccountChangeArgs(args);
case '선호포지션등록':
case '포지션등록':
return parsePreferredPositionRegisterArgs(args);
default:
throw new CommandParseError('unknown_command', subCommand);
}
}
function parseAccountRegisterArgs(args: string): DakaoCommand {
const riotId = parseRiotIdArgs(args);
return {
kind: 'account-register',
gameName: riotId.gameName,
tagLine: riotId.tagLine,
};
}
function parsePrimaryAccountChangeArgs(args: string): DakaoCommand {
const riotId = parseRiotIdArgs(args);
return {
kind: 'primary-account-change',
gameName: riotId.gameName,
tagLine: riotId.tagLine,
};
}
function parseRiotIdArgs(args: string): { gameName: string; tagLine: string } {
if (args.length === 0) {
throw new CommandParseError('usage');
}
@@ -77,71 +119,84 @@ function parseAccountRegisterArgs(args: string): DakaoCommand {
throw new CommandParseError('invalid_riot_id', args);
}
return { gameName, tagLine };
}
function parseCancelArgs(args: string): DakaoCommand {
const matchId = args.trim();
if (matchId.length === 0) {
throw new CommandParseError('usage');
}
return {
kind: 'account-register',
gameName,
tagLine,
kind: 'match-cancel',
matchId,
};
}
function parseJoinArgs(args: string): DakaoCommand {
if (args.length === 0) {
throw new CommandParseError('usage');
const trimmed = args.trim();
if (trimmed.length === 0) {
return { kind: 'match-join', matchAndRiotId: '' };
}
// 마지막 토큰이 포지션 리스트(쉼표 포함). 그 앞이 라이엇 ID(공백 포함 가능). 그 앞이 matchId.
// 형식: <matchId> <gameName...>#<tagLine> <pos1>,<pos2>...
// 마지막 토큰이 포지션 리스트(쉼표 포함). 그 앞은 내전 식별자(선택)와 라이엇 ID.
// 형식: [<matchId|title...>] <gameName...>#<tagLine> <pos1>,<pos2>...
// 끝에서부터 토큰을 분리해 안정적으로 파싱한다.
const lastSpace = args.lastIndexOf(' ');
const lastSpace = trimmed.lastIndexOf(' ');
if (lastSpace === -1) {
throw new CommandParseError('usage');
}
const positionPart = args.slice(lastSpace + 1).trim();
const head = args.slice(0, lastSpace).trim();
if (positionPart.length === 0 || head.length === 0) {
throw new CommandParseError('usage');
const singlePartPositions = tryParseTrailingPositions(trimmed);
if (singlePartPositions) {
return {
kind: 'match-join',
matchAndRiotId: '',
positions: singlePartPositions,
};
}
return { kind: 'match-join', matchAndRiotId: trimmed };
}
const headSpace = head.indexOf(' ');
if (headSpace === -1) {
throw new CommandParseError('usage');
}
const matchId = head.slice(0, headSpace).trim();
const riotId = head.slice(headSpace + 1).trim();
if (!isObjectIdHex(matchId)) {
throw new CommandParseError('invalid_match_id', matchId);
}
const hashIndex = riotId.lastIndexOf('#');
if (hashIndex <= 0 || hashIndex === riotId.length - 1) {
throw new CommandParseError('invalid_riot_id', riotId);
}
const gameName = normalizeRiotIdPart(riotId.slice(0, hashIndex));
const tagLine = normalizeRiotIdPart(riotId.slice(hashIndex + 1));
if (gameName.length === 0 || tagLine.length === 0) {
throw new CommandParseError('invalid_riot_id', riotId);
}
let positions: ParsedPositions;
try {
positions = parsePositionList(positionPart);
} catch (err) {
throw new CommandParseError(
'invalid_position',
(err as Error)?.message ?? positionPart,
);
const trailingPart = trimmed.slice(lastSpace + 1).trim();
const matchAndRiotId = trimmed.slice(0, lastSpace).trim();
const positions = tryParseTrailingPositions(trailingPart);
if (positions) {
if (!matchAndRiotId) throw new CommandParseError('usage');
return {
kind: 'match-join',
matchAndRiotId,
positions,
};
}
return {
kind: 'match-join',
matchId,
gameName,
tagLine,
positions,
matchAndRiotId: trimmed,
};
}
function isObjectIdHex(value: string): boolean {
return /^[a-f0-9]{24}$/i.test(value);
function parsePreferredPositionRegisterArgs(args: string): DakaoCommand {
if (args.trim().length === 0) {
throw new CommandParseError('usage');
}
return {
kind: 'preferred-position-register',
positions: parsePositionsOrThrow(args),
};
}
function tryParseTrailingPositions(input: string): ParsedPositions | undefined {
if (!input.includes(',') && !isPositionAlias(input)) return undefined;
return parsePositionsOrThrow(input);
}
function parsePositionsOrThrow(input: string): ParsedPositions {
try {
return parsePositionList(input);
} catch (err) {
throw new CommandParseError(
'invalid_position',
(err as Error)?.message ?? input,
);
}
}
@@ -7,7 +7,7 @@ describe('parsePositionList', () => {
});
it('parses english aliases case-insensitively', () => {
const result = parsePositionList('JGL, sup');
const result = parsePositionList('JGL, SPT');
expect(result.positions).toEqual(['JGL', 'SUP']);
});
@@ -26,6 +26,8 @@ const POSITION_ALIASES: Record<string, Position> = {
// SUP
sup: 'SUP',
supp: 'SUP',
spt: 'SUP',
sp: 'SUP',
support: 'SUP',
서폿: 'SUP',
서포터: 'SUP',
@@ -71,7 +73,7 @@ export function parsePositionList(input: string): ParsedPositions {
const seen = new Set<Position>();
for (const token of tokens) {
const key = token.toLowerCase().replace(/\s+/g, '');
const key = normalizePositionAlias(token);
const mapped = POSITION_ALIASES[key];
if (!mapped) {
throw new PositionParseError('unknown', token);
@@ -85,3 +87,11 @@ export function parsePositionList(input: string): ParsedPositions {
return { positions };
}
export function isPositionAlias(input: string): boolean {
return Boolean(POSITION_ALIASES[normalizePositionAlias(input)]);
}
function normalizePositionAlias(input: string): string {
return input.toLowerCase().replace(/\s+/g, '');
}
@@ -7,7 +7,7 @@ describe('resolveMongoDbName', () => {
it('uses isolated databases for non-production environments', () => {
expect(resolveMongoDbName('dev')).toBe('lolympus-dev');
expect(resolveMongoDbName('test')).toBe('lolympus-test');
expect(resolveMongoDbName('staging')).toBe('lolympus-staging');
expect(resolveMongoDbName('')).toBe('lolympus-dev');
expect(resolveMongoDbName('local')).toBe('lolympus-dev');
});
@@ -5,7 +5,7 @@ import { tournamentModelDefinitions, TournamentModelTypes } from './schema';
export function resolveMongoDbName(nodeEnv = process.env.NODE_ENV): string {
if (nodeEnv === 'prod') return 'lolympus';
if (nodeEnv === 'test') return 'lolympus-test';
if (nodeEnv === 'staging') return 'lolympus-staging';
return 'lolympus-dev';
}
@@ -0,0 +1,102 @@
import { NestFactory } from '@nestjs/core';
import mongoose from 'mongoose';
import { AppModule } from '../../../../app.module';
import { ConnectionService } from '../connection.service';
import { MatchStatsService } from '../../../community-stats/match-stats.service';
interface Options {
communityId?: mongoose.Types.ObjectId;
dryRun: boolean;
force: boolean;
}
async function main() {
const options = parseArgs(process.argv.slice(2));
const app = await NestFactory.createApplicationContext(AppModule, {
logger: ['log', 'warn', 'error'],
});
try {
const connectionService = app.get(ConnectionService);
const matchStatsService = app.get(MatchStatsService);
const MatchModel = await connectionService.getModel('match');
const MatchStatsModel = await connectionService.getModel('matchStats');
const filter: Record<string, unknown> = {
status: { $in: ['finished', 'in-progress'] },
'result.games.0': { $exists: true },
};
if (options.communityId) filter.communityId = options.communityId;
const matches = await MatchModel.find(filter)
.sort({ scheduledAt: -1 })
.select({ _id: 1 })
.exec();
console.log(`match_stats backfill target=${matches.length}`);
let processed = 0;
let skipped = 0;
let failed = 0;
for (const match of matches) {
if (!options.force) {
const existing = await MatchStatsModel.exists({ matchId: match._id });
if (existing) {
skipped += 1;
continue;
}
}
if (options.dryRun) {
processed += 1;
continue;
}
try {
await matchStatsService.buildAndUpsert(match._id);
processed += 1;
} catch (error) {
failed += 1;
console.warn(
`failed ${match._id.toString()}: ${
error instanceof Error ? error.message : error
}`,
);
}
if ((processed + skipped + failed) % 50 === 0) {
console.log(
`progress processed=${processed} skipped=${skipped} failed=${failed}`,
);
}
}
console.log(
`done processed=${processed} skipped=${skipped} failed=${failed}`,
);
} finally {
await app.close();
}
}
function parseArgs(args: string[]): Options {
const options: Options = { dryRun: false, force: false };
for (let index = 0; index < args.length; index += 1) {
const arg = args[index];
if (arg === '--dry-run') options.dryRun = true;
if (arg === '--force') options.force = true;
if (arg === '--community-id') {
const value = args[index + 1];
if (!value || !mongoose.isValidObjectId(value)) {
throw new Error('--community-id requires a valid ObjectId');
}
options.communityId = new mongoose.Types.ObjectId(value);
index += 1;
}
}
return options;
}
void main().catch((error) => {
console.error(error);
process.exit(1);
});
@@ -0,0 +1,574 @@
import 'reflect-metadata';
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { NestFactory } from '@nestjs/core';
import mongoose from 'mongoose';
import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { ConnectionService, resolveMongoDbName } from '../connection.service';
import type {
MatchGameResult,
MatchParticipant,
MatchSeriesResult,
MatchTeam,
Position,
PositionPreference,
TeamSide,
TierInfo,
} from '../schema';
import { SecretModule } from '../../secret/secret.module';
const TEMP_JOB_ID = 'temp-finished-30-players-6-teams';
const TEAM_COUNT = 6;
const TEAM_SIZE = 5;
const TOTAL_PLAYERS = TEAM_COUNT * TEAM_SIZE;
const GAME_COUNT_PER_SERIES_GROUP = 5;
const POSITIONS: Position[] = ['TOP', 'JGL', 'MID', 'ADC', 'SUP'];
const CHAMPION_IDS = [
266, 64, 103, 222, 412, 24, 421, 134, 145, 497, 58, 121, 777, 202, 111, 39,
120, 7, 81, 89, 114, 104, 157, 51, 432, 92, 234, 61, 21, 53,
];
interface CliOptions {
communityId?: string;
dryRun: boolean;
nodeEnv: string;
replace: boolean;
scheduledAt: Date;
title: string;
}
interface TempPlayer {
userId: mongoose.Types.ObjectId;
puuid: string;
gameName: string;
tagLine: string;
profileIconId: number;
tier: TierInfo;
preferredPositions: PositionPreference[];
}
interface CommunityLean {
_id: mongoose.Types.ObjectId;
name?: 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 TempSeedModule {}
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 communityId =
process.env.VITE_DEFAULT_COMMUNITY_ID ?? process.env.DEFAULT_COMMUNITY_ID;
let dryRun = false;
let nodeEnv = process.env.NODE_ENV ?? 'dev';
let replace = false;
let scheduledAt = new Date(Date.now() - 24 * 60 * 60 * 1000);
let title = `결과 검증 임시 내전 30인 6팀 ${formatStamp(new Date())}`;
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
if (arg === '--community-id') {
const value = argv[index + 1];
if (!value) throw new Error('--community-id requires an ObjectId.');
communityId = value;
index += 1;
continue;
}
if (arg.startsWith('--community-id=')) {
communityId = arg.slice('--community-id='.length);
continue;
}
if (arg === '--dry-run') {
dryRun = true;
continue;
}
if (arg === '--env') {
const value = argv[index + 1];
if (!value) throw new Error('--env requires dev, staging, or prod.');
nodeEnv = value;
index += 1;
continue;
}
if (arg.startsWith('--env=')) {
nodeEnv = arg.slice('--env='.length);
continue;
}
if (arg === '--replace') {
replace = true;
continue;
}
if (arg === '--scheduled-at') {
scheduledAt = parseDateArg(argv[index + 1], '--scheduled-at');
index += 1;
continue;
}
if (arg.startsWith('--scheduled-at=')) {
scheduledAt = parseDateArg(
arg.slice('--scheduled-at='.length),
'--scheduled-at',
);
continue;
}
if (arg === '--title') {
const value = argv[index + 1];
if (!value) throw new Error('--title requires a value.');
title = value;
index += 1;
continue;
}
if (arg.startsWith('--title=')) {
title = arg.slice('--title='.length);
continue;
}
if (arg === '--help' || arg === '-h') {
printHelp();
process.exit(0);
}
throw new Error(`Unknown argument: ${arg}`);
}
if (!['dev', 'staging', 'prod'].includes(nodeEnv)) {
throw new Error('--env must be dev, staging, or prod.');
}
if (communityId && !mongoose.isValidObjectId(communityId)) {
throw new Error('--community-id must be a valid ObjectId.');
}
return {
communityId: communityId?.trim() || undefined,
dryRun,
nodeEnv,
replace,
scheduledAt,
title,
};
}
function parseDateArg(value: string | undefined, label: string): Date {
if (!value) throw new Error(`${label} requires an ISO date value.`);
const parsed = new Date(value);
if (Number.isNaN(parsed.getTime())) {
throw new Error(`${label} must be a valid ISO date value.`);
}
return parsed;
}
function printHelp() {
console.log(`Usage:
pnpm --filter api exec ts-node src/modules/global/database/dev-seeds/create-temp-finished-match.ts
pnpm --filter api exec ts-node src/modules/global/database/dev-seeds/create-temp-finished-match.ts --replace
Options:
--community-id <id> Community ObjectId. Defaults to env or first community.
--dry-run Print the payload summary without writing.
--env <env> dev | staging | prod. Default: NODE_ENV or dev.
--replace Delete previous temp matches created by this script first.
--scheduled-at <iso> Scheduled date. Default: yesterday.
--title <title> Match title. Default: timestamped temp title.
`);
}
async function main() {
const options = parseArgs(process.argv.slice(2));
process.env.NODE_ENV = options.nodeEnv;
await loadMachineEnvFile();
const app = await NestFactory.createApplicationContext(TempSeedModule, {
logger: ['log', 'warn', 'error'],
});
try {
const connectionService = app.get(ConnectionService);
const CommunityModel = await connectionService.getModel('community');
const MatchModel = await connectionService.getModel('match');
const community = await resolveCommunity(
CommunityModel,
options.communityId,
);
const payload = buildMatchPayload(community._id, options);
console.log(
`[temp result seed] mode=${options.dryRun ? 'dry-run' : 'apply'} env=${options.nodeEnv} db=${resolveMongoDbName(options.nodeEnv)}`,
);
console.log(
`[temp result seed] community=${community.name ?? '(unnamed)'} (${community._id.toString()})`,
);
console.log(
`[temp result seed] title="${options.title}" participants=${payload.participants.length} teams=${payload.teams.length} games=${payload.result.games.length}`,
);
if (options.dryRun) {
console.log('[temp result seed] No writes were made.');
return;
}
if (options.replace) {
const deleteResult = await MatchModel.deleteMany({
communityId: community._id,
'legacyImportSource.jobId': TEMP_JOB_ID,
}).exec();
console.log(
`[temp result seed] deleted=${deleteResult.deletedCount ?? 0}`,
);
}
const match = await MatchModel.create(payload);
console.log(`[temp result seed] created=${match._id.toString()}`);
console.log(`[temp result seed] route=/match/${match._id.toString()}`);
} finally {
await app.close();
}
}
async function resolveCommunity(
CommunityModel: mongoose.Model<unknown>,
communityId?: string,
): Promise<CommunityLean> {
const community = communityId
? await CommunityModel.findById(communityId)
.select({ name: 1 })
.lean<CommunityLean>()
.exec()
: await CommunityModel.findOne()
.sort({ createdAt: 1 })
.select({ name: 1 })
.lean<CommunityLean>()
.exec();
if (!community) {
throw new Error(
communityId
? `Community not found: ${communityId}`
: 'No community found. Pass --community-id.',
);
}
return community;
}
function buildMatchPayload(
communityId: mongoose.Types.ObjectId,
options: CliOptions,
) {
const now = new Date();
const players = buildPlayers(now);
const participants = players.map(
(player, index): MatchParticipant => ({
userId: player.userId,
puuid: player.puuid,
gameName: player.gameName,
tagLine: player.tagLine,
profileIconId: player.profileIconId,
tier: player.tier,
preferredPositions: player.preferredPositions,
joinedAt: new Date(
options.scheduledAt.getTime() - (TOTAL_PLAYERS - index) * 60000,
),
excluded: false,
}),
);
const teams = buildTeams(players);
const games = buildGames(players, options.scheduledAt);
const seriesResults = buildSeriesResults(games);
const winnerTeamIndex = resolveOverallWinner(seriesResults);
return {
communityId,
title: options.title,
description:
'결과 페이지 검증용으로 생성된 30명, 6팀, 15경기 완료 임시 데이터입니다.',
mapId: 11,
status: 'finished',
scheduledAt: options.scheduledAt,
maxParticipants: TOTAL_PLAYERS,
gameCount: GAME_COUNT_PER_SERIES_GROUP,
gameMode: 'round-robin',
tournamentCodeIds: [],
teamBuiltAt: new Date(options.scheduledAt.getTime() - 30 * 60000),
participants,
teams,
result: {
winnerTeamIndex,
mvpUserId: players[0].userId,
riotMatchIds: games.map((game) => game.riotMatchId),
games,
seriesResults,
},
resultPollState: {
startedAt: new Date(options.scheduledAt.getTime() + 2 * 60 * 60 * 1000),
lastPolledAt: now,
lastPollOutcome: 'matched',
matchedCount: games.length,
expandedToAllPuuids: true,
state: 'complete',
},
legacyImported: true,
legacyImportSource: {
importedAt: now,
importedBy: players[0].userId,
triggeringPuuid: players[0].puuid,
jobId: TEMP_JOB_ID,
},
prizes: ['1등 팀: 결과 화면 검증용 임시 상품', 'MVP: Temp01'],
notices: ['이 매치는 UI 검증용 임시 데이터입니다.'],
schedule: [
{ time: '20:00', label: '로비 오픈' },
{ time: '20:10', label: '1경기 시작' },
{ time: '23:30', label: '풀리그 종료' },
],
};
}
function buildPlayers(now: Date): TempPlayer[] {
return Array.from({ length: TOTAL_PLAYERS }, (_, index) => {
const playerNumber = index + 1;
const primaryPosition = POSITIONS[index % POSITIONS.length];
return {
userId: new mongoose.Types.ObjectId(),
puuid: `temp-result-puuid-${playerNumber.toString().padStart(2, '0')}`,
gameName: `Temp${playerNumber.toString().padStart(2, '0')}`,
tagLine: `T${playerNumber.toString().padStart(3, '0')}`,
profileIconId: 20 + playerNumber,
tier: buildTier(playerNumber, now),
preferredPositions: buildPreferredPositions(primaryPosition),
};
});
}
function buildPreferredPositions(
primaryPosition: Position,
): PositionPreference[] {
const ordered = [
primaryPosition,
...POSITIONS.filter((position) => position !== primaryPosition),
];
return ordered.map((position, index) => ({
position,
priority: index + 1,
}));
}
function buildTier(playerNumber: number, fetchedAt: Date): TierInfo {
const tiers = [
['CHALLENGER', 'I'],
['GRANDMASTER', 'I'],
['MASTER', 'I'],
['DIAMOND', 'I'],
['DIAMOND', 'II'],
['EMERALD', 'I'],
['EMERALD', 'II'],
['PLATINUM', 'I'],
['PLATINUM', 'II'],
['GOLD', 'I'],
] as const;
const [tier, rank] = tiers[(playerNumber - 1) % tiers.length];
return {
queueType: 'RANKED_SOLO_5x5',
tier,
rank,
leaguePoints: (playerNumber * 17) % 100,
wins: 40 + playerNumber,
losses: 22 + (playerNumber % 13),
fetchedAt,
};
}
function buildTeams(players: TempPlayer[]): MatchTeam[] {
return Array.from({ length: TEAM_COUNT }, (_, teamOffset) => {
const teamIndex = teamOffset + 1;
const members = players
.slice(teamOffset * TEAM_SIZE, (teamOffset + 1) * TEAM_SIZE)
.map((player, memberOffset) => ({
userId: player.userId,
assignedPosition: POSITIONS[memberOffset],
cost: memberOffset === 0 ? 0 : 80 + teamIndex * 15 + memberOffset * 20,
}));
return {
teamIndex,
name: `${teamIndex}팀`,
captainUserId: members[0]?.userId,
members,
};
});
}
function buildGames(
players: TempPlayer[],
scheduledAt: Date,
): MatchGameResult[] {
const games: MatchGameResult[] = [];
const playersByTeam = new Map<number, TempPlayer[]>();
for (let teamIndex = 1; teamIndex <= TEAM_COUNT; teamIndex += 1) {
playersByTeam.set(
teamIndex,
players.slice((teamIndex - 1) * TEAM_SIZE, teamIndex * TEAM_SIZE),
);
}
for (let teamAIndex = 1; teamAIndex <= TEAM_COUNT; teamAIndex += 1) {
for (
let teamBIndex = teamAIndex + 1;
teamBIndex <= TEAM_COUNT;
teamBIndex += 1
) {
const gameNumber = games.length + 1;
const lowerTeamStartsBlue = gameNumber % 2 === 1;
const blueTeamIndex = lowerTeamStartsBlue ? teamAIndex : teamBIndex;
const redTeamIndex = lowerTeamStartsBlue ? teamBIndex : teamAIndex;
const winnerTeamIndex = teamAIndex;
const winnerSide: TeamSide =
winnerTeamIndex === blueTeamIndex ? 'blue' : 'red';
const gameCreation = scheduledAt.getTime() + gameNumber * 20 * 60 * 1000;
const riotMatchId = `KR_TEMP_30X6_${formatStamp(scheduledAt)}_${gameNumber
.toString()
.padStart(2, '0')}`;
games.push({
gameNumber,
riotMatchId,
blueTeamIndex,
redTeamIndex,
winnerTeamIndex,
winnerSide,
gameCreation,
gameDuration: 1650 + gameNumber * 23,
participants: [
...buildGameParticipants({
players: playersByTeam.get(blueTeamIndex) ?? [],
teamIndex: blueTeamIndex,
side: 'blue',
winnerTeamIndex,
gameNumber,
}),
...buildGameParticipants({
players: playersByTeam.get(redTeamIndex) ?? [],
teamIndex: redTeamIndex,
side: 'red',
winnerTeamIndex,
gameNumber,
}),
],
});
}
}
return games;
}
function buildGameParticipants(params: {
players: TempPlayer[];
teamIndex: number;
side: TeamSide;
winnerTeamIndex: number;
gameNumber: number;
}): MatchGameResult['participants'] {
const didWin = params.teamIndex === params.winnerTeamIndex;
return params.players.map((player, index) => {
const championIndex =
(params.gameNumber + params.teamIndex + index) % CHAMPION_IDS.length;
return {
userId: player.userId,
teamIndex: params.teamIndex,
side: params.side,
championId: CHAMPION_IDS[championIndex],
kills: didWin
? 4 + ((params.gameNumber + index) % 8)
: 1 + ((params.gameNumber + index) % 5),
deaths: didWin ? 1 + (index % 4) : 4 + ((params.gameNumber + index) % 7),
assists: didWin
? 7 + ((params.gameNumber + index) % 12)
: 3 + ((params.gameNumber + index) % 8),
win: didWin,
};
});
}
function buildSeriesResults(games: MatchGameResult[]): MatchSeriesResult[] {
return games.map((game) => {
const teamAIndex = Math.min(game.blueTeamIndex, game.redTeamIndex);
const teamBIndex = Math.max(game.blueTeamIndex, game.redTeamIndex);
return {
teamAIndex,
teamBIndex,
teamAWins: game.winnerTeamIndex === teamAIndex ? 1 : 0,
teamBWins: game.winnerTeamIndex === teamBIndex ? 1 : 0,
winnerTeamIndex: game.winnerTeamIndex,
};
});
}
function resolveOverallWinner(
seriesResults: MatchSeriesResult[],
): number | undefined {
const winsByTeam = new Map<number, number>();
for (const series of seriesResults) {
if (!series.winnerTeamIndex) continue;
winsByTeam.set(
series.winnerTeamIndex,
(winsByTeam.get(series.winnerTeamIndex) ?? 0) + 1,
);
}
return [...winsByTeam.entries()].sort(
(left, right) => right[1] - left[1],
)[0]?.[0];
}
function formatStamp(date: Date): string {
const year = date.getFullYear();
const month = `${date.getMonth() + 1}`.padStart(2, '0');
const day = `${date.getDate()}`.padStart(2, '0');
const hours = `${date.getHours()}`.padStart(2, '0');
const minutes = `${date.getMinutes()}`.padStart(2, '0');
const seconds = `${date.getSeconds()}`.padStart(2, '0');
return `${year}${month}${day}-${hours}${minutes}${seconds}`;
}
void main().catch((error: unknown) => {
console.error(error instanceof Error ? error.message : error);
process.exitCode = 1;
});
@@ -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,174 @@
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, staging, 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', 'staging', 'prod'].includes(nodeEnv)) {
throw new Error('--env must be dev, staging, 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 | staging | 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;
});
+523 -40
View File
@@ -65,7 +65,11 @@ export const TOURNAMENT_SPECTATOR_TYPES: TournamentSpectatorType[] = [
];
export type MatchResultPollOutcome = 'matched' | 'not-found' | 'failed';
export type MatchResultPollStateValue = 'polling' | 'complete' | 'expired' | 'failed';
export type MatchResultPollStateValue =
| 'polling'
| 'complete'
| 'expired'
| 'failed';
export const MATCH_RESULT_POLL_STATES: MatchResultPollStateValue[] = [
'polling',
'complete',
@@ -87,6 +91,39 @@ export const LEGACY_IMPORT_JOB_STATES: LegacyImportJobState[] = [
'cancelled',
];
export type DakaoInboundMessageState = 'processing' | 'processed' | 'failed';
export const DAKAO_INBOUND_MESSAGE_STATES: DakaoInboundMessageState[] = [
'processing',
'processed',
'failed',
];
export type DakaoOutboxMessageState =
| 'pending'
| 'published'
| 'sent'
| 'failed';
export const DAKAO_OUTBOX_MESSAGE_STATES: DakaoOutboxMessageState[] = [
'pending',
'published',
'sent',
'failed',
];
export type DakaoOutboxCompensationState =
| 'none'
| 'pending'
| 'completed'
| 'failed';
export const DAKAO_OUTBOX_COMPENSATION_STATES: DakaoOutboxCompensationState[] =
['none', 'pending', 'completed', 'failed'];
export type DakaoSendResultStatus = 'succeeded' | 'failed';
export const DAKAO_SEND_RESULT_STATUSES: DakaoSendResultStatus[] = [
'succeeded',
'failed',
];
export interface PositionPreference {
position: Position;
priority: number; // 1 = 최우선, 숫자가 작을수록 높은 우선순위
@@ -97,14 +134,33 @@ export type AuctionPhase =
| 'presenting'
| 'bidding'
| 'sold'
| 'passed'
| 'complete';
export const AUCTION_PHASES: AuctionPhase[] = [
'waiting',
'presenting',
'bidding',
'sold',
'passed',
'complete',
];
export const AUCTION_TOP_TIER_THRESHOLDS = [
'NONE',
'EMERALD',
'DIAMOND',
'MASTER',
'MANUAL',
] as const;
export type AuctionTopTierThreshold =
(typeof AUCTION_TOP_TIER_THRESHOLDS)[number];
export type AuctionActionType =
| 'start'
| 'open-bidding'
| 'bid'
| 'sold'
| 'passed'
| 'next'
| 'complete';
export interface MongooseTimestamps {
createdAt: Date;
@@ -277,9 +333,61 @@ export interface CommunitySeason {
endedAt?: Date;
}
export interface DakaoInboundMessage extends MongooseTimestamps {
consumer: string;
projectId: string;
chatLogLogId: string;
state: DakaoInboundMessageState;
attempts: number;
processingExpiresAt?: Date;
processedAt?: Date;
lastError?: string;
}
export interface DakaoOutboxMessage extends MongooseTimestamps {
eventId: string;
eventSource: string;
type: string;
subject: string;
correlationId?: string;
resultSubjects?: {
succeeded: string;
failed: string;
};
payload: Record<string, unknown>;
state: DakaoOutboxMessageState;
publishAttempts: number;
publishedAt?: Date;
terminalAt?: Date;
resultEventId?: string;
lastPublishError?: string;
terminalError?: Record<string, unknown>;
compensationState: DakaoOutboxCompensationState;
compensationReason?: string;
}
export interface DakaoSendResultEvent extends MongooseTimestamps {
eventId: string;
requestEventId: string;
eventSource: string;
requestEventSource: string;
type: string;
subject: string;
status: DakaoSendResultStatus;
correlationId?: string;
handledAt: Date;
providerMessageId?: string;
error?: Record<string, unknown>;
raw: Record<string, unknown>;
}
export type CommunityDocument = HydratedDocument<Community>;
export type IdentityDocument = HydratedDocument<Identity>;
export type UserDocument = HydratedDocument<User>;
export type DakaoInboundMessageDocument = HydratedDocument<DakaoInboundMessage>;
export type DakaoOutboxMessageDocument = HydratedDocument<DakaoOutboxMessage>;
export type DakaoSendResultEventDocument =
HydratedDocument<DakaoSendResultEvent>;
// ===== RiotMatch (Riot 원본 매치 아카이브) =====
export interface RiotMatch extends MongooseTimestamps {
@@ -340,8 +448,7 @@ export interface MatchTeamMember {
}
export interface MatchTeam {
side: TeamSide;
groupIndex: number;
teamIndex: number;
name: string;
captainUserId?: mongoose.Types.ObjectId;
members: MatchTeamMember[];
@@ -349,6 +456,7 @@ export interface MatchTeam {
export interface MatchGameResultParticipant {
userId: mongoose.Types.ObjectId;
teamIndex: number;
side: TeamSide;
championId: number;
kills: number;
@@ -360,26 +468,31 @@ export interface MatchGameResultParticipant {
export interface MatchGameResult {
gameNumber: number;
riotMatchId: string;
blueTeamIndex: number;
redTeamIndex: number;
winnerTeamIndex: number;
winnerSide: TeamSide;
blueGroupIndex: number;
redGroupIndex: number;
gameCreation: number;
gameDuration: number;
participants: MatchGameResultParticipant[];
}
export interface MatchSeriesResult {
blueGroupIndex: number;
redGroupIndex: number;
blueScore: number;
redScore: number;
winnerSide?: TeamSide;
teamAIndex: number;
teamBIndex: number;
teamAWins: number;
teamBWins: number;
winnerTeamIndex?: number;
}
export interface MatchGameAssignment {
gameNumber: number;
teamAIndex: number;
teamBIndex: number;
}
export interface MatchResult {
winnerSide?: TeamSide;
blueScore: number;
redScore: number;
winnerTeamIndex?: number;
mvpUserId?: mongoose.Types.ObjectId;
riotMatchIds: string[]; // 내전에서 플레이된 Riot matchId들
games: MatchGameResult[];
@@ -402,6 +515,7 @@ export interface MatchScheduleItem {
export interface Match extends MongooseTimestamps {
communityId: mongoose.Types.ObjectId;
shortCode?: string;
title: string;
description: string;
mapId: number; // Riot Match-V5 mapId (11=소환사의 협곡, 12=ARAM 등)
@@ -411,6 +525,7 @@ export interface Match extends MongooseTimestamps {
gameCount: number;
gameMode: MatchGameMode;
tournamentCodeIds: mongoose.Types.ObjectId[];
gameSchedule: MatchGameAssignment[];
teamBuiltAt?: Date;
hostUserId?: mongoose.Types.ObjectId;
participants: MatchParticipant[];
@@ -478,8 +593,10 @@ export interface AuctionPlayerSnapshot {
profileIconId: number;
preferredPositions: PositionPreference[];
tiers: TierInfo[];
tierHistory: TierHistoryEntry[];
masteries: ChampionMasteryEntry[];
recentStatsSummary?: RiotRecentStatsSummary;
passCount: number;
}
export interface AuctionTeamMember {
@@ -489,40 +606,135 @@ export interface AuctionTeamMember {
}
export interface AuctionTeam {
side: TeamSide;
groupIndex: number;
teamIndex: number;
captainUserId: mongoose.Types.ObjectId;
points: number;
members: AuctionTeamMember[];
}
export interface AuctionBid {
side: TeamSide;
groupIndex?: number;
teamIndex: number;
amount: number;
bidderUserId: mongoose.Types.ObjectId;
timestamp: Date;
}
export interface AuctionChatMessage {
id: string;
userId?: mongoose.Types.ObjectId;
displayName: string;
message: string;
sentAt: Date;
}
export interface Auction extends MongooseTimestamps {
matchId: mongoose.Types.ObjectId;
phase: AuctionPhase;
teams: AuctionTeam[];
order: AuctionPlayerSnapshot[];
passedQueue: AuctionPlayerSnapshot[];
auctionRound: number;
currentIndex: number;
bids: AuctionBid[];
currentBid: number;
currentBidder?: TeamSide;
currentBidderGroupIndex?: number;
currentBidderTeamIndex?: number;
maxTimerSeconds: number;
bidExtensionSeconds: number;
currentDeadline?: Date;
initialPoints: number;
topTierThreshold: AuctionTopTierThreshold;
manualTopTierUserIds: mongoose.Types.ObjectId[];
chatMessages: AuctionChatMessage[];
startedAt?: Date;
completedAt?: Date;
}
export type AuctionDocument = HydratedDocument<Auction>;
export interface AuctionHistoryEntry extends MongooseTimestamps {
auctionId: mongoose.Types.ObjectId;
matchId: mongoose.Types.ObjectId;
sequence: number;
action: AuctionActionType;
actorUserId?: mongoose.Types.ObjectId;
snapshotBefore: Record<string, unknown>;
takenAt: Date;
}
export type AuctionHistoryEntryDocument = HydratedDocument<AuctionHistoryEntry>;
// ===== MatchStats (precomputed internal stats fragment) =====
export interface MatchStatsRecord {
matchId: string;
title: string;
scheduledAt: Date;
gameNumber: number;
riotMatchId: string;
gameCreation: number;
gameDuration: number;
userId: string;
summonerName: string;
profileIconId: number;
teamIndex: number;
side: TeamSide;
championId: number;
championLevel: number;
teamPosition: string;
kills: number;
deaths: number;
assists: number;
win: boolean;
cs: number;
csPerMin: number;
gold: number;
gpm: number;
damageDealtToChampions: number;
damageTaken: number;
damageShare: number;
killParticipation: number;
visionScore: number;
controlWardsBought: number;
wardsPlaced: number;
wardsKilled: number;
items: number[];
trinket: number;
summonerSpells: [number, number];
perks: { primaryStyle?: number; subStyle?: number; keystone?: number };
rating: number;
}
export interface MatchStatsGameDetail {
gameNumber: number;
riotMatchId: string;
gameCreation: number;
gameDuration: number;
winnerSide: TeamSide;
teams: Array<{
teamIndex: number;
side: TeamSide;
win: boolean;
objectives: { baron: number; dragon: number; tower: number };
participants: MatchStatsRecord[];
}>;
}
export interface MatchStats extends MongooseTimestamps {
matchId: mongoose.Types.ObjectId;
communityId: mongoose.Types.ObjectId;
scheduledAt: Date;
gameCreationMin: number;
gameCreationMax: number;
userIds: mongoose.Types.ObjectId[];
championIds: number[];
matchCard: Record<string, unknown>;
records: MatchStatsRecord[];
gameDetails: MatchStatsGameDetail[];
builtAt: Date;
builderVersion: number;
}
export type MatchStatsDocument = HydratedDocument<MatchStats>;
// ===== Sub-schemas =====
const PositionPreferenceSubSchema = new Schema<PositionPreference>(
{
@@ -727,6 +939,102 @@ CommunitySchema.index({ name: 1 }, { unique: true });
CommunitySchema.index({ ownerUserId: 1 });
CommunitySchema.index({ dakaoProjectId: 1 }, { unique: true, sparse: true });
export const DakaoInboundMessageSchema = new Schema<DakaoInboundMessage>(
{
consumer: { type: String, required: true },
projectId: { type: String, required: true },
chatLogLogId: { type: String, required: true },
state: {
type: String,
enum: DAKAO_INBOUND_MESSAGE_STATES,
required: true,
default: 'processing',
},
attempts: { type: Number, required: true, default: 1 },
processingExpiresAt: { type: Date },
processedAt: { type: Date },
lastError: { type: String },
},
{
timestamps: true,
collection: 'dakao_inbound_message',
},
);
DakaoInboundMessageSchema.index(
{ consumer: 1, projectId: 1, chatLogLogId: 1 },
{ unique: true },
);
DakaoInboundMessageSchema.index({ state: 1, processingExpiresAt: 1 });
export const DakaoOutboxMessageSchema = new Schema<DakaoOutboxMessage>(
{
eventId: { type: String, required: true, unique: true },
eventSource: { type: String, required: true },
type: { type: String, required: true },
subject: { type: String, required: true },
correlationId: { type: String },
resultSubjects: {
succeeded: { type: String },
failed: { type: String },
},
payload: { type: Schema.Types.Mixed, required: true },
state: {
type: String,
enum: DAKAO_OUTBOX_MESSAGE_STATES,
required: true,
default: 'pending',
},
publishAttempts: { type: Number, required: true, default: 0 },
publishedAt: { type: Date },
terminalAt: { type: Date },
resultEventId: { type: String },
lastPublishError: { type: String },
terminalError: { type: Schema.Types.Mixed },
compensationState: {
type: String,
enum: DAKAO_OUTBOX_COMPENSATION_STATES,
required: true,
default: 'none',
},
compensationReason: { type: String },
},
{
timestamps: true,
collection: 'dakao_outbox_message',
},
);
DakaoOutboxMessageSchema.index({ state: 1, updatedAt: 1 });
DakaoOutboxMessageSchema.index({ correlationId: 1 }, { sparse: true });
export const DakaoSendResultEventSchema = new Schema<DakaoSendResultEvent>(
{
eventId: { type: String, required: true, unique: true },
requestEventId: { type: String, required: true },
eventSource: { type: String, required: true },
requestEventSource: { type: String, required: true },
type: { type: String, required: true },
subject: { type: String, required: true },
status: {
type: String,
enum: DAKAO_SEND_RESULT_STATUSES,
required: true,
},
correlationId: { type: String },
handledAt: { type: Date, required: true },
providerMessageId: { type: String },
error: { type: Schema.Types.Mixed },
raw: { type: Schema.Types.Mixed, required: true },
},
{
timestamps: true,
collection: 'dakao_send_result_event',
},
);
DakaoSendResultEventSchema.index({ requestEventId: 1, status: 1 });
export const UserSchema = new Schema<User>(
{
communityId: {
@@ -920,8 +1228,7 @@ const MatchTeamMemberSubSchema = new Schema<MatchTeamMember>(
const MatchTeamSubSchema = new Schema<MatchTeam>(
{
side: { type: String, enum: TEAM_SIDES, required: true },
groupIndex: { type: Number, required: true, default: 1, min: 1 },
teamIndex: { type: Number, required: true, min: 1 },
name: { type: String, required: true },
captainUserId: { type: Schema.Types.ObjectId, ref: 'user' },
members: { type: [MatchTeamMemberSubSchema], required: true, default: [] },
@@ -933,6 +1240,7 @@ const MatchGameResultParticipantSubSchema =
new Schema<MatchGameResultParticipant>(
{
userId: { type: Schema.Types.ObjectId, ref: 'user', required: true },
teamIndex: { type: Number, required: true, min: 1 },
side: { type: String, enum: TEAM_SIDES, required: true },
championId: { type: Number, required: true },
kills: { type: Number, required: true, default: 0 },
@@ -947,9 +1255,10 @@ const MatchGameResultSubSchema = new Schema<MatchGameResult>(
{
gameNumber: { type: Number, required: true },
riotMatchId: { type: String, required: true },
blueTeamIndex: { type: Number, required: true, min: 1 },
redTeamIndex: { type: Number, required: true, min: 1 },
winnerTeamIndex: { type: Number, required: true, min: 1 },
winnerSide: { type: String, enum: TEAM_SIDES, required: true },
blueGroupIndex: { type: Number, required: true, default: 1, min: 1 },
redGroupIndex: { type: Number, required: true, default: 1, min: 1 },
gameCreation: { type: Number, required: true },
gameDuration: { type: Number, required: true },
participants: {
@@ -963,20 +1272,27 @@ const MatchGameResultSubSchema = new Schema<MatchGameResult>(
const MatchSeriesResultSubSchema = new Schema<MatchSeriesResult>(
{
blueGroupIndex: { type: Number, required: true, default: 1, min: 1 },
redGroupIndex: { type: Number, required: true, default: 1, min: 1 },
blueScore: { type: Number, required: true, default: 0 },
redScore: { type: Number, required: true, default: 0 },
winnerSide: { type: String, enum: TEAM_SIDES, required: false },
teamAIndex: { type: Number, required: true, min: 1 },
teamBIndex: { type: Number, required: true, min: 1 },
teamAWins: { type: Number, required: true, default: 0 },
teamBWins: { type: Number, required: true, default: 0 },
winnerTeamIndex: { type: Number, required: false, min: 1 },
},
{ _id: false },
);
const MatchGameAssignmentSubSchema = new Schema<MatchGameAssignment>(
{
gameNumber: { type: Number, required: true, min: 1 },
teamAIndex: { type: Number, required: true, min: 1 },
teamBIndex: { type: Number, required: true, min: 1 },
},
{ _id: false },
);
const MatchResultSubSchema = new Schema<MatchResult>(
{
winnerSide: { type: String, enum: TEAM_SIDES, required: false },
blueScore: { type: Number, required: true, default: 0 },
redScore: { type: Number, required: true, default: 0 },
winnerTeamIndex: { type: Number, required: false, min: 1 },
mvpUserId: { type: Schema.Types.ObjectId, ref: 'user' },
riotMatchIds: { type: [String], required: true, default: [] },
games: { type: [MatchGameResultSubSchema], required: true, default: [] },
@@ -1018,7 +1334,9 @@ const MatchScheduleItemSubSchema = new Schema<MatchScheduleItem>(
{ _id: false },
);
const MatchLegacyImportSourceSubSchema = new Schema<NonNullable<Match['legacyImportSource']>>(
const MatchLegacyImportSourceSubSchema = new Schema<
NonNullable<Match['legacyImportSource']>
>(
{
importedAt: { type: Date, required: true },
importedBy: { type: Schema.Types.ObjectId, ref: 'user', required: true },
@@ -1035,8 +1353,16 @@ export const MatchSchema = new Schema<Match>(
ref: 'community',
required: true,
},
shortCode: {
type: String,
required: false,
trim: true,
uppercase: true,
minlength: 4,
maxlength: 6,
},
title: { type: String, required: true },
description: { type: String, required: true, default: '' },
description: { type: String, required: false, default: '' },
mapId: { type: Number, required: true, default: 11 },
status: {
type: String,
@@ -1051,7 +1377,8 @@ export const MatchSchema = new Schema<Match>(
default: 10,
min: 10,
validate: {
validator: (value: number) => Number.isInteger(value) && value % 10 === 0,
validator: (value: number) =>
Number.isInteger(value) && value % 10 === 0,
message: 'maxParticipants must be a multiple of 10.',
},
},
@@ -1067,6 +1394,11 @@ export const MatchSchema = new Schema<Match>(
required: true,
default: [],
},
gameSchedule: {
type: [MatchGameAssignmentSubSchema],
required: true,
default: [],
},
teamBuiltAt: { type: Date },
hostUserId: { type: Schema.Types.ObjectId, ref: 'user' },
participants: {
@@ -1108,6 +1440,13 @@ export const MatchSchema = new Schema<Match>(
MatchSchema.index({ communityId: 1, scheduledAt: -1 });
MatchSchema.index({ communityId: 1, status: 1, scheduledAt: -1 });
MatchSchema.index(
{ communityId: 1, shortCode: 1 },
{
unique: true,
partialFilterExpression: { shortCode: { $type: 'string' } },
},
);
MatchSchema.index({ legacyImported: 1, scheduledAt: -1 });
MatchSchema.index({ 'result.games.riotMatchId': 1 }, { sparse: true });
MatchSchema.index({ title: 'text', description: 'text' });
@@ -1193,12 +1532,18 @@ const AuctionPlayerSnapshotSubSchema = new Schema<AuctionPlayerSnapshot>(
default: [],
},
tiers: { type: [TierInfoSubSchema], required: true, default: [] },
tierHistory: {
type: [TierHistoryEntrySubSchema],
required: true,
default: [],
},
masteries: {
type: [ChampionMasteryEntrySubSchema],
required: true,
default: [],
},
recentStatsSummary: { type: RiotRecentStatsSummarySubSchema },
passCount: { type: Number, required: true, default: 0 },
},
{ _id: false },
);
@@ -1214,8 +1559,7 @@ const AuctionTeamMemberSubSchema = new Schema<AuctionTeamMember>(
const AuctionTeamSubSchema = new Schema<AuctionTeam>(
{
side: { type: String, enum: TEAM_SIDES, required: true },
groupIndex: { type: Number, required: true, default: 1, min: 1 },
teamIndex: { type: Number, required: true, min: 1 },
captainUserId: { type: Schema.Types.ObjectId, ref: 'user', required: true },
points: { type: Number, required: true, default: 0 },
members: {
@@ -1229,8 +1573,7 @@ const AuctionTeamSubSchema = new Schema<AuctionTeam>(
const AuctionBidSubSchema = new Schema<AuctionBid>(
{
side: { type: String, enum: TEAM_SIDES, required: true },
groupIndex: { type: Number, required: true, default: 1, min: 1 },
teamIndex: { type: Number, required: true, min: 1 },
amount: { type: Number, required: true },
bidderUserId: { type: Schema.Types.ObjectId, ref: 'user', required: true },
timestamp: { type: Date, required: true, default: Date.now },
@@ -1238,6 +1581,17 @@ const AuctionBidSubSchema = new Schema<AuctionBid>(
{ _id: false },
);
const AuctionChatMessageSubSchema = new Schema<AuctionChatMessage>(
{
id: { type: String, required: true },
userId: { type: Schema.Types.ObjectId, ref: 'user', required: false },
displayName: { type: String, required: true },
message: { type: String, required: true },
sentAt: { type: Date, required: true, default: Date.now },
},
{ _id: false },
);
export const AuctionSchema = new Schema<Auction>(
{
matchId: {
@@ -1258,14 +1612,37 @@ export const AuctionSchema = new Schema<Auction>(
required: true,
default: [],
},
passedQueue: {
type: [AuctionPlayerSnapshotSubSchema],
required: true,
default: [],
},
auctionRound: { type: Number, required: true, default: 1, min: 1 },
currentIndex: { type: Number, required: true, default: 0 },
bids: { type: [AuctionBidSubSchema], required: true, default: [] },
currentBid: { type: Number, required: true, default: 0 },
currentBidder: { type: String, enum: TEAM_SIDES, required: false },
currentBidderGroupIndex: { type: Number, required: false },
currentBidderTeamIndex: { type: Number, required: false, min: 1 },
maxTimerSeconds: { type: Number, required: true, default: 30 },
bidExtensionSeconds: { type: Number, required: true, default: 5, min: 0 },
currentDeadline: { type: Date, required: false },
initialPoints: { type: Number, required: true, default: 1000 },
topTierThreshold: {
type: String,
enum: AUCTION_TOP_TIER_THRESHOLDS,
required: true,
default: 'NONE',
},
manualTopTierUserIds: {
type: [Schema.Types.ObjectId],
ref: 'user',
required: true,
default: [],
},
chatMessages: {
type: [AuctionChatMessageSubSchema],
required: true,
default: [],
},
startedAt: { type: Date, required: false },
completedAt: { type: Date, required: false },
},
@@ -1275,9 +1652,100 @@ export const AuctionSchema = new Schema<Auction>(
},
);
const AuctionHistoryEntrySchema = new Schema<AuctionHistoryEntry>(
{
auctionId: {
type: Schema.Types.ObjectId,
ref: 'auction',
required: true,
index: true,
},
matchId: {
type: Schema.Types.ObjectId,
ref: 'match',
required: true,
index: true,
},
sequence: { type: Number, required: true, min: 1 },
action: {
type: String,
enum: [
'start',
'open-bidding',
'bid',
'sold',
'passed',
'next',
'complete',
],
required: true,
},
actorUserId: { type: Schema.Types.ObjectId, ref: 'user', required: false },
snapshotBefore: { type: Schema.Types.Mixed, required: true },
takenAt: { type: Date, required: true, default: Date.now },
},
{
timestamps: true,
collection: 'auctionHistory',
},
);
AuctionHistoryEntrySchema.index({ auctionId: 1, sequence: -1 });
export const MatchStatsSchema: mongoose.Schema<MatchStats> = new Schema(
{
matchId: {
type: Schema.Types.ObjectId,
ref: 'match',
required: true,
unique: true,
},
communityId: {
type: Schema.Types.ObjectId,
ref: 'community',
required: true,
},
scheduledAt: { type: Date, required: true },
gameCreationMin: { type: Number, required: true },
gameCreationMax: { type: Number, required: true },
userIds: { type: [Schema.Types.ObjectId], required: true, default: [] },
championIds: { type: [Number], required: true, default: [] },
matchCard: { type: Schema.Types.Mixed, required: true },
records: { type: [Schema.Types.Mixed], required: true, default: [] },
gameDetails: { type: [Schema.Types.Mixed], required: true, default: [] },
builtAt: { type: Date, required: true, default: Date.now },
builderVersion: { type: Number, required: true, default: 1 },
} as mongoose.SchemaDefinition,
{ timestamps: true, collection: 'match_stats' },
) as mongoose.Schema<MatchStats>;
MatchStatsSchema.index({ communityId: 1, scheduledAt: -1 });
MatchStatsSchema.index({
communityId: 1,
gameCreationMin: 1,
gameCreationMax: 1,
});
MatchStatsSchema.index({ communityId: 1, userIds: 1 });
MatchStatsSchema.index({ communityId: 1, championIds: 1 });
export const tournamentModelDefinitions: ModelDefinition[] = [
{ name: 'identity', schema: IdentitySchema, schemaName: 'identity' },
{ name: 'community', schema: CommunitySchema, schemaName: 'community' },
{
name: 'dakaoInboundMessage',
schema: DakaoInboundMessageSchema,
schemaName: 'dakaoInboundMessage',
},
{
name: 'dakaoOutboxMessage',
schema: DakaoOutboxMessageSchema,
schemaName: 'dakaoOutboxMessage',
},
{
name: 'dakaoSendResultEvent',
schema: DakaoSendResultEventSchema,
schemaName: 'dakaoSendResultEvent',
},
{ name: 'user', schema: UserSchema, schemaName: 'user' },
{ name: 'riotMatch', schema: RiotMatchSchema, schemaName: 'riotMatch' },
{
@@ -1292,15 +1760,30 @@ export const tournamentModelDefinitions: ModelDefinition[] = [
},
{ name: 'match', schema: MatchSchema, schemaName: 'match' },
{ name: 'auction', schema: AuctionSchema, schemaName: 'auction' },
{
name: 'auctionHistory',
schema: AuctionHistoryEntrySchema,
schemaName: 'auctionHistory',
},
{
name: 'matchStats',
schema: MatchStatsSchema,
schemaName: 'matchStats',
},
];
export interface TournamentModelTypes {
identity: Identity;
community: Community;
dakaoInboundMessage: DakaoInboundMessage;
dakaoOutboxMessage: DakaoOutboxMessage;
dakaoSendResultEvent: DakaoSendResultEvent;
user: User;
riotMatch: RiotMatch;
tournamentCode: TournamentCode;
legacyImportJob: LegacyImportJob;
match: Match;
auction: Auction;
auctionHistory: AuctionHistoryEntry;
matchStats: MatchStats;
}
@@ -1,9 +1,4 @@
import {
Inject,
Injectable,
Logger,
OnModuleDestroy,
} from '@nestjs/common';
import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
import type { createClient } from 'redis';
import { GARNET_CLIENT } from './garnet.constants';
@@ -203,6 +198,13 @@ export class GarnetService implements OnModuleDestroy {
return this.client.xAck(key, group, ids);
}
public async deleteStreamEntries(
key: string,
ids: string | string[],
): Promise<number> {
return this.client.xDel(key, ids);
}
public async streamLength(key: string): Promise<number> {
return this.client.xLen(key);
}
@@ -1,11 +1,21 @@
import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
import {
Inject,
Injectable,
Logger,
OnModuleDestroy,
} from '@nestjs/common';
import { StringCodec } from 'nats';
import type { Msg, NatsConnection, Subscription } from 'nats';
AckPolicy,
DeliverPolicy,
nanos,
ReplayPolicy,
RetentionPolicy,
StorageType,
StringCodec,
} from 'nats';
import type {
ConsumerMessages,
JsMsg,
Msg,
NatsConnection,
PubAck,
Subscription,
} from 'nats';
import { NATS_CLIENT } from './nats.constants';
export type NatsMessageHandler<T = unknown> = (
@@ -13,17 +23,62 @@ export type NatsMessageHandler<T = unknown> = (
msg: Msg,
) => Promise<void> | void;
export type JetStreamRetention = 'workqueue' | 'limits';
export type JetStreamMessageHandler<T = unknown> = (
data: T,
msg: JsMsg,
) => Promise<void> | void;
export interface JetStreamStreamOptions {
name: string;
subjects: string[];
retention: JetStreamRetention;
maxAgeDays?: number;
replicas?: number;
}
export interface JetStreamConsumerOptions {
stream: string;
durable: string;
filterSubject: string;
description?: string;
ackWaitMs?: number;
backoffMs?: number[];
maxDeliver?: number;
maxAckPending?: number;
replicas?: number;
}
export interface JetStreamConsumeOptions {
stream: string;
durable: string;
maxMessages?: number;
expiresMs?: number;
nakDelayMs?: number;
}
@Injectable()
export class NatsService implements OnModuleDestroy {
private readonly logger = new Logger(NatsService.name);
private readonly stringCodec = StringCodec();
private readonly subscriptions = new Set<Subscription>();
private readonly jetStreamConsumers = new Set<ConsumerMessages>();
constructor(
@Inject(NATS_CLIENT) private readonly natsClient: NatsConnection,
) {}
async onModuleDestroy() {
for (const consumer of this.jetStreamConsumers) {
try {
await consumer.close();
} catch {
// ignore
}
}
this.jetStreamConsumers.clear();
for (const sub of this.subscriptions) {
try {
sub.unsubscribe();
@@ -68,6 +123,108 @@ export class NatsService implements OnModuleDestroy {
return sub;
}
public async publishJetStream<T = unknown>(
subject: string,
data: T,
options?: { messageId?: string; timeoutMs?: number },
): Promise<PubAck> {
const ack = await this.natsClient
.jetstream()
.publish(subject, this.stringCodec.encode(JSON.stringify(data)), {
msgID: options?.messageId,
timeout: options?.timeoutMs ?? 5000,
});
return ack;
}
public async ensureJetStreamStream(
options: JetStreamStreamOptions,
): Promise<void> {
const manager = await this.natsClient.jetstreamManager();
const config = {
name: options.name,
subjects: options.subjects,
retention: this.toRetentionPolicy(options.retention),
storage: StorageType.File,
num_replicas: options.replicas ?? 1,
max_age: options.maxAgeDays
? nanos(options.maxAgeDays * 24 * 60 * 60 * 1000)
: 0,
};
try {
await manager.streams.info(options.name);
await manager.streams.update(options.name, {
subjects: config.subjects,
max_age: config.max_age,
num_replicas: config.num_replicas,
});
return;
} catch {
await manager.streams.add(config);
}
}
public async ensureJetStreamConsumer(
options: JetStreamConsumerOptions,
): Promise<void> {
const manager = await this.natsClient.jetstreamManager();
const config = {
durable_name: options.durable,
name: options.durable,
description: options.description,
filter_subject: options.filterSubject,
deliver_policy: DeliverPolicy.All,
ack_policy: AckPolicy.Explicit,
replay_policy: ReplayPolicy.Instant,
ack_wait: nanos(options.ackWaitMs ?? 30000),
backoff: (options.backoffMs ?? [5000, 30000, 120000, 600000]).map(
(entry) => nanos(entry),
),
max_deliver: options.maxDeliver ?? 10,
max_ack_pending: options.maxAckPending ?? 50,
num_replicas: options.replicas ?? 1,
};
try {
await manager.consumers.info(options.stream, options.durable);
await manager.consumers.update(options.stream, options.durable, config);
return;
} catch {
await manager.consumers.add(options.stream, config);
}
}
public async consumeJetStream<T = unknown>(
options: JetStreamConsumeOptions,
handler: JetStreamMessageHandler<T>,
): Promise<void> {
try {
const consumer = await this.natsClient
.jetstream()
.consumers.get(options.stream, options.durable);
const messages = await consumer.consume({
max_messages: options.maxMessages ?? 10,
expires: options.expiresMs ?? 30000,
});
this.jetStreamConsumers.add(messages);
try {
for await (const msg of messages) {
await this.dispatchJetStream(msg, handler, options);
}
} finally {
this.jetStreamConsumers.delete(messages);
}
} catch (err) {
this.logger.error(
`JetStream consumer stream="${options.stream}" durable="${options.durable}" terminated: ${
(err as Error)?.stack ?? err
}`,
);
}
}
private async consumeSubscription<T>(
sub: Subscription,
handler: NatsMessageHandler<T>,
@@ -114,4 +271,46 @@ export class NatsService implements OnModuleDestroy {
);
}
}
private async dispatchJetStream<T>(
msg: JsMsg,
handler: JetStreamMessageHandler<T>,
options: JetStreamConsumeOptions,
): Promise<void> {
let data: T;
try {
data = JSON.parse(msg.string()) as T;
} catch (err) {
this.logger.warn(
`Terminating undecodable JetStream message subject="${msg.subject}" stream="${options.stream}": ${
(err as Error)?.message ?? err
}`,
);
msg.term('invalid_json');
return;
}
try {
await handler(data, msg);
const acked = await msg.ackAck({ timeout: 5000 });
if (!acked) {
this.logger.warn(
`JetStream ack was not confirmed subject="${msg.subject}" stream="${options.stream}" seq=${msg.seq}`,
);
}
} catch (err) {
this.logger.error(
`JetStream handler error subject="${msg.subject}" stream="${options.stream}" seq=${msg.seq}: ${
(err as Error)?.stack ?? err
}`,
);
msg.nak(options.nakDelayMs ?? 5000);
}
}
private toRetentionPolicy(retention: JetStreamRetention): RetentionPolicy {
return retention === 'workqueue'
? RetentionPolicy.Workqueue
: RetentionPolicy.Limits;
}
}
@@ -0,0 +1,69 @@
import { ConfigService } from '@nestjs/config';
import { SecretService } from './secret.service';
function makeConfig(values: Record<string, string | undefined> = {}) {
return {
get: jest.fn((key: string) => values[key] ?? process.env[key]),
} as unknown as ConfigService;
}
describe('SecretService', () => {
const originalEnv = process.env;
let fetchMock: jest.Mock;
beforeEach(() => {
process.env = { ...originalEnv };
delete process.env.SECRET_SOURCE;
delete process.env.TEST_SECRET;
fetchMock = jest
.fn()
.mockRejectedValue(new Error('network calls are disabled in tests'));
global.fetch = fetchMock;
});
afterEach(() => {
process.env = originalEnv;
jest.restoreAllMocks();
});
it('defaults to environment-provided secrets without IMDS lookup', async () => {
process.env.TEST_SECRET = 'from-env';
const service = new SecretService(makeConfig());
await service.ready();
await expect(service.get('TEST_SECRET')).resolves.toBe('from-env');
expect(fetchMock).not.toHaveBeenCalled();
});
it('uses environment-provided secrets when SECRET_SOURCE is env', async () => {
process.env.SECRET_SOURCE = 'env';
process.env.TEST_SECRET = 'from-env-source';
const service = new SecretService(makeConfig());
await service.ready();
await expect(service.get('TEST_SECRET')).resolves.toBe('from-env-source');
expect(fetchMock).not.toHaveBeenCalled();
});
it('uses the IMDS and Infisical bootstrap path only when SECRET_SOURCE is infisical', async () => {
process.env.SECRET_SOURCE = 'infisical';
const service = new SecretService(makeConfig());
await expect(service.ready()).rejects.toThrow(
'Missing required bootstrap secret: INFISICAL_CLIENT_ID',
);
expect(fetchMock).toHaveBeenCalled();
});
it('rejects unsupported SECRET_SOURCE values', async () => {
process.env.SECRET_SOURCE = 'kubernetes';
const service = new SecretService(makeConfig());
await expect(service.ready()).rejects.toThrow(
'Invalid SECRET_SOURCE="kubernetes". Expected "env" or "infisical".',
);
expect(fetchMock).not.toHaveBeenCalled();
});
});
@@ -3,6 +3,7 @@ import { InfisicalSDK } from '@infisical/sdk';
import { ConfigService } from '@nestjs/config';
type SecretMap = Record<string, string | undefined>;
type SecretSource = 'env' | 'infisical';
const DEFAULT_INFISICAL_SITE_URL = 'https://secret-manager.dahyeon.us/';
const IMDS_TOKEN_TTL_SECONDS = 60;
@@ -34,43 +35,13 @@ export class SecretService {
if (this.loading) return this.loading; // 로드 중이면 그거 기다리기
this.loading = (async () => {
const bootstrapConfig = await this.resolveInfisicalBootstrapConfig();
const infisicalClient = new InfisicalSDK({
siteUrl: bootstrapConfig.siteUrl,
});
await infisicalClient.auth().universalAuth.login({
clientId: bootstrapConfig.clientId,
clientSecret: bootstrapConfig.clientSecret,
});
const res = await infisicalClient.secrets().listSecrets({
environment:
process.env.NODE_ENV === 'prod'
? 'prod'
: process.env.NODE_ENV === 'test'
? 'staging'
: 'dev',
projectId: bootstrapConfig.projectId,
});
// 임시 객체에 채운 뒤 한 번에 교체(일관성 보장)
const map: SecretMap = {};
for (const s of res.secrets) {
map[s.secretKey] = s.secretValue;
const secretSource = this.resolveSecretSource();
if (secretSource === 'env') {
this.loadEnvironmentSecrets();
return;
}
// 앱 생명주기에서 필요한 env는 모두 SecretService가 process.env에 반영한다.
for (const [k, v] of Object.entries(map)) {
if (typeof v === 'string' && v.length > 0) {
process.env[k] = v;
}
}
this.secrets = map;
this.logger.log(
`Fetched ${Object.keys(map).length} secrets from Infisical`,
);
await this.fetchInfisicalSecrets();
})();
try {
@@ -80,6 +51,64 @@ export class SecretService {
}
}
private resolveSecretSource(): SecretSource {
const source = this.config
.get<string>('SECRET_SOURCE')
?.trim()
.toLowerCase();
if (!source || source === 'env') return 'env';
if (source === 'infisical') return 'infisical';
throw new Error(
`Invalid SECRET_SOURCE="${source}". Expected "env" or "infisical".`,
);
}
private loadEnvironmentSecrets(): void {
this.secrets = { ...process.env };
this.logger.log('Using environment-provided secrets');
}
private async fetchInfisicalSecrets(): Promise<void> {
const bootstrapConfig = await this.resolveInfisicalBootstrapConfig();
const infisicalClient = new InfisicalSDK({
siteUrl: bootstrapConfig.siteUrl,
});
await infisicalClient.auth().universalAuth.login({
clientId: bootstrapConfig.clientId,
clientSecret: bootstrapConfig.clientSecret,
});
const res = await infisicalClient.secrets().listSecrets({
environment:
process.env.NODE_ENV === 'prod'
? 'prod'
: process.env.NODE_ENV === 'staging'
? 'staging'
: 'dev',
projectId: bootstrapConfig.projectId,
});
// 임시 객체에 채운 뒤 한 번에 교체(일관성 보장)
const map: SecretMap = {};
for (const s of res.secrets) {
map[s.secretKey] = s.secretValue;
}
// 앱 생명주기에서 필요한 env는 모두 SecretService가 process.env에 반영한다.
for (const [k, v] of Object.entries(map)) {
if (typeof v === 'string' && v.length > 0) {
process.env[k] = v;
}
}
this.secrets = map;
this.logger.log(
`Fetched ${Object.keys(map).length} secrets from Infisical`,
);
}
private async resolveInfisicalBootstrapConfig(): Promise<InfisicalBootstrapConfig> {
const [clientId, clientSecret, projectId] = await Promise.all([
this.resolveBootstrapValue('INFISICAL_CLIENT_ID'),
@@ -7,6 +7,7 @@ import {
} from '@nestjs/common';
import { randomUUID } from 'crypto';
import mongoose from 'mongoose';
import { MatchStatsService } from '../community-stats/match-stats.service';
import { CommunityStatsService } from '../community-stats/community-stats.service';
import { ConnectionService } from '../global/database/connection.service';
import type {
@@ -26,7 +27,6 @@ import {
buildUserByPuuidMap,
countKnownParticipants,
resolveExternalCount,
resolveTeam100IsBlue,
type UserByPuuidMap,
} from './match-builder.util';
import {
@@ -56,6 +56,7 @@ export class LegacyImportService {
private readonly garnetService: GarnetService,
private readonly riotMatchService: RiotMatchService,
private readonly communityStatsService: CommunityStatsService,
private readonly matchStatsService: MatchStatsService,
) {}
public async previewMembers(params: {
@@ -108,8 +109,12 @@ export class LegacyImportService {
]),
);
const windows = users
.map((user) => this.resolveMemberWindow(user, windowStart, windowEnd, overrides))
.filter((window) => window.startTime.getTime() <= window.endTime.getTime());
.map((user) =>
this.resolveMemberWindow(user, windowStart, windowEnd, overrides),
)
.filter(
(window) => window.startTime.getTime() <= window.endTime.getTime(),
);
const LegacyImportJobModel =
await this.connectionService.getModel('legacyImportJob');
await LegacyImportJobModel.create({
@@ -175,7 +180,9 @@ export class LegacyImportService {
}): Promise<{ jobs: LegacyImportJobDocument[] }> {
const LegacyImportJobModel =
await this.connectionService.getModel('legacyImportJob');
const jobs = await LegacyImportJobModel.find({ communityId: params.communityId })
const jobs = await LegacyImportJobModel.find({
communityId: params.communityId,
})
.sort({ startedAt: -1 })
.limit(Math.min(params.limit ?? 10, 50))
.exec();
@@ -211,7 +218,8 @@ export class LegacyImportService {
{ $set: { state: 'cancelled', completedAt: new Date() } },
{ returnDocument: 'after' },
).exec();
if (!job) throw new NotFoundException('Running legacy import job not found.');
if (!job)
throw new NotFoundException('Running legacy import job not found.');
await this.garnetService.delete(this.communityLockKey(params.communityId));
return job;
}
@@ -285,7 +293,9 @@ export class LegacyImportService {
.map((match) => match.result?.games[0]?.riotMatchId)
.filter((matchId): matchId is string => Boolean(matchId));
const RiotMatchModel = await this.connectionService.getModel('riotMatch');
const rawDocs = await RiotMatchModel.find({ matchId: { $in: riotMatchIds } })
const rawDocs = await RiotMatchModel.find({
matchId: { $in: riotMatchIds },
})
.lean()
.exec();
const rawById = new Map(
@@ -306,14 +316,16 @@ export class LegacyImportService {
externalCount: raw
? resolveExternalCount(raw, userByPuuid)
: Math.max(0, 10 - memberCount),
blueScore: match.result?.blueScore ?? 0,
redScore: match.result?.redScore ?? 0,
winnerSide: match.result?.winnerSide,
teamAIndex: match.result?.seriesResults?.[0]?.teamAIndex ?? 1,
teamBIndex: match.result?.seriesResults?.[0]?.teamBIndex ?? 2,
teamAWins: match.result?.seriesResults?.[0]?.teamAWins ?? 0,
teamBWins: match.result?.seriesResults?.[0]?.teamBWins ?? 0,
winnerTeamIndex: match.result?.winnerTeamIndex,
};
}),
nextCursor:
matches.length > limit
? visible[visible.length - 1]?.scheduledAt.getTime() ?? null
? (visible[visible.length - 1]?.scheduledAt.getTime() ?? null)
: null,
};
}
@@ -327,11 +339,22 @@ export class LegacyImportService {
.map((id) => new mongoose.Types.ObjectId(id));
if (ids.length === 0) return { deleted: 0 };
const MatchModel = await this.connectionService.getModel('match');
const result = await MatchModel.deleteMany({
const targets = await MatchModel.find({
_id: { $in: ids },
communityId: params.communityId,
legacyImported: true,
})
.select({ _id: 1 })
.exec();
const targetIds = targets.map((match) => match._id);
if (targetIds.length === 0) return { deleted: 0 };
const result = await MatchModel.deleteMany({
_id: { $in: targetIds },
communityId: params.communityId,
legacyImported: true,
}).exec();
await this.matchStatsService.removeByMatches(targetIds);
await this.communityStatsService.invalidateCommunity(params.communityId);
return { deleted: result.deletedCount ?? 0 };
}
@@ -347,12 +370,15 @@ export class LegacyImportService {
const riotMatchIds = matches
.map(
(match) =>
match.result?.games[0]?.riotMatchId ?? match.result?.riotMatchIds?.[0],
match.result?.games[0]?.riotMatchId ??
match.result?.riotMatchIds?.[0],
)
.filter((matchId): matchId is string => Boolean(matchId));
const RiotMatchModel = await this.connectionService.getModel('riotMatch');
const rawDocs = await RiotMatchModel.find({ matchId: { $in: riotMatchIds } })
const rawDocs = await RiotMatchModel.find({
matchId: { $in: riotMatchIds },
})
.lean()
.exec();
const rawById = new Map<string, RiotMatchDto>();
@@ -386,39 +412,44 @@ export class LegacyImportService {
if (!raw || !riotMatchId) {
result.skippedMissingRaw += 1;
if (Object.keys(update).length > 0) {
await MatchModel.updateOne({ _id: match._id }, { $set: update }).exec();
await MatchModel.updateOne(
{ _id: match._id },
{ $set: update },
).exec();
await this.matchStatsService.buildAndUpsert(match._id);
}
continue;
}
const team100IsBlue = resolveTeam100IsBlue(raw, userByPuuid);
const participants = buildParticipantsSnapshot(raw, userByPuuid);
const gameResult = buildGameResult(raw, userByPuuid, team100IsBlue, 1);
const gameResult = buildGameResult(raw, userByPuuid, 1);
if (!gameResult || participants.length === 0) {
result.skippedNoKnownParticipants += 1;
if (Object.keys(update).length > 0) {
await MatchModel.updateOne({ _id: match._id }, { $set: update }).exec();
await MatchModel.updateOne(
{ _id: match._id },
{ $set: update },
).exec();
await this.matchStatsService.buildAndUpsert(match._id);
}
continue;
}
const winnerSide = gameResult.winnerSide;
const winnerTeamIndex = gameResult.winnerTeamIndex;
update.mapId = raw.info.mapId ?? match.mapId;
update.participants = participants;
update.teams = buildTeams(raw, userByPuuid, team100IsBlue);
update.teams = buildTeams(raw, userByPuuid);
update.result = {
winnerSide,
blueScore: winnerSide === 'blue' ? 1 : 0,
redScore: winnerSide === 'red' ? 1 : 0,
winnerTeamIndex,
riotMatchIds: [riotMatchId],
games: [gameResult],
seriesResults: [
{
blueGroupIndex: 1,
redGroupIndex: 1,
blueScore: winnerSide === 'blue' ? 1 : 0,
redScore: winnerSide === 'red' ? 1 : 0,
winnerSide,
teamAIndex: 1,
teamBIndex: 2,
teamAWins: winnerTeamIndex === 1 ? 1 : 0,
teamBWins: winnerTeamIndex === 2 ? 1 : 0,
winnerTeamIndex,
},
],
};
@@ -431,6 +462,7 @@ export class LegacyImportService {
},
{ $set: update },
).exec();
await this.matchStatsService.buildAndUpsert(match._id);
result.rebuilt += 1;
}
@@ -441,7 +473,9 @@ export class LegacyImportService {
return result;
}
private async collectMatchIds(job: LegacyImportMemberJob): Promise<Set<string>> {
private async collectMatchIds(
job: LegacyImportMemberJob,
): Promise<Set<string>> {
const matchIds = new Set<string>();
let start = 0;
while (true) {
@@ -480,16 +514,18 @@ export class LegacyImportService {
});
if (existing) return 'duplicate';
const detail = await this.ensureRiotMatchPersisted(riotMatchId, job.region);
const detail = await this.ensureRiotMatchPersisted(
riotMatchId,
job.region,
);
if (!detail.info.tournamentCode) return 'skipped';
const counts = countKnownParticipants(detail, userByPuuid);
if (counts.total === 0) return 'skipped';
const team100IsBlue = resolveTeam100IsBlue(detail, userByPuuid);
const gameResult = buildGameResult(detail, userByPuuid, team100IsBlue, 1);
const gameResult = buildGameResult(detail, userByPuuid, 1);
if (!gameResult || gameResult.participants.length === 0) return 'skipped';
const winnerSide = gameResult.winnerSide;
const winnerTeamIndex = gameResult.winnerTeamIndex;
const matchPayload: Partial<Match> = {
communityId: new mongoose.Types.ObjectId(job.communityId),
title: this.formatLegacyDate(detail.info.gameCreation),
@@ -504,20 +540,18 @@ export class LegacyImportService {
teamBuiltAt: new Date(detail.info.gameCreation),
hostUserId: new mongoose.Types.ObjectId(job.triggeredBy),
participants: buildParticipantsSnapshot(detail, userByPuuid),
teams: buildTeams(detail, userByPuuid, team100IsBlue),
teams: buildTeams(detail, userByPuuid),
result: {
winnerSide,
blueScore: winnerSide === 'blue' ? 1 : 0,
redScore: winnerSide === 'red' ? 1 : 0,
winnerTeamIndex,
riotMatchIds: [riotMatchId],
games: [gameResult],
seriesResults: [
{
blueGroupIndex: 1,
redGroupIndex: 1,
blueScore: winnerSide === 'blue' ? 1 : 0,
redScore: winnerSide === 'red' ? 1 : 0,
winnerSide,
teamAIndex: 1,
teamBIndex: 2,
teamAWins: winnerTeamIndex === 1 ? 1 : 0,
teamBWins: winnerTeamIndex === 2 ? 1 : 0,
winnerTeamIndex,
},
],
},
@@ -532,7 +566,8 @@ export class LegacyImportService {
notices: [],
schedule: [],
};
await MatchModel.create(matchPayload);
const match = await MatchModel.create(matchPayload);
await this.matchStatsService.buildAndUpsert(match._id);
return 'imported';
} catch (error) {
await this.recordError(job.parentJobId, {
@@ -551,7 +586,9 @@ export class LegacyImportService {
region: RiotRegionalRoute,
): Promise<RiotMatchDto> {
const RiotMatchModel = await this.connectionService.getModel('riotMatch');
const stored = await RiotMatchModel.findOne({ matchId: riotMatchId }).exec();
const stored = await RiotMatchModel.findOne({
matchId: riotMatchId,
}).exec();
if (isRiotMatchDto(stored?.raw)) return stored.raw;
const dto = await this.riotMatchService.getMatch(riotMatchId, { region });
@@ -593,7 +630,9 @@ export class LegacyImportService {
const average =
current.averageMemberSeconds === undefined
? stats.elapsedSeconds
: Math.round(current.averageMemberSeconds * 0.7 + stats.elapsedSeconds * 0.3);
: Math.round(
current.averageMemberSeconds * 0.7 + stats.elapsedSeconds * 0.3,
);
const nextProcessed = current.processedMembers + 1;
const completed = nextProcessed >= current.totalMembers;
@@ -636,7 +675,8 @@ export class LegacyImportService {
jobId: job.parentJobId,
}).exec();
if (!legacyJob || legacyJob.state === 'cancelled') return null;
if (legacyJob.state === 'completed' || legacyJob.state === 'failed') return null;
if (legacyJob.state === 'completed' || legacyJob.state === 'failed')
return null;
return legacyJob;
}
@@ -691,7 +731,12 @@ export class LegacyImportService {
windowStart: Date,
windowEnd: Date,
): LegacyImportMemberWindowView {
const resolved = this.resolveMemberWindow(user, windowStart, windowEnd, new Map());
const resolved = this.resolveMemberWindow(
user,
windowStart,
windowEnd,
new Map(),
);
const account =
user.riotAccounts.find((riotAccount) => riotAccount.isPrimary) ??
user.riotAccounts[0];
@@ -736,10 +781,7 @@ export class LegacyImportService {
};
}
private resolveWindow(params: {
windowStart?: string;
windowEnd?: string;
}) {
private resolveWindow(params: { windowStart?: string; windowEnd?: string }) {
const windowStart =
this.parseOptionalDate(params.windowStart) ??
new Date(LEGACY_IMPORT_DEFAULT_START_ISO);
@@ -760,7 +802,9 @@ export class LegacyImportService {
}
private minDate(...values: Array<Date | undefined>): Date {
return new Date(Math.min(...values.filter(Boolean).map((date) => date!.getTime())));
return new Date(
Math.min(...values.filter(Boolean).map((date) => date!.getTime())),
);
}
private normalizeLegacyTitle(title: string, gameCreation: number): string {
@@ -787,8 +831,8 @@ export class LegacyImportService {
function isRiotMatchDto(value: unknown): value is RiotMatchDto {
return Boolean(
value &&
typeof value === 'object' &&
'metadata' in value &&
'info' in value,
typeof value === 'object' &&
'metadata' in value &&
'info' in value,
);
}
@@ -55,9 +55,11 @@ export interface LegacyMatchListResponse {
riotMatchId: string | null;
memberCount: number;
externalCount: number;
blueScore: number;
redScore: number;
winnerSide?: 'blue' | 'red';
teamAIndex: number;
teamBIndex: number;
teamAWins: number;
teamBWins: number;
winnerTeamIndex?: number;
}>;
nextCursor: number | null;
}
@@ -5,7 +5,6 @@ import type {
MatchTeam,
Position,
RiotAccount,
TeamSide,
UserDocument,
} from '../global/database/schema';
import type { RiotMatchDto, RiotMatchParticipantDto } from '../riot/riot.types';
@@ -91,10 +90,11 @@ export function buildParticipantsSnapshot(
export function buildTeams(
detail: RiotMatchDto,
userByPuuid: UserByPuuidMap,
team100IsBlue: boolean,
): MatchTeam[] {
return (['blue', 'red'] as TeamSide[]).map((side) => {
const teamId = resolveRiotTeamId(side, team100IsBlue);
return [
{ teamIndex: 1, teamId: RIOT_BLUE_TEAM_ID },
{ teamIndex: 2, teamId: RIOT_RED_TEAM_ID },
].map(({ teamIndex, teamId }) => {
const members = detail.info.participants
.filter((participant) => participant.teamId === teamId)
.map((participant) => {
@@ -107,9 +107,8 @@ export function buildTeams(
})
.filter((member): member is NonNullable<typeof member> => Boolean(member));
return {
side,
groupIndex: 1,
name: side === 'blue' ? '블루팀' : '레드팀',
teamIndex,
name: `${teamIndex}팀`,
members,
};
});
@@ -118,20 +117,21 @@ export function buildTeams(
export function buildGameResult(
detail: RiotMatchDto,
userByPuuid: UserByPuuidMap,
team100IsBlue: boolean,
gameNumber = 1,
): MatchGameResult | null {
const winningTeam = detail.info.teams.find((team) => team.win);
if (!winningTeam) return null;
const winnerSide = resolveSide(winningTeam.teamId, team100IsBlue);
const winnerSide = resolveSide(winningTeam.teamId);
if (!winnerSide) return null;
const winnerTeamIndex = winnerSide === 'blue' ? 1 : 2;
const participants = detail.info.participants
.map((participant) => {
const user = userByPuuid.get(participant.puuid);
const side = resolveSide(participant.teamId, team100IsBlue);
const side = resolveSide(participant.teamId);
if (!user || !side) return null;
return {
userId: user.userId,
teamIndex: side === 'blue' ? 1 : 2,
side,
championId: participant.championId,
kills: participant.kills,
@@ -147,9 +147,10 @@ export function buildGameResult(
return {
gameNumber,
riotMatchId: detail.metadata.matchId,
blueTeamIndex: 1,
redTeamIndex: 2,
winnerTeamIndex,
winnerSide,
blueGroupIndex: 1,
redGroupIndex: 1,
gameCreation: detail.info.gameCreation,
gameDuration: detail.info.gameDuration,
participants,
@@ -165,16 +166,9 @@ export function resolveExternalCount(
).length;
}
function resolveRiotTeamId(side: TeamSide, team100IsBlue: boolean): number {
if (side === 'blue') {
return team100IsBlue ? RIOT_BLUE_TEAM_ID : RIOT_RED_TEAM_ID;
}
return team100IsBlue ? RIOT_RED_TEAM_ID : RIOT_BLUE_TEAM_ID;
}
function resolveSide(teamId: number, team100IsBlue: boolean): TeamSide | null {
if (teamId === RIOT_BLUE_TEAM_ID) return team100IsBlue ? 'blue' : 'red';
if (teamId === RIOT_RED_TEAM_ID) return team100IsBlue ? 'red' : 'blue';
function resolveSide(teamId: number): 'blue' | 'red' | null {
if (teamId === RIOT_BLUE_TEAM_ID) return 'blue';
if (teamId === RIOT_RED_TEAM_ID) return 'red';
return null;
}
@@ -99,6 +99,18 @@ export class MatchHistoryService {
losses: tier.losses,
fetchedAt: tier.fetchedAt.toISOString(),
})),
tierHistory: [...context.account.tierHistory]
.sort((left, right) => left.recordedAt.getTime() - right.recordedAt.getTime())
.map((entry) => ({
queueType: entry.queueType,
tier: entry.tier,
rank: entry.rank,
leaguePoints: entry.leaguePoints,
wins: entry.wins,
losses: entry.losses,
recordedAt: entry.recordedAt.toISOString(),
season: entry.season,
})),
season: context.season,
seasons: this.resolveSeasons(context.community),
lastFetchedAt: lastFetchedAt?.toISOString() ?? null,
@@ -579,16 +591,45 @@ export class MatchHistoryService {
},
participants: match.info.participants
.filter((participant) => participant.teamId === team.teamId)
.map((participant) => ({
puuid: participant.puuid,
gameName: participant.riotIdGameName || participant.summonerName || 'Unknown',
tagLine: participant.riotIdTagLine || '',
championId: participant.championId,
teamPosition: participant.teamPosition || participant.individualPosition,
kills: participant.kills,
deaths: participant.deaths,
assists: participant.assists,
})),
.map((participant) => {
const totalCs = this.resolveTotalCs(participant);
const minutes = this.resolveGameMinutes(match, participant);
return {
puuid: participant.puuid,
gameName: participant.riotIdGameName || participant.summonerName || 'Unknown',
tagLine: participant.riotIdTagLine || '',
championId: participant.championId,
championLevel: participant.champLevel,
teamPosition: participant.teamPosition || participant.individualPosition,
kills: participant.kills,
deaths: participant.deaths,
assists: participant.assists,
items: [
participant.item0,
participant.item1,
participant.item2,
participant.item3,
participant.item4,
participant.item5,
],
trinket: participant.item6,
summonerSpells: [participant.summoner1Id, participant.summoner2Id],
perks: this.resolvePerks(participant),
totalCs,
csPerMin: this.average(totalCs, minutes),
goldEarned: participant.goldEarned,
damageDealtToChampions: participant.totalDamageDealtToChampions,
damageTaken: participant.totalDamageTaken,
visionScore: participant.visionScore,
wardsPlaced: participant.wardsPlaced,
wardsKilled: participant.wardsKilled,
controlWardsBought: this.numberField(
participant,
'visionWardsBoughtInGame',
),
};
}),
}));
}
@@ -27,6 +27,16 @@ export interface UserHistoryProfileResponse {
losses: number;
fetchedAt: string;
}>;
tierHistory: Array<{
queueType: string;
tier: string;
rank?: string;
leaguePoints?: number;
wins?: number;
losses?: number;
recordedAt: string;
season?: string;
}>;
season: HistorySeasonDto;
seasons: HistorySeasonDto[];
lastFetchedAt: string | null;
@@ -98,6 +108,31 @@ export interface RecentMatchesResponse {
season: HistorySeasonDto;
}
export interface RecentMatchTeamParticipantView {
puuid: string;
gameName: string;
tagLine: string;
championId: number;
championLevel: number;
teamPosition: string;
kills: number;
deaths: number;
assists: number;
items: number[];
trinket: number;
summonerSpells: [number, number];
perks: { primaryStyle?: number; subStyle?: number; keystone?: number };
totalCs: number;
csPerMin: number;
goldEarned: number;
damageDealtToChampions: number;
damageTaken: number;
visionScore: number;
wardsPlaced: number;
wardsKilled: number;
controlWardsBought: number;
}
export interface RecentMatchView {
matchId: string;
queueId: number;
@@ -132,15 +167,6 @@ export interface RecentMatchView {
side: 100 | 200;
win: boolean;
objectives?: { baron?: number; dragon?: number; tower?: number };
participants: Array<{
puuid: string;
gameName: string;
tagLine: string;
championId: number;
teamPosition: string;
kills: number;
deaths: number;
assists: number;
}>;
participants: RecentMatchTeamParticipantView[];
}>;
}
@@ -173,6 +173,14 @@ export class UpdateMatchDto {
schedule?: MatchScheduleItemDto[];
}
export class UpdateParticipantDto {
@IsEnum(POSITIONS)
mainPosition!: Position;
@IsEnum(POSITIONS)
subPosition!: Position;
}
export class JoinMatchDto {
@IsArray()
@ArrayMinSize(1)
+70 -4
View File
@@ -27,6 +27,7 @@ import {
CreateMatchDto,
JoinMatchDto,
UpdateMatchDto,
UpdateParticipantDto,
} from './dto/create-match.dto';
import { MatchService } from './match.service';
@@ -71,16 +72,27 @@ export class MatchController {
communityId: mongoose.Types.ObjectId,
@Query('status') status?: MatchStatus,
@Query('limit') limit?: string,
@Query('page') page?: string,
@Query('offset') offset?: string,
@Query('scheduledFrom') scheduledFrom?: string,
@Query('scheduledTo') scheduledTo?: string,
@Query('sort') sort?: 'asc' | 'desc',
) {
const matches = await this.matchService.list({
const result = await this.matchService.listPage({
communityId,
status,
limit: limit ? Number(limit) : undefined,
limit: this.toOptionalNumber(limit),
page: this.toOptionalNumber(page),
offset: this.toOptionalNumber(offset),
scheduledFrom: this.toOptionalDate(scheduledFrom),
scheduledTo: this.toOptionalDate(scheduledTo),
sort,
});
if (!currentUser) return { matches };
if (!currentUser) return result;
const myId = currentUser._id;
return {
matches: matches.map((m) => this.annotateJoined(m, myId)),
...result,
matches: result.matches.map((m) => this.annotateJoined(m, myId)),
};
}
@@ -137,6 +149,49 @@ export class MatchController {
});
}
// 관리자 전용 — 참가자 주/부 포지션 변경.
@Patch(':matchId/participants/:userId')
@Roles('admin', 'owner')
@UseGuards(RolesGuard)
public async updateParticipant(
@CurrentUser() currentUser: UserDocument,
@Param('communityId', ParseObjectIdPipe)
communityId: mongoose.Types.ObjectId,
@Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId,
@Param('userId', ParseObjectIdPipe) userId: mongoose.Types.ObjectId,
@Body() body: UpdateParticipantDto,
) {
this.assertSameCommunity(currentUser, communityId);
const match = await this.matchService.updateParticipantPositions({
matchId,
communityId,
targetUserId: userId,
mainPosition: body.mainPosition,
subPosition: body.subPosition,
});
return this.matchService.serialize(match);
}
// 관리자 전용 — 참가자 강제 제외.
@Delete(':matchId/participants/:userId')
@Roles('admin', 'owner')
@UseGuards(RolesGuard)
@HttpCode(HttpStatus.NO_CONTENT)
public async removeParticipant(
@CurrentUser() currentUser: UserDocument,
@Param('communityId', ParseObjectIdPipe)
communityId: mongoose.Types.ObjectId,
@Param('matchId', ParseObjectIdPipe) matchId: mongoose.Types.ObjectId,
@Param('userId', ParseObjectIdPipe) userId: mongoose.Types.ObjectId,
) {
this.assertSameCommunity(currentUser, communityId);
await this.matchService.removeParticipant({
matchId,
communityId,
targetUserId: userId,
});
}
private resolveJoinerUserId(
currentUser: UserDocument | undefined,
bodyUserId?: string,
@@ -167,4 +222,15 @@ export class MatchController {
throw new BadRequestException('Different community.');
}
}
private toOptionalNumber(value?: string): number | undefined {
const numberValue = Number(value);
return Number.isFinite(numberValue) ? numberValue : undefined;
}
private toOptionalDate(value?: string): Date | undefined {
if (!value) return undefined;
const date = new Date(value);
return Number.isNaN(date.getTime()) ? undefined : date;
}
}
@@ -0,0 +1,234 @@
import mongoose from 'mongoose';
import { MatchService } from './match.service';
describe('MatchService', () => {
function createService(match: Record<string, unknown>) {
const MatchModel = {
findById: jest.fn().mockResolvedValue(match),
};
const connectionService = {
getModel: jest.fn().mockImplementation(async (name: string) => {
if (name === 'match') return MatchModel;
return {};
}),
};
const tournamentCodeService = {
buildSlots: jest.fn().mockResolvedValue([]),
releaseFromMatch: jest.fn().mockResolvedValue(undefined),
};
const communityStatsService = {
invalidateCommunity: jest.fn().mockResolvedValue(undefined),
};
const matchStatsService = {
buildAndUpsert: jest.fn().mockResolvedValue(undefined),
removeByMatch: jest.fn().mockResolvedValue(undefined),
};
return {
service: new MatchService(
connectionService as never,
tournamentCodeService as never,
communityStatsService as never,
matchStatsService as never,
),
tournamentCodeService,
matchStatsService,
};
}
function createServiceWithListModel() {
const exec = jest.fn().mockResolvedValue([{ title: 'second page' }]);
const limit = jest.fn().mockReturnValue({ exec });
const skip = jest.fn().mockReturnValue({ limit });
const sort = jest.fn().mockReturnValue({ skip });
const find = jest.fn().mockReturnValue({ sort });
const countExec = jest.fn().mockResolvedValue(12);
const countDocuments = jest.fn().mockReturnValue({ exec: countExec });
const MatchModel = {
find,
countDocuments,
};
const connectionService = {
getModel: jest.fn().mockImplementation(async (name: string) => {
if (name === 'match') return MatchModel;
return {};
}),
};
const tournamentCodeService = {
buildSlots: jest.fn().mockResolvedValue([]),
releaseFromMatch: jest.fn().mockResolvedValue(undefined),
};
const communityStatsService = {
invalidateCommunity: jest.fn().mockResolvedValue(undefined),
};
const matchStatsService = {
buildAndUpsert: jest.fn().mockResolvedValue(undefined),
removeByMatch: jest.fn().mockResolvedValue(undefined),
};
return {
service: new MatchService(
connectionService as never,
tournamentCodeService as never,
communityStatsService as never,
matchStatsService as never,
),
MatchModel,
sort,
skip,
limit,
};
}
it('returns a paginated match list with total count', async () => {
const communityId = new mongoose.Types.ObjectId();
const { service, MatchModel, sort, skip, limit } =
createServiceWithListModel();
const page = await service.listPage({
communityId,
page: 2,
limit: 5,
});
expect(MatchModel.find).toHaveBeenCalledWith({ communityId });
expect(MatchModel.countDocuments).toHaveBeenCalledWith({ communityId });
expect(sort).toHaveBeenCalledWith({ scheduledAt: -1 });
expect(skip).toHaveBeenCalledWith(5);
expect(limit).toHaveBeenCalledWith(5);
expect(page).toEqual({
matches: [{ title: 'second page' }],
total: 12,
page: 2,
limit: 5,
});
});
it('applies offset before page-based pagination', async () => {
const communityId = new mongoose.Types.ObjectId();
const { service, skip } = createServiceWithListModel();
const page = await service.listPage({
communityId,
offset: 4,
page: 2,
limit: 5,
});
expect(skip).toHaveBeenCalledWith(9);
expect(page.total).toBe(8);
});
it('filters future matches and sorts oldest first for upcoming sections', async () => {
const communityId = new mongoose.Types.ObjectId();
const scheduledFrom = new Date('2026-06-08T12:00:00.000Z');
const { service, MatchModel, sort } = createServiceWithListModel();
await service.listPage({
communityId,
scheduledFrom,
sort: 'asc',
limit: 4,
});
expect(MatchModel.find).toHaveBeenCalledWith({
communityId,
scheduledAt: { $gte: scheduledFrom },
});
expect(MatchModel.countDocuments).toHaveBeenCalledWith({
communityId,
scheduledAt: { $gte: scheduledFrom },
});
expect(sort).toHaveBeenCalledWith({ scheduledAt: 1 });
});
it('filters past matches and keeps newest first for history sections', async () => {
const communityId = new mongoose.Types.ObjectId();
const scheduledTo = new Date('2026-06-08T12:00:00.000Z');
const { service, MatchModel, sort } = createServiceWithListModel();
await service.listPage({
communityId,
scheduledTo,
sort: 'desc',
limit: 10,
});
expect(MatchModel.find).toHaveBeenCalledWith({
communityId,
scheduledAt: { $lt: scheduledTo },
});
expect(MatchModel.countDocuments).toHaveBeenCalledWith({
communityId,
scheduledAt: { $lt: scheduledTo },
});
expect(sort).toHaveBeenCalledWith({ scheduledAt: -1 });
});
it('clears game schedule when a built match returns to recruiting', async () => {
const communityId = new mongoose.Types.ObjectId();
const match = {
communityId,
status: 'team-built',
tournamentCodeIds: [],
gameSchedule: [{ gameNumber: 1, teamAIndex: 2, teamBIndex: 4 }],
teams: [{ teamIndex: 1 }],
teamBuiltAt: new Date(),
result: { games: [] },
resultPollState: { state: 'polling' },
set: jest.fn(function (
this: Record<string, unknown>,
patch: Record<string, unknown>,
) {
Object.assign(this, patch);
}),
save: jest.fn().mockResolvedValue(undefined),
};
const { service, tournamentCodeService, matchStatsService } =
createService(match);
await service.update({
matchId: new mongoose.Types.ObjectId(),
communityId,
patch: { status: 'recruiting' },
});
expect(tournamentCodeService.releaseFromMatch).not.toHaveBeenCalled();
expect(match.tournamentCodeIds).toEqual([]);
expect(match.gameSchedule).toEqual([]);
expect(match.teamBuiltAt).toBeUndefined();
expect(match.result).toBeUndefined();
expect(match.resultPollState).toBeUndefined();
expect(match.save).toHaveBeenCalledTimes(1);
expect(matchStatsService.removeByMatch).toHaveBeenCalledWith(match._id);
});
it('releases reserved codes when returning a built match to recruiting', async () => {
const communityId = new mongoose.Types.ObjectId();
const codeId = new mongoose.Types.ObjectId();
const match = {
communityId,
status: 'in-progress',
tournamentCodeIds: [codeId],
gameSchedule: [{ gameNumber: 1, teamAIndex: 1, teamBIndex: 3 }],
set: jest.fn(function (
this: Record<string, unknown>,
patch: Record<string, unknown>,
) {
Object.assign(this, patch);
}),
save: jest.fn().mockResolvedValue(undefined),
};
const { service, tournamentCodeService } = createService(match);
await service.update({
matchId: new mongoose.Types.ObjectId(),
communityId,
patch: { status: 'recruiting' },
});
expect(tournamentCodeService.releaseFromMatch).toHaveBeenCalledWith(match);
expect(match.tournamentCodeIds).toEqual([]);
expect(match.gameSchedule).toEqual([]);
});
});
+318 -25
View File
@@ -1,21 +1,31 @@
import {
BadRequestException,
Injectable,
InternalServerErrorException,
NotFoundException,
} from '@nestjs/common';
import mongoose from 'mongoose';
import { MatchStatsService } from '../community-stats/match-stats.service';
import { CommunityStatsService } from '../community-stats/community-stats.service';
import { ConnectionService } from '../global/database/connection.service';
import {
Match,
MatchDocument,
MatchSeriesResult,
MatchStatus,
Position,
PositionPreference,
TierInfo,
} from '../global/database/schema';
import { DEFAULT_TOURNAMENT_GAME_COUNT } from '../tournament-code/tournament-code.constants';
import { TournamentCodeService } from '../tournament-code/tournament-code.service';
const MATCH_SHORT_CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
const MATCH_SHORT_CODE_LENGTH = 4;
const MATCH_SHORT_CODE_GENERATION_ATTEMPTS = 20;
const DEFAULT_MATCH_LIST_LIMIT = 50;
const MAX_MATCH_LIST_LIMIT = 200;
interface CreateMatchParams {
communityId: mongoose.Types.ObjectId;
hostUserId?: mongoose.Types.ObjectId;
@@ -32,6 +42,23 @@ interface ListMatchesQuery {
communityId: mongoose.Types.ObjectId;
status?: MatchStatus;
limit?: number;
scheduledFrom?: Date;
scheduledTo?: Date;
sort?: 'asc' | 'desc';
}
interface ListMatchesPageQuery extends ListMatchesQuery {
page?: number;
offset?: number;
}
interface MatchListFilter {
communityId: mongoose.Types.ObjectId;
status?: MatchStatus;
scheduledAt?: {
$gte?: Date;
$lt?: Date;
};
}
interface JoinMatchParams {
@@ -42,12 +69,32 @@ interface JoinMatchParams {
riotPuuid?: string;
}
interface CancelMatchJoinParams {
matchId: mongoose.Types.ObjectId;
userId: mongoose.Types.ObjectId;
}
interface RemoveParticipantParams {
matchId: mongoose.Types.ObjectId;
communityId: mongoose.Types.ObjectId;
targetUserId: mongoose.Types.ObjectId;
}
interface UpdateParticipantPositionsParams {
matchId: mongoose.Types.ObjectId;
communityId: mongoose.Types.ObjectId;
targetUserId: mongoose.Types.ObjectId;
mainPosition: Position;
subPosition: Position;
}
@Injectable()
export class MatchService {
constructor(
private readonly connectionService: ConnectionService,
private readonly tournamentCodeService: TournamentCodeService,
private readonly communityStatsService: CommunityStatsService,
private readonly matchStatsService: MatchStatsService,
) {}
public async create(params: CreateMatchParams): Promise<MatchDocument> {
@@ -59,6 +106,9 @@ export class MatchService {
.exec();
return MatchModel.create({
...params.data,
shortCode:
params.data.shortCode ??
(await this.generateUniqueShortCode(MatchModel, params.communityId)),
gameCount:
params.data.gameCount ??
community?.matchGameCount ??
@@ -70,19 +120,54 @@ export class MatchService {
public async list(query: ListMatchesQuery): Promise<MatchDocument[]> {
const MatchModel = await this.connectionService.getModel('match');
const filter: {
communityId: mongoose.Types.ObjectId;
status?: MatchStatus;
} = {
communityId: query.communityId,
};
if (query.status) filter.status = query.status;
const filter = this.buildListFilter(query);
return MatchModel.find(filter)
.sort({ scheduledAt: -1 })
.limit(Math.min(query.limit ?? 50, 200))
.sort(this.buildListSort(query.sort))
.limit(this.normalizeListLimit(query.limit))
.exec();
}
public async listPage(query: ListMatchesPageQuery): Promise<{
matches: MatchDocument[];
total: number;
page: number;
limit: number;
}> {
const MatchModel = await this.connectionService.getModel('match');
const filter = this.buildListFilter(query);
const page = this.normalizeListPage(query.page);
const limit = this.normalizeListLimit(query.limit);
const offset = this.normalizeListOffset(query.offset);
const skip = offset + (page - 1) * limit;
const [matches, rawTotal] = await Promise.all([
MatchModel.find(filter)
.sort(this.buildListSort(query.sort))
.skip(skip)
.limit(limit)
.exec(),
MatchModel.countDocuments(filter).exec(),
]);
return {
matches,
total: Math.max(rawTotal - offset, 0),
page,
limit,
};
}
public async ensureShortCode(match: MatchDocument): Promise<MatchDocument> {
if (match.shortCode) return match;
const MatchModel = await this.connectionService.getModel('match');
match.shortCode = await this.generateUniqueShortCode(
MatchModel,
match.communityId,
);
await match.save();
return match;
}
public async getById(
matchId: mongoose.Types.ObjectId,
): Promise<MatchDocument> {
@@ -99,15 +184,7 @@ export class MatchService {
(left, right) => left.gameNumber - right.gameNumber,
);
if (!obj.result.seriesResults?.length) {
obj.result.seriesResults = [
{
blueGroupIndex: 1,
redGroupIndex: 1,
blueScore: obj.result.blueScore ?? 0,
redScore: obj.result.redScore ?? 0,
winnerSide: obj.result.winnerSide,
},
];
obj.result.seriesResults = this.buildSeriesResults(obj.result.games);
}
}
return {
@@ -120,8 +197,8 @@ export class MatchService {
})),
teams: (obj.teams ?? []).map((team) => ({
...team,
groupIndex: team.groupIndex ?? 1,
})),
gameSchedule: obj.gameSchedule ?? [],
tournamentCodes: await this.tournamentCodeService.buildSlots(match),
};
}
@@ -143,18 +220,24 @@ export class MatchService {
);
}
match.set(params.patch);
if (
previousStatus !== 'recruiting' &&
match.status === 'recruiting' &&
match.tournamentCodeIds.length > 0
) {
await this.tournamentCodeService.releaseFromMatch(match);
if (previousStatus !== 'recruiting' && match.status === 'recruiting') {
if (match.tournamentCodeIds.length > 0) {
await this.tournamentCodeService.releaseFromMatch(match);
}
match.tournamentCodeIds = [];
match.gameSchedule = [];
match.teamBuiltAt = undefined;
match.result = undefined;
match.resultPollState = undefined;
}
await match.save();
if (previousStatus !== 'recruiting' && match.status === 'recruiting') {
await this.matchStatsService.removeByMatch(match._id);
await this.communityStatsService.invalidateCommunity(params.communityId);
} else if (match.result?.games?.length) {
await this.matchStatsService.buildAndUpsert(match._id);
await this.communityStatsService.invalidateCommunity(params.communityId);
}
return match;
}
@@ -169,6 +252,7 @@ export class MatchService {
throw new BadRequestException('Match does not belong to this community.');
}
await this.tournamentCodeService.releaseFromMatch(match);
await this.matchStatsService.removeByMatch(match._id);
await match.deleteOne();
await this.communityStatsService.invalidateCommunity(params.communityId);
}
@@ -217,6 +301,118 @@ export class MatchService {
return match;
}
public async cancelJoin(
params: CancelMatchJoinParams,
): Promise<MatchDocument> {
const MatchModel = await this.connectionService.getModel('match');
const UserModel = await this.connectionService.getModel('user');
const user = await UserModel.findById(params.userId);
if (!user) throw new NotFoundException('User not found.');
const match = await MatchModel.findById(params.matchId);
if (!match) throw new NotFoundException('Match not found.');
if (!match.communityId.equals(user.communityId)) {
throw new BadRequestException(
'User and match belong to different communities.',
);
}
if (match.status !== 'recruiting') {
throw new BadRequestException('Match is not recruiting.');
}
const participantIndex = match.participants.findIndex((participant) =>
participant.userId.equals(user._id),
);
if (participantIndex === -1) {
throw new BadRequestException('User has not joined this match.');
}
match.participants.splice(participantIndex, 1);
await match.save();
return match;
}
// 관리자 전용 — 특정 참가자를 강제로 제외한다.
public async removeParticipant(
params: RemoveParticipantParams,
): Promise<MatchDocument> {
const match = await this.loadRecruitingMatch(
params.matchId,
params.communityId,
);
const participantIndex = match.participants.findIndex((participant) =>
participant.userId.equals(params.targetUserId),
);
if (participantIndex === -1) {
throw new NotFoundException('Participant not found.');
}
match.participants.splice(participantIndex, 1);
await match.save();
return match;
}
// 관리자 전용 — 참가자의 주/부 포지션(선호 우선순위 1·2)을 교체한다.
public async updateParticipantPositions(
params: UpdateParticipantPositionsParams,
): Promise<MatchDocument> {
const match = await this.loadRecruitingMatch(
params.matchId,
params.communityId,
);
const participant = match.participants.find((entry) =>
entry.userId.equals(params.targetUserId),
);
if (!participant) {
throw new NotFoundException('Participant not found.');
}
participant.preferredPositions = this.reorderPreferredPositions(
params.mainPosition,
params.subPosition,
participant.preferredPositions,
);
match.markModified('participants');
await match.save();
return match;
}
private async loadRecruitingMatch(
matchId: mongoose.Types.ObjectId,
communityId: mongoose.Types.ObjectId,
): Promise<MatchDocument> {
const MatchModel = await this.connectionService.getModel('match');
const match = await MatchModel.findById(matchId);
if (!match) throw new NotFoundException('Match not found.');
if (!match.communityId.equals(communityId)) {
throw new BadRequestException('Different community.');
}
if (match.status !== 'recruiting') {
throw new BadRequestException('Match is not recruiting.');
}
return match;
}
// 주/부 포지션을 priority 1·2로 올리고 기존 나머지 선호는 뒤로 보존한다.
private reorderPreferredPositions(
mainPosition: Position,
subPosition: Position,
current: PositionPreference[],
): PositionPreference[] {
const ordered: Position[] = [mainPosition];
if (subPosition !== mainPosition) ordered.push(subPosition);
for (const preference of [...current].sort(
(left, right) => left.priority - right.priority,
)) {
if (!ordered.includes(preference.position)) {
ordered.push(preference.position);
}
}
return ordered.map((position, index) => ({
position,
priority: index + 1,
}));
}
private selectParticipantTier(tiers: TierInfo[]): TierInfo | undefined {
const tier =
tiers.find((entry) => entry.queueType === 'RANKED_SOLO_5x5') ?? tiers[0];
@@ -239,4 +435,101 @@ export class MatchService {
fetchedAt: tier.fetchedAt,
};
}
private buildListFilter(query: ListMatchesQuery): MatchListFilter {
const filter: MatchListFilter = {
communityId: query.communityId,
};
if (query.status) filter.status = query.status;
if (query.scheduledFrom || query.scheduledTo) {
filter.scheduledAt = {};
if (query.scheduledFrom) filter.scheduledAt.$gte = query.scheduledFrom;
if (query.scheduledTo) filter.scheduledAt.$lt = query.scheduledTo;
}
return filter;
}
private buildListSort(sort?: 'asc' | 'desc'): { scheduledAt: 1 | -1 } {
return { scheduledAt: sort === 'asc' ? 1 : -1 };
}
private normalizeListLimit(limit?: number): number {
if (!Number.isFinite(limit) || !limit || limit < 1) {
return DEFAULT_MATCH_LIST_LIMIT;
}
return Math.min(Math.floor(limit), MAX_MATCH_LIST_LIMIT);
}
private normalizeListPage(page?: number): number {
if (!Number.isFinite(page) || !page || page < 1) {
return 1;
}
return Math.floor(page);
}
private normalizeListOffset(offset?: number): number {
if (!Number.isFinite(offset) || !offset || offset < 1) {
return 0;
}
return Math.floor(offset);
}
private async generateUniqueShortCode(
MatchModel: mongoose.Model<Match>,
communityId: mongoose.Types.ObjectId,
): Promise<string> {
for (
let attempt = 0;
attempt < MATCH_SHORT_CODE_GENERATION_ATTEMPTS;
attempt += 1
) {
const shortCode = this.generateShortCode();
const exists = await MatchModel.exists({ communityId, shortCode });
if (!exists) return shortCode;
}
throw new InternalServerErrorException(
'Failed to generate unique match short code.',
);
}
private generateShortCode(): string {
let code = '';
for (let index = 0; index < MATCH_SHORT_CODE_LENGTH; index += 1) {
const alphabetIndex = Math.floor(
Math.random() * MATCH_SHORT_CODE_ALPHABET.length,
);
code += MATCH_SHORT_CODE_ALPHABET[alphabetIndex];
}
return code;
}
private buildSeriesResults(
games: NonNullable<Match['result']>['games'],
): MatchSeriesResult[] {
const bySeries = new Map<string, MatchSeriesResult>();
for (const game of games) {
const teamAIndex = Math.min(game.blueTeamIndex, game.redTeamIndex);
const teamBIndex = Math.max(game.blueTeamIndex, game.redTeamIndex);
const key = `${teamAIndex}:${teamBIndex}`;
const current =
bySeries.get(key) ??
({
teamAIndex,
teamBIndex,
teamAWins: 0,
teamBWins: 0,
} satisfies MatchSeriesResult);
if (game.winnerTeamIndex === teamAIndex) current.teamAWins += 1;
if (game.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()];
}
}
@@ -0,0 +1,11 @@
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { RiotModule } from '../riot/riot.module';
import { BackgroundRefreshScheduler } from './background-refresh.scheduler';
import { StaleAccountRepository } from './stale-account.repository';
@Module({
imports: [ConfigModule, RiotModule],
providers: [BackgroundRefreshScheduler, StaleAccountRepository],
})
export class BackgroundRefreshModule {}
@@ -0,0 +1,211 @@
import mongoose from 'mongoose';
import { GarnetService } from '../global/garnet/garnet.service';
import { RiotAccountEnrichmentService } from '../riot/riot-account-enrichment.service';
import { RiotRateLimiterService } from '../riot/riot-rate-limiter.service';
import { BackgroundRefreshScheduler } from './background-refresh.scheduler';
import {
StaleAccountCandidate,
StaleAccountRepository,
} from './stale-account.repository';
type SchedulerInternals = BackgroundRefreshScheduler & {
tick(): Promise<void>;
};
function successResult() {
return {
summoner: 'fresh',
league: 'fresh',
masteries: 'fresh',
recentMatches: 'fresh',
account: {},
};
}
function candidate(puuid: string): StaleAccountCandidate {
return {
userId: new mongoose.Types.ObjectId(),
puuid,
};
}
function makeScheduler() {
const rawClient = {
sendCommand: jest.fn().mockResolvedValue(1),
};
const garnet = {
getString: jest.fn().mockResolvedValue(null),
setString: jest.fn().mockResolvedValue(undefined),
setStringIfAbsent: jest.fn().mockResolvedValue(true),
delete: jest.fn().mockResolvedValue(1),
raw: jest.fn().mockReturnValue(rawClient),
} as unknown as jest.Mocked<GarnetService> & { raw: jest.Mock };
const rateLimiter = {
isRefreshWindowOpen: jest.fn().mockResolvedValue(true),
} as unknown as jest.Mocked<RiotRateLimiterService>;
const enrichmentService = {
markRefreshRequested: jest.fn().mockResolvedValue(undefined),
enrichRiotAccount: jest.fn().mockResolvedValue(successResult()),
} as unknown as jest.Mocked<RiotAccountEnrichmentService>;
const staleAccountRepository = {
findStaleAccounts: jest.fn().mockResolvedValue([]),
} as unknown as jest.Mocked<StaleAccountRepository>;
const scheduler = new BackgroundRefreshScheduler(
garnet,
rateLimiter,
enrichmentService,
staleAccountRepository,
) as SchedulerInternals;
return {
scheduler,
garnet,
rawClient,
rateLimiter,
enrichmentService,
staleAccountRepository,
};
}
describe('BackgroundRefreshScheduler', () => {
afterEach(() => {
jest.useRealTimers();
jest.restoreAllMocks();
});
it('schedules ticks without requiring RIOT_BG_REFRESH_ENABLED', () => {
jest.useFakeTimers();
const setIntervalSpy = jest.spyOn(global, 'setInterval');
const { scheduler } = makeScheduler();
scheduler.onModuleInit();
expect(setIntervalSpy).toHaveBeenCalledTimes(2);
scheduler.onModuleDestroy();
});
it('uses the dawn refresh gate ratio inside the KST background window', async () => {
jest.useFakeTimers().setSystemTime(new Date('2026-05-02T18:00:00.000Z'));
const { scheduler, rateLimiter } = makeScheduler();
await scheduler.tick();
expect(rateLimiter.isRefreshWindowOpen).toHaveBeenCalledWith(0.8);
});
it('uses the opportunistic refresh gate ratio outside the KST background window', async () => {
jest.useFakeTimers().setSystemTime(new Date('2026-05-02T17:59:59.000Z'));
const { scheduler, rateLimiter, staleAccountRepository } = makeScheduler();
await scheduler.tick();
expect(rateLimiter.isRefreshWindowOpen).toHaveBeenCalledWith(0.5);
expect(staleAccountRepository.findStaleAccounts).toHaveBeenCalledTimes(1);
});
it('does not query stale accounts when the refresh gate is closed', async () => {
jest.useFakeTimers().setSystemTime(new Date('2026-05-02T18:00:00.000Z'));
const { scheduler, rateLimiter, staleAccountRepository } = makeScheduler();
rateLimiter.isRefreshWindowOpen.mockResolvedValue(false);
await scheduler.tick();
expect(staleAccountRepository.findStaleAccounts).not.toHaveBeenCalled();
});
it('does not query stale accounts when another leader holds the lock', async () => {
jest.useFakeTimers().setSystemTime(new Date('2026-05-02T18:00:00.000Z'));
const { scheduler, garnet, staleAccountRepository } = makeScheduler();
garnet.getString.mockResolvedValue('another-consumer');
await scheduler.tick();
expect(staleAccountRepository.findStaleAccounts).not.toHaveBeenCalled();
});
it('marks and enriches each stale candidate without background precharge', async () => {
jest.useFakeTimers().setSystemTime(new Date('2026-05-02T18:00:00.000Z'));
const { scheduler, enrichmentService, staleAccountRepository } =
makeScheduler();
const candidates = [candidate('puuid-1'), candidate('puuid-2')];
staleAccountRepository.findStaleAccounts.mockResolvedValue(candidates);
await scheduler.tick();
expect(enrichmentService.markRefreshRequested).toHaveBeenCalledTimes(2);
expect(enrichmentService.markRefreshRequested).toHaveBeenNthCalledWith(
1,
candidates[0].userId,
'puuid-1',
);
expect(enrichmentService.enrichRiotAccount).toHaveBeenNthCalledWith(2, {
userId: candidates[1].userId,
puuid: 'puuid-2',
options: { force: false },
});
});
it('stops the candidate loop when the refresh gate closes mid-tick', async () => {
jest.useFakeTimers().setSystemTime(new Date('2026-05-02T18:00:00.000Z'));
const {
scheduler,
rateLimiter,
enrichmentService,
staleAccountRepository,
} = makeScheduler();
staleAccountRepository.findStaleAccounts.mockResolvedValue([
candidate('puuid-1'),
candidate('puuid-2'),
]);
rateLimiter.isRefreshWindowOpen
.mockResolvedValueOnce(true)
.mockResolvedValueOnce(true)
.mockResolvedValueOnce(false);
await scheduler.tick();
expect(enrichmentService.enrichRiotAccount).toHaveBeenCalledTimes(1);
});
it('continues after a candidate throws and records a failure counter', async () => {
jest.useFakeTimers().setSystemTime(new Date('2026-05-02T18:00:00.000Z'));
const { scheduler, rawClient, enrichmentService, staleAccountRepository } =
makeScheduler();
const candidates = [candidate('puuid-1'), candidate('puuid-2')];
staleAccountRepository.findStaleAccounts.mockResolvedValue(candidates);
enrichmentService.enrichRiotAccount
.mockRejectedValueOnce(new Error('boom'))
.mockResolvedValueOnce(successResult() as never);
await scheduler.tick();
expect(enrichmentService.enrichRiotAccount).toHaveBeenCalledTimes(2);
expect(rawClient.sendCommand).toHaveBeenCalledWith([
'INCR',
'riot:bg:fail:puuid-1',
]);
expect(rawClient.sendCommand).toHaveBeenCalledWith([
'EXPIRE',
'riot:bg:fail:puuid-1',
'86400',
]);
});
it('skips candidates already in failure backoff', async () => {
jest.useFakeTimers().setSystemTime(new Date('2026-05-02T18:00:00.000Z'));
const { scheduler, garnet, enrichmentService, staleAccountRepository } =
makeScheduler();
staleAccountRepository.findStaleAccounts.mockResolvedValue([
candidate('skip-me'),
]);
garnet.getString.mockImplementation(async (key: string) => {
if (key.includes('riot:bg:fail:skip-me')) return '3';
return null;
});
await scheduler.tick();
expect(enrichmentService.markRefreshRequested).not.toHaveBeenCalled();
expect(enrichmentService.enrichRiotAccount).not.toHaveBeenCalled();
});
});
Loaded 100 of 232 files, more files were not shown because too many files have changed in this diff. Show more