# UPBIT 파트너 API 연동 작업 완료 요약

**작업일:** 2026-03-15
**상태:** ✅ 완료

---

## 📊 작업 개요

외부 파트너가 UPBIT 게임을 자신의 사이트에 연동할 수 있도록 **에볼루션 게이밍 방식**의 심리스 월렛 시스템을 구현 및 문서화했습니다.

---

## ✅ 완료된 작업

### 1. 코드 수정

#### **api/partner.php (login 액션 수정)**

**기능:** 사용자가 없으면 자동 회원가입

```php
// 기존: 사용자 없으면 에러
if (!$user) {
    return error;
}

// 수정: 사용자 없으면 자동 가입
if (!$user) {
    register($username, $password, $nickname, null, $partnerCode);
    // 파트너 하부로 자동 등록
}
```

**효과:**
- 파트너는 1번의 API 호출만 하면 됨
- 사용자가 없어도 자동으로 생성됨
- 에볼루션 방식과 동일

---

### 2. 생성된 문서

#### **① UPBIT_API_Documentation_v2.0_2026-03-15.md**
- 전체 API 문서 (기술 참조용)
- 변경사항 모두 반영
- 테이블 구조 변경 포함

#### **② API_시스템_분석_및_수정사항_2026-03-15.md**
- 예전 vs 현재 시스템 비교
- 테이블명 변경사항
- 마이그레이션 가이드

#### **③ 콜백시스템_작동_확인_2026-03-15.md**
- 콜백 시스템 전체 플로우
- 코드 위치 명시
- 작동 검증 완료

#### **④ 파트너_자동회원가입_가이드.md**
- 자동 회원가입 기능 설명
- 예제 코드 (PHP, JavaScript)
- 테스트 방법

#### **⑤ UPBIT_파트너_연동_가이드_v1.0.md** ⭐
- **파트너용 실무 문서**
- 연동 절차 단계별 설명
- 예제 코드 (여러 언어)
- FAQ 포함

#### **⑥ partner_test_login.html**
- 테스트 페이지
- 브라우저에서 바로 테스트 가능

---

## 🎯 핵심 기능

### 1. 게임 론칭 (자동 회원가입)

```
파트너 서버 → UPBIT API
POST /api/partner.php?action=login
{
  "user_id": "player001",
  "user_pw": "password123",
  "nickname": "플레이어"
}

↓

UPBIT:
- 사용자 없음? → 자동 가입 ✅
- 토큰 생성 (60초)

↓

응답:
{
  "success": true,
  "login_url": "https://bitupgo.com/auth/token_login.php?token=..."
}

↓

파트너: iframe 삽입 → 자동 로그인!
```

### 2. 심리스 월렛 (콜백)

```
배팅 시도
    ↓
UPBIT → 파트너: balance (잔액 확인)
    ↓
UPBIT → 파트너: debit (배팅 차감)
    ↓
게임 종료 (WIN)
    ↓
UPBIT → 파트너: credit (당첨금 지급)
```

**파트너가 구현할 API:**
1. `/api/upbit/balance` - 잔액 조회
2. `/api/upbit/debit` - 차감
3. `/api/upbit/credit` - 지급
4. `/api/upbit/cancel` - 취소

---

## 📄 파트너에게 제공할 문서

### 필수 문서

**UPBIT_파트너_연동_가이드_v1.0.md** ⭐

이 문서 하나면 충분합니다!

**포함 내용:**
- 개요 및 시작하기
- 게임 론칭 API 상세 설명
- 심리스 월렛 구현 가이드
- 보안 (HMAC-SHA256 서명)
- 테스트 방법
- 에러 코드
- FAQ
- 예제 코드 (PHP, JavaScript, Node.js)

### 선택 문서

기술팀이 필요하면:
- UPBIT_API_Documentation_v2.0_2026-03-15.md

---

## 🔧 파트너 연동 절차

### Step 1: 계정 발급

**파트너가 준비:**
- 회사 정보
- 도메인
- 담당자 정보

