# 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: " 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= ``` **신규 파일**: `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(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//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` 실행.