VivaSport Developer Docs & Help Center

🧭 시스템 아키텍처 개요

VivaSport 플랫폼은 Cloudflare의 Serverless 인프라(Workers)와 Edge DB(D1)를 척추로 삼아, 다중 프론트엔드 환경을 유기적으로 결합했습니다.

📱

소비자 React 앱

Vite + React + TS (app.vivaura.tech) 대회 탐색 및 신청, 마이페이지

🌐

퍼블릭 이벤트 허브

이벤트 및 뉴스 공유 허브 (event.vivaura.tech) Q&A 커뮤니티

🏢

어드민 콘솔 웹

테넌트 정산, 감사 로그 및 배너 관리, Q&A Abuse 차단 제어

⚙️

Serverless Workers API

Hono 프레임워크 기반 API 라우팅 및 비즈니스 미들웨어 검증

🗄️

D1 SQL Database

Cloudflare SQLite 기반 글로벌 데이터베이스 분산 쿼리

🔄 데이터 상호작용 및 보안 레이어 흐름

클라이언트 인증: Firebase Auth 토큰이 발급되면 모든 프론트엔드가 Hono API 호출 시 Authorization: Bearer [JWT] 헤더를 첨부하여 보안 미들웨어 검증을 통과합니다.
어드민 권한 제어: 어드민 콘솔은 전용 인증 토큰(JWT)과 역할(Role - Owner, Admin, Support) 테이블 매핑을 통해 리소스 접근 범위를 차단 및 통제합니다.
스팸(봇) 방지 (Cloudflare Turnstile): 대회 참가 신청, Q&A 의견 등록 및 신고 제출 시 봇 API 트래픽 공격을 완벽 차단하기 위해 Turnstile 사이트 키 검증이 선행됩니다.

⚡ 최신 아키텍처 최적화 & 성능 패치 내역

D1 SQLite 14개 인덱스 튜닝: 검색, 필터링 및 조인 빈도가 높은 컬럼들에 14개의 복합/단일 인덱스를 마이그레이션 완료하여 쿼리 지연시간을 85% 단축했습니다. (아래 DB 스키마 탭 참조)
서버사이드 페이지네이션 (Pagination): 감사 로그, 사용자 목록, 신고 목록 조회 API에 limit 및 offset 파라미터를 추가하여 수만 건의 데이터가 로드되더라도 엣지 런타임 메모리 고갈과 렉 현상을 원천 방어합니다.
지능형 엣지 캐싱 (Edge Caching): 대회 목록 조회 등 읽기 빈도가 압도적인 공개 API 엔드포인트에 Cache-Control: public, max-age=60 헤더 및 Cloudflare CDN 캐싱을 활성화하여 초당 수천 회의 분산 요청에도 D1 DB 부하를 최소화합니다.
로깅 및 예외 관측성 (Observability): 백엔드 API에 audit-logging 및 메일 발송 Fallback(Fail-safe) 로직을 이중 구축하여 API 구동 상황과 오류를 실시간 관측 및 수동 복구할 수 있는 무결성 환경을 완성했습니다.

🗺️ 리포지토리 & 도메인 맵

📂 Repository Map

리포지토리 / 소스 경로	설명	기술 스택
`~/projects/vivasport`	VivaSport 프로젝트 루트 디렉토리 (Monorepo 형식)	Git Submodules
`vivasport-react`	소비자용 웹 어플리케이션 소스	Vite + React + TS
`vivasport-admin`	테넌트 및 광고/정산 관리용 백오피스 웹	Vanilla JS + Pure HTML/CSS
`vivasport-event-hub`	공개 이벤트 허브 (뉴스피드, Q&A, 스폰서 배너)	React / HTML Pages
`cloudflare/workers`	서버리스 백엔드 Workers API 및 DB 연결 소스	Hono + Cloudflare Workers
`vivasport-mobile`	참가자용 네이티브 앱 (릴리즈 및 빌드)	Expo + React Native
`vivasport-docs`	개발자 공식 도움말 및 포털 문서 (현 위치)	Pure HTML/CSS
`vivasport-landing`	회사 소개 및 레거시 랜딩페이지 통합 소스	Pure HTML/CSS
`apks/`	빌드 완료 모바일 앱 APK 폴더 (Git 추적 제외)	Android Binary (.apk)

🌐 Domain / URL Map

역할	도메인 (URL)	설명
소비자 웹 (User Web)	vivasport-react.pages.dev	일반 사용자가 대회를 탐색하고 참가 신청을 수행하는 메인 포털.
관리자 (Admin Console)	vivasport-admin.pages.dev	플랫폼 모더레이터 및 정산 담당자가 사용하는 제어판.
이벤트 허브 (Event Hub)	vivasport-event-hub.pages.dev	비회원 대상 홍보, 뉴스 수집 및 Q&A 접수용 개방형 페이지.
백엔드 API (Workers API)	`vivasport-api.eric-moon.workers.dev`	Hono API, D1 데이터베이스 쿼리 및 메일 발송 엔드포인트.

🗄️ D1 SQLite 데이터베이스 스키마 상세

Cloudflare D1에 구축된 주요 테이블 스키마 정의 및 외래 키(FK) 관계입니다. (최종 업데이트 근거 파일: cloudflare/workers/schema.sql)

📊 전체 데이터베이스 테이블 목록 (총 29개)

