# Fastify + MongoDB 서비스 전환

2026-09-08

## 확정 사항

- 사용자 지정 백엔드: Fastify.
- 사용자 최종 선택 데이터베이스: MongoDB `172.16.0.7:27017`. 이전 SQLite 선택을 대체한다.
- Fastify 인스턴스당 하나의 MongoClient 연결 풀을 유지하고 서버 종료 시 닫는다. 요청마다 연결·해제하지 않는다.
- 연결 URI와 DB 이름은 프로젝트 루트 `.config.json`으로 설정한다. `.config.json.sample`을 예시로 제공한다. 전용 DB `basket_utils` 사용은 사용자가 확인했으며 기존 다른 프로젝트 DB를 수정하지 않는다.
- 실제 구현: GPT-5.6 Luna, xhigh. 주 에이전트는 요구사항 정리·검토·검증·문서 담당.
- 범위: 로그인, 별도 관리자 페이지의 운영자 사용 승인, 여러 팀 생성/검색/가입 신청, 팀 소유자의 가입 승인과 팀원별 권한 설정, 팀별 전술 저장/불러오기, 기존 기기 전술의 명시적 가져오기.
- 기존 Three.js 편집/재생과 MP4 파일 직접 공유는 유지.
- 외부 로그인 서비스 키가 없는 초기 구현은 이메일/비밀번호 로그인. 카카오톡 파일 공유와 서비스 로그인 수단은 독립적이다.

## 사용자 흐름

1. 로그인 또는 회원가입.
2. 미승인 사용자는 승인 대기 화면. 운영자가 별도 관리자 페이지에서 서비스 이용을 승인하면 다시 로그인해 내 팀으로 진입.
3. 새 팀 생성 또는 기존 팀 이름 검색을 선택. 기존 팀에는 가입을 신청하고 해당 팀 소유자의 승인을 기다림. 계정 하나로 여러 팀 생성/참여 가능.
   - 팀 소유자는 가입 신청을 승인하면서 열람자 또는 편집자 권한을 선택하고, 이후 팀원별 권한을 변경할 수 있음.
   - 서비스 이용 승인과 팀 가입 승인은 별개. 팀 검색 결과만으로 전술이나 구성원 정보에 접근할 수 없음.
4. 팀 선택 후 해당 팀의 전술 목록 화면으로 이동. 저장된 전술을 선택하거나 새 전술의 이름·수비 형태를 정한 뒤에만 전술 캔버스로 진입.
5. 편집 화면에서 현재 팀 이름을 확인하며 저장·불러오기·MP4 생성/공유.
6. 캔버스에서 전술 목록으로 돌아갈 수 있고, 전술 목록에서 팀 선택으로 복귀. 팀 전환 시 다른 팀의 목록/임시 저장과 섞이지 않음.
7. 로그아웃 시 편집/공유 상태를 정리하고 로그인 화면으로 복귀.

## 검토 기준

- 회원가입이 자동 운영자 권한이나 자동 사용 승인을 부여하지 않는다.
- 운영자는 로컬 설정 절차로 초기화하며 공개 기본 비밀번호를 제공하지 않는다.
- 비밀번호는 해시로 저장하고 세션은 HttpOnly 쿠키로 관리한다.
- 서버가 매 요청의 승인 상태와 팀 소속을 확인한다.
- 운영자만 서비스 이용을 승인하고, 해당 팀 소유자만 팀 가입을 승인하거나 팀원 권한을 변경한다. 팀 소유자 역할은 일반 팀원 권한 변경 대상이 아니다.
- 팀 정보와 전술은 MongoDB에 저장되어 Fastify 재시작 후에도 남는다.
- 사용자·팀·전술명은 화면에서 데이터로 출력한다.
- 팀 변경/로그아웃 후 이전 요청 응답이 새 화면을 덮어쓰지 않는다.
- 저장 요청은 요청 시작 당시 팀에만 적용된다.
- 임시 저장은 사용자와 팀별로 분리한다.
- 기존 로컬 데이터는 사용자가 대상 팀을 고른 뒤 가져오고, 성공 전후 원본을 임의로 삭제하지 않는다.

## 검증 시나리오