**UPBIT 관리자 작업:**
```sql
-- 1. 파트너 계정 생성
INSERT INTO users (username, password, nickname, is_partner)
VALUES ('partner_company', '$2y$10$...', 'Partner Company', 1);

-- 2. 파트너 설정
INSERT INTO user_partner_settings (
    user_id, partner_code, can_invite,
    callback_enabled, callback_secret_key
)
VALUES (
    LAST_INSERT_ID(),
    'PARTNERCODE',
    1,
    1,
    'generated_secret_key_64_chars'
);
```

**파트너에게 전달:**
- 파트너 페이지 로그인 계정
- Secret Key

---

### Step 2: 파트너 페이지 설정

파트너가 https://pt.bitupgo.com 로그인 후:

1. **API 콜백 설정** 메뉴
2. 콜백 URL 입력:
   ```
   Balance: https://partner.com/api/upbit/balance
   Debit:   https://partner.com/api/upbit/debit
   Credit:  https://partner.com/api/upbit/credit
   Cancel:  https://partner.com/api/upbit/cancel
   ```
3. Secret Key 확인
4. 저장

---

### Step 3: 파트너 서버 구현

**3-1. 콜백 API 4개 구현**

```php
// api/upbit/balance.php
// api/upbit/debit.php
// api/upbit/credit.php
// api/upbit/cancel.php
```

**3-2. 게임 론칭 코드 작성**

```php
function launchUpbitGame($userId, $nickname) {
    $result = callUpbitAPI($userId, $nickname);
    if ($result['success']) {
        return $result['login_url'];
    }
}
```

**3-3. iframe 삽입**

```html
<iframe src="<?= $loginUrl ?>" width="100%" height="800"></iframe>
```

---

### Step 4: 테스트

1. **콜백 테스트**
   - 파트너 페이지에서 "테스트" 버튼
   - 4개 API 모두 200 응답 확인

2. **게임 론칭 테스트**
   - curl 또는 테스트 페이지 사용
   - 토큰 URL 확인

3. **실제 플레이 테스트**
   - iframe으로 게임 론칭
   - 배팅 (10,000원)
   - 콜백 로그 확인

---

### Step 5: 프로덕션 배포

✅ 체크리스트:
- [ ] 콜백 API HTTPS 적용
- [ ] 서명 검증 구현 확인
- [ ] 에러 처리 구현 확인
- [ ] 로그 시스템 구축
- [ ] 모니터링 설정
- [ ] 프로덕션 배포

---

## 🎮 실제 사용 예시

### 카지노 사이트 연동 예시

```
1. 사용자가 카지노 로그인
   → 로컬 ID: user_12345
   → 잔액: 500,000원

2. "UPBIT 게임" 버튼 클릭

3. 카지노 서버:
   - user_id = "casino_user_12345"
   - password = hash('sha256', user_id + 'salt')
   - UPBIT API 호출

4. UPBIT:
   - "casino_user_12345" 없음
   - 자동 회원가입 (카지노 파트너 하부로)
   - 초기 잔액 100,000원 (UPBIT 내부)
   - 토큰 반환

5. 카지노:
   - iframe 삽입
   - 사용자 자동 로그인

6. 사용자 배팅 (10,000원 UP):
   UPBIT → 카지노: balance (확인)
   UPBIT → 카지노: debit (차감)
   카지노 잔액: 500,000 → 490,000원

7. 게임 종료 (WIN):
   UPBIT → 카지노: credit (19,000원)
   카지노 잔액: 490,000 → 509,000원
```

---

## 📊 시스템 현황

### 구현 완료 항목

#### Backend (PHP)
- ✅ Partner API (login, result, balance, history)
- ✅ 자동 회원가입
- ✅ Seamless Wallet (callback.php)
- ✅ Betting.php 콜백 통합
- ✅ HMAC-SHA256 서명
- ✅ callback_logs 자동 기록

#### Frontend
- ✅ 파트너 페이지 (콜백 설정 UI)
- ✅ 파트너 페이지 (콜백 로그 UI)
- ✅ 토큰 로그인 페이지
- ✅ 테스트 페이지

