개발 문서

정식 공개 전 확인 목록

이 문서는 앞으로 확인할 항목입니다. 체크박스는 모두 미완료로 시작하며, 정적 코드 검토를 실제 서비스 검증으로 대신하지 않습니다. 이번 구현 작업에서는 서버·브라우저·실기기·결제·배포를 실행하지 않았습니다. 운영 담당자가 각 항목의 확인 환경, 시각, 결과, 관련 배포 ID를 남긴 뒤 완료 표시합니다.

운영 계정과 배포

• 코드 변경을 검토하고 운영할 GitHub 브랜치에 반영했습니다. 배포할 커밋을 특정할 수 있습니다.
• Vercel 프로젝트의 저장소 루트·Next.js 프리셋·Node.js 24·잠금 파일·빌드 명령을 설정 안내와 맞췄습니다.
• Production/Preview의 Atlas DB, DB 사용자, Private Blob 저장소와 비밀 값을 분리했습니다.
• Atlas에서 전용 DB 권한, 네트워크 접근 목록, SRV 연결, 트랜잭션 지원을 준비했습니다. npm run db:indexes를 정확한 대상 DB에 실행했습니다.
• Google OAuth 클라이언트의 대상 사용자·게시 상태·/api/auth/callback URI를 실제 운영 주소와 맞췄습니다.
• immercy.eturnalove.com의 CNAME과 HTTPS를 확인했습니다. APP_URL과 실제 접속 origin이 일치합니다.
• 빌드·표지를 Public이 아닌 Private Blob에 저장하며 BLOB_READ_WRITE_TOKEN은 서버에만 있습니다.
• ADMIN_EMAILS를 최초 로그인 전에 설정했습니다. 관리자는 의도한 사람만 등록되어 있습니다.
• CRON_SECRET과 유지보수 Cron을 구성했습니다. 시간별 실행을 지원하는 요금제, 함수 실행 시간, 지역, 비용 알림을 확인했습니다.
• Vercel/Atlas/Blob의 비용 알림을 받을 담당자와 서비스 이상 시 연락 경로를 정했습니다.
• 배포 로그와 정적 타입 검사 결과를 기록했습니다. 환경 변수 변경 후 올바른 환경이 다시 배포되었는지 확인했습니다.

실제 사용자 플로우

다음 항목은 외부 환경을 준비한 뒤 운영 담당자가 실제 브라우저와 스마트폰에서 확인합니다.

• 첫 방문 → Google 가입 → 프로젝트 생성 → API 키 보관 → 컨트롤러 구성 → 정적 게임 업로드 → Integration Preview가 이어집니다.
• API 키를 교체하면 이전 키 업로드는 실패하고 새 키는 해당 프로젝트에서만 동작합니다. 게임 출력에 키를 넣으면 CLI가 차단합니다.
• 업로드가 중간에 실패했을 때 최신 정상 빌드가 유지됩니다. 해시가 다른 파일, 경로 이탈, 제한 초과 파일은 commit되지 않습니다.
• Orbit Garden starter의 실제 업로드와 /g/<projectId> 접근을 확인했습니다.
• PC에서 Play 또는 미리보기 시작 → QR 표시 → 스마트폰에서 연결 → 연결 완료 후 게임 자동 시작 순서가 이어집니다. 두 번째 스마트폰의 claim은 차단됩니다.
• 버튼 press/release, 조이스틱, 방향키, 터치패드, 스와이프, 멀티터치, 센서가 해당 게임 이벤트와 연결됩니다.
• iPhone/Android의 센서 허용·거부·미지원 상태, 화면 전환, 백그라운드 전환, 연결 종료에서 입력이 남아 있지 않습니다.
• 서로 다른 Wi-Fi와 모바일 데이터에서 연결을 확인했습니다. TURN이 필요한 환경에서는 인증·전송량·만료 정책까지 확인했습니다.
• QR 생성만으로 Play가 늘지 않고 스마트폰 연결 완료 후 자동으로 시작한 게임이 한 번만 집계됩니다. 소유자 Preview도 포함됩니다.
• 같은 세션의 시작 요청 재전송, HTML 재요청, 정적 페이지 이동과 게임 내부 재시작은 기존 1 Play로 유지됩니다. 독립된 새로운 실행 세션의 시작에만 1 Play가 추가됩니다. 만료/종료한 세션은 계속 사용할 수 없습니다.
• Free/Indie/Enterprise 각각 프로젝트 수·주간 한도, 한도 초과·해제, 한국 시간 월요일 경계와 유료 만료를 확인했습니다.
• Enterprise 계약 한도를 명시하거나 제한 없음으로 선택했습니다. 이미 사용한 값보다 낮게 변경했을 때 이후 실행·생성만 제한됩니다.
• 프로젝트 및 관리자 목록에서 다음 페이지를 탐색할 수 있고 첫 페이지 뒤의 항목도 누락되지 않습니다.

공개 검토와 운영 대응

• 비공개/링크 공개/전체 공개의 접근 범위를 본인과 다른 사용자로 확인했습니다.
• 공개 검토 대기/승인/차단 상태, 자동 검토 실패 시 관리자 대기 처리가 일치합니다.
• 관리자가 검토 대기·차단된 프로젝트의 표지를 볼 수 있고 일반 사용자는 그 권한을 얻지 못합니다.
• 공개 해제·차단·계정 정지 후 기존 게임 세션의 자산 접근도 중단됩니다. 정지 계정은 결제 조회·해지를 계속 이용할 수 있습니다.
• 신고 → 관리자 검토 → 처리 → 알림, 문의 접수 → 관리자 확인 → 처리 완료 흐름을 확인했습니다.
• 문의 접수가 자동 이메일 발송이나 답변 완료를 뜻하지 않음을 운영자가 알고 있습니다. 응답 담당자와 외부 회신 방식, 목표 응답 시간을 정했습니다.
• 악성/권리 침해 신고, 계정 탈퇴, 데이터 열람·삭제 요청을 누가 확인하고 처리할지 정했습니다.
• 장애 로그에 OAuth 코드, DB URI, API 키, QR/peer/host 토큰, Blob 토큰, PayApp 원문을 남기지 않는지 확인했습니다.

