저장소: octxxiii/Oho-Mate

🕹️ OHO-MATE

한국 서버에서 통하는 한국어 — 게이머 특화 C2C 언어 학습 플랫폼 Korean for Gamers. Real lessons. Real progress. Recorded forever.

---

📖 개요 (Overview)

OHO-MATE는 한국 게임 서버에서 실전 소통을 원하는 외국인 학습자와 검증된 한국인 튜터를 매칭하는 C2C 언어 학습 플랫폼입니다.

• 🎮 LoL, VALORANT, 마인크래프트 게임 컨텍스트 특화 수업
• 🎙️ 인앱 음성 통화 — Agora RTC 기반, 플랫폼 이탈 없음
• 🤖 AI 학습 리포트 — GPT-4o-mini가 게임 맥락 + 문화 노트 포함 분석
• 💬 실시간 채팅 — Supabase Realtime, 외부 연락처 공유 차단
• ⭐ XP + 스트릭 시스템 — 레벨업, 배지, 연속 학습 보상

OHO-MATE is a Korean language tutoring marketplace purpose-built for gamers who want to communicate in Korean game servers. Every lesson is recorded as an AI report — 기록되지 않는 것은 공부가 아니다.

---

✨ 주요 기능 (Features)

🎮 학습자 (Learner)

👨‍🏫 튜터 (Tutor)

🛡️ 어드민 (Admin)

---

🏗️ 아키텍처 (Architecture)

                         ┌─────────────────────────────────┐
                         │         React SPA (Vite)        │
                         │  src/pages  src/components      │
                         │  src/context  src/lib           │
                         └────────────┬────────────────────┘
                                      │
              ┌───────────────────────┼───────────────────────┐
              │                       │                       │
    ┌─────────▼────────┐   ┌──────────▼──────────┐  ┌────────▼──────────┐
    │  Supabase (BaaS) │   │  Stripe Payments     │  │   Agora RTC       │
    │  - Auth (JWT)    │   │  - Checkout Session  │  │  - Voice Lessons  │
    │  - PostgreSQL    │   │  - Webhook → lessons │  │  - Token: Edge Fn │
    │  - Realtime Chat │   │  - auto chat room    │  │  - 50min timer    │
    │  - Edge Functions│   └─────────────────────┘  └───────────────────┘
    │    · stripe-webhook
    │    · agora-token
    │    · generate-report (GPT-4o-mini)
    │    · create-checkout
    │    · process-payout
    └──────────────────┘

핵심 설계 원칙

---

🗂️ 프로젝트 구조 (Project Structure)