- 비로그인 → 로그인 필요; 미승인 로그인 → 대기; 승인 후 → 팀 화면.
- 별도 관리자 페이지 직접 접속/새로고침/로그인 복귀와 일반 계정의 접근 제한 확인.
- 팀 검색 → 가입 신청 → 중복 신청 방지 → 소유자 승인 → 신청자의 내 팀에 표시.
- 열람자/편집자 권한 변경과 서버 저장 허용 여부, 소유자 이외 계정의 구성원 관리 제한 확인.
- 팀 A/B 생성 → 각각 다른 전술 저장 → 왕복 전환/새로고침 후 분리 확인.
- 승인된 별도 계정은 멤버가 아닌 팀의 목록/전술에 접근 불가.
- 세션 로그아웃/승인 중단 후 서버 작업 거부.
- 기존 로컬 전술 가져오기 후 서버에서 다시 열기; 원본 로컬 데이터 보존.
- 편집/Undo/재생/선수 시점/MP4 공유 기능 회귀 확인.
- PC 및 모바일 화면 폭에서 로그인·대기·팀 선택·편집 상단 컨트롤 확인.
- 실제 테스트 계정은 격리된 QA 데이터베이스만 사용. 사용자 운영 DB에 임의 계정을 남기지 않는다. 기존 DB/컬렉션을 삭제하지 않는다.

## 실행 구조

개발 중 Vite의 LAN 접속 주소를 유지하고 `/api` 요청을 Fastify에 프록시한다. 운영 모드에서는 Fastify가 빌드된 화면과 API를 제공한다. 구체적인 명령·환경변수·초기 운영자 절차는 구현 검토 후 실행 문서에 기록한다.

휴대폰 HTTP LAN 접속과 OS 파일 공유 지원은 다르다. Web Share가 필요한 실제 공유 검증에는 지원 브라우저와 신뢰할 수 있는 HTTPS 환경이 필요하다. 이번 서버 전환이 카카오톡 실기기 전송 검증을 대신하지 않는다.

## 검증 기록

- 2026-09-08: 사용자 지정 MongoDB에 드라이버 연결 및 `basket_utils` ping 성공.
- MongoDB 연결을 사용하는 Fastify 초기화, 프로젝트 인덱스 준비, `/api/health` 200 응답, `app.close()` 성공. 연결 풀 최대 크기 10 확인.
- 기존 102개와 Fastify 계약 테스트 4개를 포함해 106개 테스트 통과. 비로그인·승인 대기, 팀별 저장/조회, 다른 사용자 및 viewer의 저장 제한, 로그아웃·승인 중단 후 접근 제한, Secure 쿠키를 확인했다.
- `npm run dev`로 Fastify `0.0.0.0:3000`, Vite `0.0.0.0:5173` 실행 확인. localhost와 `192.168.5.10` 경유 API 정상 응답.
- 이 프로젝트의 예전 IPv6 전용 Vite 인스턴스가 localhost 요청을 가로채던 문제를 확인하고 해당 중복 프로세스만 종료.
- 브라우저 1440×1000 및 390×844에서 로그인·가입 화면 확인. 모바일 가로 넘침 없음. 휴대폰 실기기의 연결 확인과는 구별한다.
- 격리된 `basket_utils_qa_20260908review` DB에서 실제 화면으로 QA-A/QA-B 팀 생성·저장·왕복 전환·각 팀 임시 전술 복원 확인. 서버 재시작 후 세션 및 팀 데이터 유지 확인.
- 테스트 미승인 계정의 대기 화면, 운영자 승인 버튼, 승인 후 로그인, 새 계정에 기존 사용자의 팀이 나타나지 않음을 확인.
- 모바일 상단 버튼 줄바꿈 수정 후 현재 팀 이름과 공유·저장 아이콘이 한 줄로 표시됨을 확인.
- Fastify가 제공하는 빌드 화면에서 MP4 생성·재생 확인: 1280×720, 0.7252초, readyState 4, 끝까지 재생 완료. 팀 변경 후 이전 MP4가 제거되고 공유 버튼이 비활성화됨을 확인. 카카오톡 전송은 실행하지 않았다.
- 빌드 성공. 기존 500KB 초과 번들 경고는 남아 있다.
- 실행 및 최초 운영자 설정: [SERVER-SETUP.md](SERVER-SETUP.md).