위치기반 공동구매 O2O Wizard of Oz MVP

예비창업 거래 가설을 검증하기 위한 웹/PWA형 테스트 앱입니다. PG 결제와 운영용 회원 인증 대신, 그룹 채팅과 수동 상태 관리로 실제 이용 흐름을 검증합니다.

실행

pnpm install
pnpm dev
pnpm test
pnpm build

중앙 API 없이 로컬 관리자 흐름까지 확인하려면 개발 환경에서만 아래처럼 PIN을 지정합니다. 이 값은 운영 관리자 PIN을 대신하지 않습니다.

VITE_O2O_LOCAL_ADMIN_PIN=2468 pnpm dev

단계별 검수 배포는 아래 릴리스 단계로 제어합니다. 값이 없거나 잘못되면 현재 완료 범위인 9일차 기능을 노출합니다. 6일차 화면을 다시 확인할 때만 값을 명시적으로 6으로 설정합니다.

VITE_RELEASE_PHASE=9
O2O_RELEASE_PHASE=9

• 6일차: 계산기·11개 카테고리·그룹/입금 상태·되돌리기·목표 인원
• 8일차: 채팅·관리자·미확인 배지
• 9일차: 그룹 공유·딥링크
• 중앙 API가 연결되지 않은 6일차 화면 검수용 Preview에서만 VITE_ENABLE_GROUP_LOCAL_FALLBACK=true를 사용할 수 있습니다. 이 경우 상태는 동일 브라우저에만 저장되므로 다중 기기 검수용으로 사용하지 않습니다.

개별 접속 주소

• 사용자 앱: http://localhost:5173/customer
• 사장님 앱: http://localhost:5173/owner
• 관리자 앱: http://localhost:5173/admin
• 검증 대시보드: http://localhost:5173/dashboard
• 앱 선택 화면: http://localhost:5173/

PostHog

.env에 아래 값을 넣으면 로컬 이벤트 로그와 함께 PostHog로 이벤트가 전송됩니다.

VITE_POSTHOG_KEY=phc_xxx
VITE_POSTHOG_HOST=https://app.posthog.com

키가 없으면 브라우저 localStorage에 이벤트와 주문 이력이 저장됩니다. PostHog에는 이름·연락처를 제외한 고객번호·지역·행동 속성만 전송하고, 이름·연락처는 Google Sheets 중앙 수집에만 사용합니다.

• 방문·세션 통계: PostHog Web analytics에서 새 배포 이후의 $pageview를 확인합니다.
• 설문 제출: PostHog Activity에서 survey_submitted 커스텀 이벤트로 확인합니다. PostHog의 별도 Surveys 메뉴에는 표시되지 않습니다.
• 화면 체류와 클릭 과정: screen_view, screen_dwell, 자동 클릭 이벤트 및 Session replay에서 확인합니다.
• 채팅 본문·닉네임·연락처·이름은 PostHog 속성과 자동수집/리플레이에서 마스킹합니다. 채팅 본문은 거래 테스트용 전용 시트에만 저장합니다.

포함 범위

