# 로컬 개발과 테스트 실행 안내

## 처음 한 번만 준비하기

### 1. Node.js 확인

터미널에서 실행한다.

```bash
node --version
npm --version
```

두 명령 모두 버전 번호가 출력되어야 한다. 명령을 찾을 수 없다는 메시지가
나오면 Node.js LTS 버전을 먼저 설치한다.

### 2. 프로젝트 폴더로 이동

```bash
cd /Users/bicute/Desktop/dxp6800pro/uniare-simulator
```

### 3. 패키지 설치

프로젝트를 처음 받았거나 `package.json`이 변경되었을 때 실행한다.

```bash
npm install
```

`node_modules`는 자동 생성되며 Git에 올리지 않는다.

## 개발 서버 실행

실시간 대기실을 사용하므로 터미널 두 개를 연다.

첫 번째 터미널에서 Socket.IO 서버를 실행한다.

```bash
npm run dev:server
```

두 번째 터미널에서 Vue 개발 서버를 실행한다.

```bash
npm run dev
```

터미널에 다음과 비슷한 주소가 표시된다.

```text
Local: http://localhost:5173/
```

해당 주소를 브라우저에서 연다. 개발 중 코드를 저장하면 화면이 자동으로
갱신된다.

Vite는 브라우저의 `/socket.io` 요청을 로컬 `31873` 포트로 전달한다. 두
개발 서버를 종료하려면 각각의 터미널에서 `Control + C`를 누른다.

## 같은 네트워크의 다른 기기에서 테스트

```bash
npm run dev -- --host
```

터미널의 `Network` 주소를 같은 공유기에 연결된 휴대전화나 태블릿에서 연다.
macOS 방화벽이 연결 허용 여부를 물으면 개발 중에만 허용한다.

## 배포용 빌드 확인

코드 변경을 완료하기 전에 반드시 실행한다.

```bash
npm run build
```

성공하면 `dist/` 폴더가 생성된다. 오류가 발생하면 배포하지 말고 오류를 먼저
수정한다.

빌드 결과를 로컬에서 확인하려면 다음을 실행한다.

```bash
npm run preview
```

개발 서버와 마찬가지로 터미널에 표시된 주소로 접속한다.

## 환경변수 사용

로컬 전용 값은 프로젝트 루트의 `.env.local`에 작성한다.

```text
VITE_CARD_ASSET_BASE_URL=http://playuniare.sori.studio/card-assets
```

- `VITE_`로 시작하는 값은 브라우저에 노출될 수 있다.
- 비밀번호, 개인키, NAS 관리자 계정은 넣지 않는다.
- `.env.local`은 Git에 커밋하지 않는다.
- 로컬 개발에서 실제 카드 이미지를 확인하려면 운영 카드 자산 주소를
  `VITE_CARD_ASSET_BASE_URL`에 사용한다.

## 일반적인 작업 순서

```bash
git pull
npm install
npm run dev
```

작업이 끝난 뒤:

```bash
npm run test:server
npm run build
git status
```

`npm run test:server`는 `npm run dev:server`가 실행 중일 때 방 생성, 참가,
덱 등록, 양쪽 준비와 게임 시작 이벤트를 검증한다.

변경 문서를 확인한 후 커밋하고 푸시한다.

## 자주 발생하는 문제

### 포트가 이미 사용 중이라고 나오는 경우

Vite가 다른 포트를 자동으로 제시할 수 있다. 터미널에 새로 표시된 주소로
접속한다. 반드시 5173 포트를 고정할 필요는 없다.

로컬 Socket.IO 서버는 기본적으로 `31873` 포트를 사용한다. 이 포트가 이미
사용 중이면 두 터미널에서 같은 환경변수를 사용한다.

```bash
SOCKET_SERVER_PORT=31874 npm run dev:server
SOCKET_SERVER_PORT=31874 npm run dev
```

운영에서는 `31873`을 Docker 내부에서만 사용하므로 NAS의 다른 컨테이너가
내부에서 같은 번호를 사용해도 충돌하지 않는다.

### 실시간 서버에 연결되지 않는 경우

- `npm run dev:server` 터미널이 실행 중인지 확인한다.
- 서버 터미널에 `listening on port 31873` 메시지가 있는지 확인한다.
- 포트를 바꿨다면 Vue와 Socket.IO 서버를 같은 `SOCKET_SERVER_PORT`로
  실행했는지 확인한다.
- 브라우저 개발자 도구 Network 탭에서 `/socket.io` 요청을 확인한다.

### 패키지 오류가 발생하는 경우

먼저 다음을 다시 실행한다.

```bash
npm install
npm run build
```

문제가 지속되면 오류 전문과 Node.js 버전을 기록하고 임의로 대규모 패키지
업데이트를 하지 않는다.

### 카드 이미지가 보이지 않는 경우

- 덱의 `series` 값이 올바른지 확인한다.
- 이미지 파일명이 실제 파일과 같은지 확인한다.
- `VITE_CARD_ASSET_BASE_URL` 값 끝에 불필요한 경로가 없는지 확인한다.
- 브라우저 개발자 도구의 Network 탭에서 404 또는 CORS 오류를 확인한다.