BurningTimesAi/공유/소통/완료/2026-04-17_서버_작업_참고자료.md

---
from: 개발팀장
to: PM (DOCX 변환 → 외부 서버 작업자)
date: 2026-04-17
type: 참고자료
status: 완료
version: v1.2
audience: 외부 서버 작업자
tags: [서버참고자료, 수상한잡화점, 서버경계, 데이터SOT]
---

# 서버 작업 참고 자료 — 수상한잡화점

> **본 문서의 성격**: 수상한잡화점 프로젝트 서버 파트 작업자에게 전달하는 **참고 자료**입니다. 공식 업무 지시서가 아니라, 현 프로젝트의 서버 현황·데이터 카테고리·클라-서버 경계 원칙·참고용 API 샘플을 정리한 배경 문서입니다. 세부 구현 방향과 서버 스택 선택은 작업자가 판단·제안할 수 있는 열린 영역으로 남겨져 있습니다.
> **권장 완독 시간**: 5~7분

---

## 0. 1페이지 개요

- **프로젝트**: 수상한잡화점 (로그라이크 RPG, Unity 2022+, 모바일)
- **현 서버 스택**: PlayFab 사용 중 (Title API·CloudScript·Leaderboard·Profiles·Mail). 유지·전환·하이브리드 여부는 열린 결정 사항
- **서버 담당 영역 (현 프로젝트 범위)**: ① 재화 SOT 서버 검증·지급 ② 랭킹 저장·조회 ③ 우편·IAP 영수증 검증 ④ 서버 시간 기준 리셋
- **어뷰징 판정 책임**: 클라이언트 주도. 서버는 판정 결과(플래그) 수신 시 지급 거부 처리만 수행 (섹션 5 참조)
- **현 상태**: 서버 Critical 보안 3건 보류 중, 서버 작업자 합류 시점 재개 예정

**프로젝트 기본 원칙 4종 (확정, 변경 불가)**
1. 모든 보상은 **재화 형태로 지급**. 비재화 보상(칭호·스킨·장비·PC 등) 없음 → 모든 보상은 서버 검증·지급 대상
2. 재화 사용·획득은 **항상 서버 응답 필수**. 클라 단독 처리 금지
3. 미션 클리어 판단은 **클라 재량**. 서버는 보상 지급 시점에만 개입
4. 랭킹 등록은 **클라 정보를 서버가 그대로 저장**

---

## 1. 현 서버 스택 현황 (PlayFab 사용 중)

| 구성 요소 | 현 상태 | 비고 |
|----------|--------|------|
| PlayFab 인증·UserData·TitleData | 사용 중 | - |
| CloudScript | 사용 중 (`Get_UserInfo`·`Get_MailList`·`Get_MailReward` 등) | 함수 dump 후 버전 관리 편입 필요 |
| Leaderboard (Progression API) | 읽기 경로 존재 (`GetLeaderboard`·`GetLeaderboardAroundEntity`) | 등록 경로 미확인 → 재설계 필요 |
| Mail | `Get_AllMail` CloudScript 존재 | 재화 보상 우편 처리 |
| `Save_StageResult` (스테이지 완료 처리) | 비활성 상태 (주석 처리) | 복원·신규 설계 필요 |
| `InappInfo.cs` (IAP 영수증) | 비활성 상태 | 재활성화 + `ValidateGooglePlayPurchase` 연결 |
| `Server_Live_ID`·`Server_Dev_ID` | 코드 주석 처리 상태 | 인수인계 시 복구 |

> **스택 선택은 열린 사안**: 본 섹션은 "현재 이렇게 구현되어 있다"는 현황 기술입니다. PlayFab 유지, 하이브리드 구성, 별도 스택으로의 전환 등 서버 아키텍처 방향은 작업자 판단·제안 가능 영역입니다.

---

## 2. 서버 관리 데이터 카테고리 (8개 도메인)

| # | 도메인 | 주요 필드 | SOT 방향 |
|---|--------|----------|---------|
| 1 | 재화 인벤토리 | `dic_Item[itemid] = amount` (Gold·Soul 등) | 서버 SOT 필수 |
| 2 | PC(캐릭터) 보유 | `dic_PC[pcid]` — 레벨·경험치·각성 | 서버 SOT |
| 3 | 장비·카드 | `Equipment`·`dic_Card[cardid]` | 서버 SOT |
| 4 | 스테이지 진행 | `StageData.dic_stagedata[diff][chapter][stageid].Star` | 서버 SOT (보상 지급 연결) |
| 5 | 미션·출석 | `Mission.dic_Mission[type]`·`RewardAttandanceDay` | 서버 SOT (재화 보상) |
| 6 | 랭킹 | Leaderboard (현 PlayFab) | 서버 저장 |
| 7 | 우편 | CloudScript 기반 (현 PlayFab) | 서버 SOT |
| 8 | 시즌·패스 | 신규 정의 필요 | 기획 SOT 정의 후 구체화 |

---

## 3. 클라/서버 경계 — 핵심 원칙 3

1. **재화 사용·획득 → 서버 응답 필수**
   - 클라: 사용·획득 요청 전송 / 서버: 잔고 검증·차감·응답 (또는 지급·응답)
   - 서버 거부 시 클라 롤백

2. **미션 클리어 → 클라 판단, 재화 보상은 서버 지급**
   - 클라: 조건 체크·카운트 누적·달성 판정 / 서버: 보상 수령 요청 수신 시 지급

3. **랭킹 등록 → 클라가 계산한 값을 서버가 그대로 저장**
   - 클라: 점수·메타정보 계산·전송 / 서버: Leaderboard 저장

**보상 통일**: 모든 보상은 재화 단위. 비재화 보상(칭호·스킨·장비·PC 등) 없음.