• 사장님 상품 등록 플로우
• 사용자 공동구매 리스트, 상세, 참여, 그룹방 생성, 설문
• 판매가·목표 인원·상품 총수량·내 선택 수량 기반의 독립 예상 부담금 계산기(개당 금액 원 단위 내림, 나머지·선택액·미배정 수량 표시)
• 그룹 생성자의 호스트로 참여 / 호스트 지원 요청 선택과 호스트 지원자의 원자적 권한 승격
• 인원(targetPeople/currentPeople)과 상품(totalQuantity/orderedQuantity/selectedQuantity) 데이터를 분리해 다중 기기 수량 초과 참여 방지
• 그룹 상태 모집 중 → 모집 완료 → 상품 구매 완료 → 전달 완료 및 호스트·관리자의 한 단계 전진/되돌리기
• 참여자 상태 입금대기 → 입금확인요청 → 입금완료, 참여자의 요청 취소와 호스트·관리자의 완료 취소
• 모든 상태 변경의 이전값·변경값·실행자·시각 이력
• 그룹당 최대 20명, 목표 인원 수정(현재 인원 미만 금지, 상품 구매 완료 후 잠금)
• 그룹별 5초 폴링 채팅, 발신자·역할·전송 시각, 재접속 기록 유지, 최신 100건 표시
• 호스트·관리자의 채팅 잠금/해제와 관리자 계정의 참여 인원 제외
• 그룹별 미확인 메시지 배지와 마지막 읽음 상태 유지
• 그룹 딥링크, 링크 복사, 문자 및 모바일 공유 시트(카카오톡·설치 SNS 선택 가능)
• 그룹 생성·검색·상세·사장님 화면의 합의된 11개 카테고리 통일
• 이름·연락처 등 기본 정보와 전국 시·도 → 시·군·구 → 읍·면·동을 함께 설정하는 사용자 시작 화면
• 지역과 관계없이 모든 공개 사장님 상품·사용자 그룹을 노출
• 사장님은 고객 지역과 관계없이 본인 상품의 주문 상태를 확인하고, 지역은 픽업 안내·운영 통계 기준으로 사용
• 가상 주문 접수 및 사장님의 수동 결제 확인 상태 연동
• 사용자 픽업 확인과 주문별 상태 변경 시각 기록
• Wizard of Oz 거래 검증 대시보드와 주문 이력 CSV
• 테스트용 회원정보와 지역/동네 프로필 저장
• 좋아요/공유 UI
• 이벤트 수집, 지역 태깅, 종류별 발생/고유 사용자 집계, 체류시간, Funnel, 설문 연계
• CSV 내보내기와 QR 코드

전국 지역 목록은 행정표준코드관리시스템의 법정동 코드를 기준으로 생성합니다. node scripts/fetch-regions.mjs로 최신 목록을 다시 생성할 수 있습니다.

중앙 데이터 확인

1. /dashboard에서 전체 방문자·이벤트·Funnel·지역 현황을 30초 단위로 확인합니다.
2. Google Sheets의 전체 이벤트 탭에서 원본 행동 데이터를 확인합니다.
3. 설문 응답 탭에서 고객번호·이름·연락처·문항별 응답·제출 시간을 한 행으로 확인합니다.
4. CSV가 필요하면 대시보드 또는 Google Sheets에서 수동으로 내려받습니다.

브라우저 데이터나 캐시를 삭제하면 로컬 기록이 사라질 수 있으므로 CSV를 먼저 보관해야 합니다.

Google Sheets 중앙 수집

운영 환경에서는 track() 이벤트를 /api/collect로 전송합니다. 프로필·설문·상품/그룹/주문 상태와 중앙 대시보드 집계에 필요한 screen_view·open_listing·share_clicked는 Apps Script 웹앱을 통해 Google Sheets에 저장합니다. 체류·탭·필터·슬라이더 조작 같은 나머지 고빈도 UI 이벤트는 PostHog와 로컬 기록만 사용해 주문·그룹 저장용 Apps Script 잠금을 점유하지 않습니다. 중앙 저장이 일시적으로 바쁘거나 네트워크 오류가 나면 브라우저 재시도 큐에 보존됩니다.

Vercel에는 아래 환경변수가 필요합니다. Apps Script 소스 템플릿은 apps-script/Code.gs에 있으며, 변경 후 웹 앱을 새 버전으로 배포해야 합니다.

GOOGLE_SHEETS_COLLECTOR_URL=https://script.google.com/macros/s/.../exec
GOOGLE_SHEETS_COLLECTOR_TOKEN=...
O2O_ADMIN_PIN=...
O2O_CAPABILITY_SECRET=...
O2O_RELEASE_PHASE=9

관리자 PIN은 관리자 앱 → 상품·주문 관리자 운영 관리에서 로그인 후 변경할 수 있습니다. 새 PIN은 숫자 8~12자리이며 현재 PIN 확인이 필요합니다. 첫 변경 이후에는 GAS ScriptProperties의 O2O_ADMIN_CREDENTIAL_V1 해시가 인증 기준이 되고, O2O_ADMIN_PIN 환경변수를 바꿔도 중앙 PIN을 덮어쓰지 않습니다. 배포 시 GAS 버전 16 이상을 먼저 반영해야 합니다. 중앙 속성이 없을 때만 환경변수 PIN으로 초기 인증하므로, 운영 복구 시 해당 속성을 삭제하지 마세요. 기존 그룹 capability 세션은 PIN 변경으로 일괄 폐기되지 않습니다.