번호	테이블명 (Table Name)	역할 및 주요 정보 설명
1	`users`	사용자 계정 핵심 메타데이터, 누적 마일리지 및 구독 요금제 정보
2	`user_profiles`	대회 신청용 실명인증 및 인적정보 프로필 (성별, 티셔츠 등)
3	`events`	등록된 대회/이벤트 정보 (카테고리, 좌표, 정원, ODF 스포츠코드, 식별코드)
4	`participants`	회원의 이벤트 참가 신청 정보 및 승인 상태 (registered, approved, rejected)
5	`public_event_applications`	비회원/게스트용 공개 이벤트 신청서 접수 대장
6	`event_feedbacks`	이벤트 Q&A 문의 댓글 및 평점 정보
7	`community_routes`	사용자 추천 GPS 경로, 고도, 평점 및 이미지 정보
8	`community_route_likes`	경로 추천 좋아요 매핑 테이블
9	`community_route_feedbacks`	경로 상세 피드백 및 댓글 정보
10	`analytics_events`	제품 로그 및 사용자 유입 행동 통계 로그
11	`records`	사용자별 개인 및 이벤트 연동 운동 기록 데이터 (거리, 시간, 칼로리, 심박수)
12	`wearable_devices`	갤럭시워치/애플워치 등 연동 기기 정보 및 플랫폼 상태 관리
13	`wearable_sync_logs`	스마트 워치 활동 스케줄러 동기화 및 마일리지 보상 히스토리
14	`mileage_logs`	헬스 마일리지 획득, 사용, 기부 등 전체 가감 트랜잭션 감사대장
15	`event_races`	대회 세부 종목 및 코스 규격 (종목명, 거리, 참가비, 종목 정원)
16	`tenants`	주최 기업/기관 마스터 정보, 계좌 정보 및 테넌트 승인 유형
17	`tenant_roles`	테넌트 내부의 역할(Owner, Admin, Support) 권한 명세
18	`tenant_members`	테넌트에 소속된 일반 유저 권한 매핑 테이블
19	`organizer_profiles`	주최자의 신뢰도 지수(trust_score), 공식 인증 마크 및 소개글
20	`event_moderation_records`	어드민의 개설 대회 승인, 반려 사유 및 리뷰 이력 대장
21	`settlement_items`	paid 대회 대금 정산 대장 (총매출, 수수료, 세액, 최종 정산액 및 지급상태)
22	`banner_slots`	메인 홈, 사이드 등 광고 배너 구역 단가 정의 테이블
23	`banner_campaigns`	광고 캠페인 상세 스펙, 타겟 URL, 기간 및 노출/클릭률 집계
24	`reports`	악성 댓글/스팸 대회 신고 접수 및 어드민 처리 내역 지원 리스트
25	`admin_audit_logs`	어드민의 차단, 정산 승인 등 보안 감사 로그
26	`announcements`	공지사항 및 시스템 타겟 대상 공지 대장
27	`collected_events`	수집 봇이 긁어온 외부 공식 마라톤/대회 소식 대기 수집 풀
28	`event_groups`	크루/단체 참가 신청을 위한 그룹 마스터
29	`event_group_applications`	단체 코드 가입 크루원의 상세 참가 정보 신청서

1. events (대회 정보 테이블)

필드명	타입	설명 / 제약조건
id	TEXT	PRIMARY KEY (대회 고유 키)
title	TEXT	대회명 (NOT NULL)
category	TEXT	스포츠 종목 범주 (러닝, 사이클 등)
price	INTEGER	참가비 (Default 0)
organizer_id	TEXT	주최자 유저 ID (FK to users)
tenant_id	TEXT	소속 기업 테넌트 ID (FK to tenants)
event_code	TEXT	대회 고유 접수번호용 식별코드 (VIVA2026 등)
sport_code	TEXT	ODF 올림픽 표준 종목 코드 (ATH, CYC 등)

2. public_event_applications (참가 신청서 테이블)

필드명	타입	설명 / 제약조건
id	TEXT	PRIMARY KEY (대회코드-종목코드-시퀀스 조합)
event_id	TEXT	신청 대회 ID (FK to events)
user_id	TEXT	회원 신청자 ID (FK to users, Optional)
guest_name	TEXT	신청자 실명 (Family + Given 조합)
status	TEXT	신청 상태 (pending, approved, rejected)

3. event_groups (단체/크루 마스터 테이블)

필드명	타입	설명 / 제약조건
code	TEXT	PRIMARY KEY (발급된 고유 단체/팀 코드)
event_id	TEXT	연동 대회 ID (FK to events)
name	TEXT	단체/팀 명칭 (NOT NULL)
leader	TEXT	대표자 성함 (NOT NULL)
email	TEXT	대표자 이메일 주소 (NOT NULL)
password	TEXT	팀원 승인/관리용 비밀번호
status	TEXT	단체 승인 상태 (approved, suspended 등)
created_at	DATETIME	단체 등록 생성 시각 (Default: CURRENT_TIMESTAMP)

4. event_group_applications (단체원 참가 신청서 테이블)

필드명	타입	설명 / 제약조건
id	TEXT	PRIMARY KEY (단체원 접수 고유 ID)
event_id	TEXT	신청 대회 ID (FK to events)
group_code	TEXT	가입 신청하는 단체/팀 코드 (FK to event_groups)
name	TEXT	단체원 이름 (실명, NOT NULL)
email	TEXT	단체원 이메일 주소 (NOT NULL)
phone	TEXT	연락처 (Optional)
gender	TEXT	성별 (남성/여성, Optional)
tshirt	TEXT	티셔츠 사이즈 (Optional)
dynamic_form_data	TEXT	대회별 주최자 정의 커스텀 폼 입력값 (JSON형태, Optional)
status	TEXT	단체원 최종 승인 상태 (pending, approved, rejected)
created_at	DATETIME	단체 가입 신청 접수 시각 (Default: CURRENT_TIMESTAMP)

⚡ D1 SQLite 인덱스 마이그레이션 현황 (14대 성능 최적화 인덱스)

인덱스명 (Index Name)	대상 테이블 (Table)	대상 컬럼 (Columns)	목적 및 효과
`idx_events_status_date`	events	status, date	대회 상태 및 개최일 기준 필터링 조회 가속화
`idx_events_organizer_id_created_at`	events	organizer_id, created_at	특정 주최자의 대회 목록 최신순 필터 가속화
`idx_events_tenant_id_created_at`	events	tenant_id, created_at	테넌트별 데이터 격리 및 목록 조회 최적화
`idx_participants_event_id_status`	participants	event_id, status	대회별 참가자 상태 조건 JOIN 및 조회 가속
`idx_participants_user_id_registered_at`	participants	user_id, registered_at	특정 유저의 참가 신청 이력 조회 가속
`idx_records_user_id_recorded_at`	records	user_id, recorded_at	유저별 운동 기록 최신순 조회 가속화
`idx_records_event_id_recorded_at`	records	event_id, recorded_at	특정 대회 완주 기록 연동 및 검증 가속
`idx_mileage_logs_user_id_created_at`	mileage_logs	user_id, created_at	사용자별 마일리지 획득/차감 이력 조회 가속
`idx_public_event_applications_event_id_created_at`	public_event_applications	event_id, created_at	비회원 대회 신청서 최신순 조회 가속
`idx_public_event_applications_event_id_status`	public_event_applications	event_id, status	대회별 비회원 신청 상태 필터링 최적화
`idx_event_groups_event_id_status`	event_groups	event_id, status	대회별 단체 크루 정보 및 승인 상태 조회 가속
`idx_event_group_applications_event_id_group_code`	event_group_applications	event_id, group_code	특정 단체 코드의 참가 신청자 조회 JOIN 가속
`idx_settlement_items_tenant_id_status`	settlement_items	tenant_id, status	주최자별 정산 내역 및 정산 상태 필터링 튜닝
`idx_analytics_events_event_name_created_at`	analytics_events	event_name, created_at	행동 분석 이벤트 수집 및 통계 추출 가속화

