zenn/playuniare.sori.studio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bb5f663e48738b18b9366d803fb1b7cb6c7cfc0e
playuniare.sori.studio/docs/spec.md

4.9 KiB
Raw Blame History

프로젝트 기술 명세

프로젝트 개요

  • 프로젝트명: 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 또는 데이터베이스 저장 검토

포트 정책

  • Vue 개발 서버는 Vite가 제시하는 포트를 사용하며 기본값은 보통 5173이다.
  • 로컬 Socket.IO 서버 기본 포트는 31873이다.
  • Docker 컨테이너 내부 포트는 다른 컨테이너와 같아도 충돌하지 않는다.
  • NAS 호스트에 공개하는 포트는 다른 서비스와 겹치면 안 된다.
  • NAS 운영 HTTP 호스트 포트 기본값은 41809다.
  • 운영 HTTP 호스트 포트는 .env의 PLAYUNIARE_PRODUCTION_HTTP_PORT로 변경한다.
  • 기능 테스트는 로컬에서 수행하고 NAS에는 운영 컨테이너만 배포한다.
  • 운영 브라우저는 Socket.IO 포트를 직접 호출하지 않고 http://playuniare.sori.studio/socket.io처럼 같은 도메인의 리버스 프록시 경로를 사용한다.
  • 포트 번호는 코드에 하드코딩하지 않고 환경변수와 Compose 설정으로 관리한다.

환경변수 예정

VITE_CARD_ASSET_BASE_URL=/card-assets
VITE_SOCKET_SERVER_URL=http://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는 기존 카드 이미지를 읽을 수 있지만 수정하거나 삭제할 수 없다.
  • Nginx 작업 프로세스는 NAS 카드 파일 소유자와 같은 UID 1000의 cardreader 사용자로 실행한다.
  • 카드 이미지 URL은 /card-assets/<series>/<fileName> 형식을 사용한다.
  • 같은 Play Uniare 도메인으로 제공되므로 별도의 CORS 설정이 필요하지 않다.

배포 환경

  • 로컬 개발: Vite 개발 서버
  • 로컬 배포 검증: Docker Compose
  • NAS 운영: compose.yaml과 compose.nas.yaml
  • 운영 주소: http://playuniare.sori.studio
  • NAS 테스트 컨테이너는 별도로 유지하지 않는다.
Reference in New Issue View Git Blame Copy Permalink