• O2O_CAPABILITY_SECRET은 호스트·참여자 권한 토큰 생성용이며 운영/미리보기 환경에 같은 값을 설정합니다.
• 별도 데이터 API를 사용하는 경우 기존 O2O_DATA_API_ORIGIN과 양쪽의 동일한 O2O_DATA_API_TOKEN이 필요합니다.
• 추가 테스트 도메인은 O2O_ALLOWED_ORIGINS에 쉼표로 구분해 등록할 수 있습니다.
• 기존 전체 이벤트, 설문 응답, 공개 상품, 주문 내역은 유지되고 그룹, 그룹 참여자, 그룹 채팅, 상태 이력 시트가 추가됩니다.
• 상품·주문·그룹 권한 토큰은 브라우저에서 생성·보관하고 중앙에는 SHA-256 해시만 저장합니다. 브라우저 저장소 삭제는 기존 수정 권한을 잃게 할 수 있습니다. 장애 조사 중에는 원래 브라우저·프로필·원본 기록을 보존하고, 공개 문서나 채팅에 관리키를 복사하지 않습니다.
• 기존 해시 없는 상품이나 중앙 원본이 없는 로컬 카드는 자동 소유권 이전·버전 초기화·삭제 후 재등록으로 복구하지 않습니다. 정확한 상품 ID, 원본 데이터, 관리키와 중앙 기록의 일치를 먼저 확인해야 합니다. 확인되지 않은 과거 주문·입금 상태를 임의로 새로 만들지 않습니다.

거래 테스트 제한

배포 전 pnpm verify:release로 단위·API·실제 GAS 코드 검수, 빌드, 모바일 Chromium·WebKit 회귀 검수를 함께 실행합니다. 저장 실패, 응답 유실, 오래된 브라우저 처리 기록, 지연된 조회 응답, 화면 이탈, 중앙에 없는 로컬 상품을 포함합니다. 이 검수는 가상 시트를 사용하므로 실제 고객 기기의 성공과 구분합니다. 고객 제보는 같은 상품·브라우저 기록과 중앙 저장 결과를 확인하기 전까지 전체 해결로 표시하지 않습니다. 운영 주문·입금은 검수용으로 변경하지 않습니다.

운영 확인 절차와 과거 기록의 복구 조건은 운영·인수 확인 안내, 계약 별지 A-01~A-12의 최종 상태와 인수 체크는 최종 검수·인수 확인서, 최신 대화와의 대조 결과는 9월 11일 피드백 대조표에 기록합니다. 로컬 검수, 운영 반영, 고객 확인, 과거 데이터 복구를 각각 구분합니다.

• 채팅은 WebSocket이 아닌 앱 접속 중 5초 폴링 방식입니다. 화면에는 최근 100건만 표시하지만 중앙 원본 행은 삭제하지 않습니다.
• 앱을 종료한 상태의 푸시 알림은 제공하지 않습니다. 재접속하면 중앙 마지막 읽음 순번을 기준으로 배지를 복원합니다.
• 카카오 SDK 직접 연동 대신 모바일 운영체제 공유 시트를 사용하므로, 설치된 카카오톡·SNS 앱을 사용자가 선택합니다.
• 본 구조는 최대 20명 규모의 Wizard of Oz 검증용입니다. 정식 운영 전에는 인증·DB·실시간 메시징 구조로 전환해야 합니다.
• 모집을 수동으로 완료했을 때 미배정 상품을 임의로 0으로 만들지 않고, 모집 종료 · 배정 X / 총 Y와 미배정 수량을 사실대로 표시합니다.
• 통제된 테스트 범위에는 capability 권한 검증이 적용되지만 정식 본인인증은 아닙니다. 공개 실서비스 전에는 요청 제한, 관리자 PIN 시도 제한, 계정 기반 권한 복구 절차가 필요합니다.

제외 범위

• 실제 결제
• 결제 영수증·정산 내역 등 금전 거래 증빙
• 카카오 SDK 등 특정 SNS 사업자 API 직접 연동
• 앱 종료 상태의 푸시 알림과 WebSocket 실시간 메시징
• 정식 회원가입·신고·차단·정산을 포함한 상용 관리자 시스템
• 심층 분석 컨설팅/발표자료 작성