Oho-Mate/
├── public/
│   ├── robots.txt
│   └── sitemap.xml
├── src/
│   ├── constants/index.js          # 색상(C), 폰트(PX/KR), 태그, 등급 상수
│   ├── data/tutors.js              # 튜터 목업 데이터
│   ├── context/
│   │   ├── UserContext.jsx         # Supabase Auth + 데모 유저
│   │   ├── WishlistContext.jsx     # 찜 목록 (localStorage)
│   │   ├── XPContext.jsx           # XP + 레벨 + 배지 + XPToastPortal
│   │   └── NotificationContext.jsx # 인앱 알림
│   ├── lib/
│   │   ├── supabase.js             # Supabase 클라이언트
│   │   ├── openai.js               # GPT-4o-mini 리포트 + 데모 폴백
│   │   ├── chat.js                 # Realtime 채팅 (구독·전송·데모 데이터)
│   │   └── xp.js                  # XP 적립·조회·스트릭·배지 함수
│   ├── hooks/
│   │   └── useAgora.js             # Agora RTC CDN 로드 + 채널 조인/리브
│   ├── components/
│   │   ├── Nav.jsx                 # 반응형 네비게이션
│   │   ├── BottomNav.jsx           # 모바일 하단 탭바
│   │   ├── Footer.jsx              # 푸터 (약관·단어장 링크)
│   │   ├── VoiceRoom.jsx           # Agora 음성 UI (50분 타이머, 참가자)
│   │   ├── XPBar.jsx               # XP 진행 바 + LevelBadge
│   │   ├── Box / Btn / Chip / Stars / Modal / Toast / Avatar / ...
│   │   ├── CRT.jsx                 # 스캔라인 오버레이
│   │   ├── ErrorBoundary.jsx
│   │   └── ProtectedRoute.jsx
│   ├── pages/
│   │   ├── Home.jsx                # 게임 히어로, 게임 포털, AI 리포트 훅, 비교표
│   │   ├── TutorsList.jsx          # 검색·필터·정렬
│   │   ├── TutorDetail.jsx         # About/Schedule/Reviews 탭
│   │   ├── Booking.jsx             # Stripe 결제 3단계
│   │   ├── Dashboard.jsx           # 수업현황/AI리포트/위시리스트/XP로그
│   │   ├── TutorDashboard.jsx      # 튜터 수업관리 + 가이드 탭
│   │   ├── Messages.jsx            # Supabase Realtime 채팅
│   │   ├── ReportDetail.jsx        # AI 리포트 상세 + 플래시카드 + 퀴즈
│   │   ├── LessonRoom.jsx          # 인앱 음성 수업룸 (Agora + 노트 + 리포트)
│   │   ├── Vocab.jsx               # 한국어 게임 단어장 84개
│   │   ├── Admin.jsx               # 관리자 패널
│   │   ├── Terms.jsx               # 이용약관 (한/영)
│   │   └── Privacy.jsx             # 개인정보처리방침 (한/영)
│   ├── modals/
│   │   ├── AuthModal.jsx           # 로그인/회원가입
│   │   ├── ApplyModal.jsx          # 튜터 지원서
│   │   └── OnboardingModal.jsx     # 신규 가입 온보딩
│   └── App.jsx                     # BrowserRouter + 모든 라우트
├── supabase/
│   ├── config.toml
│   ├── migrations/
│   │   ├── 00001_initial.sql       # profiles, packages, lessons, reviews, ai_reports, notifications
│   │   └── 00002_chat_xp_games_badges.sql  # chat, xp_ledger, streaks, badges + triggers
│   └── functions/
│       ├── _shared/
│       │   ├── supabase-admin.ts
│       │   ├── cors.ts
│       │   └── exchange-rate.ts
│       ├── create-checkout/        # Stripe Checkout Session 생성
│       ├── stripe-webhook/         # 결제 완료 → lessons + chat room 자동 생성
│       ├── generate-report/        # GPT-4o-mini AI 학습 리포트 v2
│       ├── agora-token/            # Agora AccessToken2 (HMAC-SHA256, pure Deno)
│       └── process-payout/        # 튜터 정산 처리
└── index.html                      # OG / Twitter Card / JSON-LD SEO

---

🛠️ 기술 스택 (Tech Stack)

---

🗄️ DB 스키마 (핵심 테이블)

-- Migration 00001
profiles          -- 유저 프로필 (id, name, av, role, game_tags, level)
tutor_applications -- 튜터 지원서 (name, discord, lang, tags, intro, status)
packages          -- 수업 패키지 (name, lessons, price_usd, payout_krw)
lessons           -- 수업 (learner_id, tutor_id, status, amount_usd, payout_krw, exchange_rate, platform_profit)
reviews           -- 리뷰 (lesson_id, learner_id, tutor_id, rating, text)
ai_reports        -- AI 리포트 (lesson_id, report_json[v2 schema])
notifications     -- 인앱 알림 (user_id, type, title, body, metadata)

-- Migration 00002
chat_rooms        -- 채팅룸 (participants uuid[], last_message, last_message_at)
chat_messages     -- 메시지 (room_id, user_id, content, type, metadata)
                  -- type: "text" | "system" | "warning"(연락처 공유 감지)
xp_ledger         -- XP 획득 기록 (user_id, action, xp, label)
streaks           -- 연속 학습일 (user_id, current_streak, longest_streak, last_login)
game_profiles     -- 게임 프로필 (user_id, game_id, username, rank, server)
badges            -- 배지 정의 (10종 시드 데이터)
user_badges       -- 획득 배지 (user_id, badge_id)

XP 행동 테이블

---

🤖 AI 리포트 v2 스키마

interface ReportV2 {
  // Core
  date: string;
  tutor: string;
  topic: string;
  level: "입문" | "초급" | "중급" | "고급";
  duration_min: number;

  // 게임 컨텍스트
  game_context: string;          // "롤 솔랭 티어 승급전 소통" 등
  highlight_moment: string;      // 수업 중 베스트 순간
  vocab_mastery_pct: number;     // 0~100 어휘 이해도

  // 학습 분석
  vocabulary: { word, meaning, roman, example, game_usage }[];
  cultural_notes: { title, body }[];       // 문화적 맥락
  pronunciation_tips: { tip, example }[];  // 발음 교정 포인트
  good: string;           // 잘한 점
  improve: string;        // 개선점
  next_lesson: string;    // 다음 수업 추천
  homework: string;       // 과제
  overall_score: number;  // 1~10
}

