Initial commit: courtlab tactical board with team management and MP4 export

SERVER-SETUP.md

@@ -0,0 +1,92 @@
+# Fastify · MongoDB 실행 안내
+
+## 저장소
+
+사용자가 지정한 MongoDB 서버는 `172.16.0.7:27017`, 프로젝트 DB는 `basket_utils`다. SQLite 선택은 이 설정으로 대체한다. 서버는 MongoClient 연결 풀을 재사용한다.
+
+프로젝트 루트 `.config.json`에서 설정을 관리한다. 예시는 `.config.json.sample`에 있으며 새 환경에서는 복사해 사용한다. 기존 설정 파일이 있으면 덮어쓰지 않는다.
+
+```powershell
+Copy-Item .config.json.sample .config.json
+```
+
+```json
+{
+  "mongodb": {
+    "uri": "mongodb://172.16.0.7:27017",
+    "db": "basket_utils"
+  },
+  "server": {
+    "host": "0.0.0.0",
+    "port": 3000,
+    "mode": "development",
+    "allowedOrigins": [
+      "http://localhost:5173",
+      "http://127.0.0.1:5173",
+      "http://192.168.5.10:5173"
+    ],
+    "secureCookie": false
+  },
+  "bootstrap": { "password": "" },
+  "qa": { "db": "basket_utils_qa", "password": "" }
+}
+```
+
+MongoDB 인증 정보가 필요하면 `mongodb.uri`에 설정한다. 실제 `.config.json`은 Git 추적에서 제외하고 예시 파일에는 비밀번호를 넣지 않는다. 설정 변경 후 서버를 재시작한다.
+
+## 개발 실행
+
+```powershell
+npm install
+npm run dev
+```
+
+Vite 화면은 PC에서 `http://localhost:5173`, 같은 네트워크의 휴대폰에서 `http://192.168.5.10:5173`으로 접근한다. PC의 IP가 바뀌면 주소도 바뀐다. Vite의 `/api` 요청은 `server.port`에 지정한 Fastify 포트로 전달된다.
+
+LAN 접속에는 Windows 방화벽과 공유기의 기기 간 통신 허용도 필요하다. MongoDB 주소와 휴대폰이 접속할 웹 주소는 별개다.
+
+## 최초 운영자
+
+공개 기본 운영자 계정은 만들지 않는다. 사용할 이메일로 회원가입한 뒤, 서버 PC에서 해당 계정을 명시적으로 승격할 수 있다.
+
+```powershell
+node .\server\bootstrap-admin.js --email=your-email@example.com --promote-existing
+```
+
+`your-email@example.com`을 실제 가입한 이메일로 바꾼다. 기존 비밀번호는 유지된다. 이후 로그인하여 다른 사용자의 가입 신청을 승인한다.
+
+PowerShell에서는 `npm.ps1`을 통해 실행할 때 옵션이 npm 자체 설정으로 해석되어 스크립트에 전달되지 않을 수 있으므로 위처럼 Node로 직접 실행한다. 명령 끝에 역슬래시(`\`)를 붙이지 않는다.
+
+새 운영자를 직접 만들 때는 `.config.json`의 `bootstrap.password`에 사용할 비밀번호를 일시적으로 설정하고 아래 명령을 실행한다. 실행 후 비밀번호 값은 다시 빈 문자열로 바꾼다.
+
+```powershell
+node .\server\bootstrap-admin.js --email=your-email@example.com
+```
+
+## 운영 실행
+
+`.config.json`의 `server.mode`를 `production`, `server.allowedOrigins`를 실제 HTTPS 서비스 주소 배열, `server.secureCookie`를 `true`로 설정한다.
+
+```powershell
+npm run build
+npm run server
+```
+
+Fastify가 `dist` 화면과 API를 제공한다. 실제 도메인을 허용 출처로 설정하고 HTTPS 프록시 뒤에서 실행한다. 운영 세션 쿠키는 Secure를 사용한다.
+
+휴대폰의 HTTP LAN 화면 접속만으로 OS 파일 공유 조건이 충족되지는 않는다. 카카오톡으로 MP4 파일을 직접 공유하는 실기기 검증에는 지원 브라우저와 신뢰할 수 있는 HTTPS가 필요하다.
+
+## 검증
+
+```powershell
+npm test
+npm run build
+```
+
+테스트 계정은 격리된 테스트 저장소에서 사용한다. 운영 `basket_utils` DB에 QA용 계정을 임의로 넣거나 기존 컬렉션을 삭제하지 않는다.
+
+2026-09-08 검증 결과: 106개 테스트 및 빌드 통과. 별도 QA DB에서 로그인·승인·다중 팀 저장/전환과 서버 재시작 후 데이터 유지, PC/모바일 화면, MP4 생성·재생을 확인했다. 기존 번들 크기 경고는 남아 있다.
+
+JSON 설정 전환 후에는 설정 로더 검증 5개와 정적 파일 보호 검증 1개를 추가해 총 112개 테스트와 빌드가 통과했다. 설정 파일이 없거나 JSON 구문·값 타입이 잘못되면 시작 시 오류를 안내하며, JSON 구문 오류에 설정 원문을 출력하지 않는다. 운영 모드에서는 Secure 쿠키가 강제되고 개발용 HTTP 출처는 허용하지 않는다.
+
+QA seed 명령은 `basket_utils_qa` 또는 `basket_utils_qa_` 뒤에 영문·숫자·하이픈이 붙은 DB 이름만 허용한다. 이번 검증 DB는 `basket_utils_qa_20260908review`이며 테스트 데이터는 운영 DB와 분리되어 있다. QA 서버는 검증 후 종료했다.