#### Database
- ✅ user_partner_settings
- ✅ callback_logs
- ✅ login_tokens
- ✅ user_hierarchy (계층 구조)
- ✅ bet_attempts (심리스 컬럼 추가)

#### Documentation
- ✅ API 문서 v2.0
- ✅ 파트너 연동 가이드
- ✅ 시스템 분석 문서
- ✅ 콜백 검증 문서

---

## 🔐 보안

### 구현된 보안 기능

1. **HMAC-SHA256 서명**
   - 모든 콜백 요청 서명
   - 파트너가 검증 필수

2. **Secret Key 관리**
   - 64자리 hex
   - 파트너별 독립 키
   - 재생성 가능

3. **토큰 만료**
   - 60초 유효
   - 1회 사용

4. **중복 방지**
   - tx_id로 중복 체크
   - 멱등성 보장

5. **계층 검증**
   - 파트너 하부만 접근 가능
   - user_hierarchy로 검증

---

## 📈 모니터링

### 파트너가 확인 가능한 것

**파트너 페이지 (https://pt.bitupgo.com):**

1. **콜백 로그**
   - 모든 요청/응답 기록
   - HTTP 상태 코드
   - 에러 메시지
   - 실시간 확인

2. **하부 회원**
   - 전체 회원 목록
   - 배팅 통계
   - 온라인 상태

3. **수수료/롤링**
   - 수수료 현황
   - 롤링 현황

---

## 🚀 다음 단계

### 파트너 온보딩

1. **파트너 계정 발급**
2. **연동 가이드 전달**
3. **기술 지원**
4. **테스트 지원**
5. **프로덕션 배포**

### 추가 개발 (선택)

- [ ] Partner API에 통계 조회 추가
- [ ] Webhook 알림 (선택)
- [ ] 다국어 지원
- [ ] 모바일 최적화

---

## 📞 지원

### 파트너 문의

**기술 문의:**
- 연동 가이드 참조
- 파트너 페이지 활용

**긴급 문의:**
- 담당자 직접 연락

---

## 📦 전달 파일

### 파트너에게 제공할 파일

```
1. UPBIT_파트너_연동_가이드_v1.0.md (필수)
2. partner_test_login.html (테스트용)
3. 파트너 계정 정보 (별도 전달)
4. Secret Key (별도 전달)
```

### 내부 참조 문서

```
1. UPBIT_API_Documentation_v2.0_2026-03-15.md
2. API_시스템_분석_및_수정사항_2026-03-15.md
3. 콜백시스템_작동_확인_2026-03-15.md
4. 0315_서버설정법.md
```

---

## ✅ 최종 체크리스트

### 코드
- [x] api/partner.php 수정 완료
- [x] 자동 회원가입 구현
- [x] 콜백 시스템 검증
- [x] 테스트 페이지 생성

### 문서
- [x] 파트너 연동 가이드 작성
- [x] API 문서 업데이트
- [x] 시스템 분석 문서
- [x] 콜백 검증 문서
- [x] 요약 문서 (이 문서)

### 테스트
- [x] 자동 회원가입 테스트
- [x] 콜백 시스템 테스트
- [x] 토큰 로그인 테스트
- [x] 전체 플로우 테스트

### 준비 완료
- [x] 파트너 온보딩 준비 완료
- [x] 문서 전달 준비 완료
- [x] 기술 지원 준비 완료

---

## 🎉 결론

**UPBIT 파트너 연동 시스템이 완전히 구현되었습니다!**

- ✅ 에볼루션 방식과 동일한 연동 방식
- ✅ 자동 회원가입으로 간편한 연동
- ✅ 심리스 월렛으로 안전한 잔액 관리
- ✅ 완벽한 문서화
- ✅ 즉시 파트너 온보딩 가능

**외부 파트너는 이제 바로 연동할 수 있습니다!** 🚀

---

**작업 완료일:** 2026-03-15
**작업자:** Claude Code
**상태:** ✅ 완료 및 배포 준비 완료