---

🚀 시작하기 (Getting Started)

1. 저장소 클론

git clone https://github.com/octxxiii/Oho-Mate.git
cd Oho-Mate

2. 패키지 설치

npm install

3. 환경 변수 설정

cp .env.example .env

.env 파일을 열어 아래 값들을 채워주세요:

# Supabase (https://supabase.com)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key

# Stripe (https://stripe.com)
VITE_STRIPE_PUBLIC_KEY=pk_test_...

# OpenAI (https://platform.openai.com)
VITE_OPENAI_API_KEY=sk-...

# Agora (https://console.agora.io)
# Edge Function 환경변수 — Supabase Dashboard > Functions > Secrets
# AGORA_APP_ID=your-app-id
# AGORA_APP_CERTIFICATE=your-certificate (없으면 no-auth 모드)

# Stripe (Edge Function용)
# STRIPE_SECRET_KEY=sk_live_...
# STRIPE_WEBHOOK_SECRET=whsec_...

⚠️ 모든 환경 변수 없이도 데모 모드로 전 기능 실행 가능합니다.

• Supabase 미설정 → 데모 로그인 + 로컬 스토리지
• OpenAI 미설정 → 샘플 AI 리포트 반환
• Agora 미설정 → no-auth 모드 (토큰 없이 채널 접속)

4. Supabase 로컬 실행 (선택)

# Supabase CLI 필요
supabase start
supabase db reset  # 마이그레이션 00001 + 00002 적용

5. 개발 서버 실행

npm run dev

브라우저에서 http://localhost:5173 열기

---

🌐 Edge Functions 배포

# 전체 함수 배포
supabase functions deploy

# 개별 함수
supabase functions deploy stripe-webhook
supabase functions deploy agora-token
supabase functions deploy generate-report
supabase functions deploy create-checkout
supabase functions deploy process-payout

# 환경 변수 설정
supabase secrets set STRIPE_SECRET_KEY=sk_live_...
supabase secrets set STRIPE_WEBHOOK_SECRET=whsec_...
supabase secrets set AGORA_APP_ID=...
supabase secrets set AGORA_APP_CERTIFICATE=...
supabase secrets set OPENAI_API_KEY=sk-...

Stripe Webhook 엔드포인트

POST https://<project>.supabase.co/functions/v1/stripe-webhook

이벤트:
  - checkout.session.completed  → lessons 생성 + chat_room 자동 생성
  - payment_intent.succeeded    → 폴백 (checkout 미처리 시)

---

🗺️ 스프린트 로드맵

✅ Sprint 1 — Core Platform (완료)

• Agora RTC 인앱 음성 수업 (/lesson/:id)
• AI 리포트 v2 (게임 컨텍스트 + 문화 노트 + 발음 팁)
• 플래시카드 + 퀴즈 모드 (리포트 상세)
• Supabase Realtime 채팅 (연락처 공유 차단 트리거)
• XP + 스트릭 + 배지 시스템
• Stripe 결제 후 자동 채팅룸 생성
• 한국어 게임 단어장 (84개 표현, 5개 탭)
• 관리자 패널 (수익 분석 + 튜터 심사)
• 이용약관 + 개인정보처리방침 (한/영)
• SEO (OG tags, JSON-LD, robots.txt, sitemap.xml)

🔜 Sprint 2 — Growth

• Stripe Subscription (월간 무제한 패키지)
• 수업 전날 이메일 / 푸시 알림
• 튜터 비디오 자기소개 (Supabase Storage)
• 게임 계정 연동 (LoL API, VALORANT API)
• 리포트 PDF 다운로드
• 모바일 앱 (React Native)

🔮 Sprint 3 — Scale

• AI 튜터 추천 (학습 기록 기반)
• 그룹 레슨 (3~5명)
• 커뮤니티 피드 (학습 인증·게임 짤)
• 다국어 지원 (EN / JA / ZH)
• 튜터 수익 대시보드 고도화

---

🔒 보안 & 플랫폼 보호

---

📄 라이선스 (License)

MIT © 2025 OHO-MATE

---

<div align="center"> <b>🕹️ 기록되지 않는 것은 공부가 아니다</b><br/> _{Every lesson. Every word. Every level up — tracked forever.}<br/><br/> _{Made with ❤️ for Korean learners worldwide} </div>