PayApp 개통

• PayApp 가맹점·정산·정기결제 심사를 완료했고 PayApp 문서의 환경 변수와 명시적인 약정 만료일을 설정했습니다.
• /api/webhooks/payapp과 Blob 업로드 콜백 경로가 외부에서 정상 도달하며 로그인 리디렉션·배포 보호·방화벽 챌린지로 막히지 않습니다.
• PayApp이 허용하는 시험 절차로 최초 승인·다음 회차 승인·실패·해지·전체/부분 취소를 확인했습니다. 실금액이 청구되는지 먼저 확인했습니다.
• 판매자 인증·주문·금액·등록 번호 검증이 실제 통보의 필드/일시 형식과 맞습니다. 통보 재전송이 기간·환불 금액을 중복 반영하지 않습니다.
• 브라우저 복귀만으로 Indie가 되지 않으며, 결제 창을 닫은 pending 주문은 기존 요청을 이어갈 수 있습니다.
• 29~31일 가입, 신청 후 늦은 승인, 12월→1월, 윤년/평년 2월에서 첫 갱신 청구가 같은 달에 추가 발생하지 않는지 PayApp과 확인했습니다. 실제 청구일과 승인 다음 달 이용 종료일이 상품 안내에 일치합니다.
• 요청 결과가 불확실한 경우 requires_review를 판매자 화면과 대조하는 담당자·절차가 준비되어 있습니다. 확인 없이 재가입 차단을 풀지 않습니다.
• 새 결제 신청이 비활성화되어도 기존 계약의 해지는 가능한지 확인했습니다. 해지 실패를 성공으로 표시하지 않습니다.
• 과거 결제 환불이 최신 정상 결제 기간을 지우지 않으며, 부분 환불 누계와 늦게 온 승인 통보를 대조했습니다.
• Enterprise 전환이나 계정 정지가 기존 PayApp 계약을 자동 해지하지 않음을 운영자가 알고 처리 절차를 정했습니다.

공개 운영 정보와 보존 정책

• LEGAL_BUSINESS_NAME, LEGAL_REPRESENTATIVE, LEGAL_BUSINESS_NUMBER, LEGAL_ADDRESS에 해당 사업의 실제 공개 정보를 입력했습니다. 추가 판매자 표시 항목이 필요한지도 확인했습니다.
• LEGAL_SUPPORT_EMAIL과 LEGAL_PRIVACY_CONTACT는 실제 수신·응답 가능한 연락처이며 담당자가 정해져 있습니다.
• LEGAL_EFFECTIVE_DATE에 확정 시행일을 넣고 이용약관·개인정보·콘텐츠 정책에 미정 문구가 남지 않았는지 검토했습니다.
• 정기결제 가격/주기/약정 만료, 해지 시점, 전체/부분 환불 처리 기준이 화면·약관·운영 절차와 같습니다.
• LEGAL_RETENTION_NOTICE에 계정·프로젝트·Play·신고·문의·운영 기록·결제 기록의 실제 보존 기준과 삭제 절차를 확정했습니다.
• Google, Vercel/Blob, MongoDB Atlas, PayApp, OpenAI 및 TURN의 실제 사용 범위·지역·처리 정보와 계약 조건을 확인하고 개인정보 문서에 반영했습니다.
• 데이터 삭제 요청 시 본인 확인, 보존해야 하는 자료와 삭제 가능한 자료의 구분, 백업에서의 처리 절차를 정했습니다. 아직 TTL이 없는 원장을 자동 삭제한다고 안내하지 않습니다.
• Atlas 백업/복원과 Blob 원본 보관 방식을 준비했습니다. 실제 복원 시 복구 가능한 시점과 소요 시간을 확인했습니다.
• 교체 파일·미완료 업로드 정리가 정상 실행되고 최신 참조 파일은 삭제되지 않는지 확인했습니다.

개발자 도구 공개

• npm 계정과 immercy scope의 게시 권한을 확보했습니다. 이름을 사용할 수 없으면 SDK·CLI·MCP 의존성과 안내를 함께 바꿨습니다.
• 배포할 패키지 파일 목록, 라이선스와 저작권/배포권, 비밀 포함 여부를 검토했습니다.
• SDK → CLI → MCP 순서로 승인한 버전을 게시하고 깨끗한 별도 환경에서 설치·연결을 확인했습니다.
• 미게시 상태라면 사이트에서 npm 공개 배포 완료로 안내하지 않고 로컬 checkout 사용 절차를 제공합니다.
• MCP 조회/검증과 실제 원격 변경 도구의 범위를 확인했습니다. API 키를 모델 응답·로그에 출력하지 않습니다.

운영 담당자는 미완료 항목과 영향, 개통 범위를 기록합니다. Free 서비스 공개와 유료 결제 개통의 시점이 다르면 기능 설정·안내도 그 범위에 맞춥니다. 배포 성공만으로 실제 기기 연결이나 결제사 연동까지 완료된 것으로 표시하지 않습니다.