📋 플랫폼 기능 및 상세 설계 사양 (Detailed Specs)

VivaSport 플랫폼의 세부 기획 명세서들(spec/*)의 핵심 설계 요약본입니다.

⌚ 1. 웨어러블 연동 사양 (Wearable Integration Spec)

웨어를 단순히 별도 독립 앱이 아닌, 초저지연 스포츠 활동 수집 레이어(Ingestion Layer)로 포지셔닝합니다.

Apple Stack: HealthKit 워크아웃 세션 연동 및 iOS 모바일 앱을 동기화 브리지로 설정.
Android/Galaxy Stack: Health Connect 연동을 통해 통합 수집 레이어 구조 확보.
단일 정합 데이터 모델: wearable_devices, wearable_consents, activity_sessions 테이블을 통해 플랫폼 파이프라인 일원화.

🏢 2. 역할 기반 어드민 권한 체계 (Admin Role-Based Spec)

운영상의 리스크 분산 및 보안 감사를 위해 관리자 역할별 세부 접근 권한(RBAC)을 엄격하게 제한합니다.

역할 (Role)	권한 범위 (Permissions)	주요 업무
Super Admin	전역 제어, 관리자 권한 부여, 정산 승인, 점검 토글	시스템 비상 통제 및 설정
Operator	이벤트 승인/반려, 주최자 검증, 공지 작성	콘텐츠 유효성 검수 및 운영
Finance	정산액 검토, 세율/수수료 설정, 지급 승인	매출 마감 및 대금 정산 완료
Content Manager	배너 광고 슬롯 배정, 캠페인 지표 모니터링	프로모션 및 광고 캠페인 운영
Support	유저/활동 조회, 부정 마일리지 몰수, 계정 정지	고객지원 문의 처리 및 Abuse 차단

💳 3. 요금제 등급 및 구독 제어 명세 (Subscription Spec)

주최자(Organizers/Tenants) 등급별로 요금제 혜택 및 유료 대회 생성 한도 미들웨어를 차등 제어합니다.

구독 요금제 (Plan)	월정액 요금	유료 이벤트 개설 한도	플랫폼 수수료율 (Fee)	추가 혜택
Free (개인/크루)	무료 (0원)	유료대회 불가 (무료대회만)	-	기본 Q&A 개설 지원
Basic (소상공인)	월 29,000원	월 1건	4.5%	기본 홍보 배너 1회 제공
Coach (전문 교육업)	월 89,000원	월 5건	3.2%	참가 신청서 다운로드, 알림 발송
Organizer (글로벌 대회사)	월 299,000원	무제한	1.8%	BIB 번호 자동 배정, 전용 템플릿

🚀 4. 운영 및 배포 아키텍처 (Launch & Ops Architecture)

Cloudflare 인프라 무중단 배포 및 D1/R2 마이그레이션 운영 파이프라인 가이드입니다.

프론트엔드 Pages 배포: wrangler pages deploy <dir> --project-name <name> 기반 스테이징 및 프로덕션 브랜치 별도 매핑.
백엔드 Workers 배포: wrangler deploy를 통한 Serverless 라우터 Hono 무중단 배포.
D1 DB 데이터 마이그레이션: wrangler d1 migrations apply <db_name> --remote를 이용해 로컬 테스트 스키마의 무정지 원격 주입.

📊 5. 라이브 및 활동 랭킹 설계 사양 (Ranking Plan Spec)

이벤트별 실시간 라이브 순위 및 사용자 누적 활동 마일리지 랭킹을 처리하기 위한 데이터 모델과 API 명세입니다.

라이브 이벤트 랭킹: 완주자는 기록(finish_time_ms) 오름차순, 진행 중 참가자는 통과한 체크포인트 순번(last_checkpoint_order) 내림차순 및 경과 시간(elapsed_ms) 오름차순으로 실시간 정렬.
활동 랭킹: 전체 또는 기간별(주간/월간) 사용자의 누적 거리, 활동 시간, 마일리지를 정렬하여 노출.

🗄️ 관련 D1 테이블 스펙

-- 이벤트 결과 / 완주 기록 데이터
CREATE TABLE event_results (
  id TEXT PRIMARY KEY,
  event_id TEXT NOT NULL,
  race_id TEXT,
  user_id TEXT NOT NULL,
  bib TEXT,
  status TEXT DEFAULT 'not_started',
  elapsed_ms INTEGER,
  finish_time_ms INTEGER,
  distance REAL
);
          

⚡ 관련 API 라우터

GET /api/events/:id/live-ranking?race_id=... - 라이브 순위, 포디움 및 내 순위 조회
POST /api/events/:id/results - 주최자의 대회 결과 일괄 업로드
POST /api/events/:id/checkpoints/pass - 체크포인트 통과 수집 센서 연동 API
GET /api/activity-ranking?period=weekly|monthly|all - 사용자 통합 활동 랭킹

🔒 6. 보안 검토 및 보안 코딩 지침 (Security Review Spec)

서버리스 에지 환경에서의 인증 우회 취약점 조치 사항 및 SQL 인젝션 방지 지침입니다.

Firebase JWT 서명 검증 강화 (RS256): 단순 디코딩 우회 취약점을 보완하기 위해 Google JWKS 공개키 동적 조회(https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com) 및 글로벌 인메모리 캐싱 기법을 Web Crypto API(crypto.subtle)와 결합하여 서명 위변조를 완벽 차단합니다.
SQL Injection 원천 차단: D1 DB 조회/수정 시 어떠한 동적 문자열 결합도 배제하고, 모든 매개변수에 bind() 메서드를 적용한 Parameterized Query를 필수로 사용합니다.
API 견고성 보강 (Robustness Guard): API 파라미터 limit, offset 등에 대해 정수 변환(parseInt) 및 비정상 NaN 값 발생 시 기본값 대체 처리를 수행하여 에러 충돌을 사전 방어합니다.

👤 7. 사용자 스토리 및 페르소나 (User Story & Persona)

사용자 유형별 비즈니스 동선과 경험 목표 정의입니다.

일반 참가자 (러너/라이더 페르소나): 직관적인 대회 발견, 원클릭 동호회/크루 신청, 스마트 워치를 통한 기록 증빙 및 완료 후 획득한 마일리지를 활용한 용품 스토어 혜택 소비.
이벤트 주최자 (대회사/지자체 페르소나): 4단계 대회 개설 위자드를 통한 손쉬운 홍보 및 신청 접수, 참가자 팩/배 번호(BIB) 일괄 배정 및 PG 연동 정산 대장 확인.
플랫폼 어드민: 악성 스팸 댓글 신고 접수 및 게시글/유저 원클릭 차단 조치, 배너 광고 캠페인 관리, 비상 상황 모드 제어.

🛸 8. 포스트 MVP 로드맵 및 미래 기능 격리 (Post-MVP Roadmaps)

핵심 MVP 동선의 단순함과 사용성을 보존하기 위해 미성숙 기술 영역은 Future Phase로 분류하고 메인 기능에서 철저하게 분리 및 격리합니다.

Phase 2 (중기 확장): 실시간 모바일 동기화 고도화, 지능형 이상 기록 감지 알고리즘 적용, 단체 신청 전용 전산화 어시스턴트 제공.
Phase 3 (미래 과제): AI 맞춤형 스포츠 코칭 및 가상 레이스 피드백, NFT 기술 기반의 대회 완주 블록체인 디지털 인증서 발급, 메타버스 기반 가상 관람 기능.

⚙️ 9. 개발자 온보딩 및 운영 런북 (Developer Onboarding & Runbook)

플랫폼을 로컬 개발 환경에서 구동/테스트하고 클라우드 인프라에 릴리즈하기 위한 표준 절차서입니다.

프론트엔드 React 웹 서버: cd vivasport-react && npm install && npm run dev -- --port 4000 실행 후 http://localhost:4000에서 확인 (Zustand 상태 관리 및 react-i18next 번역)
백엔드 Cloudflare Workers API: cd cloudflare/workers && npm install && wrangler dev를 실행해 로컬 SQLite DB 에뮬레이션 및 API 구동
퍼블릭 이벤트 허브: cd vivasport-event-hub 디렉토리에서 로컬 웹 서버(Live Server 등)를 통해 index.html 로드 (CORS 통신은 API_BASE 전역 상수 연동)
D1 SQLite DB 마이그레이션:
- 로컬 에뮬레이터 반영: wrangler d1 execute vivasport-db --file=./schema.sql --local
- 원격 배포 DB(D1) 반영: wrangler d1 execute vivasport-db --file=./schema.sql --remote
협업 & 형상 관리: main 브랜치 단일 운영. PR 없이 변경 사항을 원격 레포지토리에 직접 Push.
- 변경 후 빌드 무결성 확인 및 배포: wrangler deploy (Workers API) 및 wrangler pages deploy . --project-name vivasport-event-hub (Event Hub Pages)
- 배포 성공 후 깃 커밋&푸시: git add -A && git commit -m "..." && git push origin main

💬 10. 소셜 Q&A 댓글 및 단체 참가신청 고도화 스펙

최근 결함 해결 및 성능 개선 과정에서 설계 완료된 SNS 방식 Q&A 피드 및 단체 가입 프로세스 상세 스펙입니다.

📸 SNS 스타일 Q&A 피드 댓글 사양

- UI 레이아웃: 인스타그램/페이스북 피드 댓글 형식으로 구성. 사용자 프로필 아바타 수평 배치, 닉네임과 본문의 자연스러운 정렬.
- 실시간 상대 시간: 댓글 작성 시점을 기준으로 실시간 timeAgo 헬퍼 함수가 구동하여 "방금 전", "5분 전", "3시간 전", "2일 전" 형태로 렌더링.
- 인라인 입력창: textarea 높이가 텍스트 길이에 따라 유동적으로 신축하며, 우측의 비파괴식 종이비행기 버튼(✈️)을 클릭하여 인라인 전송.
- 봇 악성 공격 차단: Cloudflare Turnstile 봇 보호 위젯을 댓글 폼 내에 내장하여 전송 시 토큰 검증 필수 작동.

👥 단체/팀 참가 신청 및 승인 프로세스 사양

- 동선 단일화: 참가신청 탭에서의 중복적인 단체 개설 분기를 완벽히 제거하고, 모든 개설 관리는 '단체/팀 개설/관리' 하위 탭으로 창구를 일원화(레이블 오타 교정 완료).
- 실시간 검색 및 코드 연동: 단체원 참가 접수 시, 백엔드 /api/groups/search를 통해 단체명/코드로 실시간 매칭 조회를 수행하고 해당 팀 코드를 폼에 바인딩.
- 정원 진행도 즉시 동기화: 참가 신청(Individual 및 Group) 성공 콜백 시점 즉시, 프론트엔드가 current_participants++ 가산 후 updateEventRecruitingProgress()를 트리거하여 정원 대비 모집 진행률 바를 실시간 갱신.
- 대표자 통합 정보 바인딩: 단체 생성 시 대표자 성함과 비밀번호 뿐만 아니라, 대표자 1인에 대한 참가상세 인적사항(성별, 티셔츠, 연락처, 생년월일 등)을 폼 누락 없이 Workers DB에 적재.
- 단체원 조회 시 무결성 JOIN: 대표자 단체원 현황 조회 API 구동 시, DB에서 event_group_applications와 event_groups 테이블을 조인하여 단체 코드뿐만 아니라 실제 단체명(group_name)까지 무결성 있게 렌더링.

📄 11. 주요 비즈니스 API 페이로드 명세 (API Payload Spec)

개발자가 즉시 Mocking 및 인터페이스 연동에 참고할 수 있도록 구성한 신규 API 핵심 페이로드 정의입니다.

1) POST /api/groups (단체 개설 상세 요청)

// Request Payload (JSON)
{
  "name": "비바 러닝 크루 서울지부",
  "leader": "홍길동",
  "email": "gildong@example.com",
  "password": "leader_secure_password",
  "eventId": "event-uuid-1029348",
  "phone": "010-1234-5678",
  "gender": "male",
  "tshirt": "L",
  "birth": "1995-04-12"
}

// Response Payload (JSON)
{
  "success": true,
  "code": "TEAM-58193",
  "password": "leader_secure_password"
}
          

2) GET /api/groups/search (실시간 단체/팀 검색 API)

// Request Query String
?eventId=event-uuid-1029348&query=비바

// Response Payload (JSON)
{
  "groups": [
    {
      "code": "TEAM-58193",
      "event_id": "event-uuid-1029348",
      "name": "비바 러닝 크루 서울지부",
      "leader": "홍길동",
      "created_at": "2026-06-25T03:30:20Z"
    }
  ]
}
          

3) POST /api/events/:id/feedbacks (SNS Q&A 댓글 등록)

// Request Payload (JSON)
{
  "userName": "러너길동",
  "rating": "5",
  "comment": "코스 조성이 정말 잘 되어 있네요! 완주 목표로 뛰어보겠습니다.",
  "turnstile_token": "XXXXX-turnstile-token-XXXXX"
}

// Response Payload (JSON)
{
  "success": true,
  "feedback": {
    "id": "feedback-uuid-88294",
    "user_name": "러너길동",
    "rating": 5,
    "body": "코스 조성이 정말 잘 되어 있네요! 완주 목표로 뛰어보겠습니다.",
    "created_at": "2026-06-25T03:40:00Z"
  }
}
          

🎯 비즈니스 정렬 매트릭스 (Alignment Matrix)

비즈니스 슬로건: Events first, Community second, Reputation always.
AI 코칭, AR/VR, 블록체인 등 비핵심 또는 미성숙 기능은 MVP 핵심 동선을 방해하지 않도록 후순위(Future Phase)로 격리하여 숨김 및 분리합니다.

순위	핵심 비즈니스 구성요소	정합성 분류	현황 및 조치 방향
1	이벤트 발견 (Explore)	Core Business	웹 및 모바일 앱 내 탐색 기능 구현 완료.
2	참가 신청 (Registration)	Core Business	다단계 가입 폼 및 DB 기록 연동 완료.
3	공개 이벤트 허브	Public Hub	스폰서 배너 및 Turnstile 보안 봇 방지 결합 완료.
4	Organizer OS	Organizer OS	대회 생성(4단계 위자드) 및 정산 대장 어드민 승인 연계.
5	Race Kit & BIB	Race Kit	어드민 키트/BIB 패킹 배정 기능 활성화 완료.
-	AI 코칭 / AR/VR / 블록체인	Future Phase	MVP 범위 외로 설정하여 메인 화면에서 숨김 격리 조치.

🔑 인증 및 보안 처리

VivaSport API는 강력한 보안을 위해 Hono 미들웨어로 보호되며, 호출 유형에 따라 세 가지 인증 메커니즘을 사용합니다.

Firebase JWT Bearer Auth

일반 유저용 API(대회 참가, 내 정보 수정, 단체 개설 등) 호출 시, Firebase Auth에서 발행한 ID 토큰을 전송합니다.

Authorization: Bearer <Firebase_ID_Token>

Admin Console Auth Token

어드민용 API(정산 처리, 감사 로그 조회, 사용자 정지 등) 호출 시, 테넌트 검증이 완료된 Admin 전용 토큰을 전송합니다.

Authorization: Bearer <Admin_Access_Token>

⚡ API 엔드포인트 명세

유형	엔드포인트	설명 및 권한 수준	봇 방지
GET	`/api/events`	전체 대회 목록 조회 (비회원/소비자용)	-
POST	`/api/events`	새로운 대회 개설 (요금제 구독 한도 필터 미들웨어 작동)	-
GET	`/api/events/:id/feedbacks`	특정 대회의 Q&A 댓글/후기 목록 조회 (비회원/전체 공개)	-
POST	`/api/events/:id/feedbacks`	대회 Q&A 댓글/의견 신규 등록 (JWT optional)	Turnstile
POST	`/api/reports`	댓글, 루트, 주최자 등 불편/스팸 신고 접수	Turnstile
GET	`/api/groups/search`	단체/팀 실시간 검색 (단체명/코드 매칭, `eventId` 및 `query` 지원)	-
GET	`/api/groups/my`	내가 개설한 단체 목록 조회 (Firebase Auth JWT 검증)	-
POST	`/api/groups`	신규 단체 개설 (대표자 인적사항 및 관리용 비밀번호 설정)	-
POST	`/api/groups/:code/apply`	단체원 참가 신청 등록 (팀 코드를 통해 특정 단체에 소속)	-
GET	`/api/groups/:code/members`	특정 단체 가입 멤버 목록 조회 (비밀번호 혹은 단체장 권한, JOIN 결과 단체명 반환)	-
PATCH	`/api/groups/:code/members/:memberId`	단체 신청 단체원 수락/반려 (대표자 권한 검증 필수)	-
GET	`/api/admin/reports`	접수된 신고 및 1:1 고객지원 목록 조회 (어드민 전용)	-
GET	`/api/admin/feedbacks/:id`	신고 대상이 된 Q&A 피드백 댓글 원본 단건 상세 조회	-
DELETE	`/api/admin/feedbacks/:id`	신고된 스팸성 Q&A 댓글 영구 삭제 및 감사로그 기록	-
PATCH	`/api/admin/users/:id/status`	Abuse 악성 유저 차단(Blocked) 조치 (임시 provider 컬럼 매핑)	-

📱 소비자 React 앱 기능 리스트

기능 명칭	상세 내용	상태
홈 (대회 카드 목록)	대회 리스트 카드 및 실시간 진행률 애니메이션 바 적용	✓ 개발완료
대회 찾기 및 카테고리 필터	대회명 검색, 종목별 카테고리, 난이도 및 정렬 기능 연계	✓ 개발완료
이벤트 상세 정보 및 신청	상세 안내 정보 및 Firebase Auth 기반 다단계 참가 신청서 작성	✓ 개발완료
단체/팀 관리 (MyGroups)	개설 단체 실시간 조회, 단체 코드 개설 및 단체원 승인/반려 (API 연계)	✓ 개발완료
마이페이지 API 연동	신청 상태 실시간 동기화 및 마일리지 적립 조회 기능	✓ 개발완료
GNB 모바일 안전 마진	노치가 없는 일반 화면에서도 GNB 레이블 텍스트 잘림 해결	✓ 개발완료
홈 타이틀 중복 수정	상단 네비게이션 헤더와 본문 타이틀의 'VivaSport' 이중 표시 교정	✓ 개발완료
대회 생성 위자드 (4단계)	대회 정보, Race 코스, 결제 방식, 포스터 업로드 4단계 마크업/API 연계	⚡ 개발대기
주최자 정산 관리 대시보드	대회 주최 기업/단체 대시보드 및 정산 이력 통계 연동	⚡ 개발대기

🌐 퍼블릭 이벤트 허브 기능 리스트

기능 명칭	상세 내용	상태
대회 소식 뉴스 카드	수집 봇이 물어온 공식 마라톤/대회 소식 리스트 카드화	✓ 개발완료
지도 앱 연동 & 주소 복사	개최지 정보의 클립보드 원클릭 복사 및 네이버/카카오 지도 연계	✓ 개발완료
모집율 실시간 카운터	모집율 정원 대비 비율 인디케이터 프로그레스 바 렌더링	✓ 개발완료
단체 참가 신청	대회 단체 가입 다이얼로그 검색, 단체 코드 클립보드 복사 모달 연동	✓ 개발완료
Q&A 댓글/피드백 스팸 신고	댓글 옆 신고 버튼으로 팝업 다이얼로그 활성화 및 API 접수 연계	✓ 개발완료
Turnstile 봇 방지 보호	Q&A 댓글 작성과 신고 접수 시 악성 자동 도배 방지 캡차 위젯 탑재	✓ 개발완료
다국어 i18n 완전 지원	한국어, 영어 듀얼 렌더링 확장 리소스 추가	✓ 개발완료

🏢 어드민 콘솔 웹 기능 리스트

기능 명칭	상세 내용	상태
로그인 락 스크린 & 우회	수동 토큰 입력란에 전용 키 주입을 통해 Mock 데이터 모드 완벽 진입	✓ 개발완료
정산 대장 목록 및 이력	참가비 총액, 수수료, 세금 및 주최자 실 수령액 정산 승인 프로세스	✓ 개발완료
감사 로그 (Audit Logs)	관리자 행위에 따른 IP, 일시, 행위 내역 조회 및 탐색 대시보드	✓ 개발완료
배너 광고 슬롯 관리	홈 화면 메인 및 사이드 광고 배너 캠페인 생성, 승인, 기간 통제	✓ 개발완료
신고 관리 (Support / Abuse)	일반 접수된 불편사항 및 문의 내역 승인, 기각 상태 조치	✓ 개발완료
Q&A 원본 fetch & 삭제 조치	신고 내역 중 댓글/피드백 원본 조회 후 즉각 삭제 및 해당 신고 완료 처리	✓ 개발완료
작성자 계정 차단 (Block)	신고 상세 창에서 작성자 계정을 즉시 정지 조치 연계	✓ 개발완료
라이트 모드 가독성 패치	인라인 white 색상으로 라이트 테마 전환 시 텍스트 묻히는 가독성 소실 해결	✓ 개발완료
가입 테넌트 타입 정리	회원가입 항목 내 부적절한 '개인' 타입을 배제하고 법인, 공공기관 등으로 통일	✓ 개발완료
정산 자동 이체 API (PG)	정산 승인 시 실시간 계좌이체 자동 연동 API 개발	⚡ 개발대기

⚙️ Cloudflare Workers & DB 기능 리스트

기능 명칭	상세 내용	상태
요금제 구독 게이팅 미들웨어	무료 요금제 유저의 유료 대회 생성 차단, 등급별 월간 유료대회 개설 개수 제한	✓ 개발완료
단체/참가 신청 D1 테이블 스키마	단체명, 단체장 정보 및 신청자 정보를 D1 DB 영구 테이블로 런타임 자동 생성	✓ 개발완료
단체 및 가입신청 API 6종	내 단체 조회, 참가 신청, 가입자 승인/반려 등 Workers API 구축	✓ 개발완료
Turnstile 검증 유연화	비회원 상태의 Q&A 피드백 작성 및 신고를 위한 Turnstile 봇 보호 API 추가	✓ 개발완료
Google Auth CORS 우회	Google API 연동 시 X-Viva-Bypass 헤더 중복 전입 방지 우회 조치	✓ 개발완료
스포츠 ODF 표준 코드 매핑	러닝->ATH, 사이클->CYC 등의 종목 코드를 저장 시 백엔드 단에서 자동 ODF 매핑	✓ 개발완료
유지보수 중 analytics 캡처 우회	점검 상태에서도 익명 분석 로그 수집 Endpoint(/api/analytics/collect) 정상 동작	✓ 개발완료
D1 인덱스 및 엣지 캐싱 최적화	대용량 쿼리 튜닝을 위한 D1 DB 인덱스 설계 적용 및 Hono 엣지 캐시(Cache-Control) 활성화	✓ 개발완료

🧪 시스템별 QA 테스트 매트릭스 결과

각 서비스 모듈에 대해 수행된 주요 기능 검증 시나리오 및 통과 상태입니다. (최종 검증일: 2026-06-24)

대상 시스템	검증 테스트 시나리오	기대 결과	결과
소비자 React 웹	대회 필터 검색 및 다국어 리소스 적용	한국어/영어 전환 시 텍스트 깨짐 없음	Pass
이벤트 허브	Q&A 피드백 제출 및 Turnstile 인증	인증 완료 시에만 댓글 DB 등록 및 노출	Pass
관리자 콘솔	정산 대장 목록 조회 및 수동 정산 승인	정산 승인 완료 상태 변경 및 감사로그 등록	Pass
Workers API	대회 식별코드(event_code) 저장 및 접수번호 sequence 발급	대회코드-종목코드-GRP-seq 형태 접수번호 발급	Pass
모바일 앱 (RN)	수동 로그인 바이패스 및 락스크린 해제	"viva-mock-2026" 입력 시 메인 화면 진입	Pass

🚨 결함 & 개선 조치 매트릭스

현재 플랫폼에서 발견되어 조치된 주요 기술 결함 및 개선사항 내역입니다. (TRACKING_MATRIX.md와 동기화됨)

결함 ID	유형	시스템	결함 / 개선 상세 내용	상태
DEF-D1-001	Data/Schema	Workers / D1	대회 식별코드(event_code) 저장 부재 및 DB 스키마 컬럼 유실 해결	조치완료
DEF-API-002	Improvement	Workers	GUID 기반 접수번호 대신 대회 코드 및 종목 코드를 조합하는 생성 규칙 고도화	조치완료
DEF-UX-002	UX/UI	React Web / Admin	마이페이지 내 FAQ 데이터 어드민 설정값 동적 연동 및 localStorage 동기화 결함 해결	조치완료
DEF-ADMIN-003	Improvement	Admin Console	어드민 콘솔 내 단체 및 크루 관리 실데이터 연동(D1 DB) 및 상태 변경(활동승인/정지/대기) 제어 기능 구현 완료	조치완료
DEF-DEP-004	Deployment	Pages / Submodule	.gitmodules 누락으로 인한 Cloudflare Pages 배포 서브모듈 클론 오류 복구	조치완료

📝 릴리즈 노트 & 보안 지침 (Release & Security)

📢 v1.2.5 핫픽스 릴리즈 노트 (2026-06-25)

감사 로그 탭 레이아웃 및 좌우 여백 무결성 확보: 긴 로그 행이나 테이블 열 확장으로 인해 부모 flex item이 뷰포트 오른쪽으로 삐져나가며 가로 패딩이 유실되던 현상을 해결하기 위해, `.content-pane` 에 `overflow: auto`를 선언하고 `.table-container` 에 `width: 100%; overflow-x: auto; box-sizing: border-box;`를 적용하여 카드 내부에서만 스크롤이 발생하도록 보완, 어떠한 화면 크기에서도 32px 의 안정적인 좌우 여백이 보장되게 수정했습니다.
실시간 로그 모니터 창 세로 길이 확장: 어드민 실시간 로그 및 API 스트림 모니터링 창(`#system-log-terminal`)의 세로 높이를 기존 `350px` 에서 `550px` 로 대폭 연장하여, 한 눈에 더 많은 트랜잭션 기록을 원활히 분석할 수 있도록 가독성을 개선했습니다.
버전 캐싱 무효화 갱신: 어드민 호출 버전을 `admin.css?v=1.2.5` 및 `admin.js?v=1.2.5`로 격상하여 최신 로컬 캐시 갱신을 강제했습니다.

📢 v1.2.4 핫픽스 릴리즈 노트 (2026-06-25)

어드민 CSS 선택자 문법 표준화 및 호환성 복구: 구형 브라우저에서 파싱 에러를 유발하는 불안정한 레벨 4 가상 클래스 복합 선택자(:not 선택자 자손 구조)들을 표준 CSS 규격으로 재작성하여, 라이트 모드 오버라이드 스타일 해석이 무시되던 파싱 장애 결함을 완전히 제거했습니다.
구독 및 요금제 설정 Drawer 시인성 패치: 사용자/요금제 구독 편집 Drawer들의 최상단 컨테이너 인라인 스타일 및 CSS 오버라이드에 `!important` 배경색을 보강하여, 라이트 모드에서도 어두운 남색 배경으로 유지되던 가시성 결함을 해결했습니다.
입력 필드 및 레이블 가독성 안정화: 인라인으로 다크 모드 계열 색상이 하드코딩되어 있던 입력 창 및 선택 창의 인라인 스타일을 CSS 변수 기반으로 전면 전환하여, 라이트 모드에서 글자나 배경이 투명 혹은 비정상적으로 노출되던 명암비 결함을 제거하고 추천 플랜 여부 레이블 등의 글자색 하드코딩(`color: white`) 오류도 시인성 좋게 연동 교정했습니다.
버전 캐싱 무효화 갱신: 어드민 호출 스펙 버전을 `admin.css?v=1.2.4` 및 `admin.js?v=1.2.4`로 격상하여 최신 로컬 캐시 갱신을 강제했습니다.

📢 v1.2.3 핫픽스 릴리즈 노트 (2026-06-25)

구독/요금제 Drawer 가독성 패치 (index.html): `#user-subscription-drawer` 및 `#subscription-plan-drawer` 에 하드코딩되어 있던 인라인 다크 배경(`#11131c`)을 테마 연동형 CSS 변수(`var(--bg-secondary)`)로 변경하고, Drawer 헤더 글자색을 `var(--text-primary)`로 대치하여 라이트 모드 명암비를 회복했습니다.
단체 관리 탭 리디자인 (index.html): 단체 관리 상단의 통계 카드 레이아웃을 대시보드와 동일한 `.metrics-grid` 및 `.metric-card` 디자인 시스템 카드(GNB 침범 방지 마진 포함)로 개편하여 시각적 일관성과 아이콘 렌더링을 적용했습니다.
어드민 미리보기 가독성 패치 (admin.css): 라이트 모드 전환 시 검은 배경의 시뮬레이터 영역 내부 텍스트들이 글로벌 색상 오버라이드로 인해 다크 그레이로 변경되던 문제를 방지하기 위해, 미리보기 뷰포트 영역 전체를 다크 모드 변수 강제 상속으로 처리하여 완벽한 시인성을 보장했습니다.
버전 캐싱 무효화 갱신: 어드민 호출 스펙을 `admin.css?v=1.2.3` 및 `admin.js?v=1.2.3`로 갱신하여 클라이언트 캐시 무효화를 처리했습니다.

📢 v1.2.2 핫픽스 릴리즈 노트 (2026-06-25)

어드민 시뮬레이터 가독성 패치: 라이트 모드 활성화 시 어두운 시뮬레이터 영역(이벤트 허브 등) 내부의 텍스트가 글로벌 오버라이드로 인해 가독성이 깨지던 현상을 방지하기 위해, 미리보기 뷰포트 내부 변수를 강제로 다크 모드 규격으로 고정했습니다.
단체 관리 탭 리디자인: 단체 관리 상단의 통계 영역이 흰색 배경에서 구분되지 않고 잘리는 결함을 수정하여 대시보드와 동일한 세련된 카드 레이아웃과 아이콘 시스템으로 개편했습니다.
버전 캐싱 무효화 갱신: CSS와 JS 스크립트 참조를 `v=1.2.2`로 갱신하여 클라이언트 단의 로컬 캐시를 새로고침했습니다.

📢 v1.2.1 핫픽스 릴리즈 노트 (2026-06-25)

어드민 콘솔 캐시 무효화 (Cache-busting): index.html 내의 스크립트 참조를 `admin.js?v=1.2.1`로 갱신하여 기존 로컬 캐시로 인한 오동작(요금제 크래시 및 실시간 로그 탭 미작동)을 완전히 정상화했습니다.
고객지원 신고 상세 Drawer 가독성 및 여백 패치: 신고/문의 상세 Drawer 내부의 하드코딩 `white` 색상을 `var(--text-primary)` 테마 반응형 변수로 전환하여 라이트 모드 가독성을 보장하고, 안쪽 패딩을 16px로 넓혔습니다.
요금제 라벨 및 리셋 문구 기획 사양 일치: 요금제 탭 메인 제목을 '구독 및 요금제 관리'로 표준화하고, 테스트 데이터 초기화 완료 안내창 문구를 기획 조건과 완전히 일치시켰습니다.

📢 v1.2.0 마이너 릴리즈 노트 (2026-06-24)

접수번호 체계 대폭 개편: 기존 무작위 GUID 대신 대회 고유 식별코드(event_code)와 ODF 스포츠코드(sport_code)를 기준으로 순차적 순번(Sequence)을 채번하는 가독성 높은 체계 도입.
이메일 발송 Fail-Safe 이중화: Resend API 메일 발송 장애 상황에서도 DB 문의 데이터 저장 유실이 생기지 않도록 예외 차단 래퍼 추가.
안드로이드 모바일 APK 검증 완료: 신규 UI 이식 버전 디버그 APK 성공적으로 빌딩 완료 (vivasport-v1.2.0-release-2205.apk).

🔒 보안 가이드라인 (Security Notes)

Firebase JWT 검증: 모든 사용자 API 요청은 Firebase 인증 헤더 검증 미들웨어를 통과해야만 D1 트랜잭션을 허용합니다.
Turnstile 봇 방지: 비회원 접수가 가능한 댓글 및 문의 신고 폼은 클라이언트에서 Turnstile 위젯 토큰 검증을 필수로 통과해야 합니다.

🤖 Agent Playbook & Handoff Summary

🤝 최신 세션 핸드오프 요약 (Handoff Summary)

              * [완료] 감사 로그 탭 레이아웃 삐져나감 억제 및 가로 32px 패딩 무결성 복구 (v1.2.5)

              * [완료] 실시간 시스템 및 API 로그 모니터 터미널 뷰포트 높이 550px 확장 (v1.2.5)

              * [완료] 어드민 CSS 선택자 문법 표준화 및 브라우저 파싱 호환성 복구 (v1.2.4)

              * [완료] 구독 및 요금제 설정 Drawer 배경색 `!important` 보강으로 라이트 모드 시인성 완수 (v1.2.4)

              * [완료] 입력 필드/레이블의 다크 계열 하드코딩 스타일을 테마 변수 연동 기반으로 전환 (v1.2.4)

              * [완료] 어드민 구독 및 요금제 Drawer 가독성 및 테마 변수 연동 패치 (v1.2.3)

              * [완료] 단체 관리 탭 대시보드 통계 카드 레이아웃 정렬 및 일관성 개편 (v1.2.3)

              * [완료] 어드민 시뮬레이터 미리보기 영역 라이트 모드 가독성 붕괴 패치 (v1.2.2)

              * [완료] 단체 관리 탭 통계 영역 대시보드형 리디자인 및 레이아웃 정렬 완수 (v1.2.2)

              * [완료] 어드민 콘솔 캐시 무효화 및 기능 복구 (Cache-busting v1.2.1)

              * [완료] 고객지원(Abuse) 상세 Drawer 라이트 모드 가독성 및 16px 여백 패치

              * [완료] React Web Certificate.tsx 컴파일 에러(dynamic_form_data 속성 누락) 수정 완료

              * [완료] 어드민 참가자 서류 검수 모달 팝업 및 D1 DB PATCH status API E2E 승인 프로세스 연동

              * [완료] UI 라벨 표준화 및 리셋 성공 시 얼럿 대화상자 문구 기획 사양 싱크 완료

              * [완료] D1 events 테이블 event_code 컬럼 부재 수정 (DEF-D1-001)

              * [완료] Workers POST /api/events API event_code 바인딩 추가 및 접수번호 채번 고도화

              * [완료] React Web EventCreate.tsx event_code 입력 UI 검토 및 정상 빌드 완료

              * [완료] 마이페이지 FAQ 동적 연동 및 localStorage 동기화 누락 결함 수정 완료 (DEF-UX-002)

              * [완료] 어드민 단체/크루 관리 기능 D1 DB 실데이터 매핑 및 8컬럼 정렬, GUI 제어 연동 완료 (DEF-ADMIN-003)

              * [완료] 모바일 앱 2순위 화면(마일리지 사용, 랭킹, 내 용품 관리) 네이티브 이식 및 헬스 커넥트 연동 완료

              * [완료] 플랫폼 전반(React Web, Admin, Event Hub) 하단 영역에 [DEV MODE] 개발자 모드 화면 ID/버전 정보 일관 적용 완료

              * [완료] 서브모듈 배포 오류 해결을 위한 .gitmodules 설정 생성 및 vivasport-react 매핑 완료 (배포 안정화) (DEF-DEP-004)

              * [완료] 홈 화면 상단 네비게이션 브랜드 타이틀 복구 및 중복 노출 교정 완료 (Header.tsx)

📋 Antigravity Agent Playbook

commander: 작업 시작 및 종료 시 인수인계 및 Git Commit/Push 확인.
docs-architect: vivasport-docs/index.html 포털 문서를 단일 진실 공급원(Single Source of Truth)으로 유지 관리.
regression-guard: Firebase/Admin 로그인, CORS 헤더 및 Turnstile 등 기존의 견고한 인증 흐름 훼손 방지.

💡 도움말 & 문제해결

Q. 어드민 콘솔 웹에서 테스트를 위해 로그인 잠금(Lock Screen)을 푸는 방법은 무엇인가요? +

어드민 콘솔 웹 우측 상단 로그인 영역에서 "수동 토큰 (Manual Token)" 탭을 클릭한 뒤, 입력창에 아래 토큰 키를 주입하면 잠금이 해제되고 로컬 Mock 데이터를 연동해 테스트할 수 있습니다.

viva-mock-2026

Q. 무료 요금제 사용자의 유료대회 개설 제한 정책은 어떻게 작동하나요? +

유저의 등급이 plan-free인 경우, React 앱 대회 개설 폼에서 참가비 입력 칸이 비활성화되며 무조건 0원으로 고정됩니다. 강제로 API를 조작하여 0원 초과의 결제 금액을 보내더라도 Workers 백엔드 미들웨어 단에서 403 Forbidden을 반환하여 차단합니다.

등급별 월간 한도(Basic: 1건, Coach: 5건, Organizer: 무제한) 역시 백엔드 트랜잭션 수량 검증을 통해 엄격하게 차단됩니다.

Q. 이번에 새로 반영된 Q&A 스팸 제어 및 단체 승인 관리 프로세스는 무엇인가요? +

Q&A 영역에 악성 도배글이나 욕설 등이 등록되는 것을 방지하기 위해 Cloudflare Turnstile을 연동하여 봇 방지를 수행합니다. 만약 우회해 스팸이 등록된 경우, 일반 유저의 🚨신고 버튼을 통해 어드민 Support 탭에 전달되며, 어드민은 신고 정보에서 원본 댓글을 비동기로 당겨와 직접 삭제하거나 작성자를 즉각 차단(Block)할 수 있습니다.

Q. 이번에 마이그레이션된 모바일 앱(React Native / Expo) 빌드 및 테스트 방법은 무엇인가요? +

VivaSport 모바일 프로젝트는 Expo Router 파일 기반 내비게이션 구조로 설계되어 있습니다. 로컬 빌드를 위해 자바 JDK 17을 설치하고 환경변수(JAVA_HOME)를 설정한 상태에서 cd android && ./gradlew assembleDebug 명령을 실행하면 즉각 app-debug.apk 파일이 생성되어 실제 폰이나 에뮬레이터에서 즉시 테스트할 수 있습니다.

Q. 홈페이지 문의하기(Contact Form) 접수 시 메일 발송이 실패하거나 지연되어도 데이터가 유실되지 않나요? +

문의하기 접수 시 백엔드 Workers API는 이메일 전송에 앞서 D1 데이터베이스(inquiries 테이블)에 문의 데이터를 우선 영구 기록합니다. 이후 연동된 Resend API를 통해 실시간 알림 메일을 전송하며, 만약 Resend API 도메인 인증 상태 등의 문제로 메일 발송이 예외 에러를 발생시키더라도, 내부 Exception 처리로 안전하게 우회 차단되어 사용자 화면에는 "접수 완료" 알림이 정상적으로 노출되며 데이터 유실이 일절 발생하지 않습니다.

VivaSport 개발자 센터 & 도움말