---

## 4. 핵심 API 참고 예시

> 아래는 **현 구현 참고용** 샘플입니다. 서버 스택·구현 방식이 변경될 경우 인터페이스는 재설계 대상입니다. "반드시 이 방식을 유지해야 한다"는 의미가 아닙니다.

### 4-1. `Save_StageResult` (복원 필요 — 현 PlayFab CloudScript 기준 샘플)

**유형**: CloudScript 함수 / **호출 권한**: Client (LoginSession 유효)
**역할**: 스테이지 클리어 결과를 저장하고 재화를 지급

**요청 파라미터** (예시):
```json
{
  "difficulty": 2,
  "chapter": 3,
  "stageId": 47,
  "starCount": 3,
  "clearTimeMs": 125000,
  "droppedItems": [{"itemId": 101, "amount": 500}],
  "is_abuse_flag": false
}
```

**응답 (성공)**:
```json
{
  "status": "ok",
  "grantedRewards": [{"itemId": 101, "amount": 500}],
  "newStar": 3,
  "stageProgress": {"maxStageId": 47}
}
```

**응답 (실패)**:
| 에러 코드 | 조건 | 클라 처리 |
|----------|------|----------|
| `AbuseFlagged` | `is_abuse_flag: true` 수신 | 지급 거부, 기록 저장 (섹션 5) |
| `SessionInvalid` | 세션 없음·만료 | 재로그인 유도 |
| `StageLocked` | 해당 스테이지 미해금 | 경로 이탈 처리 |

### 4-2. `Grant_MissionReward`
- 미션 보상 재화 지급. 클라가 미션 완료 판정 후 수령 요청 시 서버가 지급·응답
- `is_abuse_flag` 동일 수용 (클라가 자체 판정 시 true 동봉 가능)

### 4-3. 랭킹 등록 경로 (신규 설계 필요)
- 현 코드에서 등록 호출처 미확인 → 재구축 필요. 엔드포인트명 예: `Submit_RankingEntry`
- 클라 전송 점수·메타정보 그대로 Leaderboard 저장. 세부는 설계 단계에서 확정

---

## 5. 참고: 어뷰징 방지 체계 (클라 주도, 서버 최소 역할)

> **프로젝트 정책**: 어뷰징 **판정은 클라이언트 책임**. 서버는 판정 결과(플래그)만 받아 처리합니다.

**판정 책임**: 클라이언트 (경계값 보관·수치 검증 전부 클라에서 수행)

**서버 역할 (최소)**:
- 재화 지급 요청 페이로드에 **`is_abuse_flag: true`** 가 포함된 경우, 해당 지급을 **거부**하고 **기록** 저장
- 플래그 저장 위치: 현 스택 기준 Profile 필드 또는 별도 모니터링 엔드포인트 (구현 단계에서 결정)
- 관리자 알림 채널(Slack Webhook·이메일 등) 연계는 구현 단계에서 결정

**서버가 하지 않는 것 (프로젝트 정책)**:
- 경계값 테이블 보관 (Title Data 등에 적재 불필요)
- 경계값과 클라 전송 수치 비교 검증
- 어뷰징 판정 로직 자체

**협의 범위**: 클라이언트팀 구현 시 필요하면 서버 작업자와 **플래그 인터페이스 스펙**만 협의합니다 (판정 로직 자체는 협의 대상 아님).

---

## 6. 환경 셋업 체크리스트

- [ ] 현 서버 스택(PlayFab) 접근 권한 수령 (Title ID 인수·Game Manager 대시보드·CloudScript revision 접근) — 현 스택 유지 시
- [ ] 현 배포 CloudScript 전문 dump → 버전 관리 편입 (경로 후보: `코어코드/수상한잡화점_서버/`)
- [ ] Unity 프로젝트 clone + `git fetch origin && git pull`
- [ ] Unity 에디터 설치 (프로젝트 버전 기준)
- [ ] 현 PlayFab SDK 연동 확인 (빌드·실행 1회 성공)
- [ ] IDE (VS Code 또는 JetBrains Rider) + Node.js (CloudScript 로컬 테스트용)

---

## 7. 용어집

| 용어 | 뜻 |
|------|---|
| PlayFab | Microsoft BaaS. 본 프로젝트가 현재 사용 중인 서버 스택 |
| CloudScript | PlayFab 서버 사이드 JavaScript 실행 환경 |
| Title Data | PlayFab Title 단위 공용 설정 저장소 |
| UserData | PlayFab 유저별 서버 저장소 |
| Leaderboard | PlayFab 순위표 서비스 (Progression API) |
| ObscuredType | `CodeStage.AntiCheat` 로컬 변조 방어 타입. 서버 검증 대체재는 아님 |
| ServerData | 수상한잡화점 프로젝트 클래스(`ServerClass.cs`). 유저 데이터 SOT 로컬 표현 |
| SOT | Source of Truth. 데이터의 단일 진실 근원 |
| AntiCheat | 어뷰징·치트 방지 체계. 본 프로젝트는 클라 판정 + 서버는 플래그 수신 시 지급 거부 |

---

## 8. 변경 이력

| 일시 | 버전 | 요지 |
|------|------|------|
| 2026-04-17 | v1.2 | 외부 서버 작업자용 참고 자료로 중립화 — PlayFab 전제 제거(현 사용 중 상태로만 기술), 조직 내부 프로세스 표현 제거, "지시서" → "참고 자료"로 성격 재정의 |

---

**용도**: 서버 작업자 합류 시 본 자료를 출발점으로 사용. 세부 서버 스택 선택, 아키텍처 방향, API 스펙 확정은 배정 후 설계 단계에서 진행.