playuniare.sori.studio/docs/spec.md

프로젝트 기술 명세

프로젝트 개요

• 프로젝트명: Play Uniare
• 목적: Union Arena 덱을 불러와 카드 조작 중심의 로컬·온라인 플레이 제공
• 현재 단계: 프로젝트 기반 구성
• 프런트엔드: Vue 3, Vite, Tailwind CSS
• 배포 대상: UGREEN NAS의 Docker 환경

제품 범위

포함

• 기존 덱 빌더 쿼리에서 덱 불러오기
• 카드 수량만큼 독립 인스턴스 생성
• 덱 셔플과 드로우
• 카드 드래그 이동
• 카드 앞면·뒷면 전환
• 카드 탭·언탭
• 손패, 필드, 덱, 무덤, 공개 영역
• 덱 위·아래 또는 무덤으로 카드 이동
• 덱 위에서 여러 장을 공개한 후 목적지 지정
• 혼자 연습하는 로컬 모드
• 방 코드 기반 2인 세션
• 각 플레이어가 자신의 카드만 조작하는 권한 모델

제외

• 카드 효과와 게임 규칙 자동 판정
• 음성·텍스트 채팅
• 랭킹, 매칭, 대회 운영
• 초기 단계의 회원가입

덱 입력

초기에는 기존 덱 빌더 형식을 호환한다.

?series=ua03&seriesName=HUNTER%C3%97HUNTER&cards=<encoded-json>

수신 후 다음 절차를 적용한다.

1. 쿼리 길이와 필수 필드를 검사한다.
2. JSON 디코딩 오류를 처리한다.
3. series, imgSrc, Number, count를 검증한다.
4. 카드 수량만큼 고유한 게임 카드 인스턴스를 만든다.
5. 이미지 주소는 환경변수 기반 카드 자산 원본과 조합한다.

장기적으로는 축약된 덱 코드 또는 서버의 deckId 방식으로 전환한다.

권한 모델

• 플레이어는 자기 카드만 이동·뒤집기·탭·정리할 수 있다.
• 상대 효과로 내 카드가 제거될 때에도 내가 직접 내 카드를 이동한다.
• 서버는 모든 카드 조작에서 요청 사용자와 카드 소유자를 비교한다.
• 상대 손패에는 장수만 공개하고 카드 식별 정보는 공개하지 않는다.

화면 좌표

• 배경 이미지는 카드 배치 가이드로 사용한다.
• 실제 영역은 배경 위의 투명한 드롭 영역으로 정의한다.
• 자유 배치 좌표는 보드 너비·높이 기준 0부터 1 사이 값으로 저장한다.
• 창 크기가 변해도 같은 상대 위치를 유지해야 한다.

상태 저장

• 로컬 모드: 브라우저 메모리, 추후 복구가 필요하면 localStorage 검토
• 온라인 모드: 서버가 방 상태의 최종 권위를 가진다.
• 초기 서버: Node.js와 Socket.IO, 메모리 기반 방 상태
• 운영 안정화 단계: Redis 또는 데이터베이스 저장 검토

환경변수 예정

VITE_CARD_ASSET_BASE_URL=https://uniare.sori.studio/images
VITE_SOCKET_SERVER_URL=https://playuniare.sori.studio

실제 운영 값은 .env에 두고 Git에 커밋하지 않는다.

NAS 카드 이미지 공유

운영 NAS에서는 카드 이미지를 새 프로젝트에 복사하지 않는다. 기존 Uniare 컨테이너가 사용하는 웹 루트의 이미지 폴더를 읽기 전용으로 공유한다.

기존 Uniare 웹 루트:
/volume1/docker/projects/apps/uniare/config/www

카드 이미지 원본:
/volume1/docker/projects/apps/uniare/config/www/images

Play Uniare 컨테이너 내부:
/srv/uniare-card-images

브라우저 공개 경로:
/card-assets

• config/www는 기존 index.html이 존재하는 실제 웹 루트다.
• Docker bind mount는 images 폴더만 읽기 전용으로 연결한다.
• Play Uniare는 기존 카드 이미지를 읽을 수 있지만 수정하거나 삭제할 수 없다.
• 카드 이미지 URL은 /card-assets/<series>/<fileName> 형식을 사용한다.
• 같은 Play Uniare 도메인으로 제공되므로 별도의 CORS 설정이 필요하지 않다.